[parisc-linux] kerneldoc

[Matthew Wilcox]

i've had to explain this at least twice individually to people now,
so here goes for everyone:

No adding kerneldoc to PA implementations of functions which are used
in the generic kernel.

Kerneldoc is intended to document the kernel.  The only chance we
have of keeping it up to date is by putting it next to the code it is
intended to document.  Then when people change the meaning or usage
of a function, they will hopefully change the documentation of it too.
Like it or not, x86 is the dominant architecture and changes are generally
made there first.  So this is the _only_ architecture which should have
documentation in the asm directory unless the function being documented
is arch-specific.  Otherwise we get out of date documentation, which is
worse than useless.

Note also that kerneldoc should be used to document _what_ a
function does, not _how_ it works.  How it works should be obvious
(see Documentation/CodingStyle if you are confused on this point), and
comments on `tricks' employed should be restricted to ordinary comments.

-- 
Revolutions do not require corporate support.