improving documentation? (was Re: Kernel documentation and
specification)
Derek VerLee
bsd at noogenesis.org
Sun Apr 3 01:35:45 PST 2005
klowd9 - wrote:
> Why isnt a free copy of this book available online? The author
> obviously put alot of time and effort into making this excellent book,
> but so do thousands of other people writing code and papers every day,
> published freely on the internet, and they ask for nothing in return,
> besides perhaps, some gratitude
I'd have a look at the articals in gnu.org/philosophy on these
(important) issues. I reread them myself recently and there is some
really intresting stuff. To quote roughly, free software means free as
in free from prison not free as in free beer. Its in the core
philosophy of freebsd and linux alike to open possibilities, including
making money, for people and society as a whole.
--
However on the topic of documentation of the BSD internals, I too think
that they are lacking. I've been studing the source and reading said
book (I bought it the second I noticed it on the shelf, despite its
price), and the book is pretty good at giving one an understanding of
how the system works. Which is a crucial first step, and saves time
over figuring it out by looking at the source.
However I've been thinking about this as I've been studing the
schedulars (_4bsd and _ule) and it has struck me that, though they both
implement the same public interface (sched.h), most functions are not
even described, much less is there a proper sort of preconditions or
postconditions, or any other such documentation.
A little background story: As I posted in -stable a little while ago, i
have tested sched_ule (known to be broken) on a dual athlon with SMP
both on and off, and with sched_4bsd, with SMP on. sched_ule runs ok
with SMP compiled out. However, sched_ule+SMP causes hangs. Pretty
much the only thing changed by the kernel option sched_ule is which .c
file is compiled to implement sched.h, so it stands to reason that the
clue to the bug (unless its something in my hardware) is in sched_ule.c,
in other words, what is the difference between _ule.c and _4bsd.c that
causes _ule.c to hang when SMP is on?
Well for me to help with fixing this bug (and admittedly i should
probably be join the freebsd efforts with something simpler or higher
priority, but i became intrested in this and one has to start with
something) it'd help a lot to know the pre and post conditions for each
function. Right now, the only people who know that are the 'elite few'
who have worked on this portion or related portions of the kernel for a
while, that is, if _anybody_ knows this. And here's my point: with out
it clearly written out, how can we be sure that anyone even has a clear
conception of these things in their own minds, much less having the same
ideas between everyone who uses and depends on these functions?
I'm not here to waltz into a massive project (the freebsd kernel) and
start pointing out things that could be changed before I even take my
shoe off. This isn't even critisim, I'm just saying what I see. The
freebsd source code is very clean and easy to follow, and it contains at
least as much, probably more, documentation then average. I don't know
of any programmer who likes to document their code as much as they like
writing it, and most (myself included most of the time) just like to add
a comment here or there that begrudgingly gives a nod to the concept of
documentation and then move on. Also, this isn't going to change, so
I'm not going to suggest that it does.
What I do think could be constructive is a discussion of developing a
system or project that realistically could improve the documentation and
specification of the freebsd system internals. I'm sure most of you are
aware of the benifits of documentation and specification in a project,
so I'm not going to go into them except to point out that it'd not only
make it easier to enter the project and help out, but also, I think,
greatly improve the ability to notice and find bugs, or prevent them,
etc. (If there is some technical or cultural reasons why this isn't
totally true, well, that's why I'm here to learn.)
To start the discussion, I was thinking of something like this:
*A collection of specification, documentation, or any sort of comments
outside of what is commented on directly in the code, maintained by
project commiters.
*Each document could be, optionally, associated with the cvs version of
a source file to which it proports to apply, and whether to the whole
document or a range of lines. Also, parts of the document could "link"
to other documents, parts of other documents, line numbers within a
source file or document, etc.
*the documentation format could include embedded objects like, for
example, the xml description of a UML graph.
*there be an agreed upon set of formal specification languages (in
addition to plain old natural language) available for use, as well as a
repository of freebsd specific extensions. (I like Abstract State
Machines myself) It is my experiance that its very good to use more
then one specification language so long as they have different
aproaches, but not to have two which cover a lot of common use.
*users who are not commiters could add forum style comments to any given
document, probably through a web interface, which hopefully wouldn't
have to be too moderated. This way people could easily raise issues,
make requests, point out flaws, or most importantly, record little
tidbits of wisdom they have gained about the subject through experiance.
*hopefully the system works with and is complemented by whatever various
automated documentation tools that are found useful.
Sorry for the verbosity.
_Derek
More information about the freebsd-hackers
mailing list