Date: Fri, 26 May 2006 21:23:04 +0200 From: Alexander Leidinger <netchild@FreeBSD.org> To: Sam Leffler <sam@errno.com> Cc: cvs-src@FreeBSD.org, src-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: 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 ... Message-ID: <20060526212304.5eb490eb@Magellan.Leidinger.net> In-Reply-To: <447747F6.6010308@errno.com> References: <200605261806.k4QI67D3007680@repoman.freebsd.org> <447747F6.6010308@errno.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Quoting Sam Leffler <sam@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060526212304.5eb490eb>