lkml.org 
[lkml]   [1999]   [Sep]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [Q]: Linux and real device drivers
From
Date
  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/

\
 
 \ /
  Last update: 2005-03-22 13:54    [W:0.105 / U:37.608 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site