Alexander,
On 5/27/06, Alexander Leidinger <[EMAIL PROTECTED]> wrote:
Quoting "Poul-Henning Kamp" <[EMAIL PROTECTED]> (Sat, 27 May 2006 10:57:04
+0200):
> In message <[EMAIL PROTECTED]>, 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
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
