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 ...

[Alexander Leidinger]

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).

Bye,
Alexander.

-- 
Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR
you have to pick it up between Germany/Saarland and Luxembourg/Capellen
http://www.Leidinger.net    Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org       netchild @ FreeBSD.org  : PGP ID = 72077137