[glib: 1/2] gparamspec: mark nick/blurb as nullable

[Sebastian Dröge <sdroege src gnome org>]

commit 79c70d7a362f4b793363275cbe37d3c08f7ea884
Author: Andy Holmes <andrew g r holmes gmail com>
Date:   Sun Aug 21 15:52:38 2022 -0700

    gparamspec: mark nick/blurb as nullable
    
    GParamSpec nicks and blurbs are effectively a deprecated feature,
    or at least unused by most libraries these days. Since a number
    of C libraries (i.e. GTK4) have started to null these out, annotate
    them as `(nullable)` so bindings can do the same.
    
    Closes #2719

 gobject/gparam.c      | 15 +++++----
 gobject/gparamspecs.c | 88 +++++++++++++++++++++++++--------------------------
 2 files changed, 52 insertions(+), 51 deletions(-)
---
diff --git a/gobject/gparam.c b/gobject/gparam.c
index 14238521b1..6c1a481311 100644
--- a/gobject/gparam.c
+++ b/gobject/gparam.c
@@ -425,8 +425,8 @@ g_param_spec_is_valid_name (const gchar *name)
  * g_param_spec_internal: (skip)
  * @param_type: the #GType for the property; must be derived from %G_TYPE_PARAM
  * @name: the canonical name of the property
- * @nick: the nickname of the property
- * @blurb: a short description of the property
+ * @nick: (nullable): the nickname of the property
+ * @blurb: (nullable): a short description of the property
  * @flags: a combination of #GParamFlags
  *
  * Creates a new #GParamSpec instance.
@@ -435,11 +435,12 @@ g_param_spec_is_valid_name (const gchar *name)
  * the rules for @name. Names which violate these rules lead to undefined
  * behaviour.
  *
- * Beyond the name, #GParamSpecs have two more descriptive
- * strings associated with them, the @nick, which should be suitable
- * for use as a label for the property in a property editor, and the
- * @blurb, which should be a somewhat longer description, suitable for
- * e.g. a tooltip. The @nick and @blurb should ideally be localized.
+ * Beyond the name, #GParamSpecs have two more descriptive strings, the
+ * @nick and @blurb, which may be used as a localized label and description.
+ * For GTK and related libraries these are considered deprecated and may be
+ * omitted, while for other libraries such as GStreamer and its plugins they
+ * are essential. When in doubt, follow the conventions used in the
+ * surrounding code and supporting libraries.
  *
  * Returns: (type GObject.ParamSpec): (transfer floating): a newly allocated
  *     #GParamSpec instance, which is initially floating
diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c
index 8299b605a2..f17b3488b9 100644
--- a/gobject/gparamspecs.c
+++ b/gobject/gparamspecs.c
@@ -1852,8 +1852,8 @@ _g_param_spec_types_init (void)
 /**
  * g_param_spec_char:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -1892,8 +1892,8 @@ g_param_spec_char (const gchar *name,
 /**
  * g_param_spec_uchar:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -1932,8 +1932,8 @@ g_param_spec_uchar (const gchar *name,
 /**
  * g_param_spec_boolean:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @default_value: default value for the property specified
  * @flags: flags for the property specified
  *
@@ -1972,8 +1972,8 @@ g_param_spec_boolean (const gchar *name,
 /**
  * g_param_spec_int:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2014,8 +2014,8 @@ g_param_spec_int (const gchar *name,
 /**
  * g_param_spec_uint:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2056,8 +2056,8 @@ g_param_spec_uint (const gchar *name,
 /**
  * g_param_spec_long:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2098,8 +2098,8 @@ g_param_spec_long (const gchar *name,
 /**
  * g_param_spec_ulong:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2141,8 +2141,8 @@ g_param_spec_ulong (const gchar *name,
 /**
  * g_param_spec_int64:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2183,8 +2183,8 @@ g_param_spec_int64 (const gchar *name,
 /**
  * g_param_spec_uint64:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2226,8 +2226,8 @@ g_param_spec_uint64 (const gchar *name,
 /**
  * g_param_spec_unichar:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @default_value: default value for the property specified
  * @flags: flags for the property specified
  *
@@ -2262,8 +2262,8 @@ g_param_spec_unichar (const gchar *name,
 /**
  * g_param_spec_enum:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @enum_type: a #GType derived from %G_TYPE_ENUM
  * @default_value: default value for the property specified
  * @flags: flags for the property specified
@@ -2308,8 +2308,8 @@ g_param_spec_enum (const gchar *name,
 /**
  * g_param_spec_flags:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @flags_type: a #GType derived from %G_TYPE_FLAGS
  * @default_value: default value for the property specified
  * @flags: flags for the property specified
@@ -2354,8 +2354,8 @@ g_param_spec_flags (const gchar *name,
 /**
  * g_param_spec_float:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2396,8 +2396,8 @@ g_param_spec_float (const gchar *name,
 /**
  * g_param_spec_double:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @minimum: minimum value for the property specified
  * @maximum: maximum value for the property specified
  * @default_value: default value for the property specified
@@ -2439,8 +2439,8 @@ g_param_spec_double (const gchar *name,
 /**
  * g_param_spec_string:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @default_value: (nullable): default value for the property specified
  * @flags: flags for the property specified
  *
@@ -2472,8 +2472,8 @@ g_param_spec_string (const gchar *name,
 /**
  * g_param_spec_param:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @param_type: a #GType derived from %G_TYPE_PARAM
  * @flags: flags for the property specified
  *
@@ -2509,8 +2509,8 @@ g_param_spec_param (const gchar *name,
 /**
  * g_param_spec_boxed:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @boxed_type: %G_TYPE_BOXED derived type of this property
  * @flags: flags for the property specified
  *
@@ -2547,8 +2547,8 @@ g_param_spec_boxed (const gchar *name,
 /**
  * g_param_spec_pointer:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecPointer instance specifying a pointer property.
@@ -2579,8 +2579,8 @@ g_param_spec_pointer (const gchar *name,
 /**
  * g_param_spec_gtype:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @is_a_type: a #GType whose subtypes are allowed as values
  *  of the property (use %G_TYPE_NONE for any type)
  * @flags: flags for the property specified
@@ -2617,8 +2617,8 @@ g_param_spec_gtype (const gchar *name,
 /**
  * g_param_spec_value_array: (skip)
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @element_spec: a #GParamSpec describing the elements contained in
  *  arrays of this property, may be %NULL
  * @flags: flags for the property specified
@@ -2661,8 +2661,8 @@ g_param_spec_value_array (const gchar *name,
 /**
  * g_param_spec_object:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @object_type: %G_TYPE_OBJECT derived type of this property
  * @flags: flags for the property specified
  *
@@ -2741,8 +2741,8 @@ g_param_spec_override (const gchar *name,
 /**
  * g_param_spec_variant:
  * @name: canonical name of the property specified
- * @nick: nick name for the property specified
- * @blurb: description of the property specified
+ * @nick: (nullable): nick name for the property specified
+ * @blurb: (nullable): description of the property specified
  * @type: a #GVariantType
  * @default_value: (nullable) (transfer full): a #GVariant of type @type to
  *                 use as the default value, or %NULL