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

[Scott Long]

Poul-Henning Kamp wrote:

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

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