Re: [RFC] Use Doxygen for internals documentation

[Tom Tromey <tromey@redhat.com>]

>>>>> "Stan" == Stan Shebs <stanshebs@earthlink.net> writes:

Stan> This patch is the third and final step in the transition away from the
Stan> old GDB internals manual.

Thanks, Stan.

I applied your patch and built the docs locally.  This went smoothly.


I don't have a problem with the new way of formatting comments, or with
requiring them in review.

It seems to me that we should require docs for extern objects.  For
static objects I think it's fine to use less formal comments; but I'm
curious what others think.


Looking at the generated docs makes me wonder what knobs we have to
change the output.  Here's what I noticed:

I started by looking at the minsyms section.  I rearranged minsyms a
while back to have the comments in the header and to try to make it act
somewhat more like a self-contained module.  So, I was particularly
curious how this would render.

Starting here it looks promising enough:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/pages.html

(When we have two dozen modules here will we be able to organize them
somehow?)

Clicking through to the Minimal Symbols page, though, just gives some
text about the header.  (As an aside it's clear that this paragraph
needs a rewrite for Doxygen...)

However, there's nothing there about the module API, nor any link to
minsyms.h.  Is the latter something we can add?


I can go to the files page:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/files.html

and click through to minsyms.h:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/minsyms_8h.html

This lays out the contents of the file -- but not any introductory
text.  So that seems odd.

And, the contents are in an arbitrary order: Classes, Defines,
Functions.  What if we arranged the file in a particular order to
emphasize related things?  Could we reflect this in the docs somehow?

Finally, having to go to the Files page is sub-optimal just because it
presumes that one knows the layout.  It would be better if we could
start from some top-level view of "Modules of GDB" and click through to
the modules to understand their details.


I think it's fine to move forward even if all the answers are negative.
It's definitely an improvement.

Tom