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

[Robert Watson]

On Sat, 27 May 2006, Alexander Leidinger wrote:

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

This sounds very worrying.

> 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.
>
> And the most important point is: what does it mean if a function is 
> internal? Does it mean 3rd party developers are not allowed to use them, but 
> committers are free to use it? Or does it mean nobody is allowed to use them 
> except they are used in the same subsystem (or even only in a small part of 
> the subsystem as specified in the docu of the functions)?

Who is this documentation for?  If it's for us, then it should document 
everything.  But if it's for third party developers, it certainly should not 
document everything.  Over the last few years, we've been informally working 
to refine the set of functions and symbols depended on by device drivers, and 
on several occasions we've had discussions about taking this much more 
seriously.

If you want an example of one way to approach this, take a look at Apple's KPI 
drive.  They explicitly document which functions, data structures, 
definitions, etc, may be depended on by drivers of particular types.  This 
helps to eliminate ABI breakage across versions, allowing device drivers to 
work on many versions of Mac OS X.  As a general rule, third party code should 
only use documented KPIs, or it will risk getting broken due to API changes 
(and no longer compile) or due to ABI changes (where the code compiles but may 
corrupt kernel data structures).  If we want to support third party device 
driver vendors better, we need to take this issue more seriously.  For that 
matter, if we even want books on how to write device drivers, we need to take 
it seriously!

So if this is documentation for use by developers modifying the code without a 
concern about APIs and ABIs changing, this is fine.  But it cannot be 
documentation for third party developers writing to any of our 
pluggable/loadable interfaces in its current form, because that documentation 
is by definition exclusive, not inclusive -- things should only appear in it 
when explicitly intended to be there.

Robert N M Watson