[glib] Document NULL shortcut to g_value_array_insert etc.

[Matthias Clasen <matthiasc src gnome org>]

commit 2504ec988e0288b8616907b43e489c74d49a08f0
Author: Will Thompson <will willthompson co uk>
Date:   Thu Jul 8 19:30:53 2010 -0400

    Document NULL shortcut to g_value_array_insert etc.
    
    You can pass a NULL GValue * to any of g_value_array_insert, _prepend or
    _append to add a new, uninitialized value. This is a very useful
    shortcut, and it should be documented rather than left languishing in a
    comment in the implementation.
    
    Fixes Gnome bug #552363.

 gobject/gvaluearray.c |   18 ++++++++++--------
 1 files changed, 10 insertions(+), 8 deletions(-)
---
diff --git a/gobject/gvaluearray.c b/gobject/gvaluearray.c
index 29bbd1a..3bc6787 100644
--- a/gobject/gvaluearray.c
+++ b/gobject/gvaluearray.c
@@ -187,9 +187,11 @@ g_value_array_copy (const GValueArray *value_array)
 /**
  * g_value_array_prepend:
  * @value_array: #GValueArray to add an element to
- * @value: #GValue to copy into #GValueArray
+ * @value: #GValue to copy into #GValueArray, or %NULL
+ *
+ * Insert a copy of @value as first element of @value_array. If @value is
+ * %NULL, an uninitialized value is prepended.
  *
- * Insert a copy of @value as first element of @value_array.
  *
  * Returns: the #GValueArray passed in as @value_array
  */
@@ -205,9 +207,10 @@ g_value_array_prepend (GValueArray  *value_array,
 /**
  * g_value_array_append:
  * @value_array: #GValueArray to add an element to
- * @value: #GValue to copy into #GValueArray
+ * @value: #GValue to copy into #GValueArray, or %NULL
  *
- * Insert a copy of @value as last element of @value_array.
+ * Insert a copy of @value as last element of @value_array. If @value is
+ * %NULL, an uninitialized value is appended.
  *
  * Returns: the #GValueArray passed in as @value_array
  */
@@ -224,9 +227,10 @@ g_value_array_append (GValueArray  *value_array,
  * g_value_array_insert:
  * @value_array: #GValueArray to add an element to
  * @index_: insertion position, must be &lt;= value_array-&gt;n_values
- * @value: #GValue to copy into #GValueArray
+ * @value: #GValue to copy into #GValueArray, or %NULL
  *
- * Insert a copy of @value at specified position into @value_array.
+ * Insert a copy of @value at specified position into @value_array. If @value
+ * is %NULL, an uninitialized value is inserted.
  *
  * Returns: the #GValueArray passed in as @value_array
  */
@@ -240,8 +244,6 @@ g_value_array_insert (GValueArray  *value_array,
   g_return_val_if_fail (value_array != NULL, NULL);
   g_return_val_if_fail (index <= value_array->n_values, value_array);
 
-  /* we support NULL for "value" as a shortcut for an unset value */
-
   i = value_array->n_values;
   value_array_grow (value_array, value_array->n_values + 1, FALSE);
   if (index + 1 < value_array->n_values)