Re: [MiNT] Kernel documentation shortcomings

[Alan Hourihane <alanh@fairlite.co.uk>]

On Wed, 2010-08-25 at 22:55 +0200, Jo Even Skarstein wrote:
> On 08/25/2010 10:38 PM, Vincent Rivière wrote:
> > Jo Even Skarstein wrote:
> >> I think it's a bad idea to maintain the API docs in a wiki. The
> >> syscalls/API should be documented in the code itself, where the API is
> >> implemented, using a system like Doxygen (which is already used for
> >> the GEM bindings). Then export this to plain HTML and link to it from
> >> the wiki.
> > 
> > Very true for the reference developer docs.
> > However, it may be a bit difficult for the system calls because they are
> > not always implemented as functions.
> > And also, the TOS (and MiNT) system calls are actually an "interface".
> > They must be implemented by some actual component (TOS, EmuTOS,
> > FreeMiNT...). So, in the case of the system calls, maybe the interface
> > documentation should be defined externally, for example in the Wiki (or
> > an editable version of tos.hyp) ?
> 
> The point in having the API docs in the code itself is to force the
> developers to keep the API docs up to date whenever there's a change.
> External docs won't be updated.

I'm inclined to say that the API docs aren't up-to-date just because
some developers get lazy documenting things, me included. Having others
help, makes life easier. So I don't buy that argument.

Alan.