Re: [RFC] Use Doxygen for internals documentation

[Pedro Alves <palves@redhat.com>]

On 10/11/2013 11:13 PM, Stan Shebs wrote:
> 
> 1) Its parser get befuddled by some of our macrology.
...

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

GCC has these problems solved by running a simple filter on
the sources before feeding them to doxygen.  I think we
could/should do the same.

http://gcc.gnu.org/viewcvs/gcc/trunk/contrib/filter_params.pl?view=markup

1 	#!/usr/bin/perl
2 	
3 	# Filters out some of the #defines used throughout the GCC sources:
4 	# - GTY(()) marks declarations for gengtype.c
5 	# - PARAMS(()) is used for K&R compatibility. See ansidecl.h.
6 	
7 	while (<>) {
8 	s/^\/\* /\/\*\* \@verbatim /;
9 	s/\*\// \@endverbatim \*\//;
10 	s/GTY[ \t]*\(\(.*\)\)//g;
11 	s/[ \t]ATTRIBUTE_UNUSED//g;
12 	s/PARAMS[ \t]*\(\((.*?)\)\)/\($1\)/sg;
13 	print;
14 	}

David Malcolm just recently posted a gcc patch that rewrites
that in Python (and makes it smarter):

  http://gcc.gnu.org/ml/gcc-patches/2013-10/msg02728.html

-- 
Pedro Alves