Re: "Documentation by paper"

[Tom Tromey <tromey at redhat dot com>]

>>>>> "Richard" == Richard Kenner <kenner@vlsi1.ultra.nyu.edu> writes:

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

Well, GCC has many faces.  Parts of it definitely do need API-type
documentation.  For instance, documenting the API to (generic- or
gimple-) trees would be a great benefit to front-end writers.  OTOH
writing API documentation for every non-static function of every
tree-ssa optimizer may be less useful.

My experience with java (which heavily uses the doxygen-like javadoc)
is that documentation like this is very useful.  It isn't a complete
solution, you must also have a high-level overview and, sometimes,
tutorials.  It also works best when the javadoc is written as a
specification or contract and not a mere description of the method's
body.

Tom