Messages in this thread | | | Subject | Re: [Q]: Linux and real device drivers | From | Nat Lanza <> | Date | 26 Sep 1999 18:50:23 -0400 |
| |
David Olofson <audiality@swipnet.se> writes:
> 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/
| |