cvs commit: src/sys/doc/subsys Dependencies Doxyfile-cam Doxyfile-crypto Doxyfile-dev_pci Doxyfile-dev_sound Doxyfile-dev_usb Doxyfile-geom Doxyfile-i4b Doxyfile-kern Doxyfile-libkern Doxyfile-linux Doxyfile-net80211 ...

[Sam Leffler]

Alexander Leidinger wrote:
> Quoting Sam Leffler <sam at errno.com> (Fri, 26 May 2006 11:24:54 -0700):
> 
>> Can someone explain the purpose of this?  Is the intent to annotate
>> source code for generating documentation?  I don't recall seeing a
>> discussion about this.
> 
> While the man pages we have are good references if you know what you
> want to use, we lack a high-level view of the kernel API (for internal
> use and for 3rd party work). The FreeBSD architecture hand book doesn't
> count here in my eyes.
> 
> Doxygen is able to help here. It generates call graphs, dependency
> graphs, links from one part of the docs to other related parts of the
> docs without any need to change anything in the source. By augmenting
> the source with some special doxygen comments (several existing
> comments could be converted to doxygen comments which would improve the
> kernel docs use a lot), you can even generate a tightly integrated
> high- and low-level documentation of the source.
> 
> There was no specific documentation of "should we use doxygen or not?".
> At some point I presented my doxygen framework in public mailinglists
> and those which know the possibilities of doxygen liked it, and those
> which don't know them, didn't care about it.
> 
> On Monday there's a discussion (started in cvs-all) which triggered a
> cleanup and this commit.
> 
> BTW: we already have doxygen stuff in the tree since a long time. For
> example the rijndael code contains doxygen comments. And
> /usr/src/sys/doc contains a doxygen config for the entire kernel since
> 2004 (if you are only interest in the docs of a subsystem it's a waste
> of time and needs a lot of resources... my system needs several hours
> to generate just the docs for some subsystems).

Someone else pointed out to me that the bulk of the discussion about
this happened under an unrelated subject.  I checked arch@ and found
exactly 3 msgs with doxygen in the subject--2 from gnn and 1 from you.
I'd actually read them but they were content-free so ignored them.  <24
hours later you made this commit.  Hardly a public discussion and
certainly not enough time for folks to voice disagreement.

	Sam