[RFC] Use Doxygen for internals documentation

[Stan Shebs <stanshebs at earthlink dot net>]

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

It adds the use of Doxygen ( http://www.stack.nl/~dimitri/doxygen/ ),
perhaps the most widely-used documentation generator.  Doxygen combines
a basic source parser with an annotation scheme for comments, producing
a collection of web pages that is both API and cross-reference.  Doxygen
is already used by several GNU projects, including libstdc++ and Bison.

Doxygen will work on any random pile of source files, but it's more
effective if you set up a config file (a "Doxyfile") and tweak source
code comments; this patch sets up basic machinery and adds a bunch of
annotation to minsyms.h and utils.h, so people can get a feel for how
they like it.

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
	doxy/gdbserver - GDBserver xref
	doxy/xml - XML version, for further script-crunching

To look at it, you can open a browser on any file, or start with the
index.html in each subdir, and then click around.  The directories are
large, because they have copies of the source files with lots of links
added.  (I found it very handy to go from sources to doc and back with
just a couple clicks.)

To see how the annotations work, look down through minsyms.h and
utils.h, you can see the comments attached to declarations.

Doxygen has some flaws for us:

1) Its parser get befuddled by some of our macrology.
2) It doesn't know about host/target configs, just indexes everything
   and then gets confused by multiple files with functions of the same
   name.
3) The only way I could find to get Emacs to preserve our current
   formatting rules is to have the opening "/**" on a line by itself.
4) Even the API-only version is large, and needs tweaking so that
   more-important headers are more visible.

Even so, with the minimal configuration here, I found the result to
be a useful way to navigate around all the sources, quickly look up
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.

Stan
stan@codesourcery.com

Attachment: doxy-patch-1
Description: Text document