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 ...
minimarmot at gmail.com
Sat May 27 08:27:41 PDT 2006
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:
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.
> 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.
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.
More information about the cvs-src