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: Yao Qi <yao at codesourcery dot com>
- To: Stan Shebs <stanshebs at earthlink dot net>
- Cc: <gdb-patches at sourceware dot org>
- Date: Mon, 14 Oct 2013 21:18:57 +0800
- Subject: Re: [RFC] Use Doxygen for internals documentation
- Authentication-results: sourceware.org; auth=none
- References: <525877F6 dot 40001 at earthlink dot net>
On 10/12/2013 06:13 AM, Stan Shebs wrote:
This patch is the third and final step in the transition away from the
old GDB internals manual.
I tried this patch, and overall, I like the doc generated by doxygen.
To try it out, install doxygen, apply this patch to GDB, configure in
the usual way, then do
make doxy
in the doc objdir. This will produce a "doxy" subdir, with three
subdirs in turn, each based on a different config file:
doxy/gdb-api - GDB's "API", basically what is in .h files
doxy/gdb-xref - the full xref, voluminous
Any reason to produce both of them? I'd like to have a single one.
doxy/gdbserver - GDBserver xref
doxy/xml - XML version, for further script-crunching
Do you have an example that these xml files can be consumed by other tools?
To see how the annotations work, look down through minsyms.h and
utils.h, you can see the comments attached to declarations.
types, see what is used and what is not used.
So I think it's worth going ahead and introducing. But of course
something like this only works if everybody signs on, patches are
required to have Doxygen annotations for header file additions, and
so forth. Look at the header file changes, try noodling around the
Doxygen output, see if you're willing to be looking at all this for
the next N years.
With this change, we need to write comments in a new way for doxygen. I
go through your patch to minsyms.h, and think the comment style looks
fine to me.
--
Yao (éå)