From owner-cvs-all@FreeBSD.ORG  Thu May 18 18:22:30 2006
Return-Path: <owner-cvs-all@FreeBSD.ORG>
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 F31FC16A557;
	Thu, 18 May 2006 18:22:29 +0000 (UTC) (envelope-from imp@bsdimp.com)
Received: from harmony.bsdimp.com (vc4-2-0-87.dsl.netrack.net [199.45.160.85])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 76B6143D4C;
	Thu, 18 May 2006 18:22:29 +0000 (GMT) (envelope-from imp@bsdimp.com)
Received: from localhost (localhost.village.org [IPv6:::1] (may be forged))
	by harmony.bsdimp.com (8.13.4/8.13.4) with ESMTP id k4IILMFI091622;
	Thu, 18 May 2006 12:21:22 -0600 (MDT) (envelope-from imp@bsdimp.com)
Date: Thu, 18 May 2006 12:21:22 -0600 (MDT)
Message-Id: <20060518.122122.71180479.imp@bsdimp.com>
To: phk@phk.freebsd.dk
From: Warner Losh <imp@bsdimp.com>
In-Reply-To: <39977.1147973989@critter.freebsd.dk>
References: <m2ejyrl0gd.wl%gnn@neville-neil.com>
	<39977.1147973989@critter.freebsd.dk>
X-Mailer: Mew version 3.3 on Emacs 21.3 / Mule 5.0 (SAKAKI)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=us-ascii
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: cvs commit: src Makefile.inc1 ObsoleteFiles.inc
 src/etc/defaults rc.conf src/etc/mtree BSD.usr.dist src/etc/rc.d Makefile
 isdnd pcvt syscons src/release/picobsd/build picobsd src/share/man/man4
 Makefile atkbd.4 kbdmux.4 pcvt.4 splash.4 vkbd.4 ... 
X-BeenThere: cvs-all@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: CVS commit messages for the entire tree <cvs-all.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-all>,
	<mailto:cvs-all-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/cvs-all>
List-Post: <mailto:cvs-all@freebsd.org>
List-Help: <mailto:cvs-all-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-all>,
	<mailto:cvs-all-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 18 May 2006 18:22:30 -0000

From: "Poul-Henning Kamp" <phk@phk.freebsd.dk>
Subject: Re: cvs commit: src Makefile.inc1 ObsoleteFiles.inc src/etc/defaults rc.conf src/etc/mtree BSD.usr.dist src/etc/rc.d Makefile isdnd pcvt syscons src/release/picobsd/build picobsd src/share/man/man4 Makefile atkbd.4 kbdmux.4 pcvt.4 splash.4 vkbd.4 ... 
Date: Thu, 18 May 2006 19:39:49 +0200

> In message <m2ejyrl0gd.wl%gnn@neville-neil.com>, "George V. Neville-Neil" write
> s:
> >At Thu, 18 May 2006 15:47:30 +0200,
> >Poul-Henning Kamp wrote:
> >> Part of the problem is that there will never be a "definitive kernel
> >> API manual" for FreeBSD, it will always be in flux and therefore
> >> drivers will need to be updated to keep abreast.
> >
> >I so hate to chime in on this thread, but I really think we need to
> >start putting things into the code and using Doxygen, or a moral
> >equivalent, to at least have a chance of keeping such things up to
> >date.  Someone a while back set up a proper Doxygen file for use with
> >FreeBSD and we might simply pursue that tack.
> 
> 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.  It isn't as good as carefully
hand-crafted man pages, but it is a lot better than we have now.

Warner