> 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),

Why not kernel subroutines?  Section 9 strikes me as a Good Thing.
Where _would_ you put the kernel-internal interface descriptions?

> Documentation specific to the implementation of the kernel (or any
> other program) should be kept in the source code.

I agree and disagree.  Implementation documentation that applies to
only one piece of code should be kept with that code.  But
documentation that describes an interface provided by a module, such
documentation can and often should be pulled out into something like a
section 9 manpage...even if that interface is not available except
within the kernel.  I certainly know back when I was working on the sc
driver (still am, theoretically, but I haven't touched it in far too
long) I would have loved to have had a scsi(9) manpage documenting the
interface(s) provided and required by the /sys/scsi/ subsystem.

					der Mouse

			    mouse@collatz.mcrcim.mcgill.edu