Date: Sat, 27 May 2006 10:45:39 +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: <20060527104539.1f4c0738@Magellan.Leidinger.net> In-Reply-To: <11534.1148678206@critter.freebsd.dk> References: <20060526204457.3e545e4f@Magellan.Leidinger.net> <11534.1148678206@critter.freebsd.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
Quoting "Poul-Henning Kamp" <phk@phk.freebsd.dk> (Fri, 26 May 2006 23:16:46 +0200): > In message <20060526204457.3e545e4f@Magellan.Leidinger.net>, Alexander Leidinger writes: > >Quoting "Poul-Henning Kamp" <phk@phk.freebsd.dk> (Fri, 26 May 2006 20:20:36 +0200): > > > >> In message <200605261806.k4QI67D3007680@repoman.freebsd.org>, Alexander Leiding > >> er writes: > >> > >> > This is the kernel subsystem API documentation generation framework. > >> > > >> > It uses doxygen to generate the API documentation. For each subsystem > >> > a very small (about 20 lines with comments) subsystem specific Doxyfile > >> > has to be written (have a look at the README for more). All common doxygen > >> > options are specified in a separate file. > >> > >> Now, this is all well and good, but the most critical question in > >> my mind is: how do we prevent (or alternatively: mark up) documentation > >> for functions which are not supposed to be public ? > > > >http://www.stack.nl/~dimitri/doxygen/commands.html#cmdinternal > > 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. 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. And the most important point is: what does it mean if a function is internal? Does it mean 3rd party developers are not allowed to use them, but committers are free to use it? Or does it mean nobody is allowed to use them except they are used in the same subsystem (or even only in a small part of the subsystem as specified in the docu of the functions)? I think I have to tell you about some behavior of doxygen: - by default it only includes functions with doxygen comments in the generated pages - I configured it to include even undocumented functions, since we don't have much documented ones (configurable per subsystem) - you can build docs for internal and for public use, the public one does not contain the stuff which is marked as internal (you can mark an entire function as internal, or only parts of the docs for a function) - people which look at the internal docs see which parts are public and which are internal - currently we are building the internal docs and I think we need to publish the internal ones (we're open source, we don't have trade secrets there) 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?20060527104539.1f4c0738>