It's possible to run GCC's sources through Doxygen by setting
INPUT_FILTER = contrib/filter_gcc_for_doxygen
within contrib/gcc.doxy and invoking doxygen on the latter file.
The script filters out various preprocessor constructs from GCC sources
before Doxygen tries to parse them.
However, as written, it works one line at-a-time, and thus can't cope
with GTY markers that span multiple lines. I added such a marker
in r204170 (symtab_node_base), and I'd like to add more such markers
(see http://gcc.gnu.org/ml/gcc-patches/2013-10/msg02703.html).
So the attached patch rewrites the filtering script to cope with multiline
GTY markers.
I'm not familiar with Perl, so I rewrote the script in Python.
I expanded the regexes for readability, and added a unit-testing suite.
I also tweaked how comments get layed with @verbatim
to avoid inconsistent indentation between the first line and subsequent
lines within a comment.
Tested with Python 2.7; you can see a sample of the output (from my
gimple-as-C++-inheritance working copy) at:
http://dmalcolm.fedorapeople.org/gcc/2013-10-31/doxygen/html/structgimple__statement__base.html
In particular, with this patch Doxygen is able to cope with the symtab
GTY marker, and thus parse the symtab class hierarchy, giving the output
viewable here:
http://dmalcolm.fedorapeople.org/gcc/2013-10-31/doxygen/html/classsymtab__node__base.html
OK for trunk?
contrib/
* filter_gcc_for_doxygen: Use filter_params.py rather than
filter_params.pl.
* filter_params.pl: Delete in favor of...
* filter_params.py: New, porting the perl script to python in
order to cope with GTY markers that span multiple lines,
tweaking the layout of comments, and adding a test suite.
---
contrib/filter_gcc_for_doxygen | 2 +-
contrib/filter_params.pl | 14 ---
contrib/filter_params.py | 191 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 192 insertions(+), 15 deletions(-)
delete mode 100755 contrib/filter_params.pl
create mode 100644 contrib/filter_params.py
diff --git a/contrib/filter_gcc_for_doxygen b/contrib/filter_gcc_for_doxygen
index 3787eeb..ca1db31 100755
--- a/contrib/filter_gcc_for_doxygen
+++ b/contrib/filter_gcc_for_doxygen
@@ -8,5 +8,5 @@
# process is put on stdout.
dir=`dirname $0`
-perl $dir/filter_params.pl < $1 | perl $dir/filter_knr2ansi.pl
+python $dir/filter_params.py $1 | perl $dir/filter_knr2ansi.pl
exit 0
diff --git a/contrib/filter_params.pl b/contrib/filter_params.pl
deleted file mode 100755
index 22dae6c..0000000
--- a/contrib/filter_params.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/usr/bin/perl
-
-# Filters out some of the #defines used throughout the GCC sources:
-# - GTY(()) marks declarations for gengtype.c
-# - PARAMS(()) is used for K&R compatibility. See ansidecl.h.
-
-while (<>) {
- s/^\/\* /\/\*\* \@verbatim /;
- s/\*\// \@endverbatim \*\//;
- s/GTY[ \t]*\(\(.*\)\)//g;
- s/[ \t]ATTRIBUTE_UNUSED//g;
- s/PARAMS[ \t]*\(\((.*?)\)\)/\($1\)/sg;
- print;
-}
diff --git a/contrib/filter_params.py b/contrib/filter_params.py
new file mode 100644
index 0000000..d5092f6
--- /dev/null
+++ b/contrib/filter_params.py
@@ -0,0 +1,191 @@
+#!/usr/bin/python
+"""
+Filters out some of the #defines used throughout the GCC sources:
+- GTY(()) marks declarations for gengtype.c
+- PARAMS(()) is used for K&R compatibility. See ansidecl.h.
+
+When passed one or more filenames, acts on those files and prints the
+results to stdout.
+
+When run without a filename, runs a unit-testing suite.
+"""
+import re
+import sys
+import unittest
+
+# Optional whitespace
+opt_ws = '\s*'
+
+def filter_src(text):
+ """
+ str -> str. We operate on the whole of the source file at once
+ (rather than individual lines) so that we can have multiline
+ regexes.
+ """
+
+ # First, convert tabs to spaces so that we can line things up
+ # sanely.
+ text = text.expandtabs(8)
+
+ # Convert C comments from GNU coding convention of:
+ # /* FIRST_LINE
+ # NEXT_LINE
+ # FINAL_LINE. */
+ # to:
+ # /** @verbatim
+ # FIRST_LINE
+ # NEXT_LINE
+ # FINAL_LINE. @endverbatim */
+ # so that doxygen will parse them, and so the first line
+ # lines up correctly with subsequent lines.
+ # Single-line comments turn from:
+ # /* TEXT. */
+ # into:
+ # /** @verbatim
+ # TEXT. @endverbatim */
+
+ text = re.sub(r'^([ \t]*)/\*+ ',
+ (r'\1/** @verbatim\n'
+ r'\1 '),
+ text,
+ flags=re.MULTILINE)
+ text = re.sub(r'\*+/',
+ r'@endverbatim */',
+ text)
+
+ # Remove GTY markings (potentially multiline ones):
+ text = re.sub('GTY' + opt_ws + r'\(\(.*?\)\)\s+',
+ '',
+ text,
+ flags=(re.MULTILINE|re.DOTALL))
+
+ # Strip out 'ATTRIBUTE_UNUSED'
+ text = re.sub('\sATTRIBUTE_UNUSED',
+ '',
+ text)
+
+ # PARAMS(()) is used for K&R compatibility. See ansidecl.h.
+ text = re.sub('PARAMS' + opt_ws + r'\(\((.*?)\)\)',
+ r'(\1)',
+ text)
+
+ return text
+
+class FilteringTests(unittest.TestCase):
+ '''
+ Unit tests for filter_src.
+ '''
+ def assert_filters_to(self, src_input, expected_result):
+ # assertMultiLineEqual was added to unittest in 2.7/3.1
+ if hasattr(self, 'assertMultiLineEqual'):
+ assertion = self.assertMultiLineEqual
+ else:
+ assertion = self.assertEqual
+ assertion(expected_result, filter_src(src_input))
+
+ def test_comment_example(self):
+ self.assert_filters_to(
+ (' /* FIRST_LINE\n'
+ ' NEXT_LINE\n'
+ ' FINAL_LINE. */\n'),
+ (' /** @verbatim\n'
+ ' FIRST_LINE\n'
+ ' NEXT_LINE\n'
+ ' FINAL_LINE. @endverbatim */\n'))
+
+ def test_oneliner_comment(self):
+ self.assert_filters_to(
+ '/* Returns the string representing CLASS. */\n',
+ ('/** @verbatim\n'
+ ' Returns the string representing CLASS. @endverbatim */\n'))
+
+ def test_multiline_comment_without_initial_indent(self):
+ self.assert_filters_to(
+ ('/* The thread-local storage model associated with a given
VAR_DECL\n'
+ " or SYMBOL_REF. This isn't used much, but both trees and RTL
refer\n"
+ " to it, so it's here. */\n"),
+ ('/** @verbatim\n'
+ ' The thread-local storage model associated with a given
VAR_DECL\n'
+ " or SYMBOL_REF. This isn't used much, but both trees and RTL
refer\n"
+ " to it, so it's here. @endverbatim */\n"))
+
+ def test_multiline_comment_with_initial_indent(self):
+ self.assert_filters_to(
+ (' /* Set once the definition was analyzed. The list of
references and\n'
+ ' other properties are built during analysis. */\n'),
+ (' /** @verbatim\n'
+ ' Set once the definition was analyzed. The list of
references and\n'
+ ' other properties are built during analysis. @endverbatim
*/\n'))
+
+ def test_multiline_comment_with_tabs(self):
+ # Ensure that multiline comments containing tabs look sane, in
+ # this case, one with initial indentation.
+ self.assert_filters_to(
+ (' /* All the anchor SYMBOL_REFs used to address these objects,
sorted\n'
+ ' in order of increasing offset, and then increasing TLS
model.\n'
+ ' The following conditions will hold for each element X in
this vector:\n'
+ '\n'
+ '\t SYMBOL_REF_HAS_BLOCK_INFO_P (X)\n'
+ '\t SYMBOL_REF_ANCHOR_P (X)\n'
+ '\t SYMBOL_REF_BLOCK (X) == [address of this structure]\n'
+ '\t SYMBOL_REF_BLOCK_OFFSET (X) >= 0. */\n'
+ ' vec<rtx, va_gc> *anchors;\n'),
+ (' /** @verbatim\n'
+ ' All the anchor SYMBOL_REFs used to address these objects,
sorted\n'
+ ' in order of increasing offset, and then increasing TLS
model.\n'
+ ' The following conditions will hold for each element X in
this vector:\n'
+ '\n'
+ ' SYMBOL_REF_HAS_BLOCK_INFO_P (X)\n'
+ ' SYMBOL_REF_ANCHOR_P (X)\n'
+ ' SYMBOL_REF_BLOCK (X) == [address of this structure]\n'
+ ' SYMBOL_REF_BLOCK_OFFSET (X) >= 0. @endverbatim */\n'
+ ' vec<rtx, va_gc> *anchors;\n'))
+
+ def test_simple_GTY(self):
+ # Ensure that a simple GTY is filtered out.
+ self.assert_filters_to(
+ ('typedef struct GTY(()) alias_pair {\n'
+ ' tree decl;\n'
+ ' tree target;\n'
+ '} alias_pair;\n'),
+ ('typedef struct alias_pair {\n'
+ ' tree decl;\n'
+ ' tree target;\n'
+ '} alias_pair;\n'))
+
+ def test_multiline_GTY(self):
+ # Ensure that a multiline GTY is filtered out.
+ self.assert_filters_to(
+ ('class GTY((desc ("%h.type"), tag ("SYMTAB_SYMBOL"),\n'
+ '\t chain_next ("%h.next"), chain_prev ("%h.previous")))\n'
+ ' symtab_node_base\n'
+ '{\n'),
+ ('class symtab_node_base\n'
+ '{\n'))
+
+ def test_ATTRIBUTE_UNUSED(self):
+ # Ensure that ATTRIBUTE_UNUSED is filtered out.
+ self.assert_filters_to(
+ ('static void\n'
+ 'record_set (rtx dest, const_rtx set, void *data
ATTRIBUTE_UNUSED)\n'
+ '{\n'),
+ ('static void\n'
+ 'record_set (rtx dest, const_rtx set, void *data)\n'
+ '{\n'))
+
+ def test_PARAMS(self):
+ self.assert_filters_to(
+ 'char *strcpy PARAMS ((char *dest, char *source));\n',
+ 'char *strcpy (char *dest, char *source);\n')
+
+def act_on_files(argv):
+ for filename in argv[1:]:
+ with open(filename) as f:
+ text = f.read()
+ print(filter_src(text))
+
+if __name__ == '__main__':
+ if len(sys.argv) > 1:
+ act_on_files(sys.argv)
+ else:
+ unittest.main()
--
1.7.11.7
