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

diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py
index 97f8161..7344488 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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">
     <bitfield name="Bitfield" c:type="AnnotationBitfield">
-      <member name="foo" value="1" c:identifier="ANN_FLAG_FOO"/>
-      <member name="bar" value="2" c:identifier="ANN_FLAG_BAR"/>
+      <member name="foo" value="1" c:identifier="ANN_FLAG_FOO">
+      </member>
+      <member name="bar" value="2" c:identifier="ANN_FLAG_BAR">
+      </member>
     </bitfield>
     <constant name="CALCULATED_DEFINE"
               value="100"

diff --git a/tests/scanner/Foo-1.0-expected.gir b/tests/scanner/Foo-1.0-expected.gir
index b0c3634..048ed42 100644 (file)
--- a/tests/scanner/Foo-1.0-expected.gir
+++ b/tests/scanner/Foo-1.0-expected.gir
@@ -26,12 +26,16 @@ and/or use gtk-doc annotations.  -->
     <enumeration name="ASingle" c:type="FooASingle">
       <member name="some_single_enum"
               value="0"
-              c:identifier="FOO_SOME_SINGLE_ENUM"/>
+              c:identifier="FOO_SOME_SINGLE_ENUM">
+      </member>
     </enumeration>
     <enumeration name="AddressType" c:type="FooAddressType">
-      <member name="invalid" value="0" c:identifier="FOO_ADDRESS_INVALID"/>
-      <member name="ipv4" value="1" c:identifier="FOO_ADDRESS_IPV4"/>
-      <member name="ipv6" value="2" c:identifier="FOO_ADDRESS_IPV6"/>
+      <member name="invalid" value="0" c:identifier="FOO_ADDRESS_INVALID">
+      </member>
+      <member name="ipv4" value="1" c:identifier="FOO_ADDRESS_IPV4">
+      </member>
+      <member name="ipv6" value="2" c:identifier="FOO_ADDRESS_IPV6">
+      </member>
     </enumeration>
     <record name="BRect"
             c:type="FooBRect"
@@ -162,15 +166,22 @@ and/or use gtk-doc annotations.  -->
       <type name="utf8" c:type="gchar*"/>
     </constant>
     <enumeration name="EnumFullname" c:type="FooEnumFullname">
-      <member name="one" value="1" c:identifier="FOO_ENUM_FULLNAME_ONE"/>
-      <member name="two" value="2" c:identifier="FOO_ENUM_FULLNAME_TWO"/>
-      <member name="three" value="3" c:identifier="FOO_ENUM_FULLNAME_THREE"/>
+      <member name="one" value="1" c:identifier="FOO_ENUM_FULLNAME_ONE">
+      </member>
+      <member name="two" value="2" c:identifier="FOO_ENUM_FULLNAME_TWO">
+      </member>
+      <member name="three" value="3" c:identifier="FOO_ENUM_FULLNAME_THREE">
+      </member>
     </enumeration>
     <enumeration name="EnumNoType" c:type="FooEnumNoType">
-      <member name="un" value="1" c:identifier="FOO_ENUM_UN"/>
-      <member name="deux" value="2" c:identifier="FOO_ENUM_DEUX"/>
-      <member name="trois" value="3" c:identifier="FOO_ENUM_TROIS"/>
-      <member name="neuf" value="9" c:identifier="FOO_ENUM_NEUF"/>
+      <member name="un" value="1" c:identifier="FOO_ENUM_UN">
+      </member>
+      <member name="deux" value="2" c:identifier="FOO_ENUM_DEUX">
+      </member>
+      <member name="trois" value="3" c:identifier="FOO_ENUM_TROIS">
+      </member>
+      <member name="neuf" value="9" c:identifier="FOO_ENUM_NEUF">
+      </member>
     </enumeration>
     <enumeration name="EnumType"
                  glib:type-name="FooEnumType"
@@ -179,15 +190,18 @@ and/or use gtk-doc annotations.  -->
       <member name="alpha"
               value="0"
               c:identifier="FOO_ENUM_ALPHA"
-              glib:nick="alpha"/>
+              glib:nick="alpha">
+      </member>
       <member name="beta"
               value="1"
               c:identifier="FOO_ENUM_BETA"
-              glib:nick="beta"/>
+              glib:nick="beta">
+      </member>
       <member name="delta"
               value="2"
               c:identifier="FOO_ENUM_DELTA"
-              glib:nick="delta"/>
+              glib:nick="delta">
+      </member>
       <function name="method" c:identifier="foo_enum_type_method">
         <return-value transfer-ownership="none">
           <type name="gint" c:type="int"/>
