Truth is, essential documention isnt in commented code.... its exchanged
in email between the few knowledgeable developers and those who are
becoming knowledgeable.
If we forced documentation rules, this would kill kernel developement like
nothing else. If you worry about docs, you arent going to bother molding
and shifting the code.
Most important: Do NOT solidify an interface. Once that happens, all
fresh kernel developement will stop and it will merely degenerate into bug
fixes.
Basically: When you are busy happily hacking away... You *cant* document
all your changes, coz your hacks generally spread out over several time
periods and stretches of code.
What we have now is sufficient: Someone produces a patch that
accomplishes a goal, with a short description of what it does. You should
figure out from the patch how it alters the "base" kernel.
I really suggest that a lot of you that have contributed to this whole
"documentation" thread should read the FAQ for this mailing list. It
should be posted shortly. When you see it posted within the next two
weeks, *read* it. Then you'll understand why all this rigorous
documentation would be more a hindrance than a help.
Peace out
Don Dibos