Messages in this thread | | | Date | 17 Jul 1997 16:07:16 +0200 | From | Frohwalt Egerer <> | Subject | Re: Take A deep Breath - Kernel Documentation |
| |
s_dkling@student.uni-ulm.de (Dietmar Kling) writes:
[...]
> 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
| |