[MiNT] Kernel documentation shortcomings

[m0n0 <ole@monochrom.net>]

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...

Greets,
m0n0