Re: "Documentation by paper"

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    If such high-level documentation is written inside a comment at the top
    of each file, then you can coax the publishing tool of your choice to
    emit it in a dozen different formats.

No, that's not the level of documentation we're talking about!

The comments in each file describe what each file does at the high
level.  What high-level documentation of GCC would consist of is an
overview of what the files do when put together.  That is not at all
the same as a concatenation of all the high-level comments in file.
They are two very different things and you cannot derive one from the
other.  The upper-level documentation should concentrate on such
things as what order optimizations are done and how they interact.
These are not things that are documented into the individual source files.

    But it is possible to extract documentation from the source code
    directly, and that is what I would like us to do for the internal API
    and design documentation, at least.

I don't see this.  I don't understand how duplicating the low-level
information that's in each file into a master document would improve the
documentation quality of GCC.  You can make the API argument, but even
that's weak.  Consider the optimizers, for example: you may have a 10,000
line source file that goes into extensive detail on on optimization
algorithm and has dozens of internal functions. But from an *API* point
of view, it's very simple: you call a function of a certain name and it
does a certain optimization.