This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
Felix Lee wrote:
kenner@vlsi1.ultra.nyu.edu (Richard Kenner):
How could I possibly write documentation on code that I need documentation
to understand? Any documentation I could write would be totally useless!
why do you say that? I think it's generally not that hard to
approach unfamiliar code and add documentation when I figure out
what it's doing. it's often just tedious. of course, my
understanding can be faulty, but that's what peer review is
supposed to be for.
Well I already answered this. It is *impossible* to generate
complete documentation this way. Yes, you can say what a function
does (that's the information contained in the code), but you
can't say:
o what it is supposed to do (there may be a discrepancy due to
bugs, or the function may be non-deterministic, i.e. there are
several ways to achieve the required result, and by documenting
from the code, you will overspecify.)
o why particular choices were made in the way it was written
o what it is doing at a higher level of abstraction
o what was not done, and why it was not done.
Certainly there are cases where people who did not write the code
originally can improve the documentation if it is missing, but it
is an illusion to think that this can subsitute for accurate and
complete documentation written contemperaneously with the code.