Formalized, required documentation, of the sort where each function *MUST*
be commented with pre- and post-conditions, arguments, return value,
algorithms used, expected execution times, stack space required, opcodes
needed, and all that garbage have no place in the kernel, I agree.
However, nobody suggested *that*.
Requiring kernel developers to write man pages for everything in the kernel
is silly, I agree. If someone wants to, I say let 'em go ahead. I see no
objection to documentation *if* the code is also good. See below.
The original poster wanted man pages for some kernel things. I cannot blame
him; it would be nice. However, no one has since said that all kernel hackers
should be required to write those man pages for him.
What has been suggested is a standard method of marking source comments so
that an automated tool could gather those comments and generate man-page-like
output for developers, which is a nice idea. If someone does not want to use
these tools, they do not have to, but it is nice to have them if you want
them.
>> First of all, if someone is going to go to the trouble of writing decent
>> documentation, they will almost always have gone to the trouble of writing
>> decent code.
>
> Actually, _most_ programmers in the real world don't know how to write
> decent code and they instead write lots of design documents and insist on
> tons of meaningless comments.
I do not consider those people programmers.
If someone submits crap to be included in the kernel, they will be told
'No'. This is nothing new.
[Much complaining about Microsoft Windows deleted]
> Maybe. But they sure as hell wrote a lot of Documentation.
Have you ever *read* Microsoft's documentation? I consider it all crap.
It is incomplete, incorrect, hard to read, wordy, typically out-of-date, and
often expensive. However, everyone seems to understand that crap has no place
in the kernel, and that extends to kernel docs as well.
-- Benjamin Scott dragonhawk@iname.com
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/