diff --git a/gobject/gparam.c b/gobject/gparam.c index 14238521b..6c1a48131 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 8299b605a..f17b3488b 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