Re: "Documentation by paper"

[Geert Bosch <bosch at gnat dot com>]

On Jan 27, 2004, at 12:50, Joe Buck wrote:
> Paper documentation is nice as well, but the way to get both, and to 
> keep
> the code and documentation consistent, is to use doxygen-style comments
> and use that to generate the documentation.

Having looked at the tree-ssa documentation for a bit, I find that
the doxygen generated documentation is nice in that it provides
cross-references. However, I find the fill-in style of documentation
useless. There is a lot of "empty" documentation, which basically
rehashes all fields of a structure with their references, but without
any description of what that field does. Since all semantic information
is obviously present to link each identifier use in the code to its
definition and all other uses, I don't see why extra markup is needed,
or why the generated documentation needs so much verbosity.

The main issue right now is lack of documentation, not the
formatting of it. Especially high-level per file overviews
and full descriptions of  datastructures (including individual
fields) and a few key  properties such as conditions for data
to be valid, initialization and main use of the data (why it exists).

  -Geert