From owner-cvs-all@FreeBSD.ORG Sat May 27 08:57:14 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 4040616B20F; Sat, 27 May 2006 08:57:14 +0000 (UTC) (envelope-from phk@critter.freebsd.dk) Received: from pfepc.post.tele.dk (pfepc.post.tele.dk [195.41.46.237]) by mx1.FreeBSD.org (Postfix) with ESMTP id 72C2743D67; Sat, 27 May 2006 08:57:08 +0000 (GMT) (envelope-from phk@critter.freebsd.dk) Received: from critter.freebsd.dk (0x50a07cfc.naenxx7.adsl-dhcp.tele.dk [80.160.124.252]) by pfepc.post.tele.dk (Postfix) with ESMTP id B67868A000E; Sat, 27 May 2006 10:57:06 +0200 (CEST) Received: from critter.freebsd.dk (localhost [127.0.0.1]) by critter.freebsd.dk (8.13.6/8.13.6) with ESMTP id k4R8v4gN013818; Sat, 27 May 2006 10:57:04 +0200 (CEST) (envelope-from phk@critter.freebsd.dk) To: Alexander Leidinger From: "Poul-Henning Kamp" In-Reply-To: Your message of "Sat, 27 May 2006 10:45:39 +0200." <20060527104539.1f4c0738@Magellan.Leidinger.net> Date: Sat, 27 May 2006 10:57:04 +0200 Message-ID: <13817.1148720224@critter.freebsd.dk> Sender: phk@critter.freebsd.dk 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 08:57:20 -0000 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. -- Poul-Henning Kamp | UNIX since Zilog Zeus 3.20 phk@FreeBSD.ORG | TCP/IP since RFC 956 FreeBSD committer | BSD since 4.3-tahoe Never attribute to malice what can adequately be explained by incompetence.