On Sun, 26 Sep 1999, Oliver Xymoron wrote:
> Some problems with documentation:
>
> - is a poor substitute for code
> - can never be complete, accurate, or timely enough to match the source
True, if the documentation is so extensive that it's too much work to update it.
> - <language> is much more ambiguous than C
> - encourages bad habits
> - developers substitute docs for readable code
I thought we were dealing with people that prefer to code? ;-)
> - people read the documentation and fear the code
> - when people do read the code, they interpret it as suggested by the
> documentation, missing subtle and not so subtle bugs
> - fewer people understand the actual code
This is true for overuse of inline documentaion in code - not API docs...
> - adds more inertia to the interfaces of a system
> - means changes require a greater investment of effort
> - implicitly promises things won't get changed
> - broken designs stay broken longer
> - is a lot of work
I'm not so sure...
> - and we've been doing pretty damn well without it
> - and there are good reasons to think it's a hindrance
> - and there are more important/interesting things to do
> - and you don't get very far telling volunteers to do things they don't
> want to
> - and other people who are motivated in that direction can do it
I agree to some extent... BUT, I think there's one thing we need to sort out
first: What kind of documentation is this all about?
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...
//David
·A·U·D·I·A·L·I·T·Y· P r o f e s s i o n a l L i n u x A u d i o
- - ------------------------------------------------------------- - -
·Rock Solid David Olofson:
·Low Latency www.angelfire.com/or/audiality ·Audio Hacker
·Plug-Ins audiality@swipnet.se ·Linux Advocate
·Open Source ·Singer/Composer
-
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/