From owner-cvs-all@FreeBSD.ORG Thu May 18 18:31:54 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 238D316A5A1; Thu, 18 May 2006 18:31:54 +0000 (UTC) (envelope-from frank@exit.com) Received: from tinker.exit.com (tinker.exit.com [206.223.0.1]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3B82743DAE; Thu, 18 May 2006 18:31:16 +0000 (GMT) (envelope-from frank@exit.com) Received: from realtime.exit.com (realtime [206.223.0.5]) by tinker.exit.com (8.13.4/8.13.4) with ESMTP id k4IIV5m8029300; Thu, 18 May 2006 11:31:05 -0700 (PDT) (envelope-from frank@exit.com) Received: from realtime.exit.com (localhost [127.0.0.1]) by realtime.exit.com (8.13.6/8.13.6) with ESMTP id k4IIV4cR077253; Thu, 18 May 2006 11:31:05 -0700 (PDT) (envelope-from frank@exit.com) Received: (from frank@localhost) by realtime.exit.com (8.13.6/8.13.6/Submit) id k4IIV35O077252; Thu, 18 May 2006 11:31:03 -0700 (PDT) (envelope-from frank@exit.com) X-Authentication-Warning: realtime.exit.com: frank set sender to frank@exit.com using -f From: Frank Mayhar To: Warner Losh In-Reply-To: <20060518.122122.71180479.imp@bsdimp.com> References: <39977.1147973989@critter.freebsd.dk> <20060518.122122.71180479.imp@bsdimp.com> Content-Type: text/plain Content-Transfer-Encoding: 7bit Organization: Exit Consulting Date: Thu, 18 May 2006 11:31:03 -0700 Message-Id: <1147977063.76767.8.camel@realtime.exit.com> Mime-Version: 1.0 X-Mailer: Evolution 2.6.1 FreeBSD GNOME Team Port X-Virus-Scanned: ClamAV 0.88/1468/Thu May 18 07:48:03 2006 on tinker.exit.com X-Virus-Status: Clean Cc: src-committers@freebsd.org, cvs-src@freebsd.org, gnn@neville-neil.com, cvs-all@freebsd.org, phk@phk.freebsd.dk, 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 Reply-To: frank@exit.com List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 18 May 2006 18:32:23 -0000 [Doxygen] Once upon a time, Back In The Day(tm), I worked on a mainframe OS called CP6. CP6 had a lot of cool attributes, but the one that is relevant here is that we kept our entire API documentation (including multiple levels of error messages) in the code itself. Every distinct type of documentation had a special comment-code (like, for example, /*E* to start an error message block) and we had a munger that would crawl the source, extract the marked commentary and assemble it into a formatted manual. A tech writer wrote the introduction and a few other things, but those tended to remain static with only minor tweaks from release to release. The really big changes were done in the marked commentary by the developers involved. It worked, but of course it required discipline, both personal and imposed. That's the tricky part in an all-volunteer effort. -- Frank Mayhar frank@exit.com http://www.exit.com/ Exit Consulting http://www.gpsclock.com/ http://www.exit.com/blog/frank/