From owner-cvs-all@FreeBSD.ORG Mon May 29 08:11:12 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 9EB6616A55E; Mon, 29 May 2006 08:11:12 +0000 (UTC) (envelope-from netchild@FreeBSD.org) Received: from www.ebusiness-leidinger.de (jojo.ms-net.de [84.16.236.246]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2F79543D62; Mon, 29 May 2006 08:11:05 +0000 (GMT) (envelope-from netchild@FreeBSD.org) Received: from Andro-Beta.Leidinger.net (p54A5FF80.dip.t-dialin.net [84.165.255.128]) (authenticated bits=0) by www.ebusiness-leidinger.de (8.13.4/8.13.4) with ESMTP id k4T8AU3o081576; Mon, 29 May 2006 10:10:31 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Received: from localhost (localhost [127.0.0.1]) by Andro-Beta.Leidinger.net (8.13.4/8.13.3) with ESMTP id k4T8AxVH065780; Mon, 29 May 2006 10:10:59 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Received: from pslux.cec.eu.int (pslux.cec.eu.int [158.169.9.14]) by webmail.leidinger.net (Horde MIME library) with HTTP; Mon, 29 May 2006 10:10:58 +0200 Message-ID: <20060529101058.obvbkq7a4gkk8o4k@netchild.homeip.net> X-Priority: 3 (Normal) Date: Mon, 29 May 2006 10:10:58 +0200 From: Alexander Leidinger To: "M. Warner Losh" References: <20060528123915.7fe8e278@Magellan.Leidinger.net> <20060528.131212.-1037137048.imp@bsdimp.com> <20060528214157.71671d52@Magellan.Leidinger.net> <20060528.140140.652863809.imp@bsdimp.com> In-Reply-To: <20060528.140140.652863809.imp@bsdimp.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8; DelSp="Yes"; format="flowed" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable User-Agent: Internet Messaging Program (IMP) H3 (4.1) / FreeBSD-4.11 X-Virus-Scanned: by amavisd-new X-Mailman-Approved-At: Mon, 29 May 2006 20:04:09 +0000 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-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: Mon, 29 May 2006 08:11:24 -0000 Quoting "M. Warner Losh" (from Sun, 28 May 2006 =20 14:01:40 -0600 (MDT)): > In message: <20060528214157.71671d52@Magellan.Leidinger.net> > Alexander Leidinger writes: > : 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. Maybe I didn't expressed myself good enough... or we don't share the =20 same definition of 3rd party software. Let's assume we have a graph of software API layers in the kernel. =20 Some functions (=3D internal) in each node in the graph are only for use =20 in the same node. Some functions (=3D public) are allowed to be used in =20 directly connected adjacent nodes, and some functions (=3D external) are =20 allowed to be called "from everywhere". The "everywhere" part is a simplification, it doesn't make sense to =20 use the disk driver API when you write a sound driver, but it shows =20 what I have in mind regarding those 3 documentation levels. > : > : 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. The disclaimer I committed yesterday shows up on the front page of =20 every API documentation. It's just a file with some C style comments =20 and doxygen markup. A high level overview of a subsystem can be =20 written the same way and included in the generated documentation. And =20 an overview which handles the higher level perspective of several =20 subsystem can be written the same way. They don't have to be =20 integrated into the source files, but keeping it besides the source =20 files is just fine IMO. It's like putting a "design =20 decissions"-document beneath the source files (or a readme, install =20 instructions, upgrade hints, whatever). Bye, Alexander. --=20 http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID =3D B0063FE7 http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID =3D 72077137 guru, n: =09A computer owner who can read the manual.