From owner-cvs-all@FreeBSD.ORG Sat May 27 16:48:21 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 BD30116C2B6; Sat, 27 May 2006 16:48:21 +0000 (UTC) (envelope-from scottl@samsco.org) Received: from pooker.samsco.org (pooker.samsco.org [168.103.85.57]) by mx1.FreeBSD.org (Postfix) with ESMTP id E0A3443D48; Sat, 27 May 2006 16:48:18 +0000 (GMT) (envelope-from scottl@samsco.org) Received: from [192.168.254.14] (imini.samsco.home [192.168.254.14]) (authenticated bits=0) by pooker.samsco.org (8.13.4/8.13.4) with ESMTP id k4RGmBR7049884; Sat, 27 May 2006 10:48:16 -0600 (MDT) (envelope-from scottl@samsco.org) Message-ID: <447882CB.8020003@samsco.org> Date: Sat, 27 May 2006 10:48:11 -0600 From: Scott Long User-Agent: Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.7.7) Gecko/20050416 X-Accept-Language: en-us, en MIME-Version: 1.0 To: Poul-Henning Kamp References: <13817.1148720224@critter.freebsd.dk> In-Reply-To: <13817.1148720224@critter.freebsd.dk> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-1.4 required=3.8 tests=ALL_TRUSTED autolearn=failed version=3.1.1 X-Spam-Checker-Version: SpamAssassin 3.1.1 (2006-03-10) on pooker.samsco.org Cc: cvs-src@FreeBSD.org, src-committers@FreeBSD.org, Alexander Leidinger , 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 16:48:41 -0000 Poul-Henning Kamp wrote: > 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. > > 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. > > So until somebody explicitly decides otherwise on a function by function > bases, all functions should either be excluded or marked internal > automatically. > All very good points. Unfortunately, the very nature of open source means that people will go treading into non-APIs if they think that it helps them solve a problem. I have a long list of 3rd party drivers that do exactly this; calling MD routines in order to grub around in the BIOS, hijacking CAM internals because the correct API wasn't clear, etc. Whether a non-API appears is doxygen or not is irrelevant, an industrious developer will find it anyways. Scott