Re: linux-kernel-digest V1 #94
Corey Sweeney (corey@interaccess.com)
Sat, 24 Jun 1995 12:03:03 -0500 (CDT)
> From: Mike Shaver <shaver@neon.ingenia.com>
> Date: Fri, 23 Jun 1995 00:57:45 -0400 (EDT)
> Subject: Documenting kernel
>
> As per a recent thread in c.o.l.d.s, I'm going to try my hand at
> documenting the kernel sources. Before I start, there are some things
> I'd like to check...
>
> 1) Should I even bother? It's quite possible that someone has
> tried/suggested this before, and it proved unwise. If this is the
> case, I'd love to hear about it now.
>
> 2) What I'm thinking of is a comment before each function like this:
> /*
> * linux/path/to/file.c: this_func()
> * Description of the function.
> *
> * Args: Arguments
> * Return: Return values, and significance thereof
> * Assumes: What the function requires to be true. (Stuff that should be
> * allocated, cli()/sti() stuff, etc.... I'll know more about pitfalls
> * once I figure out more about the kernel.)
> * Alters: gotchas, etc.
> * Calls: what functions it (perhaps) calls, in varying detail
> * Called by: what functions refer to it, with source tree locations
> * Author/Maintainer: who to talk to about bugs, etc.
> * Appeared: which kernel version it appeared in (I may need some help
> * with this...)
> */
>
> Comments?
>
> 3) I'd like to have some feedback on the comments (and I know there
> will be *tons* of dumb questions at first) before I'm ambitious enough
> to submit them as patches. Should I post them here, or is there
> someone willing to take on a mentorship role?
>
> 4) What parts of the kernel are most in need of commenting, and which
> are stable enough that I won't be playing catch up forever? Of
> course, it's possible that the works in progress would benefit most
> from commenting...
>
> I'm sure there is more that I'm forgetting, but you'll let me know,
> right? =)
>
> Mike
take a look at dosemu.... we went through this in dosemu a long time ago,
and what we ended up with was entering specially formated comments, that
would get stripped out, and shoved into a document called dang. you can
take a look to get some ideas there.
Corey Sweeney