Re: [RFC] Use Doxygen for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 10/14/13 6:18 AM, Yao Qi wrote:
> 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.

So people can take a look without installing the patch, I put a copy of
the output on github:

	http://stanshebs.github.io/gdb-doxy-test/


>>     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.

gdb-xref has the most information, but the cross-references can be
lengthy - in utils.h for instance, the references to gdb_stderr
etc fill multiple screens, and it's a distraction if you're just
looking for the right function to print a ULONGEST.

It wasn't obvious which one would be the most useful, and I didn't see
an option to "twist out" the API into a full xref, so I just ran it
twice.  If one of these is disliked, no problem to eliminate - hackers
can always create a personal page collection, doxygen is pretty fast
if you skip the macro expansion.

>>     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?

Not yet, still learning the XML-fu necessary.  A couple easy examples
would be "find orphans" and "report the percentage of the API that has
been documented".

Stan
stan@codesourcery.com