| |||||||||||||
Kernel Documentation FantasyKernel Documentation FantasyPosted Nov 27, 2003 2:49 UTC (Thu) by utoddl (subscriber, #1232)In reply to: Kernel Documentation Fantasy by iabervon Parent article: Review: Linux Kernel Development
Caveat: I've done very little literate programming -- a couple of toy projects that were one-offs just to see what it looked like. It was fun. It was also a lot of work up front. I'll therefore take your comments at face value and consider that there is a core truth there. But to your specific points: "Where would the information be that tells you, for example, the lock ordering rules?" Probably in a section or sub-section entitled Lock Ordering Rules, and indexed under "locks" and "rules" and probably a few other ways. Where is the discussion on lock ordering rules now? In some terse comments here and there in the kernel source? No, it's actually scattered about in several years of kerneldev mailing list archives. The hard-fought, well thrashed out issues are important to understand, but their subtle influence on some of the code will be easily lost on the next generation of kernel hackers who try to learn how Linux works by reading only the code and embedded comments, but without those discussions. Old mistakes will be made again and lost lessons relearned the hard way. About your example digression: Yes, it is wordy. But I think it also advances my knowledge of TeX for the very reasons you cite. It gets across the context that we're about to deal with portability issues that may not be obvious to someone only looking at the code and who's familiar with only one or a few OSs, and only sees a "Danger, Will Robinson" comment with lots of exclamation marks. :-) Besides, in my Documentation Fantasy, the prose are always perfect, succinct yet engaging, with just the right touch of humor, and they always correct themselves whenever patches are applied. And corbet always checks 'em over in his spare time just to be sure. Hey, as long as I'm dreaming...
(Log in to post comments)
Kernel Documentation Fantasy Posted Dec 2, 2003 4:59 UTC (Tue) by iabervon (subscriber, #722) [Link] Ah, but a section entitled Lock Ordering Rules, indexed under "locks" and"rules", doesn't need to be part of the kernel source. In fact, it probably would do better not to be interspersed with any code at all. It's certainly something that's worth documenting (although the Linux principal of lock ordering is, "if you have to document it, it's too complicated"). For that matter, the ideal kernel document would contain explanations of everything that isn't in the code, and why. What the bit of TeX actually told me was why people use C instead of Pascal in general (the Pascal standard omits most of the things necessary for making a large project manageable). Personally, I'd love to have a complete explanation of the kernel. But I don't think that literate programming actually forms a clear presentation of an explanation (nor does it help to clarify the code itself).
|
|||||||||||||