From d893890d1098953d6740d5c8114d278b6d9875fc Mon Sep 17 00:00:00 2001 From: Giovanni Campagna Date: Tue, 28 Aug 2012 00:11:40 +0200 Subject: [PATCH] Add documentation for enumeration members Enum members were Annotated in the AST, and most code already assumed they could have docs. What was missing was reading the docs from the comment blocks and writing them in the XML. https://bugzilla.gnome.org/show_bug.cgi?id=683046 --- giscanner/girwriter.py | 3 +- giscanner/maintransformer.py | 11 ++++ tests/scanner/Annotation-1.0-expected.gir | 6 +- tests/scanner/Foo-1.0-expected.gir | 104 ++++++++++++++++++++---------- tests/scanner/Regress-1.0-expected.gir | 90 +++++++++++++++++--------- tests/scanner/SLetter-1.0-expected.gir | 18 ++++-- tests/scanner/Utility-1.0-expected.gir | 18 ++++-- tests/scanner/regress.h | 7 ++ 8 files changed, 179 insertions(+), 78 deletions(-) diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py index 97f8161..7344488 100644 --- a/giscanner/girwriter.py +++ b/giscanner/girwriter.py @@ -363,7 +363,8 @@ and/or use gtk-doc annotations. ''') ('c:identifier', member.symbol)] if member.nick is not None: attrs.append(('glib:nick', member.nick)) - self.write_tag('member', attrs) + with self.tagcontext('member', attrs): + self._write_generic(member) def _write_constant(self, constant): attrs = [('name', constant.name), diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py index d4163fa..bf276c0 100644 --- a/giscanner/maintransformer.py +++ b/giscanner/maintransformer.py @@ -215,6 +215,8 @@ usage is void (*_gtk_reserved1)(void);""" if isinstance(node, (ast.Class, ast.Interface, ast.Union, ast.Enum, ast.Bitfield, ast.Callback)): self._apply_annotations_annotated(node, self._get_block(node)) + if isinstance(node, (ast.Enum, ast.Bitfield)): + self._apply_annotations_enum_members(node, self._get_block(node)) if isinstance(node, (ast.Class, ast.Interface, ast.Record, ast.Union)): block = self._get_block(node) for field in node.fields: @@ -820,6 +822,15 @@ usage is void (*_gtk_reserved1)(void);""" if tag: node.value = tag.value + def _apply_annotations_enum_members(self, node, block): + if block is None: + return + + for m in node.members: + tag = block.params.get(m.symbol, None) + if tag is not None: + m.doc = tag.comment + def _pass_read_annotations2(self, node, chain): if isinstance(node, ast.Function): self._apply_annotations2_function(node, chain) diff --git a/tests/scanner/Annotation-1.0-expected.gir b/tests/scanner/Annotation-1.0-expected.gir index 2ea6c54..73d982d 100644 --- a/tests/scanner/Annotation-1.0-expected.gir +++ b/tests/scanner/Annotation-1.0-expected.gir @@ -17,8 +17,10 @@ and/or use gtk-doc annotations. --> c:identifier-prefixes="Annotation" c:symbol-prefixes="annotation"> - - + + + + + c:identifier="FOO_SOME_SINGLE_ENUM"> + - - - + + + + + + - - - + + + + + + - - - - + + + + + + + + + glib:nick="alpha"> + + glib:nick="beta"> + + glib:nick="delta"> + @@ -217,15 +231,18 @@ and/or use gtk-doc annotations. --> + glib:nick="good"> + + glib:nick="bad"> + + glib:nick="ugly"> + @@ -257,9 +274,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + + + glib:nick="first"> + + glib:nick="second"> + + glib:nick="third"> + @@ -693,23 +716,36 @@ it because it's not a boxed type. Some type that is only interesting from C and should not be exposed to language bindings. - - + + a skippable enum value + + + another skippable enum value + - - - - - - + + + + + + + + + + + + + c:identifier="FOO_LAYER_FOCUSED_WINDOW"> + - + c:identifier="FOO_LAYER_OVERRIDE_REDIRECT"> + + + diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir index 125a1ea..53b3adc 100644 --- a/tests/scanner/Regress-1.0-expected.gir +++ b/tests/scanner/Regress-1.0-expected.gir @@ -38,9 +38,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + + + glib:nick="code1"> + + glib:nick="code2"> + + glib:nick="code3"> + @@ -353,34 +359,44 @@ use it should be. glib:error-domain="regress-test-def-error"> + c:identifier="REGRESS_TEST_DEF_ERROR_CODE0"> + + c:identifier="REGRESS_TEST_DEF_ERROR_CODE1"> + + c:identifier="REGRESS_TEST_DEF_ERROR_CODE2"> + + By purpose, not all members have documentation + glib:nick="value1"> + value 1 + + glib:nick="value2"> + value 2 + + glib:nick="value3"> + + glib:nick="value4"> + @@ -393,9 +409,12 @@ use it should be. - - - + + + + + + + glib:nick="value1"> + + glib:nick="value2"> + + glib:nick="code1"> + + glib:nick="code2"> + + glib:nick="code3"> + @@ -440,15 +464,18 @@ use it should be. + glib:nick="flag1"> + + glib:nick="flag2"> + + glib:nick="flag3"> + + glib:nick="code1"> + + glib:nick="code2"> + + glib:nick="code3"> + @@ -1376,10 +1406,12 @@ the introspection client langage. + c:identifier="REGRESS_TEST_PUBLIC_ENUM_BEFORE"> + + c:identifier="REGRESS_TEST_PUBLIC_ENUM_AFTER"> + diff --git a/tests/scanner/SLetter-1.0-expected.gir b/tests/scanner/SLetter-1.0-expected.gir index c6da0df..0c43860 100644 --- a/tests/scanner/SLetter-1.0-expected.gir +++ b/tests/scanner/SLetter-1.0-expected.gir @@ -18,9 +18,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + + @@ -33,9 +36,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + + diff --git a/tests/scanner/Utility-1.0-expected.gir b/tests/scanner/Utility-1.0-expected.gir index 747f99c..3d73880 100644 --- a/tests/scanner/Utility-1.0-expected.gir +++ b/tests/scanner/Utility-1.0-expected.gir @@ -40,9 +40,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + + @@ -58,9 +61,12 @@ and/or use gtk-doc annotations. --> - - - + + + + + +