"Documentation by paper"

[Andrew Sutton]

> There is a *big* difference between looking at interface comments in
> a header and looking at the implementation!

isn't that the _point_ of an interface? i sure as hell don't look at the libc 
implementations of posix methods to figure out what the parameters do.

sorry to keep extending this thread... it's late and i have some strong 
feelings about the topic - especially since my masters thesis revolves around 
the topics of program understanding, redocumentation and reverse engineering 
(not reverse engineering like decss). maybe it's me, but it seems a bit odd 
that people would argue against documentation extraction in favor of having 
developers look at the implementation as a reference. but then again, i'm 
only a software engin... i mean grad student.

andrew sutton
asutton@cs.kent.edu