Merge branch 'standalone-doc-sections' into 'master'

Add the notion of standalone doc sections.

See merge request GNOME/gobject-introspection!226

12 files changed, 124 insertions, 28 deletions

diff --git a/girepository/girparser.c b/girepository/girparser.c
index 53450baf..ad676e33 100644
--- a/girepository/girparser.c
+++ b/girepository/girparser.c
@@ -2830,7 +2830,8 @@ start_element_handler (GMarkupParseContext *context,
 			       ctx, error))
     goto out;
       if (strcmp ("doc", element_name) == 0 || strcmp ("doc-deprecated", element_name) == 0 ||
-          strcmp ("doc-stability", element_name) == 0 || strcmp ("doc-version", element_name) == 0)
+          strcmp ("doc-stability", element_name) == 0 || strcmp ("doc-version", element_name) == 0 ||
+          strcmp ("docsection", element_name) == 0)
         {
           state_switch (ctx, STATE_PASSTHROUGH);
           goto out;
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 41d3ead2..2b837362 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)
 
@@ -443,6 +445,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 3c4ef695..9077a1d0 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)
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.standalone_section.page b/tests/scanner/Regress-1.0-C-expected/Regress.standalone_section.page
new file mode 100644
index 00000000..76a55515
--- /dev/null
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.standalone_section.page
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<page id="Regress.standalone_section"
+      type="topic"
+      style="default"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="default" type="guide"/>
+  </info>
+  <title>Regress.standalone_section</title>
+  <p>This documentation section isn't associated with an object
+in particular, but it should be serialized in the gir nevertheless.</p>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.standalone_section.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.standalone_section.page
new file mode 100644
index 00000000..76a55515
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.standalone_section.page
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<page id="Regress.standalone_section"
+      type="topic"
+      style="default"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="default" type="guide"/>
+  </info>
+  <title>Regress.standalone_section</title>
+  <p>This documentation section isn't associated with an object
+in particular, but it should be serialized in the gir nevertheless.</p>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.standalone_section.page b/tests/scanner/Regress-1.0-Python-expected/Regress.standalone_section.page
new file mode 100644
index 00000000..76a55515
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.standalone_section.page
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<page id="Regress.standalone_section"
+      type="topic"
+      style="default"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="default" type="guide"/>
+  </info>
+  <title>Regress.standalone_section</title>
+  <p>This documentation section isn't associated with an object
+in particular, but it should be serialized in the gir nevertheless.</p>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index 62f456f8..3a1764e8 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -1876,13 +1876,13 @@ it says it's pointer but it's actually a string.</doc>
                 c:identifier="regress_foo_object_get_default">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="330">This function is intended to match clutter_stage_get_default which
+             line="337">This function is intended to match clutter_stage_get_default which
 uses a C sugar return type.</doc>
         <source-position filename="foo.h" line="205"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="foo.c"
-               line="336">The global #RegressFooSubobject</doc>
+               line="343">The global #RegressFooSubobject</doc>
           <type name="FooSubobject" c:type="RegressFooObject*"/>
         </return-value>
       </function>
@@ -1896,22 +1896,22 @@ uses a C sugar return type.</doc>
       <virtual-method name="read_fn" invoker="read">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="291">Read some stuff.</doc>
+             line="298">Read some stuff.</doc>
         <source-position filename="foo.h" line="117"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
           <instance-parameter name="object" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="293">obj</doc>
+            <doc xml:space="preserve" filename="foo.c" line="300">obj</doc>
             <type name="FooObject" c:type="RegressFooObject*"/>
           </instance-parameter>
           <parameter name="offset" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="294">offset</doc>
+            <doc xml:space="preserve" filename="foo.c" line="301">offset</doc>
             <type name="gint" c:type="int"/>
           </parameter>
           <parameter name="length" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="295">length</doc>
+            <doc xml:space="preserve" filename="foo.c" line="302">length</doc>
             <type name="gint" c:type="int"/>
           </parameter>
         </parameters>
@@ -1934,7 +1934,7 @@ uses a C sugar return type.</doc>
               c:identifier="regress_foo_object_append_new_stack_layer">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="779">This shouldn't be scanned as a constructor.</doc>
