> Some problems with documentation:
>
> - is a poor substitute for code
Unfortunately, code is also a poor substitute for documentation.
> - can never be complete, accurate, or timely enough to match the source
I don't think anyone's claiming that it can be. I think the claim is
just that you can get it close enough to help.
> - encourages bad habits
I disagree. I think guessing at what the Right Way is by looking at
what other code does with those interfaces encourages bad habits
because nothing tells you not to do them.
> - 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
I don't think the goal is to completely replace reading the code with
documentation. I think the goal should be to have the documentation
serve as an introduction to the interfaces. Yes, you'll never
understand a piece of code as well by reading about it as you will by
reading it, but you'll get a basic level of knowledge faster and with
less effort by reading documentation.
> - adds more inertia to the interfaces of a system
> - means changes require a greater investment of effort
I'm not convinced this is bad. There _should_ be some inertia to an
interface; otherwise, what's the point?
> - implicitly promises things won't get changed
> - broken designs stay broken longer
I'm not sure this is true; documentation can simply mean "this is how
this works, and this is how it changed since the last version" instead
of "this is how it works now and always". Mention that interfaces can
change in the documentation; make sure the reader knows that. Make the
few relatively unchangeable interfaces loud and obvious exceptions.
> - is a lot of work
Well, yes. Most worthwhile things are.
> - and we've been doing pretty damn well without it
So? Are you sure we couldn't do better with it?
> I think the informal commentary style of things like
> Documentation/exceptions.txt is far preferable to any sort of formal
> function-by-function docs, inline or otherwise.
Unfortunately, even that sort of documentation is often outdated and
not as useful as it could be. So even if we entirely reject the idea
of API documentation, it would still be good to try and keep what
little documentation that we do have up to date.
--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/