At 10:57 pm 5/23/96 -0400, you wrote:
[...]
>>Mind you, when I write a driver for a piece of hardware, I will
>>put some kind of paragraph sized comment near the start of the
>>source code. It will contain a description of what the supported
>>hardware is, how it should be configured, assumptions I made in
>>writing the driver, known limitations, things I would like to do
>>to the driver if I ever found the time, and any major wierd features
>>that gave me headaches. In general I collect information to help myself
>>at some future date when I have to dive back into my own code,
>>never mind help some other poor fool that might need to dig into it.
>>I just can't imagine writing code without making these kinds of notes
>>in the sources.
>
>I don't think this is exactly a applicable statement for _all_ drivers.
>There are plenty I can see that have notes at the top, and have appropriate
>comments interspersed throughout.  Some even have ASCII block diagrams
>on how the circuitry is supposed to work!
>
>But I think that putting information like this in the source code to the
>driver is actually not such a great idea.  It should go into the man
>page!  This is the place where information is supposed to go.  However,
>some of the driver man pages aren't in great shape either :-/
>
[...]

I disagree.  While I was experimenting with writing a new filesystem driver,
I found the source code documentation to be sketchy and woefully inadequate,
and man pages on the subject were nonexistant.  Most of the source files
that I looked at only had a copyright notice at the top, and if it did
include a description of what the file was for it was just a one-liner.

And I believe implementation details should not go into man pages either.
man pages should be used for command descriptions, system call API details
(library routines, -not- kernel subroutines), file formats, etc. that are
required by users, system administrators, and application programmers.
Documentation specific to the implementation of the kernel (or any other
program) should be kept in the source code.
-----------------------
Trevin Beattie          "Do not meddle in the affairs of wizards,
trevin@xmission.com     for you are crunchy and good with ketchup."
      {:->                                     --unknown