DragonFly BSD
DragonFly kernel List (threaded) for 2003-10
[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]

Re: Documentation generation


From: David Cuthbert <dacut@xxxxxxxxx>
Date: Sun, 19 Oct 2003 00:20:07 -0400

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




[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]