Date: Sat, 27 May 2006 12:33:44 +0200 From: Alexander Leidinger <netchild@FreeBSD.org> To: "Poul-Henning Kamp" <phk@phk.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 ... Message-ID: <20060527123344.355119b8@Magellan.Leidinger.net> In-Reply-To: <13817.1148720224@critter.freebsd.dk> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
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 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. 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--- IMPORTANT: This API documentation may contain functions which are either public or for internal use only. Since we have not reviewed every part of the documentation yet, some internal functions are not marked as such. Until we finished reviewing the API documentation and 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 kernel subsystem in another kernel subsystem you better search for 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. ---snip--- The PDF version contains the same text. Improvements to the text are welcome. > So until somebody explicitly decides otherwise on a function by function > 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. -- 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060527123344.355119b8>