Re: "Documentation by paper"

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

    Do you have a suggested syntax which allows us to extract nicely formatted
    HTML, LaTeX, and troff documentation?

No, because you can't "extract" documentation in a mechanical fashion.
High-level documentation is not a collection of low-level details.

    The @param and @return and whatnot are not intended for humans

But humans will be reading them.  Every time they look at the sources.

    I have complaints about doxygen myself.  But IMO it's better than anything
    else that's been concretely suggested.  And -- undisputed fact -- it's
    better than what we habe right now, which is nothing.

I would *certainly* dispute that fact. It's far *worse* than "nothing".
What we desperately need is well-written high-level documentation of
methods and algorithms and how everything fits together.  Finding ways
of automatically extracting low-level details from code and calling
it "high-level documentation" *detracts* from that effort.