>I am not talking about man pages, but about coding style really.
>Let me give an example.  Who would guess that the if_eg.c
>driver was for the 3C505 board by looking at the sources?
>My first recourse is of course the source code, like any real
>"hacker" worth his salt.  So, I wander to /usr/src/sys/dev/isa
>and grep for the string "505" in the directory with the
>network drivers and concluded there was no driver.

Hmmm ...

% cd /sys/dev/isa
% grep 505 *.c
if_eg.c: * Support for 3Com 3c505 Etherlink+ card.

Or even:

% man -k 505
eg (4) - Ethernet driver for 3Com 3c505 Ethernet boards

(This is on my -current i386 system).

>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 have just paid a visit to the linux world and come away quite
>impressed.  I was in their linux/drivers/block directory looking
>at support of VLB IDE controllers, and was impressed that the
>various drivers all had the sorts of comment blocks just mentioned.
>There was a README.ide file that was a goldmine of information,
>and while I am on the topic, I need to mention the concept of linux
>"HOWTO" files, which are much like little FAQ's on selected topics of
>interest.  They are doing a lot of things that we would do well to
>emulate.

BTW, I was under the impression that VLB IDE controllers "just work", since
the bus interface is exactly the same -- the bus is just faster.

--Ken