From owner-cvs-all@FreeBSD.ORG Fri May 26 21:18:14 2006 Return-Path: X-Original-To: cvs-all@FreeBSD.org Delivered-To: cvs-all@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4376216A7AE; Fri, 26 May 2006 21:18:14 +0000 (UTC) (envelope-from sam@errno.com) Received: from ebb.errno.com (ebb.errno.com [69.12.149.25]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0560943D60; Fri, 26 May 2006 21:17:51 +0000 (GMT) (envelope-from sam@errno.com) Received: from [10.0.0.248] (trouble.errno.com [10.0.0.248]) (authenticated bits=0) by ebb.errno.com (8.13.6/8.12.6) with ESMTP id k4QLHoWU090675 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 26 May 2006 14:17:51 -0700 (PDT) (envelope-from sam@errno.com) Message-ID: <4477707E.2000906@errno.com> Date: Fri, 26 May 2006 14:17:50 -0700 From: Sam Leffler User-Agent: Thunderbird 1.5.0.2 (X11/20060508) MIME-Version: 1.0 To: Alexander Leidinger References: <200605261806.k4QI67D3007680@repoman.freebsd.org> <447747F6.6010308@errno.com> <20060526212304.5eb490eb@Magellan.Leidinger.net> In-Reply-To: <20060526212304.5eb490eb@Magellan.Leidinger.net> X-Enigmail-Version: 0.94.0.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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 ... X-BeenThere: cvs-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 26 May 2006 21:18:23 -0000 Alexander Leidinger wrote: > Quoting Sam Leffler (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