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

[Alexander Leidinger]

Quoting Robert Watson <rwatson at FreeBSD.org> (Sat, 27 May 2006 20:09:54 +0100 (BST)):

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

Not documented functions are not included in the doxygen output by
default. I've changed this default since we have nearly no documented
function. If we switch back to the default, you get what you want, but
it's not helpful anymore (for e.g. our SoC students or anyone else who
wants to help improving the kernel).

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

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

Bye,
Alexander.

-- 
Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR
you have to pick it up between Germany/Saarland and Luxembourg/Capellen
http://www.Leidinger.net    Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org       netchild @ FreeBSD.org  : PGP ID = 72077137