Merge branch 'aleksm/mkenums-since' into 'master'

glib-mkenums: allow optional 'since' tag

See merge request GNOME/glib!1492

docs/reference/gobject/glib-mkenums.xml

@@ -172,25 +172,62 @@ in your templates, to improve the reproducibility of the build. (Since: 2.22)
 Some C comments are treated specially in the parsed enum definitions,
 such comments start out with the trigraph sequence <literal>/*&lt;</literal>
 and end with the trigraph sequence <literal>&gt;*/</literal>.
-Per enum definition, the options <literal>skip</literal> and <literal>flags</literal> can be specified, to
+</para>
-indicate this enum definition to be skipped, or for it to be treated as
+
-a flags definition, or to specify the common prefix to be stripped from
+<para>The following options can be specified per enum definition:</para>
-all values to generate value nicknames, respectively. The <literal>underscore_name</literal>
+<variablelist>
-option can be used to specify the word separation used in the <function>*_get_type()</function>
+<varlistentry>
+<term><literal>skip</literal></term>
+<listitem><para>
+Indicates this enum definition should  be skipped.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>flags</literal></term>
+<listitem><para>
+Indicates this enum should be treated as a flags definition.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>underscore_name</literal></term>
+<listitem><para>
+Specifies the word separation used in the <function>*_get_type()</function>
 function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
-</para>
+</para></listitem>
-<para>
+</varlistentry>
-Per value definition, the options <literal>skip</literal> and <literal>nick</literal> are supported.
+<varlistentry>
-The former causes the value to be skipped, and the latter can be used to
+<term><literal>since</literal></term>
-specify the otherwise auto-generated nickname.
+<listitem><para>
-Examples:
+Specifies the version tag that will be used to substitute the <literal>@enumsince@</literal>
-</para>
+keyword in the template, useful when documenting methods generated from the enums
+(e.g. <literal>Since: @enumsince@</literal>). (Since: 2.66)
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>The following options can be specified per value definition:</para>
+<variablelist>
+<varlistentry>
+<term><literal>skip</literal></term>
+<listitem><para>
+Indicates the value should be skipped.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>nick</literal></term>
+<listitem><para>
+Specifies the otherwise auto-generated nickname.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Examples:</para>
 <informalexample><programlisting>
 typedef enum /*&lt; skip &gt;*/
 {
   PREFIX_FOO
 } PrefixThisEnumWillBeSkipped;
-typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
+typedef enum /*&lt; flags,prefix=PREFIX,since=1.0 &gt;*/
 {
   PREFIX_THE_ZEROTH_VALUE,	/*&lt; skip &gt;*/
   PREFIX_THE_FIRST_VALUE,

gobject/glib-mkenums.in

@@ -130,6 +130,7 @@ option_lowercase_name = ''  # DEPRECATED.  A lower case name to use as part
                             # one that we guess. For instance, when an enum
                             # uses abnormal capitalization and we can not
                             # guess where to put the underscores.
+option_since = ''           # User provided version info for the enum.
 seenbitshift = 0        # Have we seen bitshift operators?
 enum_prefix = None        # Prefix for this enumeration
 enumname = ''            # Name for this enumeration
@@ -256,6 +257,7 @@ help_epilog = '''Production text substitutions:
   \u0040ENUMNAME\u0040            PREFIX_THE_XENUM
   \u0040ENUMSHORT\u0040           THE_XENUM
   \u0040ENUMPREFIX\u0040          PREFIX
+  \u0040enumsince\u0040           the user-provided since value given
   \u0040VALUENAME\u0040           PREFIX_THE_XVALUE
   \u0040valuenick\u0040           the-xvalue
   \u0040valuenum\u0040            the integer value (limited support, Since: 2.26)
@@ -515,11 +517,13 @@ def process_file(curfilename):
                         flags = int(flags)
                 option_lowercase_name = options.get('lowercase_name', None)
                 option_underscore_name = options.get('underscore_name', None)
+                option_since = options.get('since', None)
             else:
                 enum_prefix = None
                 flags = None
                 option_lowercase_name = None
                 option_underscore_name = None
+                option_since = None
 
             if option_lowercase_name is not None:
                 if option_underscore_name is not None:
@@ -620,6 +624,11 @@ def process_file(curfilename):
                 enumlong = enumname_prefix + "_" + enumshort
                 enumsym = enumlong.lower()
 
+            if option_since is not None:
+                enumsince = option_since
+            else:
+                enumsince = ""
+
             if firstenum:
                 firstenum = False
 
@@ -641,6 +650,7 @@ def process_file(curfilename):
                 prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
                 prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
                 prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
+                prod = prod.replace('\u0040enumsince\u0040', enumsince)
                 if flags:
                     prod = prod.replace('\u0040type\u0040', 'flags')
                 else:
@@ -663,6 +673,7 @@ def process_file(curfilename):
                 prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
                 prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
                 prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
+                prod = prod.replace('\u0040enumsince\u0040', enumsince)
                 if flags:
                     prod = prod.replace('\u0040type\u0040', 'flags')
                 else:
@@ -729,6 +740,7 @@ def process_file(curfilename):
                 prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
                 prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
                 prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
+                prod = prod.replace('\u0040enumsince\u0040', enumsince)
                 if flags:
                     prod = prod.replace('\u0040type\u0040', 'flags')
                 else:

gobject/tests/mkenums.py

@@ -153,6 +153,7 @@ enum_name: @enum_name@
 ENUMNAME: @ENUMNAME@
 ENUMSHORT: @ENUMSHORT@
 ENUMPREFIX: @ENUMPREFIX@
+enumsince: @enumsince@
 type: @type@
 Type: @Type@
 TYPE: @TYPE@
@@ -165,6 +166,7 @@ enum_name: @enum_name@
 ENUMNAME: @ENUMNAME@
 ENUMSHORT: @ENUMSHORT@
 ENUMPREFIX: @ENUMPREFIX@
+enumsince: @enumsince@
 type: @type@
 Type: @Type@
 TYPE: @TYPE@
@@ -187,6 +189,7 @@ enum_name: @enum_name@
 ENUMNAME: @ENUMNAME@
 ENUMSHORT: @ENUMSHORT@
 ENUMPREFIX: @ENUMPREFIX@
+enumsince: @enumsince@
 type: @type@
 Type: @Type@
 TYPE: @TYPE@
@@ -225,7 +228,7 @@ file-tail
 
     def assertSingleEnum(self, result, enum_name_camel, enum_name_lower,
                          enum_name_upper, enum_name_short, enum_prefix,
-                         type_lower, type_camel, type_upper,
+                         enum_since, type_lower, type_camel, type_upper,
                          value_name, value_nick, value_num):
         """Assert that out (from runMkenumsWithHeader()) contains a single
            enum and value matching the given arguments."""
@@ -235,6 +238,7 @@ file-tail
             'enum_name_upper': enum_name_upper,
             'enum_name_short': enum_name_short,
             'enum_prefix': enum_prefix,
+            'enum_since': enum_since,
             'type_lower': type_lower,
             'type_camel': type_camel,
             'type_upper': type_upper,
@@ -258,6 +262,7 @@ enum_name: {enum_name_lower}
 ENUMNAME: {enum_name_upper}
 ENUMSHORT: {enum_name_short}
 ENUMPREFIX: {enum_prefix}
+enumsince: {enum_since}
 type: {type_lower}
 Type: {type_camel}
 TYPE: {type_upper}
@@ -267,6 +272,7 @@ enum_name: {enum_name_lower}
 ENUMNAME: {enum_name_upper}
 ENUMSHORT: {enum_name_short}
 ENUMPREFIX: {enum_prefix}
+enumsince: {enum_since}
 type: {type_lower}
 Type: {type_camel}
 TYPE: {type_upper}
@@ -283,6 +289,7 @@ enum_name: {enum_name_lower}
 ENUMNAME: {enum_name_upper}
 ENUMSHORT: {enum_name_short}
 ENUMPREFIX: {enum_prefix}
+enumsince: {enum_since}
 type: {type_lower}
 Type: {type_camel}
 TYPE: {type_upper}
@@ -360,7 +367,7 @@ comment: {standard_bottom_comment}
         self.assertEqual('', result.err)
         self.assertSingleEnum(result, 'SomeEnumIdentifier',
                               'some_enum_identifier', 'SOME_ENUM_IDENTIFIER',
-                              'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum',
+                              'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum',
                               'ENUM', 'ENUM_VALUE', 'value', '0')
 
     def test_non_utf8_encoding(self):
@@ -375,7 +382,7 @@ comment: {standard_bottom_comment}
         self.assertIn('WARNING: UnicodeWarning: ', result.err)
         self.assertSingleEnum(result, 'SomeEnumIdentifier',
                               'some_enum_identifier', 'SOME_ENUM_IDENTIFIER',
-                              'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum',
+                              'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum',
                               'ENUM', 'ENUM_VALUE', 'value', '0')
 
     def test_reproducible(self):
@@ -430,7 +437,7 @@ comment: {standard_bottom_comment}
         self.assertEqual('', result.err)
         self.assertSingleEnum(result, 'GeglSamplerType',
                               'gegl_sampler_type', 'GEGL_SAMPLER_TYPE',
-                              'SAMPLER_TYPE', 'GEGL', 'enum', 'Enum',
+                              'SAMPLER_TYPE', 'GEGL', '', 'enum', 'Enum',
                               'ENUM', 'GEGL_SAMPLER_NEAREST', 'nearest', '0')
 
     def test_filename_basename_in_fhead_ftail(self):
@@ -477,6 +484,20 @@ comment
 comment: {standard_bottom_comment}
 '''.format(**result.subs).strip(), result.out)
 
+    def test_since(self):
+        """Test user-provided 'since' version handling
+        https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1492"""
+        h_contents = '''
+        typedef enum { /*< since=1.0 >*/
+            QMI_WMS_MESSAGE_PROTOCOL_CDMA = 0,
+        } QmiWmsMessageProtocol;
+        '''
+        result = self.runMkenumsWithHeader(h_contents)
+        self.assertEqual('', result.err)
+        self.assertSingleEnum(result, 'QmiWmsMessageProtocol',
+                              'qmi_wms_message_protocol', 'QMI_WMS_MESSAGE_PROTOCOL',
+                              'WMS_MESSAGE_PROTOCOL', 'QMI', '1.0', 'enum', 'Enum',
+                              'ENUM', 'QMI_WMS_MESSAGE_PROTOCOL_CDMA', 'cdma', '0')
 
 class TestRspMkenums(TestMkenums):
     '''Run all tests again in @rspfile mode'''