Date: Sun, 03 Apr 2005 04:35:43 -0500 From: Derek VerLee <bsd@noogenesis.org> To: klowd9 - <klowd92@hotmail.com> Cc: freebsd-hackers@FreeBSD.org Subject: improving documentation? (was Re: Kernel documentation and specification) Message-ID: <424FB8EF.3080204@noogenesis.org> In-Reply-To: <BAY10-F26231E2731D0B73B2E9E00BF400@phx.gbl> References: <BAY10-F26231E2731D0B73B2E9E00BF400@phx.gbl>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?424FB8EF.3080204>