"Documentation by paper"

[Richard Kenner]

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

You lost me.

    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.

I haven't heard anybody say it's "deprecated".  The point, though, is that
the code documenation will always need to be more detailed than an internals
manual. This is usually true for even overview documentation.  Some person,
not a tool, needs to figure out what information to include in the
internals manual, how to present it, and how to index it.  That person has
all the code documentation as material to use for the manual, but presumably
would want to both edit and reformat it.