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.) [EMAIL PROTECTED] I was raised by a pack of wild corn dogs. To Unsubscribe: send mail to [EMAIL PROTECTED] with "unsubscribe freebsd-current" in the body of the message