Add the notion of standalone doc sections.

Up to now, section annotations had to match a class or interface
name in order to be serialized in the gir.

With this commit, they now get serialized as docsection nodes,
for potential use by documentation tools.

5 files changed, 35 insertions, 1 deletions

diff --git a/giscanner/ast.py b/giscanner/ast.py
index 66fe0cf1..593969f2 100644
--- a/giscanner/ast.py
+++ b/giscanner/ast.py
@@ -660,6 +660,11 @@ GIName.  It's possible for nodes to contain or point to other nodes."""
         pass
 
 
+class DocSection(Node):
+    def __init__(self, name=None):
+        Node.__init__(self, name)
+
+
 class Registered:
     """A node that (possibly) has gtype_name and get_type."""
     def __init__(self, gtype_name, get_type):
diff --git a/giscanner/girparser.py b/giscanner/girparser.py
index 35206a41..d229b164 100644
--- a/giscanner/girparser.py
+++ b/giscanner/girparser.py
@@ -138,6 +138,7 @@ class GIRParser(object):
             _corens('interface'): self._parse_object_interface,
             _corens('record'): self._parse_record,
             _corens('union'): self._parse_union,
+            _corens('docsection'): self._parse_doc_section,
             _glibns('boxed'): self._parse_boxed}
 
         if not self._types_only:
@@ -150,6 +151,11 @@ class GIRParser(object):
             if method is not None:
                 method(node)
 
+    def _parse_doc_section(self, node):
+        docsection = ast.DocSection(node.attrib["name"])
+        self._parse_generic_attribs(node, docsection)
+        self._namespace.append(docsection)
+
     def _parse_include(self, node):
         include = ast.Include(node.attrib['name'], node.attrib['version'])
         self._includes.add(include)
diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py
index d1333cb7..05f4434e 100644
--- a/giscanner/girwriter.py
+++ b/giscanner/girwriter.py
@@ -113,6 +113,8 @@ class GIRWriter(XMLWriter):
             self._write_alias(node)
         elif isinstance(node, ast.Constant):
             self._write_constant(node)
+        elif isinstance(node, ast.DocSection):
+            self._write_doc_section(node)
         else:
             print('WRITER: Unhandled node', node)
 
@@ -442,6 +444,11 @@ class GIRWriter(XMLWriter):
         with self.tagcontext('member', attrs):
             self._write_generic(member)
 
+    def _write_doc_section(self, doc_section):
+        attrs = [('name', doc_section.name)]
+        with self.tagcontext('docsection', attrs):
+            self._write_generic(doc_section)
+
     def _write_constant(self, constant):
         attrs = [('name', constant.name),
                  ('value', constant.value),
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index 9468751d..c04620de 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -69,6 +69,10 @@ class MainTransformer(object):
         # Read in most annotations now.
         self._namespace.walk(self._pass_read_annotations)
 
+        # Now that we have associated doc SECTIONs to classes,
+        # add the unused section blocks as standalone nodes.
+        self._add_standalone_doc_sections()
+
         # Now that we've possibly seen more types from annotations,
         # do another type resolution pass.
         self._namespace.walk(self._pass_type_resolution)
@@ -101,6 +105,14 @@ class MainTransformer(object):
 
     # Private
 
+    def _add_standalone_doc_sections(self):
+        for block_name, block in self._blocks.items():
+            if block_name.startswith("SECTION:") and block.description:
+                node = ast.DocSection(block_name[8:])
+                node.doc = block.description
+                node.doc_position = block.position
+                self._namespace.append(node)
+
     def _pass_fixup_hidden_fields(self, node, chain):
         """Hide all callbacks starting with _; the typical
         usage is void (*_gtk_reserved1)(void);"""
@@ -240,7 +252,9 @@ class MainTransformer(object):
                 self._apply_annotations_field(node, block, field)
             name = self._get_annotation_name(node)
             section_name = 'SECTION:%s' % (name.lower(), )
-            block = self._blocks.get(section_name)
+            # We pop it from our blocks so that we can serialize leftover
+            # SECTIONs as standalone nodes
+            block = self._blocks.pop(section_name, None)
             self._apply_annotations_annotated(node, block)
         if isinstance(node, (ast.Class, ast.Interface)):
             for prop in node.properties:
diff --git a/giscanner/sectionparser.py b/giscanner/sectionparser.py
index ed4660fe..b8850432 100644
--- a/giscanner/sectionparser.py
+++ b/giscanner/sectionparser.py
@@ -148,5 +148,7 @@ def generate_sections_file(transformer):
                 append_symbol(section, meth.symbol)
             for meth in node.static_methods:
                 append_symbol(section, meth.symbol)
+        elif isinstance(node, ast.DocSection):
+            section = new_section(None, node.name)
 
     return SectionsFile(sections)