diff options
-rw-r--r-- | girepository/girparser.c | 3 | ||||
-rw-r--r-- | giscanner/ast.py | 5 | ||||
-rw-r--r-- | giscanner/girparser.py | 6 | ||||
-rw-r--r-- | giscanner/girwriter.py | 7 | ||||
-rw-r--r-- | giscanner/maintransformer.py | 16 | ||||
-rw-r--r-- | giscanner/sectionparser.py | 2 | ||||
-rw-r--r-- | tests/scanner/Regress-1.0-C-expected/Regress.standalone_section.page | 15 | ||||
-rw-r--r-- | tests/scanner/Regress-1.0-Gjs-expected/Regress.standalone_section.page | 15 | ||||
-rw-r--r-- | tests/scanner/Regress-1.0-Python-expected/Regress.standalone_section.page | 15 | ||||
-rw-r--r-- | tests/scanner/Regress-1.0-expected.gir | 58 | ||||
-rw-r--r-- | tests/scanner/Regress-1.0-sections-expected.txt | 3 | ||||
-rw-r--r-- | tests/scanner/foo.c | 7 |
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; |