"Documentation by paper"

[Paul Koning]

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

 >> Weird, I thought you didn't like extracting documentation
 >> from the source code.

 Richard> I don't like *automated* extraction, but there's nothing
 Richard> wrong with a human rewriting code documentation to the level
 Richard> appropriate for an internals manual.

An internals manual has indexing (or at least it can, and should).
How do you do that in code docs?

In my experience, a major problem with gcc -- unless you've been
working on it full time for at least 5 years -- is that it's so
complex that it's nearly impossible to get started.  The internals
manual helps a little, though its indexing and cross-referencing isn't
nearly good enough.  If the internals manual is deprecated in favor of
/* ... */, I fear this problem will get much worse, not better.

   paul