[gimp] libgimp*: more docs and annotations

[Michael Natterer <mitch src gnome org>]

commit 254271971eca23d96bd9a52120d03c562c4377b1
Author: Michael Natterer <mitch gimp org>
Date:   Mon Aug 5 15:44:40 2019 +0200

    libgimp*: more docs and annotations

 libgimp/gimpparamspecs.c     |   8 +-
 libgimpbase/gimpparamspecs.c | 251 ++++++++++++++++++++++++++-----------------
 libgimpbase/gimpparasite.c   |  17 +--
 3 files changed, 166 insertions(+), 110 deletions(-)
---
diff --git a/libgimp/gimpparamspecs.c b/libgimp/gimpparamspecs.c
index cb43edbf96..5b5f7b25a3 100644
--- a/libgimp/gimpparamspecs.c
+++ b/libgimp/gimpparamspecs.c
@@ -1315,19 +1315,19 @@ gimp_param_display_id_values_cmp (GParamSpec   *pspec,
 }
 
 /**
- * gimp_param_spec_vectors_id:
+ * gimp_param_spec_display_id:
  * @name:    Canonical name of the property specified.
  * @nick:    Nick name of the property specified.
  * @blurb:   Description of the property specified.
  * @none_ok: Whether no ID is a valid value.
  * @flags:   Flags for the property specified.
  *
- * Creates a new #GimpParamSpecVectorsID specifying a
- * #GIMP_TYPE_VECTORS_ID property.
+ * Creates a new #GimpParamSpecDisplayID specifying a
+ * #GIMP_TYPE_DISPLAY_ID property.
  *
  * See g_param_spec_internal() for details on property names.
  *
- * Returns: (transfer full): The newly created #GimpParamSpecVectorsID.
+ * Returns: (transfer full): The newly created #GimpParamSpecDisplayID.
  *
  * Since: 3.0
  **/
diff --git a/libgimpbase/gimpparamspecs.c b/libgimpbase/gimpparamspecs.c
index a1ed5ede58..c36cce48c9 100644
--- a/libgimpbase/gimpparamspecs.c
+++ b/libgimpbase/gimpparamspecs.c
@@ -90,18 +90,24 @@ gimp_param_int32_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int32:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @minimum: the minimum accepted value.
- * @maximum: the maximum accepted value.
- * @default_value: the default value.
- * @flags: #GParamFlags for the new parameter.
+ * @name:          Canonical name of the property specified.
+ * @nick:          Nick name of the property specified.
+ * @blurb:         Description of the property specified.
+ * @minimum:       The minimum accepted value.
+ * @maximum:       The maximum accepted value.
+ * @default_value: The default value.
+ * @flags:         Flags for the property specified.
  *
- * Create a new int32 #GParamSpec with the given specifications.
+ * Creates a new #GimpParamSpecInt32 specifying a
+ * #GIMP_TYPE_INT32 property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created
+ *          #GimpParamSpecInt32.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int32 (const gchar *name,
                        const gchar *nick,
@@ -194,18 +200,23 @@ gimp_param_int16_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int16:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @minimum: the minimum accepted value.
- * @maximum: the maximum accepted value.
- * @default_value: the default value.
- * @flags: #GParamFlags for the new parameter.
+ * @name:          Canonical name of the property specified.
+ * @nick:          Nick name of the property specified.
+ * @blurb:         Description of the property specified.
+ * @minimum:       The minimum accepted value.
+ * @maximum:       The maximum accepted value.
+ * @default_value: The default value.
+ * @flags:         Flags for the property specified.
  *
- * Create a new int16 #GParamSpec with the given specifications.
+ * Creates a new #GimpParamSpecInt16 specifying a
+ * #GIMP_TYPE_INT16 property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecInt16.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int16 (const gchar *name,
                        const gchar *nick,
@@ -298,18 +309,23 @@ gimp_param_int8_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int8:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @minimum: the minimum accepted value.
- * @maximum: the maximum accepted value.
- * @default_value: the default value.
- * @flags: #GParamFlags for the new parameter.
+ * @name:          Canonical name of the property specified.
+ * @nick:          Nick name of the property specified.
+ * @blurb:         Description of the property specified.
+ * @minimum:       The minimum accepted value.
+ * @maximum:       The maximum accepted value.
+ * @default_value: The default value.
+ * @flags:         Flags for the property specified.
  *
- * Create a new int8 #GParamSpec with the given specifications.
+ * Creates a new #GimpParamSpecInt8 specifying a
+ * #GIMP_TYPE_INT8 property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecInt8.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int8 (const gchar *name,
                       const gchar *nick,