@@ -217,15 +231,18 @@ and/or use gtk-doc annotations.  -->
       <member name="good"
               value="0"
               c:identifier="FOO_ERROR_GOOD"
-              glib:nick="good"/>
+              glib:nick="good">
+      </member>
       <member name="bad"
               value="1"
               c:identifier="FOO_ERROR_BAD"
-              glib:nick="bad"/>
+              glib:nick="bad">
+      </member>
       <member name="ugly"
               value="2"
               c:identifier="FOO_ERROR_UGLY"
-              glib:nick="ugly"/>
+              glib:nick="ugly">
+      </member>
       <function name="quark" c:identifier="foo_error_quark">
         <return-value transfer-ownership="none">
           <type name="GLib.Quark" c:type="GQuark"/>
@@ -257,9 +274,12 @@ and/or use gtk-doc annotations.  -->
       </field>
     </record>
     <bitfield name="FlagsNoType" c:type="FooFlagsNoType">
-      <member name="ett" value="1" c:identifier="FOO_FLAGS_ETT"/>
-      <member name="tva" value="2" c:identifier="FOO_FLAGS_TVA"/>
-      <member name="fyra" value="4" c:identifier="FOO_FLAGS_FYRA"/>
+      <member name="ett" value="1" c:identifier="FOO_FLAGS_ETT">
+      </member>
+      <member name="tva" value="2" c:identifier="FOO_FLAGS_TVA">
+      </member>
+      <member name="fyra" value="4" c:identifier="FOO_FLAGS_FYRA">
+      </member>
     </bitfield>
     <bitfield name="FlagsType"
               glib:type-name="FooFlagsType"
@@ -268,15 +288,18 @@ and/or use gtk-doc annotations.  -->
       <member name="first"
               value="1"
               c:identifier="FOO_FLAGS_FIRST"
-              glib:nick="first"/>
+              glib:nick="first">
+      </member>
       <member name="second"
               value="2"
               c:identifier="FOO_FLAGS_SECOND"
-              glib:nick="second"/>
+              glib:nick="second">
+      </member>
       <member name="third"
               value="4"
               c:identifier="FOO_FLAGS_THIRD"
-              glib:nick="third"/>
+              glib:nick="third">
+      </member>
     </bitfield>
     <record name="ForeignStruct" c:type="FooForeignStruct" foreign="1">
       <field name="foo" writable="1">
@@ -693,23 +716,36 @@ it because it's not a boxed type.</doc>
     <enumeration name="Skippable" introspectable="0" c:type="FooSkippable">
       <doc xml:whitespace="preserve">Some type that is only interesting from C and should not be
 exposed to language bindings.</doc>
-      <member name="one" value="0" c:identifier="FOO_SKIPPABLE_ONE"/>
-      <member name="two" value="1" c:identifier="FOO_SKIPPABLE_TWO"/>
+      <member name="one" value="0" c:identifier="FOO_SKIPPABLE_ONE">
+        <doc xml:whitespace="preserve">a skippable enum value</doc>
+      </member>
+      <member name="two" value="1" c:identifier="FOO_SKIPPABLE_TWO">
+        <doc xml:whitespace="preserve">another skippable enum value</doc>
+      </member>
     </enumeration>
     <enumeration name="StackLayer" c:type="FooStackLayer">
-      <member name="desktop" value="0" c:identifier="FOO_LAYER_DESKTOP"/>
-      <member name="bottom" value="1" c:identifier="FOO_LAYER_BOTTOM"/>
-      <member name="normal" value="2" c:identifier="FOO_LAYER_NORMAL"/>
-      <member name="top" value="4" c:identifier="FOO_LAYER_TOP"/>
-      <member name="dock" value="4" c:identifier="FOO_LAYER_DOCK"/>
-      <member name="fullscreen" value="5" c:identifier="FOO_LAYER_FULLSCREEN"/>
+      <member name="desktop" value="0" c:identifier="FOO_LAYER_DESKTOP">
+      </member>
+      <member name="bottom" value="1" c:identifier="FOO_LAYER_BOTTOM">
+      </member>
+      <member name="normal" value="2" c:identifier="FOO_LAYER_NORMAL">
+      </member>
+      <member name="top" value="4" c:identifier="FOO_LAYER_TOP">
+      </member>
+      <member name="dock" value="4" c:identifier="FOO_LAYER_DOCK">
+      </member>
+      <member name="fullscreen" value="5" c:identifier="FOO_LAYER_FULLSCREEN">
+      </member>
       <member name="focused_window"
               value="6"
