Re: [MiNT] Kernel documentation shortcomings

[Jo Even Skarstein <joska@online.no>]

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.

> Of course, programmer's guide explaining general things and examples
> should go into the Wiki, with references to the official documentation
> of the functions used.

Agree.

Jo Even