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 ...

[Alexander Leidinger]

Quoting "Poul-Henning Kamp" <phk at phk.freebsd.dk> (Fri, 26 May 2006 23:16:46 +0200):

> In message <20060526204457.3e545e4f at Magellan.Leidinger.net>, Alexander Leidinger writes:
> >Quoting "Poul-Henning Kamp" <phk at phk.freebsd.dk> (Fri, 26 May 2006 20:20:36 +0200):
> >
> >> In message <200605261806.k4QI67D3007680 at 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