Re: [MiNT] Kernel documentation shortcomings

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

On Mon, 2010-08-23 at 14:16 +0200, m0n0 wrote:
> Kernel documentation shortcomings
> 
> Hello everyone. I think the FreeMiNT docs are out of bounds.
> Here are just some examples...
> 
> 
> doc/programmer/man/README:
> --------------------------
> 
> "These are (out of date) manpages for some system calls.  They are
> provided for informational purposes only and they are in bad need
> of a general revision."
> 
> What is about up to date documentation for the system calls?
> Did someone introduced new System calls since 1.16 ?
> How to generate up-to-date system call reference?
> Do we have to edit the MAN pages manually?
> How to update the version numbers in the MAN pages?
> Shouldn't they all contain the same version?
> 
> doc/programmer/kerinfo.txt:
> ---------------------------
> 
> "
>  * All functions should be called using the GCC calling conventions:
>  *
>  * (1) parameters are passed on the stack, aligned on 16 bit 
> boundaries
>  * (2) registers d0-d1 and a0-a1 are scratch registers and may be 
> modified
>  *     by the called functions
>  * (3) if the function returns a value, it will be returned in 
> register
>  *     d0
>  *
>  * data types:
>  * -----------
>  * int   is 16bit
>  * short is 16bit
>  * long  is 32bit
> "
> 
> Is this info up to date? Is int still 16 bit when compiling an kernel 
> for freemint?
> Wasn't -mshort removed from kernel compilation?
> About number 3 ("function returns a value it will be returned in 
> register d0"):
> Is that true? At least not for floating point results, right?
> 
> 
> /NEWS
> 
> isn't updated since kernel 1.15.12. Do we really need it? I mean,...
> the news also get into readme.1.17.0. - if we don't need it, why not 
> remove it.
> Otherwise it needs to be updated...
> 
> /todo.txt
> 
> says: "Important todos for 1.16 release"
> 
> Which of these points are solved? Which stuff is carried into 1.17 rc 
> ?
> I guess the toswin 2.7 todo can be closed? =)
> 
> One point out of the todo.txt:
> "- also invent some sane format for the documentation
>   (STG? info? HTML?) and convert everything into it."
> 
> I think this has to be done, right ;) ?
> 
> What do others think, will it make sense to release an "1.17 beta / 
> rc" - with such an outdated documentation?
> I think up-to-date documentation is a must for an release candidate.
> If we can decide on how to continue the documentation ( it's really 
> unordered somehow...),
> wouldn't it be great to see up-to-date documentation within 1.17? :) 
> That's would be a clean release,
> I guess...

I agree that the documentation is very out of date, but some pieces are
still relevant.

But I'd really really really like to get all of this into a wiki that
everyone can maintain. And ship a basic readme, with/without a wiki
converted to some kind of document format.

And I'll admit that I'm the worst documentation person, so it'd be nice
to have some people help convert that documentation that's in the
tarball doc/ directory and get it onto the wiki.

Alan.