>And I believe implementation details should not go into man pages either.
>man pages should be used for command descriptions, system call API details
>(library routines, -not- kernel subroutines), file formats, etc. that are
>required by users, system administrators, and application programmers.
>Documentation specific to the implementation of the kernel (or any other
>program) should be kept in the source code.

I didn't mean to imply that source code without comments was a good idea -
just that the information that he mentioned would make more sense in a
man page, because man pages are supposed to be references.

For example, the original poster talked about:

- Supported hardware.  Perfect for a man page, and there's already plenty of
  precedent (look at ed(4)).

- Assumptions made and known limitations.  Fits nicely inside of a CAVEATS
  section.

- Future plans and weird problems.  Both are canidates for the BUGS section.

Sure, this stuff would be fine in the source code as well.  But I think
that having a quick reference that showed all of the above information
would make sense as well.  It's hard to do an apropos(1) on the source
code! (Yes, I know about grep, and I use it plenty.  But I'd rather say
"apropos vnode" than "grep vnode /sys/*/*.[ch] /sys/*/*/*.[ch]").

And to be honest, I don't really understand your "keep it in the kernel"
argument.  I'd love it if a vnode(9) or pmap(9) man page appeared one day
that explained how those interfaces worked, because I'm curious about
them, but even if the source code in question _was_ well commented, it would
be easier to read a man page than piece a number of source files together.
But certainly this wouldn't be any excuse for not commenting source code
more.

--Ken