From owner-cvs-src@FreeBSD.ORG Sat May 27 10:33:46 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 D597B16A549; Sat, 27 May 2006 10:33:46 +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 50C9643D4C; Sat, 27 May 2006 10:33:45 +0000 (GMT) (envelope-from netchild@FreeBSD.org) Received: from Andro-Beta.Leidinger.net (p54A5CD3E.dip.t-dialin.net [84.165.205.62]) (authenticated bits=0) by www.ebusiness-leidinger.de (8.13.4/8.13.4) with ESMTP id k4RAXa2n069963; Sat, 27 May 2006 12:33:37 +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 k4RAXg4A075961; Sat, 27 May 2006 12:33:42 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Date: Sat, 27 May 2006 12:33:44 +0200 From: Alexander Leidinger To: "Poul-Henning Kamp" Message-ID: <20060527123344.355119b8@Magellan.Leidinger.net> In-Reply-To: <13817.1148720224@critter.freebsd.dk> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk> 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, src-committers@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: Sat, 27 May 2006 10:33:51 -0000 Quoting "Poul-Henning Kamp" (Sat, 27 May 2006 10:57:04 +0200): > In message <20060527104539.1f4c0738@Magellan.Leidinger.net>, Alexander Leidinger writes: > > >> Can we agree that no functions will be put into publicized documentation > >> until somebody has considered if the function actually is a public > >> function or not ? > > > >Does this mean you want to have everything marked as "@internal" by > >default? I don't think there's a switch which does this, so you would > >have to mark every function with @internal by hand. > > Yes, until somebody decides otherwise. > > We do not want all non-static kernel functions become published APIs > by default. > > >What about adding a comment to the pages which tells everyone that we > >are working on this documentation and so far we haven't reviewed every > >function and decided if it is an internal one or not. > > I don't think the documentation should be published before it reaches > a certain level of quality. "Not including random stuff" would be > a sensible first goal-post. Since there's not only API documentation but also some graphs (include, call, caller, ... see http://www.stack.nl/~dimitri/doxygen/diagrams.html for more), I want to go a different approach. At http://www.leidinger.net/FreeBSD/doxygen_notreviewed.png I have a screenshot of the the index page of the HTML documentation. It shows the following text in a very prominent position: ---snip--- IMPORTANT: This API documentation may contain functions which are either public or for internal use only. Since we have not reviewed every part of the documentation yet, some internal functions are not marked as such. Until we finished reviewing the API documentation and augmented functions for internal use with appropriate comments you have to take this into account. In case you want to use a function of this kernel subsystem in another kernel subsystem you better search for precedence of use outside this subsystem. If the function is not used outside this subsystem you should ask on the mailinglists about it, else you risk to break something. ---snip--- The PDF version contains the same text. Improvements to the text are welcome. > So until somebody explicitly decides otherwise on a function by function > bases, all functions should either be excluded or marked internal > automatically. AFAIK marking them as internal is not possible automatically. So I propose the above. Currently we have no indication about internal functions at all. Publishing the doxygen generated docs together with this text at least gives a hint to everyone, that they are not allowed to use every function. 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