Add caller-allocates annotations

For ClutterColor, ClutterUnits, ClutterInterval and the Perspective
accessor in ClutterStage.

clutter/clutter-color.c

@@ -50,7 +50,7 @@
  * clutter_color_add:
  * @a: a #ClutterColor
  * @b: a #ClutterColor
- * @result: (out): return location for the result
+ * @result: (out caller-allocates): return location for the result
  *
  * Adds @a to @b and saves the resulting color inside @result.
  *
@@ -77,7 +77,7 @@ clutter_color_add (const ClutterColor *a,
  * clutter_color_subtract:
  * @a: a #ClutterColor
  * @b: a #ClutterColor
- * @result: (out): return location for the result
+ * @result: (out caller-allocates): return location for the result
  *
  * Subtracts @b from @a and saves the resulting color inside @result.
  *
@@ -106,7 +106,7 @@ clutter_color_subtract (const ClutterColor *a,
 /**
  * clutter_color_lighten:
  * @color: a #ClutterColor
- * @result: (out): return location for the lighter color
+ * @result: (out caller-allocates): return location for the lighter color
  *
  * Lightens @color by a fixed amount, and saves the changed color
  * in @result.
@@ -121,7 +121,7 @@ clutter_color_lighten (const ClutterColor *color,
 /**
  * clutter_color_darken:
  * @color: a #ClutterColor
- * @result: (out): return location for the darker color
+ * @result: (out caller-allocates): return location for the darker color
  *
  * Darkens @color by a fixed amount, and saves the changed color
  * in @result.
@@ -290,7 +290,7 @@ clutter_color_from_hls (ClutterColor *color,
  * clutter_color_shade:
  * @color: a #ClutterColor
  * @factor: the shade factor to apply
- * @result: (out): return location for the shaded color
+ * @result: (out caller-allocates): return location for the shaded color
  *
  * Shades @color by @factor and saves the modified color into @result.
  */
@@ -345,7 +345,7 @@ clutter_color_to_pixel (const ClutterColor *color)
 
 /**
  * clutter_color_from_pixel:
- * @color: (out): return location for a #ClutterColor
+ * @color: (out caller-allocates): return location for a #ClutterColor
  * @pixel: a 32 bit packed integer containing a color
  *
  * Converts @pixel from the packed representation of a four 8 bit channel
@@ -365,7 +365,7 @@ clutter_color_from_pixel (ClutterColor *color,
 
 /**
  * clutter_color_from_string:
- * @color: (out): return location for a #ClutterColor
+ * @color: (out caller-allocates): return location for a #ClutterColor
  * @str: a string specifiying a color (named color or #RRGGBBAA)
  *
  * Parses a string definition of a color, filling the
@@ -562,7 +562,7 @@ clutter_color_hash (gconstpointer v)
  * Makes a copy of the color structure.  The result must be
  * freed using clutter_color_free().
  *
- * Return value: an allocated copy of @color.
+ * Return value: (transfer full): an allocated copy of @color.
  *
  * Since: 0.2
  */
@@ -787,7 +787,7 @@ clutter_param_color_get_type (void)
 }
 
 /**
- * clutter_param_spec_color:
+ * clutter_param_spec_color: (skip)
  * @name: name of the property
  * @nick: short name
  * @blurb: description (can be translatable)

clutter/clutter-fixed.c

@@ -153,7 +153,7 @@ clutter_param_fixed_get_type (void)
 }
 
 /**
- * clutter_param_spec_fixed:
+ * clutter_param_spec_fixed: (skip)
  * @name: name of the property
  * @nick: short name
  * @blurb: description (can be translatable)

clutter/clutter-interval.c

@@ -698,7 +698,7 @@ clutter_interval_set_initial_value (ClutterInterval *interval,
 /**
  * clutter_interval_get_initial_value:
  * @interval: a #ClutterInterval
- * @value: a #GValue
+ * @value: (out caller-allocates): a #GValue
  *
  * Retrieves the initial value of @interval and copies
  * it into @value.
@@ -767,7 +767,7 @@ clutter_interval_set_final_value (ClutterInterval *interval,
 /**
  * clutter_interval_get_final_value:
  * @interval: a #ClutterInterval
- * @value: a #GValue
+ * @value: (out caller-allocates): a #GValue
  *
  * Retrieves the final value of @interval and copies
  * it into @value.
@@ -901,7 +901,7 @@ clutter_interval_validate (ClutterInterval *interval,
  * clutter_interval_compute_value:
  * @interval: a #ClutterInterval
  * @factor: the progress factor, between 0 and 1
- * @value: return location for an initialized #GValue
+ * @value: (out caller-allocates): return location for an initialized #GValue
  *
  * Computes the value between the @interval boundaries given the
  * progress @factor and copies it into @value.

clutter/clutter-stage.c

@@ -1474,7 +1474,8 @@ clutter_stage_set_perspective (ClutterStage       *stage,
 /**
  * clutter_stage_get_perspective:
  * @stage: A #ClutterStage
- * @perspective: return location for a #ClutterPerspective
+ * @perspective: (out caller-allocates) (allow-none): return location for a
+ *   #ClutterPerspective
  *
  * Retrieves the stage perspective.
  */

clutter/clutter-units.c

@@ -140,7 +140,7 @@ units_em_to_pixels (const gchar *font_name,
 
 /**
  * clutter_units_from_mm:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @mm: millimeters
  *
  * Stores a value in millimiters inside @units
@@ -166,7 +166,7 @@ clutter_units_from_mm (ClutterUnits *units,
 
 /**
  * clutter_units_from_cm:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @cm: centimeters
  *
  * Stores a value in centimeters inside @units
@@ -192,7 +192,7 @@ clutter_units_from_cm (ClutterUnits *units,
 
 /**
  * clutter_units_from_pt:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @pt: typographic points
  *
  * Stores a value in typographic points inside @units
@@ -218,7 +218,7 @@ clutter_units_from_pt (ClutterUnits *units,
 
 /**
  * clutter_units_from_em:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @em: em
  *
  * Stores a value in em inside @units, using the default font
@@ -245,8 +245,8 @@ clutter_units_from_em (ClutterUnits *units,
 
 /**
  * clutter_units_from_em_for_font:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
- * @font_name: the font name and size
+ * @font_name: (allow-none): the font name and size
  * @em: em
  *
  * Stores a value in em inside @units using @font_name
@@ -273,7 +273,7 @@ clutter_units_from_em_for_font (ClutterUnits *units,
 
 /**
  * clutter_units_from_pixels:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @px: pixels
  *
  * Stores a value in pixels inside @units
@@ -339,8 +339,9 @@ clutter_units_get_unit_value (const ClutterUnits *units)
  *
  * Copies @units
  *
- * Return value: the newly created copy of a #ClutterUnits structure.
+ * Return value: (transfer full): the newly created copy of a
- *   Use clutter_units_free() to free the allocated resources
+ *   #ClutterUnits structure. Use clutter_units_free() to free
+ *   the allocated resources
  *
  * Since: 1.0
  */
@@ -427,7 +428,7 @@ clutter_units_to_pixels (ClutterUnits *units)
 
 /**
  * clutter_units_from_string:
- * @units: a #ClutterUnits
+ * @units: (out caller-allocates): a #ClutterUnits
  * @str: the string to convert
  *
  * Parses a value and updates @units with it
@@ -911,7 +912,7 @@ clutter_param_units_get_type (void)
 }
 
 /**
- * clutter_param_spec_units:
+ * clutter_param_spec_units: (skip)
  * @name: name of the property
  * @nick: short name
  * @blurb: description (can be translatable)