Messages in this thread | | | Date | Mon, 27 Sep 1999 15:29:14 -0400 (EDT) | From | Benjamin Scott <> | Subject | Re: [Q]: Linux and real device drivers |
| |
On Mon, 27 Sep 1999, Oliver Xymoron wrote: > The initial suggestion that started this thread was to write manpage-like > documentation for kernel internals. This capital-D formalized Documentation > is what I'm objecting to. It's evil.
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/
| |