[gimp] libgimpbase: fix/improve docs/annotations.

[Jehan <jehanp src gnome org>]

commit d999248d701a656c74d516535881fe3685d5e4aa
Author: Jehan <jehan girinstud io>
Date:   Mon Aug 5 16:18:14 2019 +0200

    libgimpbase: fix/improve docs/annotations.
    
    Our GimpStringArray is so weird. We are obviously expecting it to be
    NULL-terminated since, when we duplicate the data, we add one value.
    Yet we were not checking that the stored data was NULL-terminated, in
    particular when the string array is created with static data (in which
    case, we use the input data as-is, without re-allocating).
    
    Note that this doesn't fix the type mismatch Gimp.StringArray vs
    Gimp.Array when introspecting.

 libgimpbase/gimpparamspecs.c | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)
---
diff --git a/libgimpbase/gimpparamspecs.c b/libgimpbase/gimpparamspecs.c
index c36cce48c9..40bada7916 100644
--- a/libgimpbase/gimpparamspecs.c
+++ b/libgimpbase/gimpparamspecs.c
@@ -1321,13 +1321,19 @@ gimp_value_take_float_array (GValue  *value,
 
 /**
  * gimp_string_array_new:
- * @data: (array length=length): an array of strings.
+ * @data: (array length=length) (transfer none): an array of strings.
  * @length: the length of @data.
  * @static_data: whether the strings in @data are static strings rather
  *               than allocated.
  *
  * Creates a new #GimpArray containing string data, of size @length.
  *
+ * If @static_data is %TRUE, @data is used as-is and should also be
+ * NULL-terminated.
+ *
+ * If @static_data is %FALSE, the string and array will be re-allocated,
+ * hence you are expected to free your input data after.
+ *
  * Returns: (transfer full) (type GimpArray): a new #GimpArray.
  */
 GimpArray *
@@ -1339,6 +1345,8 @@ gimp_string_array_new (const gchar **data,
 
   g_return_val_if_fail ((data == NULL && length == 0) ||
                         (data != NULL && length  > 0), NULL);
+  g_return_val_if_fail (! static_data || ! data ||
+                        g_strv_length (data) == length, NULL);
 
   array = g_slice_new0 (GimpArray);
 
@@ -1561,7 +1569,7 @@ gimp_value_get_string_array (const GValue *value)
  * gimp_value_dup_string_array:
  * @value: a #GValue holding a string #GimpArray.
  *
- * Returns: (transfer none)  (array zero-terminated=1): a deep copy of the array of strings.
+ * Returns: (transfer full)  (array zero-terminated=1): a deep copy of the array of strings.
  */
 gchar **
 gimp_value_dup_string_array (const GValue *value)