Re: [PATCH] Use Doxygen for internals documentation

[Yao Qi <yao@codesourcery.com>]

Stan,
I applied this patch and run 'make doxy' in dir doc.  It looks good!

On 02/07/2014 07:55 AM, Stan Shebs wrote:
> +<p>
> +These are primarily useful for people working on GDB itself.  Users of
> +GDB, people working with stubs, and people working on frontends to GDB
> +are all better served by the GDB manual, which is the official
> +definition for all of GDB's external interfaces.

We may add a link to GDB manual.

> diff --git a/gdb/doc/filter-for-doxygen b/gdb/doc/filter-for-doxygen
> new file mode 100755
> index 0000000..457d088
> --- /dev/null
> +++ b/gdb/doc/filter-for-doxygen
> @@ -0,0 +1,14 @@
> +#!/bin/sh
> +

Missing copyright header?

> +# This filters GDB source before Doxygen can get confused by it;
> +# this script is listed in the doxyfile. The output is not very
> +# pretty, but at least we get output that Doxygen can understand.
> +#
> +# $1 is a source file of some kind. The source we wish doxygen to
> +# process is put on stdout.
> +
> +# (Adapted from gcc/contrib/filter_gcc_for_doxygen)
> +
> +dir=`dirname $0`
> +perl $dir/filter-params.pl < $1
> +exit 0
> diff --git a/gdb/doc/filter-params.pl b/gdb/doc/filter-params.pl
> new file mode 100644
> index 0000000..eedcc5b
> --- /dev/null
> +++ b/gdb/doc/filter-params.pl
> @@ -0,0 +1,11 @@
> +#!/usr/bin/perl
> +

Likewise.

> +# This Perl script tweaks GDB sources to be more useful for Doxygen.
> +
> +while (<>) {
> +    # Allow "/* * " as an equivalent to "/** ", better for Emacs compat.
> +    s/^\/\* \* /\/** /sg;
> +    # Manually expand macro seen in structs and such.
> +    s/ENUM_BITFIELD[ \t]*\((.*?)\)/__extension__ enum $1/sg;

Why do we need this substitution here?  Anything wrong if we don't do
the substitution?  I don't recall this was asked in last review.

-- 
Yao (齐尧)