Update doc extraction tool to handle GObjectIntrospection annotations.

	* codegen/docextract.py (FunctionDoc): Renamed class to GtkDoc.
	(GtkDoc::annotations): Added a list field to store annotations which
	are 2-tuples of (name, value).
	(GtkDoc::ret): Modified field to store the return description along
	with a list of annotations as described above.
	(GtkDoc::params): Now holds a list of 3-tupples: name, description and
	annotations (as described above).
	(GtkDoc::block_type): Add a field to tell if the comment block is a
	function block, signal block or property block.
	(GtkDoc::set_type):
	(GtkDoc::get_type): Add methods for setting/getting the block type.
	(GtkDoc::add_param): Modified to also accept a list of annotations to
	be added with the parameter.
	(GtkDoc::add_annotation):
	(GtkDoc::get_annotations): Added methods to add/get annotations for
	the comment block.
	(GtkDoc::append_description): Renamed to append_to_description().
	(GtkDoc::get_param_description): Removed unused method.
	(GtkDoc::get_description): Added method to get block description.
	(GtkDoc::add_return): Added method to add a return accepting the first
	line of the description and its annotations.
	(GtkDoc::append_return): Renamed to append_to_return().
	(Regular expressions):
	 - Made the names of the variables un-abbreviated.

	 - Added 'since', 'deprecated' and 'rename to' regular expressions.

	 - Modified the return matching regular expression so that it doesn't
	   match descriptions that begin with 'Returns ...'.  This improves
	   the docs of many function.

	 - Added signal and property comment block identifier matching regular
	   expressions in case those are useful.

	- Modified existing identifier matching regular expressions (function,
	  signal, and property regular expressions) to properly parse
	  annotations.  Also added a regular expression for extracting
	  annotations from the parameter and return descriptions.

	- Refined the function name matching regular expression to only accept
	  identifiers that begin with a lowercase letter.  This eliminates
	  'SECTION:' matches.

	- Finally, grouped commonly related expressions like return_pattern,
	  since_pattern, etc.  into groups (in lists) so that matching those
	  sections can be done using loops.

	(Parsing algorithm): Modified the algorithm to use a functional
	approach to parsing.  Extra methods like skip_to_comment() and
	processs_params() have been added and used in the parse_file()
	function to now process the comment blocks.
	(parse_dir): Added file processing output to stderr.
	* codegen/docextract_to_xml.py (usage): Added function to print out
	the usage.
	(print_annotations): Added function to print the given list of
	annotations.
	(options): Added --with-signals (-i), with-properties (-p) and
	--with-annotation (-a) to the existing --source-dir (-s) option.

	(algorithm): Now prints annotations, if specified.  Also, prints
	signals and properties correctly (using names like Class::signal-one
	for signals and Classs:property) with xml such as <signal
	name="...">...</signal>.  The return xml is slightly modified with
	annotations but this would only be exhibited if annotation xml is
	requested.

1 files changed, 65 insertions, 22 deletions

diff --git a/codegen/docextract_to_xml.py b/codegen/docextract_to_xml.py
index f8d3bae..638ac94 100755
--- a/codegen/docextract_to_xml.py
+++ b/codegen/docextract_to_xml.py
@@ -13,6 +13,13 @@ import sys
 
 import docextract
 
+def usage():
+    sys.stderr.write('usage: docextract_to_xml.py ' +
+        '[-s /src/dir | --source-dir=/src/dir] ' +
+        '[-a | --with-annotations] [-p | --with-properties] ' +
+        '[-i | --with-signals ]\n')
+    sys.exit(1)
+
 def escape_text(unescaped_text):
     # Escape every "&" not part of an entity reference
     escaped_text = re.sub(r'&(?![A-Za-z]+;)', '&', unescaped_text)
@@ -30,23 +37,34 @@ def escape_text(unescaped_text):
 
     return escaped_text
 
+def print_annotations(annotations):
+    for annotation in annotations:
+        print "<annotation name=" + annotation[0] +  ">" + \
+                escape_text(annotation[1]) + "</annotation>"
+
 if __name__ == '__main__':
     try:
-        opts, args = getopt.getopt(sys.argv[1:], "d:s:o:",
-                                   ["source-dir="])
+        opts, args = getopt.getopt(sys.argv[1:], "d:s:o:api",
+                                   ["source-dir=", "with-annotations",
+                                     "with-properties", "with-signals"])
     except getopt.error, e:
-        sys.stderr.write('docgen.py: %s\n' % e)
-        sys.stderr.write(
-            'usage: docgen.py [-s /src/dir]\n')
-        sys.exit(1)
+        sys.stderr.write('docextract_to_xml.py: %s\n' % e)
+        usage()
     source_dirs = []
+    with_annotations = False
+    with_signals = False
+    with_properties = False
     for opt, arg in opts:
         if opt in ('-s', '--source-dir'):
             source_dirs.append(arg)
+        if opt in ('-a', '--with-annotations'):
+            with_annotations = True
+        if opt in ('-p', '--with-properties'):
+            with_properties = True
+        if opt in ('-i', '--with-signals'):
+            with_signals = True
     if len(args) != 0:
-        sys.stderr.write(
-            'usage: docgen.py  [-s /src/dir]\n')
-        sys.exit(1)
+        usage()
 
     docs = docextract.extract(source_dirs);
     docextract.extract_tmpl(source_dirs, docs); #Try the tmpl sgml files too.
@@ -58,25 +76,50 @@ if __name__ == '__main__':
         print "<root>"
 
         for name, value in docs.items():
-            print "<function name=\"" + escape_text(name) + "\">"
+            # Get the type of comment block ('function', 'signal' or
+            # 'property') (the value is a GtkDoc).
+            block_type = value.get_type()
+
+            # Skip signals if the option was not specified.
+            if block_type == 'signal' and not with_signals:
+                continue
+            # Likewise for properties.
+            elif block_type == 'property' and not with_properties:
+                continue
+
+            print "<" + block_type + " name=\"" + escape_text(name) + "\">"
 
             print "<description>"
-            #The value is a docextract.FunctionDoc
-            print escape_text(value.description)
+            print escape_text(value.get_description())
             print "</description>"
 
-             # Loop through the parameters:
-            print "<parameters>"
-            for name, description in value.params:
-                print "<parameter name=\"" + escape_text(name) + "\">"
-                print "<parameter_description>" + escape_text(description) + "</parameter_description>"
-                print "</parameter>"
+            # Loop through the parameters if not dealing with a property:
+            if block_type != 'property':
+                print "<parameters>"
+                for name, description, annotations in value.params:
+                        print "<parameter name=\"" + escape_text(name) + "\">"
+                        print "<parameter_description>" + escape_text(description) + "</parameter_description>"
+
+                        if with_annotations:
+                            print_annotations(annotations)
+
+                        print "</parameter>"
+
+                print "</parameters>"
 
-            print "</parameters>"
+                # Show the return-type (also if not dealing with a property):
+                if with_annotations:
+                    print "<return>"
+                    print "<return_description>" + escape_text(value.ret[0]) + \
+                            "</return_description>"
+                    print_annotations(value.ret[1])
+                    print "</return>"
+                else:
+                    print "<return>" + escape_text(value.ret[0]) + "</return>"
 
-            # Show the return-type:
-            print "<return>" + escape_text(value.ret) + "</return>"
+            if with_annotations:
+                print_annotations(value.get_annotations())
 
-            print "</function>\n"
+            print "</" + block_type + ">\n"
 
         print "</root>"