"Documentation by paper"

[Richard Kenner]

    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.

I haven't heard anybody make that argument.  The issue is that of
"extraction".  A lot of us fail to see that "extracting" documentation
is useful and if the method of generating it involves anotations that
make the source harder to read and write, it's a net negative.

As Robert points out, if you generate a separate file for documentation,
it's easy to have old versions of that file around without knowing it.
If all the documentation (both specification and implementation) is in
the same place as the source, you don't have that risk.