-              c:identifier="FOO_LAYER_FOCUSED_WINDOW"/>
+              c:identifier="FOO_LAYER_FOCUSED_WINDOW">
+      </member>
       <member name="override_redirect"
               value="7"
-              c:identifier="FOO_LAYER_OVERRIDE_REDIRECT"/>
-      <member name="last" value="8" c:identifier="FOO_LAYER_LAST"/>
+              c:identifier="FOO_LAYER_OVERRIDE_REDIRECT">
+      </member>
+      <member name="last" value="8" c:identifier="FOO_LAYER_LAST">
+      </member>
     </enumeration>
     <record name="Struct" c:type="FooStruct">
       <field name="priv" writable="1">

diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index 125a1ea..53b3adc 100644 (file)
--- 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.  -->
     <enumeration name="ATestError"
                  c:type="RegressATestError"
                  glib:error-domain="regress-atest-error">
-      <member name="code0" value="0" c:identifier="REGRESS_ATEST_ERROR_CODE0"/>
-      <member name="code1" value="1" c:identifier="REGRESS_ATEST_ERROR_CODE1"/>
-      <member name="code2" value="2" c:identifier="REGRESS_ATEST_ERROR_CODE2"/>
+      <member name="code0" value="0" c:identifier="REGRESS_ATEST_ERROR_CODE0">
+      </member>
+      <member name="code1" value="1" c:identifier="REGRESS_ATEST_ERROR_CODE1">
+      </member>
+      <member name="code2" value="2" c:identifier="REGRESS_ATEST_ERROR_CODE2">
+      </member>
     </enumeration>
     <constant name="DOUBLE_CONSTANT"
               value="44.220000"
@@ -117,15 +120,18 @@ use it should be.</doc>
       <member name="code1"
               value="1"
               c:identifier="REGRESS_TEST_ABC_ERROR_CODE1"
-              glib:nick="code1"/>
+              glib:nick="code1">
+      </member>
       <member name="code2"
               value="2"
               c:identifier="REGRESS_TEST_ABC_ERROR_CODE2"
-              glib:nick="code2"/>
+              glib:nick="code2">
+      </member>
       <member name="code3"
               value="3"
               c:identifier="REGRESS_TEST_ABC_ERROR_CODE3"
-              glib:nick="code3"/>
+              glib:nick="code3">
+      </member>
       <function name="quark" c:identifier="regress_test_abc_error_quark">
         <return-value transfer-ownership="none">
           <type name="GLib.Quark" c:type="GQuark"/>
@@ -353,34 +359,44 @@ use it should be.</doc>
                  glib:error-domain="regress-test-def-error">
       <member name="code0"
               value="0"
-              c:identifier="REGRESS_TEST_DEF_ERROR_CODE0"/>
+              c:identifier="REGRESS_TEST_DEF_ERROR_CODE0">
+      </member>
       <member name="code1"
               value="1"
-              c:identifier="REGRESS_TEST_DEF_ERROR_CODE1"/>
+              c:identifier="REGRESS_TEST_DEF_ERROR_CODE1">
+      </member>
       <member name="code2"
               value="2"
-              c:identifier="REGRESS_TEST_DEF_ERROR_CODE2"/>
+              c:identifier="REGRESS_TEST_DEF_ERROR_CODE2">
+      </member>
     </enumeration>
     <enumeration name="TestEnum"
                  glib:type-name="RegressTestEnum"
                  glib:get-type="regress_test_enum_get_type"
                  c:type="RegressTestEnum">
+      <doc xml:whitespace="preserve">By purpose, not all members have documentation</doc>
       <member name="value1"
               value="0"
               c:identifier="REGRESS_TEST_VALUE1"
-              glib:nick="value1"/>
+              glib:nick="value1">
+        <doc xml:whitespace="preserve">value 1</doc>
+      </member>
       <member name="value2"
               value="1"
               c:identifier="REGRESS_TEST_VALUE2"
-              glib:nick="value2"/>
+              glib:nick="value2">
+        <doc xml:whitespace="preserve">value 2</doc>
+      </member>
       <member name="value3"
               value="-1"
               c:identifier="REGRESS_TEST_VALUE3"
-              glib:nick="value3"/>
+              glib:nick="value3">
+      </member>
       <member name="value4"
               value="48"
               c:identifier="REGRESS_TEST_VALUE4"
-              glib:nick="value4"/>
+              glib:nick="value4">
+      </member>
       <function name="param" c:identifier="regress_test_enum_param">
         <return-value transfer-ownership="none">
           <type name="utf8" c:type="const gchar*"/>
