Date: Tue, 23 Apr 2002 18:36:59 -0400 (EDT) From: Chris BeHanna <behanna@zbzoom.net> To: FreeBSD-Stable <stable@freebsd.org> Cc: freebsd-current@freebsd.org Subject: Re: FreeBSD 4.5-STABLE not easily scalable to large servers ... ? Message-ID: <20020423182536.N72471-100000@topperwein.dyndns.org> In-Reply-To: <200204232020.g3NKKJb38154@hokkshideh2.jetcafe.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 23 Apr 2002, Dave Hayes wrote:
> Terry Lambert (who fits my arbitrary definition of a "good" cynic)
> writes:
> > It's a hazard of Open Source projects, in general, that there are
> > so many people hacking on whatever they think is cool that nothing
> > ever really gets built to a long term design plan that's stable
> > enough that a book stands a chance of having a 1 year lifetime.
>
> I could not help but notice your multiple attempts at expresing this
> particular concept often, that is...an implied necessity of a book
> that explains what's going on under the kernel hood. I agree that such
> a book would rapidly be out of date, but I also see the necessity
> thereof.
>
> So, it's time to question the assumption that the information you want
> available should be in "a book".
>
> Many websites have "annotation" as a form of ad-hoc documentation
> (e.g. php.net). Why not have someone take a crack at documenting the
> FreeBSD kernel, and perhaps use some annotation feature to create a
> "living" document which (hopefully) comes close to describing the
> kernel architechture?
>
> If you want to track a moving target, perhaps you need to use a moving
> track?
doxygen is *wonderful* for this for large C++ projects: it's able
to draw you inheritance graphs and collaboration diagrams, as well as
generate pretty, nicely formatted HTML containing API descriptions
generated from javadoc-like comments in header files.
I've never tried it on straight C. I suppose it is possible, but
given the lack of inheritance, collaboration diagrams are going to
be very messy.
Still and all, it might be a very useful thing. If not doxygen,
then perhaps some way to run the headers through jade/sgmlformat, with
docbook-style SGML embedded in comments in header files describing
kernel API calls and their parameters, with all typedef'd datatypes
appropriately cross-linked. As a hack, one could even <gulp> embed
POD within comments and run perldoc on everything. This could be done
nightly or twice daily, with updates appearing live at freebsd.org.
HTML versions of man pages with crosslinks go part of the way; what
I'm thinking about (if any of you have used doxygen you'll know where
I'm going) is a bit more comprehensive, with links to the actual
header file from which the documentation was generated, so that the
reader can see the declaration in its native context (with the doxygen
or docbook comments stripped out for clarity).
This still wouldn't address the need for some kind of overall
architectural document, as well as the difficulty of keeping it
up-to-date, but it would be of tremendous help to everyone working on
the project. *If* developers can get used to updating the in-comment
documentation whenever they make changes, then this reference would
automatically be kept up-to-date.
--
Chris BeHanna
Software Engineer (Remove "bogus" before responding.)
behanna@bogus.zbzoom.net
I was raised by a pack of wild corn dogs.
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020423182536.N72471-100000>