From owner-cvs-all@FreeBSD.ORG Sun May 28 19:42:01 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 1DCCB16A50A; Sun, 28 May 2006 19:42:01 +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 198D443D53; Sun, 28 May 2006 19:41:59 +0000 (GMT) (envelope-from netchild@FreeBSD.org) Received: from Andro-Beta.Leidinger.net (p54A5F984.dip.t-dialin.net [84.165.249.132]) (authenticated bits=0) by www.ebusiness-leidinger.de (8.13.4/8.13.4) with ESMTP id k4SJfVVl078508; Sun, 28 May 2006 21:41:32 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Received: from Magellan.Leidinger.net (Magellan.Leidinger.net [192.168.1.1]) by Andro-Beta.Leidinger.net (8.13.4/8.13.3) with ESMTP id k4SJfr6d059097; Sun, 28 May 2006 21:41:54 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Date: Sun, 28 May 2006 21:41:57 +0200 From: Alexander Leidinger To: "M. Warner Losh" Message-ID: <20060528214157.71671d52@Magellan.Leidinger.net> In-Reply-To: <20060528.131212.-1037137048.imp@bsdimp.com> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <20060527200440.G79162@fledge.watson.org> <20060528123915.7fe8e278@Magellan.Leidinger.net> <20060528.131212.-1037137048.imp@bsdimp.com> Organization: FreeBSD X-Mailer: Sylpheed-Claws 2.2.0 (GTK+ 2.8.17; i386-portbld-freebsd7.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Virus-Scanned: by amavisd-new 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: Sun, 28 May 2006 19:42:05 -0000 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? > : 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). Bye, Alexander. -- Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR you have to pick it up between Germany/Saarland and Luxembourg/Capellen http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID = B0063FE7 http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID = 72077137