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]

Alexander,

On 5/27/06, Alexander Leidinger <netchild at freebsd.org> wrote:
> 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---

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

finish

> 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