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