"Documentation by paper"

[Andrew Sutton]

> > Is there anyone *except* Richard Kenner who is against this?
>
> Yes, me. I agree with Richard on this, I don't see any
> significant advantage in the separated documentation. In
> fact I suspect it in practice has the negative effect of
> out-of-date documentation wandering around.
> 
> I would certainly not pay even a minimal obfuscation cost
> in the sources for this. For one thing, it makes it harder
> work to keep the documentation up to date in the sources.
> Given most people's attitude to documentation, it is hard
> enough to get people to keep doc up to date without putting
> additional roadblocks in the way.

just a lurker's comment, but i think the point that several people were trying 
to make was that you can write a relatively static overview and use something 
like doxygen to keep the specifics of the api up to date. it shouldn't be 
that hard to document your functions.

andrew sutton
asutton@cs.kent.edu