Re: Documentation generation

[David Cuthbert <dacut@xxxxxxxxx>]

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