+             line="786">This shouldn't be scanned as a constructor.</doc>
         <source-position filename="foo.h" line="581"/>
         <return-value transfer-ownership="none">
           <type name="FooOtherObject" c:type="RegressFooOtherObject*"/>
@@ -1965,14 +1965,14 @@ uses a C sugar return type.</doc>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="foo.c"
-               line="240">%NULL always</doc>
+               line="247">%NULL always</doc>
           <type name="Utility.Object" c:type="UtilityObject*"/>
         </return-value>
         <parameters>
           <instance-parameter name="object" transfer-ownership="none">
             <doc xml:space="preserve"
                  filename="foo.c"
-                 line="238">a #RegressFooObject</doc>
+                 line="245">a #RegressFooObject</doc>
             <type name="FooObject" c:type="RegressFooObject*"/>
           </instance-parameter>
         </parameters>
@@ -2023,7 +2023,7 @@ uses a C sugar return type.</doc>
               introspectable="0">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="266">Not sure why this test is here...</doc>
+             line="273">Not sure why this test is here...</doc>
         <source-position filename="foo.h" line="152"/>
         <return-value transfer-ownership="none">
           <type name="FooObjectCookie" c:type="RegressFooObjectCookie"/>
@@ -2040,22 +2040,22 @@ uses a C sugar return type.</doc>
       <method name="read" c:identifier="regress_foo_object_read">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="291">Read some stuff.</doc>
+             line="298">Read some stuff.</doc>
         <source-position filename="foo.h" line="176"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
           <instance-parameter name="object" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="293">obj</doc>
+            <doc xml:space="preserve" filename="foo.c" line="300">obj</doc>
             <type name="FooObject" c:type="RegressFooObject*"/>
           </instance-parameter>
           <parameter name="offset" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="294">offset</doc>
+            <doc xml:space="preserve" filename="foo.c" line="301">offset</doc>
             <type name="gint" c:type="int"/>
           </parameter>
           <parameter name="length" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="295">length</doc>
+            <doc xml:space="preserve" filename="foo.c" line="302">length</doc>
             <type name="gint" c:type="int"/>
           </parameter>
         </parameters>
@@ -2065,14 +2065,14 @@ uses a C sugar return type.</doc>
               introspectable="0">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="305">This is only useful from C.</doc>
+             line="312">This is only useful from C.</doc>
         <source-position filename="foo.h" line="184"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
           <instance-parameter name="object" transfer-ownership="none">
-            <doc xml:space="preserve" filename="foo.c" line="307">obj</doc>
+            <doc xml:space="preserve" filename="foo.c" line="314">obj</doc>
             <type name="FooObject" c:type="RegressFooObject*"/>
           </instance-parameter>
         </parameters>
@@ -2198,19 +2198,19 @@ uses a C sugar return type.</doc>
           </return-value>
           <parameters>
             <parameter name="object" transfer-ownership="none">
-              <doc xml:space="preserve" filename="foo.c" line="293">obj</doc>
+              <doc xml:space="preserve" filename="foo.c" line="300">obj</doc>
               <type name="FooObject" c:type="RegressFooObject*"/>
             </parameter>
             <parameter name="offset" transfer-ownership="none">
               <doc xml:space="preserve"
                    filename="foo.c"
-                   line="294">offset</doc>
+                   line="301">offset</doc>
               <type name="gint" c:type="int"/>
             </parameter>
             <parameter name="length" transfer-ownership="none">
               <doc xml:space="preserve"
                    filename="foo.c"
-                   line="295">length</doc>
+                   line="302">length</doc>
               <type name="gint" c:type="int"/>
             </parameter>
           </parameters>
@@ -2263,13 +2263,13 @@ uses a C sugar return type.</doc>
                               transfer-ownership="full">
             <doc xml:space="preserve"
                  filename="foo.c"
-                 line="559">add to this rect</doc>
+                 line="566">add to this rect</doc>
             <type name="FooRectangle" c:type="RegressFooRectangle*"/>
           </instance-parameter>
           <parameter name="r2" transfer-ownership="none">
             <doc xml:space="preserve"
                  filename="foo.c"
