From owner-cvs-src@FreeBSD.ORG Sun May 28 20:05:34 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 DFD4D16C88B; Sun, 28 May 2006 20:05:33 +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 64EAB43D58; Sun, 28 May 2006 20:05:08 +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 k4SK1aqD095602; Sun, 28 May 2006 14:01:36 -0600 (MDT) (envelope-from imp@bsdimp.com) Date: Sun, 28 May 2006 14:01:40 -0600 (MDT) Message-Id: <20060528.140140.652863809.imp@bsdimp.com> To: netchild@FreeBSD.ORG From: "M. Warner Losh" In-Reply-To: <20060528214157.71671d52@Magellan.Leidinger.net> References: <20060528123915.7fe8e278@Magellan.Leidinger.net> <20060528.131212.-1037137048.imp@bsdimp.com> <20060528214157.71671d52@Magellan.Leidinger.net> X-Mailer: Mew version 4.2 on Emacs 21.3 / Mule 5.0 (SAKAKI) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Cc: cvs-src@FreeBSD.ORG, phk@phk.freebsd.dk, src-committers@FreeBSD.ORG, rwatson@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-src@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 28 May 2006 20:05:42 -0000 In message: <20060528214157.71671d52@Magellan.Leidinger.net> Alexander Leidinger writes: : Quoting "M. Warner Losh" (Sun, 28 May 2006 13:12:12 -0600 (MDT)): : : > In message: <20060528123915.7fe8e278@Magellan.Leidinger.net> : > Alexander Leidinger writes: : > : But when we have marked the internal functions as such, we can also : > : generate an official version without the internal functions. It's just : > : a switch. But so far I think we need to include everything until a : > : subsystem is fully documented. : > : > I think we should document everything and mark the *EXTERNAL* : > functions as such. I agree with your commentary about having full : > kernel docs, and approved API subset as well. However, kernel : > functions are by default internal unless we deside otherwise. : : We can make this a 3-tier document. We can mark some functions as : @internal, some without any special markup (they are public then), and : some with some special comments/notes/whatever (we have to invent : something). : : The functions marked as @internal are only for the use in the subsystem : itself (maybe together with any other documented constraint). The : functions without any special markup can be used in other subsystems of : the kernel. And finally the special marked functions -- let's call them : EXTERNAL -- can be used by 3rd party developers. : : How does this sound? One area where we have had problems in the past is when the 2nd tier of functions changes. Many interfaces that the designer had intended to be private were used inappropriately elsewhere in the kernel. We have issues with this in vinum, many of the file system drivers, many of the tty drivers, etc. Of course, there used to be almost no documentation at all, so people just used what seemed right, despite the original author's intentions. Usually these sub-systems have well defined interfaces to each other, and other sub-systems calling in is a bad thing. Ditto with the driver <-> driver abstraction layers (tty, sound, etc). They should be using only what you call the external interfaces and nothing else. So I'm not sure how well your proposal maps to our current needs. : > : Since we have no API docs, everyone has to have a look at the kernel on : > : his own. This only provides a little bit of help here. : > : > We have api docs. Please don't say that we have none. There's a : > bunch of documentation in the man9 section of the man page. Sure, it : > is incomplete, misleading and obsolete in places, but it is : > documentation. : : Sorry... there are docs which document the API, I agree. But we don't : really have well known API documentation (as in high level overview, : what fits together how, and such). You have to know what you want to : do, then you can make use of plenty of docs. But if you don't know what : you are searching, it's not easy (maybe more easy as in linux, I don't : know, but not as easy as it could be). Again, between the handbook and the man pages we have this. It needs a lot of work, but we do have it. It shows what to do at a very rudamentary level, but you can find what you want. I'm not sure you'll ever find the high level overview in the sources. There's rarely a good place for it, and it changes with time. Warner