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> (Sat, 27 May 2006 10:57:04 +0200):

> In message <20060527104539.1f4c0738 at 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