> IMO, a description of the "kernel API" would be quite useful for
> anyone who's just going to hack a driver or two. I don't think much
> more than a list of function calls with very brief descriptions is
> needed. A reference to where you can find the actual code should be
> included, for those who want more details.
>
> The docs should describe which calls to use and _what they are for_;
> not how they work in detail. Thus, you won't have to update the docs
> unless you actually change the way a function call works, or the
> arguments. And even when you do that, it's just a matter of
> adjusting the documentation tags just before the lines you're
> hacking...
_Exactly_. The problem I'd like to solve is not "how, exactly, does
the memory allocator work?" but rather "how should I allocate memory?
which functions should I use in which circumstances?", for example.
I'd also like to see something similar to document API changes -- a
few lines of "<foo> changed to <bar>, here's how to update your code"
along with a brief explanation of why the change happened would go a
long way.
I'm sort of ambivalent on the idea of inline documentation, though,
since I think it asks for a little too much discipline -- I think it's
easier to just knock out a brief summary of an interface than to make
sure that there's documentation in a format that the extraction script
can understand in each of the proper places.
--nat
-- nat lanza --------------------- research programmer, parallel data lab, cmu scs magus@cs.cmu.edu -------------------------------- http://www.cs.cmu.edu/~magus/ there are no whole truths; all truths are half-truths -- alfred north whitehead- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/