[...]
> No, i think it's not good to have the source full of comments (they _are_ useful, agreed!) , there should be some kind of outside documentation.
[...]
> 1. WE NEED A KIND OF STYLE GUIDE FOR DOCUMENTATION!
> 2. DOCUMENTATION WRITERS MUST FOLLOW THE STYLE GUIDE!
> 3. WE NEED A KIND OF STYLE GUIDE FOR DOCUMENTATION!
As kind of external documentation should base on manual pages
generated from the source, we need a kind of style guide for internal
documentation more than one for external documentation. I'd love to
see some of the available tools (I just remember c2man from the top of
my head) to be declared 'official linux kernel documentation tool'.
Modern versions of such tools find out the synopsis for a call from
the C function definition, which makes the total 'overhead' for
documenting a kernel functions about two or three lines of comment,
with most comments being one-liners and some important functions with
a lot of comments.
Froh
-- Frohwalt Egerer(Only wimps use tape backup: _real_ men just upload their important stuff on ftp, and let the rest of the world mirror it ;) -- Linus Torvalds