Date: Fri, 26 May 2006 14:17:50 -0700 From: Sam Leffler <sam@errno.com> To: Alexander Leidinger <netchild@FreeBSD.org> 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: <4477707E.2000906@errno.com> In-Reply-To: <20060526212304.5eb490eb@Magellan.Leidinger.net> References: <200605261806.k4QI67D3007680@repoman.freebsd.org> <447747F6.6010308@errno.com> <20060526212304.5eb490eb@Magellan.Leidinger.net>
next in thread | previous in thread | raw e-mail | index | archive | help
Alexander Leidinger wrote: > 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). 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4477707E.2000906>