Poul-Henning Kamp wrote:
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.
Rather than aim to enable this for the entire kernel and create
showel-ware documentation of no value, why don't you start with one
subsystem which is currently being worked on and make a usable
documentation of that subsystem ?
And the most important point is: what does it mean if a function is
internal?
It means that the function should not be called outside the subsystem
it is part of.
To take an example: g_run_events() is not static, but it should be
called only from one single place and there will never be a reason
to call it from anywhere else.
There is no automatic way to make this determination, you need somebody
to look at each and every function to decide it.
So until somebody explicitly decides otherwise on a function by function
bases, all functions should either be excluded or marked internal
automatically.
All very good points. Unfortunately, the very nature of open source
means that people will go treading into non-APIs if they think that it
helps them solve a problem. I have a long list of 3rd party drivers
that do exactly this; calling MD routines in order to grub around in
the BIOS, hijacking CAM internals because the correct API wasn't clear,
etc. Whether a non-API appears is doxygen or not is irrelevant, an
industrious developer will find it anyways.
Scott
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
