Documentation generation

David Cuthbert dacut at kanga.org
Sat Oct 18 21:20:07 PDT 2003


Matthew Dillon wrote:
    I don't think we want to integrate document generation into the source
    code.  The problem is that you can't get too wordy without making the
    source unreadable, and the result are usually definitions so sparse as
    to be useless for understanding any serious API.
Yeah, Doxygen (and JavaDoc) both result in code that's more sparse than 
I care for, making it more difficult for maintainers.  For users of the 
code, though, the indices and cross-reference tables that result are 
quite valuable.

For this reason, I usually end up doxygen'ing only the header files at 
work, keeping the actual code "pristine."

    I am not adverse to having document-generating co-files, though, 
    to describe kernel interfaces.
The main issue with this is failing to keep the documentation in sync 
with the code.  Of course, my experience with the methodology I use at 
work is that this happens, anyway.  So be it; I'll start putting 
together some reference doco separately, probably not auto-generated, 
but I'll try to keep a close eye on what happens.

I must confess a bit of an ulterior motive here.  I recently wrote a 
Linux device driver, and found myself frustrated with the sparse, 
incoherent, misleading, and/or missing documentation of various 
interfaces.  And as much as I like the various O'Reilly books on the 
topic, they simply can't keep up-to-date with the changes being made in 
even the patch releases.  I found myself delving into the depths of the 
kernel code far more than what I consider acceptable for a production 
system.

So what I'd like to produce here is a kind of driver development kit, of 
sorts.  I don't know if that will ever happen, but, hey, documentation 
can't hurt, right?

Dave






More information about the Kernel mailing list