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
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
