From owner-cvs-all@FreeBSD.ORG Fri May 26 20:54:59 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 0EAE916B907; Fri, 26 May 2006 20:54:52 +0000 (UTC) (envelope-from netchild@FreeBSD.org) Received: from www.ebusiness-leidinger.de (jojo.ms-net.de [84.16.236.246]) by mx1.FreeBSD.org (Postfix) with ESMTP id A0C8843D7D; Fri, 26 May 2006 20:54:42 +0000 (GMT) (envelope-from netchild@FreeBSD.org) Received: from Andro-Beta.Leidinger.net (p54A5FC6A.dip.t-dialin.net [84.165.252.106]) (authenticated bits=0) by www.ebusiness-leidinger.de (8.13.4/8.13.4) with ESMTP id k4QKg4U8065018; Fri, 26 May 2006 22:42:06 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Received: from Magellan.Leidinger.net (Magellan.Leidinger.net [192.168.1.1]) by Andro-Beta.Leidinger.net (8.13.4/8.13.3) with ESMTP id k4QJN3Tp072670; Fri, 26 May 2006 21:23:03 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Date: Fri, 26 May 2006 21:23:04 +0200 From: Alexander Leidinger To: Sam Leffler Message-ID: <20060526212304.5eb490eb@Magellan.Leidinger.net> In-Reply-To: <447747F6.6010308@errno.com> References: <200605261806.k4QI67D3007680@repoman.freebsd.org> <447747F6.6010308@errno.com> Organization: FreeBSD X-Mailer: Sylpheed-Claws 2.2.0 (GTK+ 2.8.17; i386-portbld-freebsd7.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Virus-Scanned: by amavisd-new 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 20:55:06 -0000 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). 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