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

Poul-Henning Kamp phk at phk.freebsd.dk
Sat May 27 01:57:20 PDT 2006


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.

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.

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe    
Never attribute to malice what can adequately be explained by incompetence.


More information about the cvs-src mailing list