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

Ben Kaduk minimarmot at
Sat May 27 08:27:41 PDT 2006


On 5/27/06, Alexander Leidinger <netchild at> wrote:
> Quoting "Poul-Henning Kamp" <phk at> (Sat, 27 May 2006 10:57:04 +0200):
> > In message <20060527104539.1f4c0738 at>, 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
> for more), I want to
> go a different approach.
> At 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


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

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

More information about the cvs-src mailing list