Kernel documentation

Doxygen's output is worse than useless because it separates documentation from code. It's like the antithesis of an extreme interpretation of Knuth's literate programming.

Doxygen also encourages dirtying up otherwise clean and readable programs and header files by encouraging rules-oriented documentation, leading to things like documenting a buffer pointer and its length variable separately (as "the buffer that does X" and "the length of the buffer that does X") because The Rules say that each parameter must have Doxygen entries. The problem being that every programmer past the novice stage understands that a "x_p" and "x_len", in that order, is a matched pair to that effect; therefore documentation (Doxygen's input) making the fact explicit is often also worse than useless (noise, potentially misleading or outright wrong).

Many corporations have "coding standards" enforcing rules such as that above, and I'm guessing that if a tool like Doxygen were adopted then more would follow.