Re: "Documentation by paper"

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

    I would say that libstdc++ is a place where doxygen-style comments are
    more useful, because the documentation for a library tends to be more
    reference style anyhow.  There are relatively few specific cases where
    different library functions must work together in interesting ways,
    and thus require additional documentation.

I agree, but would put it a little differently: because the functions
represent a published interface, in that case, the intended readership of the
comments is very different than the code, but you want to put the two
physically close together for maintainabilty purposes.

In other words, I think this sort of approach is perfectly acceptable, and a
good idea, for libraries, where the API is what counts.  But GCC is a very
different animal, precisely because of the interfactions you mention.