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 Sun, 28 May 2006, Alexander Leidinger wrote:

<snip: display only documented by default, disclaimer, etc>

Sounds good.

>>> 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.
>
> Scott already commented why this doesn't matter in a different branch of 
> this discussion. So I don't comment on this part of the above paragraph.
>
> I think this documentation is for (junior) kernel developers in the 
> beginning. And as long as we document which parts of the API are for 3rd 
> party developers (either my marking other parts as internal, or by adding a 
> sentence that a particular function is part of the API which 3rd party 
> developers are allowed to use), we can ship even with every other part of 
> the kernel-docs visible (it doesn't matter according to Scott, and I agree). 
> This way a 3rd party developer is able to get the big picture and maybe 
> understand ambiguous parts of the API better. If hi then decides to use 
> internal functions, he isn't allowed to moan (and as Scott said he probably 
> would have done it even when we don't include the internal API in the docs).
>
> But when we have marked the internal functions as such, we can also generate 
> an official version without the internal functions. It's just a switch. But 
> so far I think we need to include everything until a subsystem is fully 
> documented.
>
> Since we have no API docs, everyone has to have a look at the kernel on his 
> own. This only provides a little bit of help here.

If we agree this is documentation for people working on the kernel rather than 
documentation for people programming third party components intended to plug 
into our plug-in interfaces, then this is all good.

The goal of providing well-defined plug-in interfaces isn't to prevent a third 
party developer from shooting their feet -- after all, they are running code 
in the kernel address space.  The goal is to help them not shoot their feet in 
the event they are not trying to do so.  We do this by documenting what 
interfaces they should use, and telling them that if they use these 
interfaces, we will try to avoid shooting their feet for them.

>> 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!
>
> Yes. I agree. And until we documented which functions form the official API 
> and which ones are internal, we should tell 3rd party developers about this 
> as proposed in another branch of this thread. See 
> http://www.leidinger.net/FreeBSD/doxygen_notreviewed.png for an example.

I like the way this appears.

>> 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.
>
> Since we are Open Source they can have a look and use unofficial parts 
> without our docs. But when we clearly say "this is for internal use only", 
> they can't moan. And we as developers have a benefit from the docs too.

Exactly.  But I do think we should provide separate explicitly documentation 
for APIs intended to be consumed by third parties.

Robert N M Watson