DragonFly kernel List (threaded) for 2003-10
Re: Documentation generation
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
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
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?