This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [RFC] Use Doxygen for internals documentation
- From: Tom Tromey <tromey at redhat dot com>
- To: Stan Shebs <stanshebs at earthlink dot net>
- Cc: gdb-patches at sourceware dot org
- Date: Wed, 16 Oct 2013 11:28:16 -0600
- Subject: Re: [RFC] Use Doxygen for internals documentation
- Authentication-results: sourceware.org; auth=none
- References: <525877F6 dot 40001 at earthlink dot net>
>>>>> "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