@@ -393,9 +409,12 @@ use it should be.</doc>
       </function>
     </enumeration>
     <enumeration name="TestEnumNoGEnum" c:type="RegressTestEnumNoGEnum">
-      <member name="evalue1" value="0" c:identifier="REGRESS_TEST_EVALUE1"/>
-      <member name="evalue2" value="42" c:identifier="REGRESS_TEST_EVALUE2"/>
-      <member name="evalue3" value="48" c:identifier="REGRESS_TEST_EVALUE3"/>
+      <member name="evalue1" value="0" c:identifier="REGRESS_TEST_EVALUE1">
+      </member>
+      <member name="evalue2" value="42" c:identifier="REGRESS_TEST_EVALUE2">
+      </member>
+      <member name="evalue3" value="48" c:identifier="REGRESS_TEST_EVALUE3">
+      </member>
     </enumeration>
     <enumeration name="TestEnumUnsigned"
                  glib:type-name="RegressTestEnumUnsigned"
@@ -404,11 +423,13 @@ use it should be.</doc>
       <member name="value1"
               value="1"
               c:identifier="REGRESS_TEST_UNSIGNED_VALUE1"
-              glib:nick="value1"/>
+              glib:nick="value1">
+      </member>
       <member name="value2"
               value="2147483648"
               c:identifier="REGRESS_TEST_UNSIGNED_VALUE2"
-              glib:nick="value2"/>
+              glib:nick="value2">
+      </member>
     </enumeration>
     <enumeration name="TestError"
                  glib:type-name="RegressTestError"
@@ -418,15 +439,18 @@ use it should be.</doc>
       <member name="code1"
               value="1"
               c:identifier="REGRESS_TEST_ERROR_CODE1"
-              glib:nick="code1"/>
+              glib:nick="code1">
+      </member>
       <member name="code2"
               value="2"
               c:identifier="REGRESS_TEST_ERROR_CODE2"
-              glib:nick="code2"/>
+              glib:nick="code2">
+      </member>
       <member name="code3"
               value="3"
               c:identifier="REGRESS_TEST_ERROR_CODE3"
-              glib:nick="code3"/>
+              glib:nick="code3">
+      </member>
       <function name="quark" c:identifier="regress_test_error_quark">
         <return-value transfer-ownership="none">
           <type name="GLib.Quark" c:type="GQuark"/>
@@ -440,15 +464,18 @@ use it should be.</doc>
       <member name="flag1"
               value="1"
               c:identifier="TEST_FLAG1"
-              glib:nick="flag1"/>
+              glib:nick="flag1">
+      </member>
       <member name="flag2"
               value="2"
               c:identifier="TEST_FLAG2"
-              glib:nick="flag2"/>
+              glib:nick="flag2">
+      </member>
       <member name="flag3"
               value="4"
               c:identifier="TEST_FLAG3"
-              glib:nick="flag3"/>
+              glib:nick="flag3">
+      </member>
     </bitfield>
     <class name="TestFloating"
            c:symbol-prefix="test_floating"
@@ -1357,15 +1384,18 @@ the introspection client langage.</doc>
       <member name="code1"
               value="1"
               c:identifier="REGRESS_TEST_OTHER_ERROR_CODE1"
-              glib:nick="code1"/>
+              glib:nick="code1">
+      </member>
       <member name="code2"
               value="2"
               c:identifier="REGRESS_TEST_OTHER_ERROR_CODE2"
-              glib:nick="code2"/>
+              glib:nick="code2">
+      </member>
       <member name="code3"
               value="3"
               c:identifier="REGRESS_TEST_OTHER_ERROR_CODE3"
-              glib:nick="code3"/>
+              glib:nick="code3">
+      </member>
       <function name="quark"
                 c:identifier="regress_test_unconventional_error_quark">
         <return-value transfer-ownership="none">
@@ -1376,10 +1406,12 @@ the introspection client langage.</doc>
     <bitfield name="TestPrivateEnum" c:type="RegressTestPrivateEnum">
       <member name="public_enum_before"
               value="1"
-              c:identifier="REGRESS_TEST_PUBLIC_ENUM_BEFORE"/>
+              c:identifier="REGRESS_TEST_PUBLIC_ENUM_BEFORE">
+      </member>
       <member name="public_enum_after"
               value="4"
-              c:identifier="REGRESS_TEST_PUBLIC_ENUM_AFTER"/>
+              c:identifier="REGRESS_TEST_PUBLIC_ENUM_AFTER">
+      </member>
     </bitfield>
     <record name="TestPrivateStruct" c:type="RegressTestPrivateStruct">
       <field name="this_is_public_before" writable="1">

