But the problem is, only the *developer* can do this, and the
developers don't seem to want to do this. If a patch comes in that's
a thousand lines, and the only doc is a subject line of "fixes
problems in foo driver", no one else is going to know the what the
problems were; some may spend a few long hours looking at it under a
microscope, but they'll still have to guess what the problems were.
And this isn't necessarily a hypothetical example; I have seen several
patches that were essentially documented just that way.
There's no valid reason for a developer to NOT document or comment.
they don't have to do it well, but they should do some. Just look at
the average file in the kernel, and it's probably less than 5%
comments, with most of those being just who worked on the file.
Ignoring documentation, the kernel is a very well written piece of
code; but as a former TA, I can not possibly give it a grade of A
because there are no comments and the docs are inadequate. If this
were commercial code, I think the developers would be chewed out by
their bosses on a weekly basis.