I find documentation comes in the following bins:

1. User documentation (possible sub-split into "how to use this from kernel space" and "how to use this from user space")

2. Information for someone who's interested in modifying the code. Possibly including architectural considerations (eg locking), performance, ideas for future improvement, etc.

3. Random swearing and abuse

I think the second and third categories of documentation should be kept out of the kernel books and left as plain comments by the code.