From owner-cvs-src@FreeBSD.ORG Fri May 19 11:15:04 2006 Return-Path: X-Original-To: cvs-src@FreeBSD.org Delivered-To: cvs-src@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 06CD016A420; Fri, 19 May 2006 11:15:03 +0000 (UTC) (envelope-from babkin@verizon.net) Received: from vms042pub.verizon.net (vms042pub.verizon.net [206.46.252.42]) by mx1.FreeBSD.org (Postfix) with ESMTP id AF40343D45; Fri, 19 May 2006 11:15:03 +0000 (GMT) (envelope-from babkin@verizon.net) Received: from vms168.mailsrvcs.net ([192.168.1.1]) by vms042.mailsrvcs.net (Sun Java System Messaging Server 6.2-4.02 (built Sep 9 2005)) with ESMTPA id <0IZI00JEHF8YXK32@vms042.mailsrvcs.net>; Fri, 19 May 2006 06:14:58 -0500 (CDT) Date: Fri, 19 May 2006 06:14:58 -0500 (CDT) From: Sergey Babkin To: Warner Losh , phk@phk.freebsd.dk Message-id: <16489295.8854801148037298444.JavaMail.root@vms168.mailsrvcs.net> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7bit Cc: src-committers@FreeBSD.org, cvs-src@FreeBSD.org, gnn@neville-neil.com, cvs-all@FreeBSD.org, julian@elischer.org, hellmuth.michaelis@t-online.de Subject: Re: Re: cvs commit: src Makefile.inc1 ObsoleteFiles.inc src/etc/defaults rc.conf X-BeenThere: cvs-src@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: babkin@users.sf.net List-Id: CVS commit messages for the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 19 May 2006 11:15:04 -0000 >From: Warner Losh >> In message <20060518.122122.71180479.imp@bsdimp.com>, Warner Losh writes: >> >> >> I've not been very impressed with what I've seen from sources using >> >> this approach, but I guess having the prototypes with one line >> >> comments is better than nothing. >> > >> >Doxygen does more than one line, and you get out of it the effort that >> >you put into it as far as quality goes. >> >> That was sort of what I hinted at: most places I've seen don't seem >> to have the follow-through to actually get more than the prototypes >> out. > >Yes. It takes everyone pulling together to make it work. Doxygen is definitely beffer than nothing but not a replacement for proper man pages either. I've had experience with this kind of documentation in Qt, and it gives some idea of what is happening inside the function but always leaves enough mystery. The part that is missing is the big picture of how these functions are intended to work together. -SB