Quoting "M. Warner Losh" <[EMAIL PROTECTED]> (from Sun, 28 May 2006
14:01:40 -0600 (MDT)):
In message: <[EMAIL PROTECTED]>
Alexander Leidinger <[EMAIL PROTECTED]> writes:
: We can make this a 3-tier document. We can mark some functions as
: @internal, some without any special markup (they are public then), and
: some with some special comments/notes/whatever (we have to invent
: something).
:
: The functions marked as @internal are only for the use in the subsystem
: itself (maybe together with any other documented constraint). The
: functions without any special markup can be used in other subsystems of
: the kernel. And finally the special marked functions -- let's call them
: EXTERNAL -- can be used by 3rd party developers.
:
: How does this sound?
One area where we have had problems in the past is when the 2nd tier
of functions changes. Many interfaces that the designer had intended
to be private were used inappropriately elsewhere in the kernel. We
have issues with this in vinum, many of the file system drivers, many
of the tty drivers, etc. Of course, there used to be almost no
documentation at all, so people just used what seemed right, despite
the original author's intentions. Usually these sub-systems have well
defined interfaces to each other, and other sub-systems calling in is
a bad thing. Ditto with the driver <-> driver abstraction layers
(tty, sound, etc). They should be using only what you call the
external interfaces and nothing else. So I'm not sure how well your
proposal maps to our current needs.
Maybe I didn't expressed myself good enough... or we don't share the
same definition of 3rd party software.
Let's assume we have a graph of software API layers in the kernel.
Some functions (= internal) in each node in the graph are only for use
in the same node. Some functions (= public) are allowed to be used in
directly connected adjacent nodes, and some functions (= external) are
allowed to be called "from everywhere".
The "everywhere" part is a simplification, it doesn't make sense to
use the disk driver API when you write a sound driver, but it shows
what I have in mind regarding those 3 documentation levels.
: > : 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.
: >
: > We have api docs. Please don't say that we have none. There's a
: > bunch of documentation in the man9 section of the man page. Sure, it
: > is incomplete, misleading and obsolete in places, but it is
: > documentation.
:
: Sorry... there are docs which document the API, I agree. But we don't
: really have well known API documentation (as in high level overview,
: what fits together how, and such). You have to know what you want to
: do, then you can make use of plenty of docs. But if you don't know what
: you are searching, it's not easy (maybe more easy as in linux, I don't
: know, but not as easy as it could be).
Again, between the handbook and the man pages we have this. It needs
a lot of work, but we do have it. It shows what to do at a very
rudamentary level, but you can find what you want.
I'm not sure you'll ever find the high level overview in the sources.
There's rarely a good place for it, and it changes with time.
The disclaimer I committed yesterday shows up on the front page of
every API documentation. It's just a file with some C style comments
and doxygen markup. A high level overview of a subsystem can be
written the same way and included in the generated documentation. And
an overview which handles the higher level perspective of several
subsystem can be written the same way. They don't have to be
integrated into the source files, but keeping it besides the source
files is just fine IMO. It's like putting a "design
decissions"-document beneath the source files (or a readme, install
instructions, upgrade hints, whatever).
Bye,
Alexander.
--
http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID = 72077137
guru, n:
A computer owner who can read the manual.
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
