Re: [MiNT] Kernel documentation shortcomings

[Paul Wratt <paul.wratt@gmail.com>]

On Thu, Aug 26, 2010 at 8:05 AM, Alan Hourihane <alanh@fairlite.co.uk> wrote:
> 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.
>

:)

This was (one of) the point about "pain"

The other was that offline usable docs are not available if only the
wiki is used (moot point now)

exporting wiki to udo allow cvs to keep ofline docs (or for them to be
generated)

having a way to convert to wiki (for posting wiki edits for example)
would allow non-wiki browsers and apps to be used on "our" systems to
update wiki, instead on IE/FF and "their" os (ie original comment did
not mean wiki should not be central point)

I also agree about API docs to, the idea "many people make light work".

It should be possible for source code and/or Doxygen to used also.
Getting this right for offline docs with wiki content will just be a
matter of testing (both should be possible at the same time)

Paul