From owner-cvs-all@FreeBSD.ORG Sat May 27 09:37:44 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 7975416A693; Sat, 27 May 2006 09:37:44 +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 E8CFD43D5A; Sat, 27 May 2006 09:37:43 +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 k4R9bZjG069779; Sat, 27 May 2006 11:37:35 +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 k4R9bfrl067968; Sat, 27 May 2006 11:37:41 +0200 (CEST) (envelope-from netchild@FreeBSD.org) Date: Sat, 27 May 2006 11:37:43 +0200 From: Alexander Leidinger To: "Poul-Henning Kamp" Message-ID: <20060527113743.03b5a263@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-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: Sat, 27 May 2006 09:38:09 -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. I prepare something regarding this and come back to you later with an example. > Rather than aim to enable this for the entire kernel and create > showel-ware documentation of no value, why don't you start with one > subsystem which is currently being worked on and make a usable > documentation of that subsystem ? > > >And the most important point is: what does it mean if a function is > >internal? > > It means that the function should not be called outside the subsystem > it is part of. > > To take an example: g_run_events() is not static, but it should be > called only from one single place and there will never be a reason > to call it from anywhere else. > > There is no automatic way to make this determination, you need somebody > to look at each and every function to decide it. That's the same way I think about @internal. > So until somebody explicitly decides otherwise on a function by function > bases, all functions should either be excluded or marked internal > automatically. You got already a response for this, but wait for my example which will hopefully address your concerns. 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