Date: Sat, 27 May 2006 10:27:05 -0500 From: "Ben Kaduk" <minimarmot@gmail.com> To: "Alexander Leidinger" <netchild@freebsd.org> Cc: cvs-src@freebsd.org, Poul-Henning Kamp <phk@phk.freebsd.dk>, 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 ... Message-ID: <47d0403c0605270827n665ccd5ved9ba0effccf248b@mail.gmail.com> In-Reply-To: <20060527123344.355119b8@Magellan.Leidinger.net> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk> <20060527123344.355119b8@Magellan.Leidinger.net>
next in thread | previous in thread | raw e-mail | index | archive | help
Alexander, On 5/27/06, Alexander Leidinger <netchild@freebsd.org> wrote: > Quoting "Poul-Henning Kamp" <phk@phk.freebsd.dk> (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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?47d0403c0605270827n665ccd5ved9ba0effccf248b>