@@ -446,25 +462,32 @@ gimp_param_string_validate (GParamSpec *pspec,
 
 /**
  * gimp_param_spec_string:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @allow_non_utf8: whether non-UTF8 text is allowed.
- * @null_ok: whether %NULL is an acceptable value.
- * @non_empty: whether the empty string is an acceptable value.
- * @default_value: the default value.
- * @flags: #GParamFlags for the new parameter.
+ * @name:           Canonical name of the property specified.
+ * @nick:           Nick name of the property specified.
+ * @blurb:          Description of the property specified.
+ * @allow_non_utf8: Whether non-UTF-8 strings are allowed.
+ * @null_ok:        Whether %NULL is allowed.
+ * @non_empty:      Whether a non-½NULL value must be set.
+ * @default_:       The default value.
+ * @flags:          Flags for the property specified.
+ *
+ * Creates a new #GimpParamSpecString specifying a
+ * #GIMP_TYPE_STRING property.
  *
- * Create a new string #GParamSpec with the given specifications.
+ * If @allow_non_utf8 is %FALSE, non-valid UTF-8 strings will be
+ * replaced by question marks.
  *
  * If @null_ok is %FALSE, %NULL strings will be replaced by an empty
  * string.
+ *
  * If @non_empty is %TRUE, empty strings will be replaced by `"none"`.
- * If @allow_non_utf8 is %FALSE, non-valid UTF-8 strings will be
- * replaced by question marks.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecString.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_string (const gchar *name,
                         const gchar *nick,
@@ -648,16 +671,20 @@ gimp_param_array_values_cmp (GParamSpec   *pspec,
 
 /**
  * gimp_param_spec_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray data with the given
- * specifications.
+ * Creates a new #GimpParamSpecArray specifying a
+ * #GIMP_TYPE_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecArray.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_array (const gchar *name,
                        const gchar *nick,
@@ -790,16 +817,20 @@ gimp_param_int8_array_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int8_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of int8 with the given
- * specifications.
+ * Creates a new #GimpParamSpecInt8Array specifying a
+ * #GIMP_TYPE_INT8_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecInt8Array.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int8_array (const gchar *name,
                             const gchar *nick,
@@ -924,16 +955,20 @@ gimp_param_int16_array_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int16_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of int16 with the given
- * specifications.
+ * Creates a new #GimpParamSpecInt16Array specifying a
+ * #GIMP_TYPE_INT16_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecInt16Array.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int16_array (const gchar *name,
                              const gchar *nick,
@@ -1061,16 +1096,20 @@ gimp_param_int32_array_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_int32_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of int32 with the given
- * specifications.
+ * Creates a new #GimpParamSpecInt32Array specifying a
+ * #GIMP_TYPE_INT32_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecInt32Array.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_int32_array (const gchar *name,
                              const gchar *nick,
@@ -1198,16 +1237,20 @@ gimp_param_float_array_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_float_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of float with the given
- * specifications.
+ * Creates a new #GimpParamSpecFloatArray specifying a
+ * #GIMP_TYPE_FLOAT_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecFloatArray.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_float_array (const gchar *name,
                              const gchar *nick,
@@ -1327,7 +1370,7 @@ gimp_string_array_new (const gchar **data,
  * Creates a new #GimpArray containing a deep copy of @array.
  *
  * Returns: (transfer full) (type GimpArray): a new #GimpArray.
- */
+ **/
 GimpArray *
 gimp_string_array_copy (const GimpArray *array)
 {
@@ -1465,16 +1508,20 @@ gimp_param_string_array_values_cmp (GParamSpec   *pspec,
 
 /**
  * gimp_param_spec_string_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of string with the given
- * specifications.
+ * Creates a new #GimpParamSpecStringArray specifying a
+ * #GIMP_TYPE_STRING_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecStringArray.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_string_array (const gchar *name,
                               const gchar *nick,
@@ -1646,16 +1693,20 @@ gimp_param_rgb_array_init (GParamSpec *pspec)
 
 /**
  * gimp_param_spec_rgb_array:
- * @name: new parameter's name.
- * @nick: nick name for the parameter.
- * @blurb: longer description of the parameter.
- * @flags: #GParamFlags for the new parameter.
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Create a new #GParamSpec for #GimpArray of rgb with the given
- * specifications.
+ * Creates a new #GimpParamSpecRgbArray specifying a
+ * #GIMP_TYPE_RGB_ARRAY property.
  *
- * Returns: (transfer full) (type GParamSpec): a new #GParamSpec.
- */
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecRgbArray.
+ *
+ * Since: 3.0
+ **/
 GParamSpec *
 gimp_param_spec_rgb_array (const gchar *name,
                            const gchar *nick,
diff --git a/libgimpbase/gimpparasite.c b/libgimpbase/gimpparasite.c
index 52510433d1..2341237120 100644
--- a/libgimpbase/gimpparasite.c
+++ b/libgimpbase/gimpparasite.c
@@ -172,15 +172,20 @@ gimp_param_parasite_values_cmp (GParamSpec   *pspec,
 
 /**
  * gimp_param_spec_parasite:
- * @name: the #GParamSpec's name.
- * @nick: the #GParamSpec's nick.
- * @blurb: the #GParamSpec's blurb.
- * @flags: a combination of #GParamFlags
+ * @name:  Canonical name of the property specified.
+ * @nick:  Nick name of the property specified.
+ * @blurb: Description of the property specified.
+ * @flags: Flags for the property specified.
  *
- * Returns: (transfer full): a newly allocated #GimpParamSpecParasite.
+ * Creates a new #GimpParamSpecParasite specifying a
+ * #GIMP_TYPE_PARASITE property.
+ *
+ * See g_param_spec_internal() for details on property names.
+ *
+ * Returns: (transfer full): The newly created #GimpParamSpecParasite.
  *
  * Since: 2.3.8
- */
+ **/
 GParamSpec *
 gimp_param_spec_parasite (const gchar *name,
                           const gchar *nick,