Re: [Q]: Linux and real device drivers

Richard Gooch (rgooch@ras.ucalgary.ca)
Sat, 25 Sep 1999 20:44:09 -0600

David Hinds writes:
> On Sat, Sep 25, 1999 at 05:58:37PM +0100, Alan Cox wrote:
> > > Relying on the kernel source code as a primary means of communication
> > > between key kernel developers is simply wrong.
> >
> > Any better ideas. None I have seen in any other free project worked.
>
> One suggestion would be to have a set of man pages included in the
> kernel tree. And try to make them sufficiently useful that people
> would want to keep them up to date. In this case, I think adding to
> the kernel tree would be a good thing, because it keeps the
> documentation in the same place as what it is documenting. I'd be
> willing to write man pages for a few things myself. The current
> documentation in the kernel tree is a bit too informal and
> incomplete.

Yes. I advocate embedding markup tags in a comment block for each
function, which can then be automatically extracted to generate man
pages. This keeps the API documentation right there in the source
code, which vastly increases the chances that an update will be
reflected in the documentation.

If you look at my devfs patch, you can see what it looks like
(fs/devfs/base.c). Also look at smp_call_function() in
arch/i386/kernel/smp.c for an example.

I've got code which extracts this and allows you to generate man pages
and HTML (complete with cross-referencing/hyperlinks). I've been using
this scheme for years now. It works really well.

It's a lot of work to go through code and add all those markups, but
it's worth the effort in the long run. Once you're set up and in a
routine, you never have to worry about API documentation again.

Regards,

Richard....
Old: rgooch@atnf.csiro.au
Current: rgooch@ras.ucalgary.ca

-
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/