From owner-cvs-all@FreeBSD.ORG Sun May 28 13:08:32 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 3D79316A54B; Sun, 28 May 2006 13:08:32 +0000 (UTC) (envelope-from rwatson@FreeBSD.org) Received: from cyrus.watson.org (cyrus.watson.org [209.31.154.42]) by mx1.FreeBSD.org (Postfix) with ESMTP id C9E7743D46; Sun, 28 May 2006 13:08:31 +0000 (GMT) (envelope-from rwatson@FreeBSD.org) Received: from fledge.watson.org (fledge.watson.org [209.31.154.41]) by cyrus.watson.org (Postfix) with ESMTP id 1D01D46C73; Sun, 28 May 2006 09:08:31 -0400 (EDT) Date: Sun, 28 May 2006 14:08:31 +0100 (BST) From: Robert Watson X-X-Sender: robert@fledge.watson.org To: Alexander Leidinger In-Reply-To: <20060528150353.094da5b8@Magellan.Leidinger.net> Message-ID: <20060528140604.J79162@fledge.watson.org> References: <20060526204457.3e545e4f@Magellan.Leidinger.net> <11534.1148678206@critter.freebsd.dk> <20060527104539.1f4c0738@Magellan.Leidinger.net> <20060527200440.G79162@fledge.watson.org> <20060528150353.094da5b8@Magellan.Leidinger.net> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: gnn@FreeBSD.org, Poul-Henning Kamp , src-committers@FreeBSD.org, cvs-all@FreeBSD.org, cvs-src@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: Sun, 28 May 2006 13:08:32 -0000 On Sun, 28 May 2006, Alexander Leidinger wrote: > Quoting gnn@FreeBSD.org (Sun, 28 May 2006 11:12:19 +0900): > >> Am I allowed to call this a tempest in a teacup? >> >> There, I just have. >> >> While I think that there have been some very good points made both ways, I >> believe that since the documentation will be generated only by people who >> are using the system, and will not appear on line, or in a manual, that we >> do not need to worry about this. It is, IMHO, easier > > As Scott already said: it doesn't matter if it is made public or not. "The > bad guys"(TM) will use non-public functions regardless. I think the bad guys concept is a red herring. Not even having the source code matters for bad guys -- there's some darn evil code that runs on entirely closed source platforms and run-time patches kernels. This code is by necessity very fragile, and the vendors of those closed source systems work hard to try and convince people to use published APIs, and add APIs to try and facilitate it. Otherwise they risk one of the Evil Apps hitting the Critical Must Support List, and leaving them stuck for how to change the kernel in the future. Presumably, what matters to us is making it clear what APIs (structures, etc) are intended for "external" use -- i.e., use that doesn't closely track internal development. It's seeming to me more and more like we should consider Doxygen an "internal" use tool, label it as such, and not try to use it as documentation for developers programming to plug-in interfaces. Robert N M Watson