Re: [Q]: Linux and real device drivers

Benjamin Scott (dragonhawk@iname.com)
Mon, 27 Sep 1999 15:29:14 -0400 (EDT)


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/