[RFC] Use Doxygen for internals documentation

[Yao Qi]

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 (齐尧)