build-aux,mkenums: new 'since' tag support in mkenums

The mkenums change has been shared with upstream glib for comments:
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1492

This change allows us to have one single documentation method
associated to each enum/flag, instead of keeping the version info in a
separate documentation block, which gobject-introspection doesn't like.

4 files changed, 16 insertions, 0 deletions

diff --git a/build-aux/qmi-mkenums b/build-aux/qmi-mkenums
index 826bf82..8531317 100755
--- a/build-aux/qmi-mkenums
+++ b/build-aux/qmi-mkenums
@@ -133,6 +133,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
@@ -259,6 +260,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 (qmi-mkenums only)
   \u0040VALUENAME\u0040           PREFIX_THE_XVALUE
   \u0040valuenick\u0040           the-xvalue
   \u0040valuenum\u0040            the integer value (limited support, Since: 2.26)
@@ -518,11 +520,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:
@@ -623,6 +627,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
 
@@ -644,6 +653,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:
@@ -666,6 +676,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:
@@ -732,6 +743,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:
diff --git a/build-aux/templates/qmi-enum-types-template.h b/build-aux/templates/qmi-enum-types-template.h
index 3457e9b..5500038 100644
--- a/build-aux/templates/qmi-enum-types-template.h
+++ b/build-aux/templates/qmi-enum-types-template.h
@@ -25,6 +25,7 @@ GType @enum_name@_get_type (void) G_GNUC_CONST;
  * Gets the nickname string for the #@EnumName@ specified at @val.
  *
  * Returns: (transfer none): a string with the nickname, or %NULL if not found. Do not free the returned value.
+ * Since: @enumsince@
  */
 const gchar *@enum_name@_get_string (@EnumName@ val);
 #endif
@@ -38,6 +39,7 @@ const gchar *@enum_name@_get_string (@EnumName@ val);
  * each #@EnumName@ in @mask.
  *
  * Returns: (transfer full): a string with the list of nicknames, or %NULL if none given. The returned value should be freed with g_free().
+ * Since: @enumsince@
  */
 gchar *@enum_name@_build_string_from_mask (@EnumName@ mask);
 #endif
diff --git a/build-aux/templates/qmi-error-types-template.h b/build-aux/templates/qmi-error-types-template.h
index b0dfdb2..0af0374 100644
--- a/build-aux/templates/qmi-error-types-template.h
+++ b/build-aux/templates/qmi-error-types-template.h
@@ -23,6 +23,7 @@ GType  @enum_name@_get_type (void) G_GNUC_CONST;
  * Gets the nickname string for the #@EnumName@ specified at @val.
  *
  * Returns: (transfer none): a string with the nickname, or %NULL if not found. Do not free the returned value.
+ * Since: @enumsince@
  */
 const gchar *@enum_name@_get_string (@EnumName@ val);
 /*** END value-header ***/
diff --git a/build-aux/templates/qmi-flags64-types-template.h b/build-aux/templates/qmi-flags64-types-template.h
index f471c29..9ba53cb 100644
--- a/build-aux/templates/qmi-flags64-types-template.h
+++ b/build-aux/templates/qmi-flags64-types-template.h
@@ -26,6 +26,7 @@ G_BEGIN_DECLS
  * each #@EnumName@ in @mask.
  *
  * Returns: (transfer full): a string with the list of nicknames, or %NULL if none given. The returned value should be freed with g_free().
+ * Since: @enumsince@
  */
 gchar *@enum_name@_build_string_from_mask (@EnumName@ mask);