From owner-cvs-all@FreeBSD.ORG Sat May 27 15:33:17 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 8036516BD90 for ; Sat, 27 May 2006 15:33:17 +0000 (UTC) (envelope-from minimarmot@gmail.com) Received: from ug-out-1314.google.com (ug-out-1314.google.com [66.249.92.174]) by mx1.FreeBSD.org (Postfix) with ESMTP id AE5AD43D5F for ; Sat, 27 May 2006 15:33:14 +0000 (GMT) (envelope-from minimarmot@gmail.com) Received: by ug-out-1314.google.com with SMTP id m3so120153uge for ; Sat, 27 May 2006 08:33:13 -0700 (PDT) DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=beta; d=gmail.com; h=received:message-id:date:from:to:subject:cc:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references; b=Yaut2DV0o48dF0G8FQURD73arHu6Q2/IyAFji/IXwJD034vaIp1Gy9N8KJECRqycLbW7zYawwi0jXutxjH4BxBGI4kPT8LqLYYtawJrTIty9c5KLOFjQZZkxV5D1J4ZbiydwHk5zjwI3sg5ffRARU3YdaAsuTML2VKM/L2JhfS8= Received: by 10.67.108.27 with SMTP id k27mr431378ugm; Sat, 27 May 2006 08:27:05 -0700 (PDT) Received: by 10.67.87.3 with HTTP; Sat, 27 May 2006 08:27:05 -0700 (PDT) Message-ID: <47d0403c0605270827n665ccd5ved9ba0effccf248b@mail.gmail.com> Date: Sat, 27 May 2006 10:27:05 -0500 From: "Ben Kaduk" To: "Alexander Leidinger" In-Reply-To: <20060527123344.355119b8@Magellan.Leidinger.net> MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: quoted-printable Content-Disposition: inline References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk> <20060527123344.355119b8@Magellan.Leidinger.net> Cc: cvs-src@freebsd.org, Poul-Henning Kamp , 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 15:33:36 -0000 Alexander, On 5/27/06, Alexander Leidinger wrote: > 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 documenta= tion > > >> 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--- I have a few comments about the wording of this disclaimer. > IMPORTANT: This API documentation may contain functions which are > either public or for internal use only. Since we have not reviewed Do you mean "not public" here? > every part of the documentation yet, some internal functions are not > marked as such. Until we finished reviewing the API documentation and finish > 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 documentation and add appropriate comments to functions which are only for internal use, you should take this into account. > kernel subsystem in another kernel subsystem you better search for you should search > 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. you risk breaking 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 functio= n > > 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. > > Also, I am not certain that we should disclaim against "breaking something," but I can not think of a better admonition at the moment Thanks for putting in the work to generate Doxygen documentation. I am just starting to read the kernel code, and I feel that the call graphs, etc. that it generates will be quite helpful. -Ben Kaduk