-                 line="560">source rectangle</doc>
+                 line="567">source rectangle</doc>
             <type name="FooRectangle" c:type="const RegressFooRectangle*"/>
           </parameter>
         </parameters>
@@ -2279,7 +2279,7 @@ uses a C sugar return type.</doc>
                 introspectable="0">
         <doc xml:space="preserve"
              filename="foo.c"
-             line="540">This is a C convenience constructor; we have to (skip)
+             line="547">This is a C convenience constructor; we have to (skip)
 it because it's not a boxed type.</doc>
         <source-position filename="foo.h" line="357"/>
         <return-value>
@@ -6071,7 +6071,7 @@ detection, and fixing it via annotations.</doc>
               c:identifier="regress_foo_not_a_constructor_new">
       <doc xml:space="preserve"
            filename="foo.c"
-           line="792">This should be scanned as a top-level function, and shouldn't cause
+           line="799">This should be scanned as a top-level function, and shouldn't cause
 a "Can't find matching type for constructor" warning.</doc>
       <source-position filename="foo.h" line="221"/>
       <return-value transfer-ownership="none">
@@ -6084,7 +6084,7 @@ a "Can't find matching type for constructor" warning.</doc>
               introspectable="0">
       <doc xml:space="preserve"
            filename="foo.c"
-           line="540">This is a C convenience constructor; we have to (skip)
+           line="547">This is a C convenience constructor; we have to (skip)
 it because it's not a boxed type.</doc>
       <source-position filename="foo.h" line="357"/>
       <return-value>
@@ -6110,7 +6110,7 @@ it because it's not a boxed type.</doc>
               introspectable="0">
       <doc xml:space="preserve"
            filename="foo.c"
-           line="719">Does something that's only interesting from C and should not be
+           line="726">Does something that's only interesting from C and should not be
 exposed to language bindings.</doc>
       <source-position filename="foo.h" line="556"/>
       <return-value transfer-ownership="none">
@@ -6120,7 +6120,7 @@ exposed to language bindings.</doc>
         <parameter name="fs" transfer-ownership="none">
           <doc xml:space="preserve"
                filename="foo.c"
-               line="721">a #RegressFooSkippable</doc>
+               line="728">a #RegressFooSkippable</doc>
           <type name="FooSkippable" c:type="RegressFooSkippable"/>
         </parameter>
       </parameters>
@@ -6445,6 +6445,12 @@ libgnome-keyring.</doc>
         </parameter>
       </parameters>
     </function>
+    <docsection name="standalone_section">
+      <doc xml:space="preserve"
+           filename="foo.c"
+           line="8">This documentation section isn't associated with an object
+in particular, but it should be serialized in the gir nevertheless.</doc>
+    </docsection>
     <function name="test_abc_error_quark"
               c:identifier="regress_test_abc_error_quark"
               moved-to="TestABCError.quark">
diff --git a/tests/scanner/Regress-1.0-sections-expected.txt b/tests/scanner/Regress-1.0-sections-expected.txt
index b35b3a9a..a5d8f64d 100644
--- a/tests/scanner/Regress-1.0-sections-expected.txt
+++ b/tests/scanner/Regress-1.0-sections-expected.txt
@@ -389,3 +389,6 @@ RegressTestWi8021xClass
 regress_test_wi_802_1x_get_testbool
 regress_test_wi_802_1x_set_testbool
 regress_test_wi_802_1x_static_method
+
+<SECTION>
+<TITLE>standalone_section</TITLE>
diff --git a/tests/scanner/foo.c b/tests/scanner/foo.c
index 19bf848b..e409e0a3 100644
--- a/tests/scanner/foo.c
+++ b/tests/scanner/foo.c
@@ -5,6 +5,13 @@
 
 #include "foo.h"
 
+/**
+ * SECTION:standalone_section
+ *
+ * This documentation section isn't associated with an object
+ * in particular, but it should be serialized in the gir nevertheless.
+ */
+
 /* A hidden type not exposed publicly, similar to GUPNP's XML wrapper
    object */
 typedef struct _RegressFooHidden RegressFooHidden;