docextract_to_xml.py: Distinguish sections from properties

* tools/defs_gen/docextract.py:
* tools/defs_gen/docextract_to_xml.py: Don't treat sections as properties.
Add the --with-sections command-line option. Generate <section> tags.

2 files changed, 26 insertions, 13 deletions

diff --git a/tools/defs_gen/docextract.py b/tools/defs_gen/docextract.py
index 7bf49119..f794ef8c 100644
--- a/tools/defs_gen/docextract.py
+++ b/tools/defs_gen/docextract.py
@@ -65,6 +65,7 @@ function_name_pattern = re.compile(r'^([a-z]\w*)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
 signal_name_pattern = re.compile(r'^([A-Z]\w+::[a-z0-9-]+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
 property_name_pattern = re.compile(r'^([A-Z]\w+:[a-z0-9-]+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
 enum_name_pattern = re.compile(r'^([A-Z]\w+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
+section_name_pattern = re.compile(r'^SECTION:([a-z0-9_-]+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
 return_pattern = re.compile(r'^@?(returns:|return\s+value:)(.*\n?)$', re.IGNORECASE)
 deprecated_pattern = re.compile(r'^(deprecated\s*:\s*.*\n?)$', re.IGNORECASE)
 rename_to_pattern = re.compile(r'^(rename\s+to)\s*:\s*(.*\n?)$', re.IGNORECASE)
@@ -77,9 +78,13 @@ annotation_lead_pattern = re.compile(r'^\s*\(\s*(.*?)\s*\)\s*')
 
 # These patterns determine the identifier of the current comment block.  They
 # are grouped in a list for easy determination of block identifiers (in
-# skip_to_identifier).  The function_name_pattern should be tested for last
-# because it always matches signal and property identifiers.
-identifier_patterns = [ signal_name_pattern, property_name_pattern, enum_name_pattern, function_name_pattern ]
+# skip_to_identifier).
+# The function_name_pattern shall be tested for last, because it always matches
+# signal and property identifiers.
+# The property_name_pattern shall be tested for after the section_name_pattern,
+# because the property_name_pattern matches most section identifiers.
+identifier_patterns = [ signal_name_pattern, section_name_pattern,
+    property_name_pattern, enum_name_pattern, function_name_pattern ]
 
 # This pattern is to match return sections that forget to have a colon (':')
 # after the initial 'Return' phrase.  It is not included by default in the list
@@ -195,6 +200,8 @@ def skip_to_identifier(fp, line, cur_doc):
                 # Set the GtkDoc type.
                 if pattern == signal_name_pattern:
                     cur_doc.set_type('signal')
+                elif pattern == section_name_pattern:
+                    cur_doc.set_type('section')
                 elif pattern == property_name_pattern:
                     cur_doc.set_type('property')
                 elif pattern == enum_name_pattern:
diff --git a/tools/defs_gen/docextract_to_xml.py b/tools/defs_gen/docextract_to_xml.py
index 4222250a..00c4f8ce 100755
--- a/tools/defs_gen/docextract_to_xml.py
+++ b/tools/defs_gen/docextract_to_xml.py
@@ -14,8 +14,8 @@ 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] ' +
+        '[-s /src/dir | --source-dir=/src/dir] [-a | --with-annotations] ' +
+        '[-p | --with-properties] [-c | --with-sections] ' +
         '[-n | --no-since] [-i | --no-signals ] [-e | --no-enums ]\n')
     sys.exit(1)
 
@@ -61,10 +61,10 @@ def print_annotations(annotations):
 
 if __name__ == '__main__':
     try:
-        opts, args = getopt.getopt(sys.argv[1:], "d:s:o:apnie",
+        opts, args = getopt.getopt(sys.argv[1:], "d:s:o:apcnie",
                                    ["source-dir=", "with-annotations",
-                                     "with-properties", "no-since",
-                                     "no-signals", "no-enums"])
+                                    "with-properties", "with-sections",
+                                    "no-since", "no-signals", "no-enums"])
     except getopt.error as e:
         sys.stderr.write('docextract_to_xml.py: %s\n' % e)
         usage()
@@ -72,6 +72,7 @@ if __name__ == '__main__':
     with_annotations = False
     with_signals = True
     with_properties = False
+    with_sections = False
     with_enums = True
     for opt, arg in opts:
         if opt in ('-s', '--source-dir'):
@@ -80,6 +81,8 @@ if __name__ == '__main__':
             with_annotations = True
         if opt in ('-p', '--with-properties'):
             with_properties = True
+        if opt in ('-c', '--with-sections'):
+            with_sections = True
         if opt in ('-n', '--no-since'):
             docextract.no_since = True
         if opt in ('-i', '--no-signals'):
@@ -99,8 +102,8 @@ if __name__ == '__main__':
         print("<root>")
 
         for name, value in sorted(docs.items()):
-            # Get the type of comment block ('function', 'signal' or
-            # 'property') (the value is a GtkDoc).
+            # Get the type of comment block ('function', 'signal',
+            # 'property', 'section' or 'enum') (the value is a GtkDoc).
             block_type = value.get_type()
 
             # Skip signals if the option was not specified.
@@ -109,6 +112,9 @@ if __name__ == '__main__':
             # Likewise for properties.
             elif block_type == 'property' and not with_properties:
                 continue
+            # Likewise for sections.
+            elif block_type == 'section' and not with_sections:
+                continue
             # Likewise for enums.
             elif block_type == 'enum' and not with_enums:
                 continue
@@ -133,9 +139,9 @@ if __name__ == '__main__':
 
                 print("</parameters>")
 
-            if block_type != 'property' and block_type != 'enum':
-              # Show the return-type (also if not dealing with a property or
-              # enum):
+            if block_type not in ('property', 'section', 'enum'):
+              # Show the return-type if not dealing with a property, section
+              # or enum:
               if with_annotations:
                   print("<return>")
                   print("<return_description>" + escape_text(value.ret[0]) + \