introspection: assorted annotation fixes ported from Vala

https://bugzilla.gnome.org/show_bug.cgi?id=677778

clutter/clutter-binding-pool.c

@@ -452,7 +452,8 @@ clutter_binding_pool_find (const gchar *name)
  * @action_name: the name of the action
  * @key_val: key symbol
  * @modifiers: bitmask of modifiers
- * @callback: function to be called when the action is activated
+ * @callback: (type Clutter.BindingActionFunc): function to be called
+ *   when the action is activated
  * @data: data to be passed to @callback
  * @notify: function to be called when the action is removed
  *   from the pool

clutter/clutter-color.c

@@ -828,8 +828,8 @@ clutter_color_to_string (const ClutterColor *color)
 
 /**
  * clutter_color_equal:
- * @v1: a #ClutterColor
+ * @v1: (type Clutter.Color): a #ClutterColor
- * @v2: a #ClutterColor
+ * @v2: (type Clutter.Color): a #ClutterColor
  *
  * Compares two #ClutterColor<!-- -->s and checks if they are the same.
  *
@@ -863,7 +863,7 @@ clutter_color_equal (gconstpointer v1,
 
 /**
  * clutter_color_hash:
- * @v: a #ClutterColor
+ * @v: (type Clutter.Color): a #ClutterColor
  *
  * Converts a #ClutterColor to a hash value.
  *

clutter/clutter-main.c

@@ -1889,8 +1889,8 @@ clutter_get_option_group_without_init (void)
  * @parameter_string: (allow-none): a string which is displayed in the
  *   first line of <option>--help</option> output, after
  *   <literal><replaceable>programname</replaceable> [OPTION...]</literal>
- * @entries: (allow-none): a %NULL terminated array of #GOptionEntry<!-- -->s
+ * @entries: (array) (allow-none): a %NULL terminated array of
- *   describing the options of your program
+ *   #GOptionEntry<!-- -->s describing the options of your program
  * @translation_domain: (allow-none): a translation domain to use for
  *   translating the <option>--help</option> output for the options in
  *   @entries with gettext(), or %NULL

clutter/clutter-shader-types.c

@@ -383,7 +383,7 @@ clutter_shader_matrix_get_type (void)
  * clutter_value_set_shader_float:
  * @value: a #GValue
  * @size: number of floating point values in @floats
- * @floats: an array of floating point values
+ * @floats: (array length=size): an array of floating point values
  *
  * Sets @floats as the contents of @value. The passed #GValue
  * must have been initialized using %CLUTTER_TYPE_SHADER_FLOAT.
@@ -413,7 +413,7 @@ clutter_value_set_shader_float (GValue         *value,
  * clutter_value_set_shader_int:
  * @value: a #GValue
  * @size: number of integer values in @ints
- * @ints: an array of integer values
+ * @ints: (array length=size): an array of integer values
  *
  * Sets @ints as the contents of @value. The passed #GValue
  * must have been initialized using %CLUTTER_TYPE_SHADER_INT.
@@ -443,7 +443,7 @@ clutter_value_set_shader_int (GValue     *value,
  * clutter_value_set_shader_matrix:
  * @value: a #GValue
  * @size: number of floating point values in @floats
- * @matrix: a matrix of floating point values
+ * @matrix: (array length=size): a matrix of floating point values
  *
  * Sets @matrix as the contents of @value. The passed #GValue
  * must have been initialized using %CLUTTER_TYPE_SHADER_MATRIX.
@@ -472,16 +472,16 @@ clutter_value_set_shader_matrix (GValue       *value,
 /**
  * clutter_value_get_shader_float:
  * @value: a #GValue
- * @length: return location for the number of returned floating
+ * @length: (out): return location for the number of returned floating
  *   point values, or %NULL
  *
  * Retrieves the list of floating point values stored inside
  * the passed #GValue. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_FLOAT.
  *
- * Return value: the pointer to a list of floating point values.
+ * Return value: (array length=length): the pointer to a list of
- *   The returned value is owned by the #GValue and should never
+ *   floating point values.  The returned value is owned by the
- *   be modified or freed.
+ *   #GValue and should never be modified or freed.
  *
  * Since: 0.8
  */
@@ -504,16 +504,16 @@ clutter_value_get_shader_float (const GValue *value,
 /**
  * clutter_value_get_shader_int:
  * @value: a #GValue
- * @length: return location for the number of returned integer
+ * @length: (out): return location for the number of returned integer
  *   values, or %NULL
  *
  * Retrieves the list of integer values stored inside the passed
  * #GValue. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_INT.
  *
- * Return value: the pointer to a list of integer values.
+ * Return value: (array length=length): the pointer to a list of
- *   The returned value is owned by the #GValue and should never
+ *   integer values.  The returned value is owned by the #GValue and
- *   be modified or freed.
+ *   should never be modified or freed.
  *
  * Since: 0.8
  */

clutter/clutter-stage.c

@@ -2823,7 +2823,7 @@ clutter_stage_hide_cursor (ClutterStage *stage)
  * The alpha data contained in the returned buffer is driver-dependent,
  * and not guaranteed to hold any sensible value.
  *
- * Return value: (array): a pointer to newly allocated memory with the buffer
+ * Return value: (transfer full) (array): a pointer to newly allocated memory with the buffer
  *   or %NULL if the read failed. Use g_free() on the returned data
  *   to release the resources it has allocated.
  */