diff --git a/tests/scanner/SLetter-1.0-expected.gir b/tests/scanner/SLetter-1.0-expected.gir
index c6da0df..0c43860 100644 (file)
--- 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.  -->
     <enumeration name="DBusError"
                  c:type="SDBusError"
                  glib:error-domain="s-dbus-error">
-      <member name="code1" value="1" c:identifier="S_DBUS_ERROR_CODE1"/>
-      <member name="code2" value="2" c:identifier="S_DBUS_ERROR_CODE2"/>
-      <member name="code3" value="3" c:identifier="S_DBUS_ERROR_CODE3"/>
+      <member name="code1" value="1" c:identifier="S_DBUS_ERROR_CODE1">
+      </member>
+      <member name="code2" value="2" c:identifier="S_DBUS_ERROR_CODE2">
+      </member>
+      <member name="code3" value="3" c:identifier="S_DBUS_ERROR_CODE3">
+      </member>
     </enumeration>
     <record name="Point" c:type="SPoint">
       <field name="x" writable="1">
@@ -33,9 +36,12 @@ and/or use gtk-doc annotations.  -->
     <enumeration name="SpawnError"
                  c:type="SSpawnError"
                  glib:error-domain="s-spawn-error">
-      <member name="code1" value="1" c:identifier="S_SPAWN_ERROR_CODE1"/>
-      <member name="code2" value="2" c:identifier="S_SPAWN_ERROR_CODE2"/>
-      <member name="code3" value="3" c:identifier="S_SPAWN_ERROR_CODE3"/>
+      <member name="code1" value="1" c:identifier="S_SPAWN_ERROR_CODE1">
+      </member>
+      <member name="code2" value="2" c:identifier="S_SPAWN_ERROR_CODE2">
+      </member>
+      <member name="code3" value="3" c:identifier="S_SPAWN_ERROR_CODE3">
+      </member>
     </enumeration>
     <function name="dbus_error_quark" c:identifier="s_dbus_error_quark">
       <return-value transfer-ownership="none">

diff --git a/tests/scanner/Utility-1.0-expected.gir b/tests/scanner/Utility-1.0-expected.gir
index 747f99c..3d73880 100644 (file)
--- 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.  -->
       </record>
     </union>
     <enumeration name="EnumType" c:type="UtilityEnumType">
-      <member name="a" value="0" c:identifier="UTILITY_ENUM_A"/>
-      <member name="b" value="1" c:identifier="UTILITY_ENUM_B"/>
-      <member name="c" value="2" c:identifier="UTILITY_ENUM_C"/>
+      <member name="a" value="0" c:identifier="UTILITY_ENUM_A">
+      </member>
+      <member name="b" value="1" c:identifier="UTILITY_ENUM_B">
+      </member>
+      <member name="c" value="2" c:identifier="UTILITY_ENUM_C">
+      </member>
     </enumeration>
     <callback name="FileFunc" c:type="UtilityFileFunc">
       <return-value transfer-ownership="none">
@@ -58,9 +61,12 @@ and/or use gtk-doc annotations.  -->
       </parameters>
     </callback>
     <bitfield name="FlagType" c:type="UtilityFlagType">
-      <member name="a" value="1" c:identifier="UTILITY_FLAG_A"/>
-      <member name="b" value="2" c:identifier="UTILITY_FLAG_B"/>
-      <member name="c" value="4" c:identifier="UTILITY_FLAG_C"/>
+      <member name="a" value="1" c:identifier="UTILITY_FLAG_A">
+      </member>
+      <member name="b" value="2" c:identifier="UTILITY_FLAG_B">
+      </member>
+      <member name="c" value="4" c:identifier="UTILITY_FLAG_C">
+      </member>
     </bitfield>
     <class name="Object"
            c:symbol-prefix="object"

diff --git a/tests/scanner/regress.h b/tests/scanner/regress.h
index b1a8286..aba29df 100644 (file)
--- a/tests/scanner/regress.h
+++ b/tests/scanner/regress.h
@@ -150,6 +150,13 @@ GVariant *regress_test_gvariant_as (void);
 
 #define NUM_REGRESS_FOO
 
+/**
+ * RegressTestEnum:
+ * @REGRESS_TEST_VALUE1: value 1
+ * @REGRESS_TEST_VALUE2: value 2
+ *
+ * By purpose, not all members have documentation
+ */
 typedef enum
 {
   REGRESS_TEST_VALUE1,