In cases where the code being added to the main kernel distribution is
"stable" or "perfect and complete the first time", it's sort of okay to
let documentation slide; after all, "it works", and people who need to
figure it out will learn more by figuring it out than by having it told
to them. Likewise, when the chief programmers are viewed as some sort of
gods, you don't want them writing the documentation so people don't
blindly believe the inevitable bugs in it.
However, especially when Linus decides to throw a half-done (and likely
otherwise buggy in ways nobody can debug until the change is "completed")
but major revision into the code, I see great value in allowing the
intelligent but non-telepathic masses in on the Great One's intent, so
that we can have enough of an idea of what's meant to see bugs when we
look at them, rather than not knowing what's a bug and trying in vain
to justify how these bugs could be correct code. I remember some
excellent descriptions of the big changes (losing verify_area and
friends) around 2.1.2-2.1.4 written for developers-of-other-stuff...
Additionally, I get the feeling that the major reason the current developers
who can do things the rest of us are "not capable of" are that way (and are
so few) partly because they both have the time to work on things and have
already paid the learning curve and already know the existing code they plan
on interfacing to or replacing. The step up from no documentation to minimal
documentation almost certainly seems worth it: the first step in understanding
new code is always the hard one.
I admit, I haven't had time to contribute much of anything to Linux, and
won't have time until my thesis is done, and as such I don't feel I have
the right to say "you should do this". However, I do feel that code
documentation, especially on substantially new code that nobody but the
author understands yet, would be useful both for debugging and for adding
to the base of competent debuggers and developers, and as such would be *a*
good use of *somebody's* time. Those who don't agree will of course ignore
me, and those who think they have better things to do (like me :-() will of
course do those better things. And if I ever have difficulty understanding
a piece of kernel and figure it out, I do promise to bounce a patchful of
comments off of its author...
Keith