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
rwatson at FreeBSD.org
Sat May 27 12:10:39 PDT 2006
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
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
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
More information about the cvs-src