diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 1b41014d3..9aa3aad9a 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -3358,10 +3358,10 @@ clutter_actor_queue_relayout (ClutterActor *self)
 /**
  * clutter_actor_get_preferred_size:
  * @self: a #ClutterActor
- * @min_width_p: return location for the minimum width, or %NULL
- * @min_height_p: return location for the minimum height, or %NULL
- * @natural_width_p: return location for the natural width, or %NULL
- * @natural_height_p: return location for the natural height, or %NULL
+ * @min_width_p: (out) (allow-none): return location for the minimum width, or %NULL
+ * @min_height_p: (out) (allow-none): return location for the minimum height, or %NULL
+ * @natural_width_p: (out) (allow-none): return location for the natural width, or %NULL
+ * @natural_height_p: (out) (allow-none): return location for the natural height, or %NULL
  *
  * Computes the preferred minimum and natural size of an actor, taking into
  * account the actor's geometry management (either height-for-width
@@ -6121,7 +6121,7 @@ clutter_actor_set_parent (ClutterActor *self,
  *
  * Retrieves the parent of @self.
  *
- * Return Value: The #ClutterActor parent, or %NULL if no parent is set
+ * Return Value: (transfer none): The #ClutterActor parent, or %NULL if no parent is set
  */
 ClutterActor *
 clutter_actor_get_parent (ClutterActor *self)
@@ -6297,7 +6297,7 @@ clutter_actor_reparent (ClutterActor *self,
 /**
  * clutter_actor_raise:
  * @self: A #ClutterActor
- * @below: A #ClutterActor to raise above.
+ * @below: (allow-none): A #ClutterActor to raise above.
  *
  * Puts @self above @below.
  *
@@ -6339,7 +6339,7 @@ clutter_actor_raise (ClutterActor *self,
 /**
  * clutter_actor_lower:
  * @self: A #ClutterActor
- * @above: A #ClutterActor to lower below
+ * @above: (allow-none): A #ClutterActor to lower below
  *
  * Puts @self below @above.
  *
@@ -7253,11 +7253,11 @@ clutter_scriptable_iface_init (ClutterScriptableIface *iface)
 /**
  * clutter_actor_transform_stage_point
  * @self: A #ClutterActor
- * @x: x screen coordinate of the point to unproject, in #ClutterUnit<!-- -->s
- * @y: y screen coordinate of the point to unproject, in #ClutterUnit<!-- -->s
- * @x_out: return location for the unprojected x coordinance, in
+ * @x: (in): x screen coordinate of the point to unproject, in #ClutterUnit<!-- -->s
+ * @y: (in): y screen coordinate of the point to unproject, in #ClutterUnit<!-- -->s
+ * @x_out: (out): return location for the unprojected x coordinance, in
  *   #ClutterUnit<!-- -->s
- * @y_out: return location for the unprojected y coordinance, in
+ * @y_out: (out): return location for the unprojected y coordinance, in
  *   #ClutterUnit<!-- -->s
  *
  * This function translates screen coordinates (@x, @y) to
@@ -7601,7 +7601,7 @@ destroy_shader_data (ClutterActor *self)
  *
  * Queries the currently set #ClutterShader on @self.
  *
- * Return value: The currently set #ClutterShader or %NULL if no
+ * Return value: (transfer none): The currently set #ClutterShader or %NULL if no
  *   shader is set.
  *
  * Since: 0.6
@@ -7952,7 +7952,7 @@ clutter_actor_get_box_from_vertices (ClutterVertex    vtx[4],
  *
  * Retrieves the #ClutterStage where @actor is contained.
  *
- * Return value: the stage containing the actor, or %NULL
+ * Return value: (transfer none): the stage containing the actor, or %NULL
  *
  * Since: 0.8
  */
@@ -8055,9 +8055,9 @@ clutter_actor_grab_key_focus (ClutterActor *self)
  * and render text using cogl_pango_render_layout() to reuse the
  * glyphs cache also used by Clutter.
  *
- * Return value: the #PangoContext for a #ClutterActor. The returned
- *   #PangoContext is owned by the actor and should not be unreferenced
- *   by the application code
+ * Return value: (transfer none): the #PangoContext for a #ClutterActor.
+ *   The returned #PangoContext is owned by the actor and should not be
+ *   unreferenced by the application code
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-alpha.c b/clutter/clutter-alpha.c
index 4fab3426a..412bf4c11 100644
--- a/clutter/clutter-alpha.c
+++ b/clutter/clutter-alpha.c
@@ -465,7 +465,7 @@ clutter_alpha_set_timeline (ClutterAlpha    *alpha,
  *
  * Gets the #ClutterTimeline bound to @alpha.
  *
- * Return value: a #ClutterTimeline instance
+ * Return value: (transfer none): a #ClutterTimeline instance
  *
  * Since: 0.2
  */
diff --git a/clutter/clutter-animation.c b/clutter/clutter-animation.c
index f05206940..e1340c333 100644
--- a/clutter/clutter-animation.c
+++ b/clutter/clutter-animation.c
@@ -627,9 +627,9 @@ clutter_animation_update_property (ClutterAnimation *animation,
  * Retrieves the #ClutterInterval associated to @property_name
  * inside @animation.
  *
- * Return value: a #ClutterInterval or %NULL if no property with
- *   the same name was found. The returned interval is owned by
- *   the #ClutterAnimation and should not be unreferenced
+ * Return value: (transfer none): a #ClutterInterval or %NULL if no
+ *   property with the same name was found. The returned interval is
+ *   owned by the #ClutterAnimation and should not be unreferenced
  *
  * Since: 1.0
  */
@@ -794,7 +794,7 @@ clutter_animation_set_object (ClutterAnimation *animation,
  *
  * Retrieves the #GObject attached to @animation.
  *
- * Return value: a #GObject
+ * Return value: (transfer none): a #GObject
  *
  * Since: 1.0
  */
@@ -1044,7 +1044,7 @@ clutter_animation_set_timeline (ClutterAnimation *animation,
  *
  * Retrieves the #ClutterTimeline used by @animation
  *
- * Return value: the timeline used by the animation
+ * Return value: (transfer none): the timeline used by the animation
  *
  * Since: 1.0
  */
@@ -1117,7 +1117,7 @@ clutter_animation_set_alpha (ClutterAnimation *animation,
  *
  * Retrieves the #ClutterAlpha used by @animation.
  *
- * Return value: the alpha object used by the animation
+ * Return value: (transfer none): the alpha object used by the animation
  *
  * Since: 1.0
  */
@@ -1261,7 +1261,7 @@ clutter_animation_setup_valist (ClutterAnimation *animation,
  * This function is useful if you want to use an existing #ClutterAlpha
  * to animate @actor.
  *
- * Return value: a #ClutterAnimation object. The object is owned by the
+ * Return value: (transfer none): a #ClutterAnimation object. The object is owned by the
  *   #ClutterActor and should not be unreferenced with g_object_unref()
  *
  * Since: 1.0
@@ -1326,8 +1326,9 @@ clutter_actor_animate_with_alpha (ClutterActor *actor,
  * This function is useful if you want to use an existing timeline
  * to animate @actor.
  *
- * Return value: a #ClutterAnimation object. The object is owned by the
- *   #ClutterActor and should not be unreferenced with g_object_unref()
+ * Return value: (transfer none): a #ClutterAnimation object. The object is
+ *    owned by the #ClutterActor and should not be unreferenced with
+ *    g_object_unref()
  *
  * Since: 1.0
  */
@@ -1423,8 +1424,9 @@ clutter_actor_animate_with_timeline (ClutterActor    *actor,
  * as it is complete. To avoid this, you should keep a reference on the
  * returned value using g_object_ref().</note>
  *
- * Return value: a #ClutterAnimation object. The object is owned by the
- *   #ClutterActor and should not be unreferenced with g_object_unref()
+ * Return value: (transfer none): a #ClutterAnimation object. The object is
+ *   owned by the #ClutterActor and should not be unreferenced with
+ *   g_object_unref()
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-backend.c b/clutter/clutter-backend.c
index da8f77ee6..2c94c026c 100644
--- a/clutter/clutter-backend.c
+++ b/clutter/clutter-backend.c
@@ -364,14 +364,14 @@ _clutter_backend_get_units_per_em (ClutterBackend *backend)
 }
 
 /**
- * clutter_get_default_backend:
+ * clutter_get_default_backend1:
  *
  * Retrieves the default #ClutterBackend used by Clutter. The
  * #ClutterBackend holds backend-specific configuration options.
  *
- * Return value: the default backend. You should not ref or
- *   unref the returned object. Applications should rarely need
- *   to use this.
+ * Return value: (transfer none): the default backend. You should
+ *   not ref or unref the returned object. Applications should rarely
+ *   need to use this.
  *
  * Since: 0.4
  */
@@ -561,7 +561,7 @@ clutter_backend_set_font_options (ClutterBackend       *backend,
  *
  * Retrieves the font options for @backend.
  *
- * Return value: the font options of the #ClutterBackend
+ * Return value: (transfer none): the font options of the #ClutterBackend
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter-behaviour-path.c b/clutter/clutter-behaviour-path.c
index eea1733b7..d40e90ebf 100644
--- a/clutter/clutter-behaviour-path.c
+++ b/clutter/clutter-behaviour-path.c
@@ -426,7 +426,7 @@ clutter_behaviour_path_set_path (ClutterBehaviourPath *pathb,
  *
  * Get the current path of the behaviour
  *
- * Return value: the path
+ * Return value: (transfer none): the path
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-behaviour.c b/clutter/clutter-behaviour.c
index e507c5d9b..bbea431e4 100644
--- a/clutter/clutter-behaviour.c
+++ b/clutter/clutter-behaviour.c
@@ -457,7 +457,7 @@ clutter_behaviour_get_n_actors (ClutterBehaviour *behave)
  *
  * Gets an actor the behaviour was applied to referenced by index num.
  *
- * Return value: A Clutter actor or NULL if @index_ is invalid.
+ * Return value: (transfer none): A Clutter actor or NULL if @index_ is invalid.
  *
  * Since: 0.2
  */
@@ -507,7 +507,7 @@ clutter_behaviour_actors_foreach (ClutterBehaviour            *behave,
  *
  * Retrieves the #ClutterAlpha object bound to @behave.
  *
- * Return value: a #ClutterAlpha object, or %NULL if no alpha
+ * Return value: (transfer none): a #ClutterAlpha object, or %NULL if no alpha
  *   object has been bound to this behaviour.
  * 
  * Since: 0.2
@@ -613,8 +613,8 @@ clutter_behaviour_set_alpha (ClutterBehaviour *behave,
  * for derived classes to use this in there alpha notify method but use 
  * #clutter_behaviour_actors_foreach as it avoids alot of needless allocations.
  *
- * Return value: a list of actors. You should free the returned list
- *   with g_slist_free() when finished using it.
+ * Return value: (transfer container) (element-type ClutterActor): a list of actors.
+ *   You should free the returned list with g_slist_free() when finished using it.
  * 
  * Since: 0.2
  */
diff --git a/clutter/clutter-binding-pool.c b/clutter/clutter-binding-pool.c
index 73398a58d..a3b79b6de 100644
--- a/clutter/clutter-binding-pool.c
+++ b/clutter/clutter-binding-pool.c
@@ -383,9 +383,9 @@ clutter_binding_pool_new (const gchar *name)
  *   pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));
  * ]|
  *
- * Return value: the binding pool for the given class. The returned
- *   #ClutterBindingPool is owned by Clutter and should not be freed
- *   directly
+ * Return value: (transfer none): the binding pool for the given class.
+ *   The returned #ClutterBindingPool is owned by Clutter and should not
+ *   be freed directly
  *
  * Since: 1.0
  */
@@ -417,7 +417,7 @@ clutter_binding_pool_get_for_class (gpointer klass)
  *
  * Finds the #ClutterBindingPool with @name.
  *
- * Return value: a pointer to the #ClutterBindingPool, or %NULL
+ * Return value: (transfer none): a pointer to the #ClutterBindingPool, or %NULL
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-child-meta.c b/clutter/clutter-child-meta.c
index 488b2f32d..082e02f3c 100644
--- a/clutter/clutter-child-meta.c
+++ b/clutter/clutter-child-meta.c
@@ -156,7 +156,7 @@ clutter_child_meta_init (ClutterChildMeta *self)
  *
  * Retrieves the container using @data
  *
- * Return value: a #ClutterContainer
+ * Return value: (transfer none): a #ClutterContainer
  *
  * Since: 0.8
  */
@@ -174,7 +174,7 @@ clutter_child_meta_get_container (ClutterChildMeta *data)
  *
  * Retrieves the actor wrapped by @data
  *
- * Return value: a #ClutterActor
+ * Return value: (transfer none): a #ClutterActor
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter-clone.c b/clutter/clutter-clone.c
index e20031718..4a37ebfbc 100644
--- a/clutter/clutter-clone.c
+++ b/clutter/clutter-clone.c
@@ -342,7 +342,7 @@ clutter_clone_set_source (ClutterClone *clone,
  *
  * Retrieves the source #ClutterActor being cloned by @clone
  *
- * Return value: the actor source for the clone
+ * Return value: (transfer none): the actor source for the clone
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-color.c b/clutter/clutter-color.c
index d1751bc71..a0624459a 100644
--- a/clutter/clutter-color.c
+++ b/clutter/clutter-color.c
@@ -46,7 +46,7 @@
  * clutter_color_add:
  * @src1: a #ClutterColor
  * @src2: a #ClutterColor
- * @dest: return location for the result
+ * @dest: (out): return location for the result
  *
  * Adds @src2 to @src1 and saves the resulting color
  * inside @dest.
@@ -74,7 +74,7 @@ clutter_color_add (const ClutterColor *src1,
  * clutter_color_subtract:
  * @src1: a #ClutterColor
  * @src2: a #ClutterColor
- * @dest: return location for the result
+ * @dest: (out): return location for the result
  *
  * Subtracts @src2 from @src1 and saves the resulting
  * color inside @dest. This function assumes that the components
@@ -103,7 +103,7 @@ clutter_color_subtract (const ClutterColor *src1,
 /**
  * clutter_color_lighten:
  * @src: a #ClutterColor
- * @dest: return location for the lighter color
+ * @dest: (out): return location for the lighter color
  *
  * Lightens @src by a fixed amount, and saves the changed
  * color in @dest.
@@ -118,7 +118,7 @@ clutter_color_lighten (const ClutterColor *src,
 /**
  * clutter_color_darken:
  * @src: a #ClutterColor
- * @dest: return location for the darker color
+ * @dest: (out): return location for the darker color
  *
  * Darkens @src by a fixed amount, and saves the changed color
  * in @dest.
@@ -226,7 +226,7 @@ clutter_color_to_hlsx (const ClutterColor *src,
 
 /**
  * clutter_color_from_hlsx:
- * @dest: return location for a #ClutterColor
+ * @dest: (out): return location for a #ClutterColor
  * @hue: hue value (0 .. 360)
  * @luminance: luminance value (0 .. 1)
  * @saturation: saturation value (0 .. 1)
@@ -380,7 +380,7 @@ clutter_color_to_hls (const ClutterColor *src,
 
 /**
  * clutter_color_from_hls:
- * @dest: return location for a #ClutterColor
+ * @dest: (out): return location for a #ClutterColor
  * @hue: hue value (0 .. 255)
  * @luminance: luminance value (0 .. 255)
  * @saturation: saturation value (0 .. 255)
@@ -407,7 +407,7 @@ clutter_color_from_hls (ClutterColor *dest,
 /**
  * clutter_color_shade:
  * @src: a #ClutterColor
- * @dest: return location for the shaded color
+ * @dest: (out): return location for the shaded color
  * @shade: the shade factor to apply
  * 
  * Shades @src by the factor of @shade and saves the modified
@@ -424,7 +424,7 @@ clutter_color_shade (const ClutterColor *src,
 /**
  * clutter_color_shadex:
  * @src: a #ClutterColor
- * @dest: return location for the shaded color
+ * @dest: (out): return location for the shaded color
  * @shade: #ClutterFixed the shade factor to apply
  * 
  * Fixed point version of clutter_color_shade().
@@ -481,7 +481,7 @@ clutter_color_to_pixel (const ClutterColor *src)
 
 /**
  * clutter_color_from_pixel:
- * @dest: return location for a #ClutterColor
+ * @dest: (out): 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
@@ -502,7 +502,7 @@ clutter_color_from_pixel (ClutterColor *dest,
 /**
  * clutter_color_parse:
  * @color: a string specifiying a color (named color or #RRGGBBAA)
- * @dest: return location for a #ClutterColor
+ * @dest: (out): return location for a #ClutterColor
  *
  * Parses a string definition of a color, filling the
  * <structfield>red</structfield>, <structfield>green</structfield>, 
diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c
index a5f70f4a2..790d34c19 100644
--- a/clutter/clutter-container.c
+++ b/clutter/clutter-container.c
@@ -424,8 +424,9 @@ get_children_cb (ClutterActor *child,
  *
  * Retrieves all the children of @container.
  *
- * Return value: a list of #ClutterActor<!-- -->s. Use g_list_free()
- *   on the returned list when done.
+ * Return value: (element-type Actor) (transfer container): a list
+ *   of #ClutterActor<!-- -->s. Use g_list_free() on the returned
+ *   list when done.
  *
  * Since: 0.4
  */
@@ -609,8 +610,8 @@ clutter_container_sort_depth_order (ClutterContainer *container)
  * Finds a child actor of a container by its name. Search recurses
  * into any child container.
  *
- * Return value: The child actor with the requested name, or %NULL if no
- *   actor with that name was found.
+ * Return value: (transfer none): The child actor with the requested name,
+ *   or %NULL if no actor with that name was found.
  *
  * Since: 0.6
  */
@@ -753,9 +754,9 @@ destroy_child_meta (ClutterContainer *container,
  * Retrieves the #ClutterChildMeta which contains the data about the
  * @container specific state for @actor.
  *
- * Return value: the #ClutterChildMeta for the @actor child of @container
- *   or %NULL if the specifiec actor does not exist or the container is not
- *   configured to provide #ClutterChildMeta<!-- -->s
+ * Return value: (transfer none): the #ClutterChildMeta for the @actor child
+ *   of @container or %NULL if the specifiec actor does not exist or the
+ *   container is not configured to provide #ClutterChildMeta<!-- -->s
  *
  * Since: 0.8
  */
@@ -826,8 +827,8 @@ clutter_container_destroy_child_meta (ClutterContainer *container,
  *
  * Looks up the #GParamSpec for a child property of @klass.
  *
- * Return value: The #GParamSpec for the property or %NULL if no such
- *   property exist.
+ * Return value: (transfer none): The #GParamSpec for the property or %NULL
+ *   if no such property exist.
  *
  * Since: 0.8
  */
@@ -865,8 +866,8 @@ clutter_container_class_find_child_property (GObjectClass *klass,
  *
  * Returns an array of #GParamSpec for all child properties.
  *
- * Return value: an array of #GParamSpec<!-- -->s which should be freed
- *   after use.
+ * Return value: (array length=n_properties) (transfer container): an array
+ *   of #GParamSpec<!-- -->s which should be freed after use.
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index 0c3899ef0..a275c4da9 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -169,7 +169,7 @@ clutter_event_get_coords (ClutterEvent *event,
  * Retrieves the source #ClutterActor the event originated from, or
  * NULL if the event has no source.
  *
- * Return value: a #ClutterActor
+ * Return value: (transfer none): a #ClutterActor
  *
  * Since: 0.6
  */
@@ -188,7 +188,7 @@ clutter_event_get_source (ClutterEvent *event)
  * Retrieves the source #ClutterStage the event originated for, or
  * NULL if the event has no stage.
  *
- * Return value: a #ClutterStage
+ * Return value: (transfer none): a #ClutterStage
  *
  * Since: 0.8
  */
@@ -460,7 +460,7 @@ clutter_event_get (void)
  * Returns a pointer to the first event from the event queue but 
  * does not remove it. 
  *
- * Return value: A #ClutterEvent or NULL if queue empty.
+ * Return value: (transfer none): A #ClutterEvent or NULL if queue empty.
  *
  * Since: 0.4
  */
diff --git a/clutter/clutter-group.c b/clutter/clutter-group.c
index 85359ea62..454487aca 100644
--- a/clutter/clutter-group.c
+++ b/clutter/clutter-group.c
@@ -794,7 +794,7 @@ clutter_group_get_n_children (ClutterGroup *self)
  *
  * Gets a groups child held at @index_ in stack.
  *
- * Return value: A Clutter actor or NULL if @index_ is invalid.
+ * Return value: (transfer none): A Clutter actor or NULL if @index_ is invalid.
  *
  * Since: 0.2
  **/
diff --git a/clutter/clutter-interval.c b/clutter/clutter-interval.c
index 1be5f38a7..8410be23f 100644
--- a/clutter/clutter-interval.c
+++ b/clutter/clutter-interval.c
@@ -693,8 +693,8 @@ clutter_interval_get_initial_value (ClutterInterval *interval,
  *
  * Gets the pointer to the initial value of @interval
  *
- * Return value: the initial value of the interval. The value
- *   is owned by the #ClutterInterval and it should not be
+ * Return value: (transfer none): the initial value of the interval.
+ *   The value is owned by the #ClutterInterval and it should not be
  *   modified or freed
  *
  * Since: 1.0
@@ -766,8 +766,8 @@ clutter_interval_get_final_value (ClutterInterval *interval,
  *
  * Gets the pointer to the final value of @interval
  *
- * Return value: the final value of the interval. The value
- *   is owned by the #ClutterInterval and it should not be
+ * Return value: (transfer none): the final value of the interval.
+ *   The value is owned by the #ClutterInterval and it should not be
  *   modified or freed
  *
  * Since: 1.0
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 39118b2d6..0a013d091 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -1377,7 +1377,7 @@ post_parse_hook (GOptionContext  *context,
  * Clutter #GOptionGroup has returned %TRUE, Clutter is guaranteed to be
  * initialized.
  *
- * Return value: a #GOptionGroup for the commandline arguments
+ * Return value: (transfer full): a #GOptionGroup for the commandline arguments
  *   recognized by Clutter
  *
  * Since: 0.2
@@ -1420,7 +1420,7 @@ clutter_get_option_group (void)
  * function when needing to set foreign display connection with
  * clutter_x11_set_display(), or with gtk_clutter_init().
  *
- * Return value: a #GOptionGroup for the commandline arguments
+ * Return value: (transfer full): a #GOptionGroup for the commandline arguments
  *   recognized by Clutter
  *
  * Since: 0.8.2
@@ -1441,10 +1441,15 @@ clutter_get_option_group_without_init (void)
   return group;
 }
 
+/* Note that the gobject-introspection annotations for the argc/argv
+ * parameters do not produce the right result; however, they do
+ * allow the common case of argc=NULL, argv=NULL to work.
+ */
+
 /**
  * clutter_init_with_args:
- * @argc: a pointer to the number of command line arguments
- * @argv: a pointer to the array of command line arguments
+ * @argc: (inout): a pointer to the number of command line arguments
+ * @argv: (array length=argc) (inout): a pointer to the array of command line arguments
  * @parameter_string: a string which is displayed in the
  *   first line of <option>--help</option> output, after
  *   <literal><replaceable>programname</replaceable> [OPTION...]</literal>
@@ -1564,8 +1569,8 @@ clutter_parse_args (int    *argc,
 
 /**
  * clutter_init:
- * @argc: The number of arguments in @argv
- * @argv: A pointer to an array of arguments.
+ * @argc: (inout): The number of arguments in @argv
+ * @argv: (array length=argc) (inout): A pointer to an array of arguments.
  *
  * It will initialise everything needed to operate with Clutter and
  * parses some standard command line options. @argc and @argv are
@@ -2220,8 +2225,8 @@ clutter_do_event (ClutterEvent *event)
  *
  * Retrieves the #ClutterActor with @id.
  *
- * Return value: the actor with the passed id or %NULL. The returned
- *   actor does not have its reference count increased.
+ * Return value: (transfer none): the actor with the passed id or %NULL.
+ *   The returned actor does not have its reference count increased.
  *
  * Since: 0.6
  */
@@ -2454,7 +2459,7 @@ clutter_ungrab_pointer_for_device (gint id)
  *
  * Queries the current pointer grab of clutter.
  *
- * Return value: the actor currently holding the pointer grab, or NULL if there is no grab.
+ * Return value: (transfer none): the actor currently holding the pointer grab, or NULL if there is no grab.
  *
  * Since: 0.6
  */
@@ -2539,7 +2544,7 @@ clutter_ungrab_keyboard (void)
  *
  * Queries the current keyboard grab of clutter.
  *
- * Return value: the actor currently holding the keyboard grab, or NULL if there is no grab.
+ * Return value: (transfer none): the actor currently holding the keyboard grab, or NULL if there is no grab.
  *
  * Since: 0.6
  */
@@ -2715,7 +2720,7 @@ clutter_get_font_flags (void)
  *
  * Retrieves the #ClutterInputDevice from its id.
  *
- * Return value: a #ClutterInputDevice, or %NULL
+ * Return value: (transfer none): a #ClutterInputDevice, or %NULL
  *
  * Since: 0.8
  */
@@ -2748,9 +2753,8 @@ clutter_get_input_device_for_id (gint id)
  * You can use the global font map object with the COGL
  * Pango API.
  *
- * Return value: the #PangoFontMap instance. The returned
- *   value is owned by Clutter and it should never be
- *   unreferenced.
+ * Return value: (transfer none): the #PangoFontMap instance. The returned
+ *   value is owned by Clutter and it should never be unreferenced.
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-model.c b/clutter/clutter-model.c
index c301d56cd..5ccb6c56e 100644
--- a/clutter/clutter-model.c
+++ b/clutter/clutter-model.c
@@ -593,7 +593,7 @@ clutter_model_set_column_name (ClutterModel *model,
  * clutter_model_set_types:
  * @model: a #ClutterModel
  * @n_columns: number of columns for the model
- * @types: an array of #GType types
+ * @types: (array length=n_columns): an array of #GType types
  *
  * Sets the types of the columns inside a #ClutterModel.
  *
@@ -637,7 +637,7 @@ clutter_model_set_types (ClutterModel *model,
  * clutter_model_set_names:
  * @model: a #ClutterModel
  * @n_columns: the number of column names
- * @names: an array of strings
+ * @names: (array length=n_columns): an array of strings
  *
  * Assigns a name to the columns of a #ClutterModel.
  *
@@ -691,8 +691,8 @@ clutter_model_get_n_columns (ClutterModel *model)
  * clutter_model_appendv:
  * @model: a #ClutterModel
  * @n_columns: the number of columns and values
- * @columns: a vector with the columns to set
- * @values: a vector with the values
+ * @columns: (array length=n_columns): a vector with the columns to set
+ * @values: (array length=n_columns): a vector with the values
  *
  * Creates and appends a new row to the #ClutterModel, setting the row
  * values for the given @columns upon creation.
@@ -787,8 +787,8 @@ clutter_model_append (ClutterModel *model,
  * clutter_model_prependv:
  * @model: a #ClutterModel
  * @n_columns: the number of columns and values to set
- * @columns: a vector containing the columns to set
- * @values: a vector containing the values for the cells
+ * @columns: (array length=n_columns): a vector containing the columns to set
+ * @values: (array length=n_columns): a vector containing the values for the cells
  *
  * Creates and prepends a new row to the #ClutterModel, setting the row
  * values for the given @columns upon creation.
@@ -924,8 +924,8 @@ clutter_model_insert (ClutterModel *model,
  * @model: a #ClutterModel
  * @row: row index
  * @n_columns: the number of columns and values to set
- * @columns: a vector containing the columns to set
- * @values: a vector containing the values for the cells
+ * @columns: (array length=n_columns): a vector containing the columns to set
+ * @values: (array length=n_columns): a vector containing the values for the cells
  *
  * Inserts data at @row into the #ClutterModel, setting the row
  * values for the given @columns upon creation.
@@ -1117,9 +1117,9 @@ clutter_model_get_column_type (ClutterModel *model,
  *
  * Retrieves a #ClutterModelIter representing the row at the given index.
  *
- * Return value: A new #ClutterModelIter, or %NULL if @row was out of bounds.
- *   When done using the iterator object, call g_object_unref() to deallocate
- *   its resources
+ * Return value: (transfer full): A new #ClutterModelIter, or %NULL if @row was
+ *   out of bounds. When done using the iterator object, call g_object_unref()
+ *   to deallocate its resources
  *
  * Since: 0.6
  */
@@ -1145,7 +1145,7 @@ clutter_model_get_iter_at_row (ClutterModel *model,
  *
  * Retrieves a #ClutterModelIter representing the first row in @model.
  *
- * Return value: A new #ClutterModelIter. Call g_object_unref() when
+ * Return value: (transfer full): A new #ClutterModelIter. Call g_object_unref() when
  *   done using it
  *
  * Since: 0.6
@@ -1164,7 +1164,7 @@ clutter_model_get_first_iter (ClutterModel *model)
  *
  * Retrieves a #ClutterModelIter representing the last row in @model.
  *
- * Return value: A new #ClutterModelIter. Call g_object_unref() when
+ * Return value: (transfer full): A new #ClutterModelIter. Call g_object_unref() when
  *   done using it
  *
  * Since: 0.6
@@ -1928,7 +1928,7 @@ clutter_model_iter_is_last (ClutterModelIter *iter)
  * The model implementation should take into account the presence of
  * a filter function.
  *
- * Return value: The passed iterator, updated to point at the next
+ * Return value: (transfer none): The passed iterator, updated to point at the next
  *   row in the model.
  *
  * Since: 0.6
@@ -1955,7 +1955,7 @@ clutter_model_iter_next (ClutterModelIter *iter)
  * The model implementation should take into account the presence of
  * a filter function.
  *
- * Return value: The passed iterator, updated to point at the previous
+ * Return value: (transfer none): The passed iterator, updated to point at the previous
  *   row in the model.
  *
  * Since: 0.6
@@ -1980,7 +1980,7 @@ clutter_model_iter_prev (ClutterModelIter *iter)
  * 
  * Retrieves a pointer to the #ClutterModel that this iter is part of.
  *
- * Return value: a pointer to a #ClutterModel.
+ * Return value: (transfer none): a pointer to a #ClutterModel.
  *
  * Since: 0.6
  */
diff --git a/clutter/clutter-path.c b/clutter/clutter-path.c
index 43566d588..88f4c5685 100644
--- a/clutter/clutter-path.c
+++ b/clutter/clutter-path.c
@@ -936,7 +936,7 @@ clutter_path_get_node (ClutterPath     *path,
  * list to become invalid so you should copy them if you want to keep
  * the list.
  *
- * Return value: a list of nodes in the path.
+ * Return value: (transfer container) (element-type ClutterPathNode): a list of nodes in the path.
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-score.c b/clutter/clutter-score.c
index cbb808a02..5e640f628 100644
--- a/clutter/clutter-score.c
+++ b/clutter/clutter-score.c
@@ -1078,8 +1078,9 @@ clutter_score_remove_all (ClutterScore *score)
  *
  * Retrieves the #ClutterTimeline for @id inside @score.
  *
- * Return value: the requested timeline, or %NULL. This function does
- *   not increase the reference count on the returned #ClutterTimeline
+ * Return value: (transfer none): the requested timeline, or %NULL. This
+ *   function does not increase the reference count on the returned
+ *   #ClutterTimeline
  *
  * Since: 0.6
  */
@@ -1108,10 +1109,10 @@ clutter_score_get_timeline (ClutterScore *score,
  *
  * Retrieves a list of all the #ClutterTimelines managed by @score.
  *
- * Return value: a #GSList containing all the timelines in the score.
- *   This function does not increase the reference count of the
- *   returned timelines. Use g_slist_free() on the returned list to
- *   deallocate its resources.
+ * Return value: (transfer container) (element-type ClutterTimeline): a #GSList
+ *   containing all the timelines in the score. This function does not increase
+ *   the reference count of the returned timelines. Use g_slist_free() on the
+ *   returned list to deallocate its resources.
  *
  * Since: 0.6
  */
diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c
index faeeede35..c0154c8cb 100644
--- a/clutter/clutter-script.c
+++ b/clutter/clutter-script.c
@@ -1888,8 +1888,8 @@ clutter_script_load_from_data (ClutterScript  *script,
  * Retrieves the object bound to @name. This function does not increment
  * the reference count of the returned object.
  *
- * Return value: the named object, or %NULL if no object with the
- *   given name was available
+ * Return value: : (transfer none): the named object, or %NULL if no object
+ *   with the given name was available
  *
  * Since: 0.6
  */
@@ -2438,8 +2438,8 @@ clutter_script_lookup_filename (ClutterScript *script,
  * Note: this function does not increment the reference count of the
  * objects it returns.
  *
- * Return value: a list of #GObject<!-- -->s, or %NULL. The objects are
- *   owned by the #ClutterScript instance. Use g_list_free() on the
+ * Return value: (transfer container) (element-type GObject): a list of #GObject<!-- -->s,
+ *   or %NULL. The objects are owned by the #ClutterScript instance. Use g_list_free() on the
  *   returned value when done.
  *
  * Since: 0.8.2
diff --git a/clutter/clutter-shader-types.c b/clutter/clutter-shader-types.c
index f19afac74..b6f64beee 100644
--- a/clutter/clutter-shader-types.c
+++ b/clutter/clutter-shader-types.c
@@ -533,16 +533,16 @@ clutter_value_get_shader_int (const GValue *value,
 /**
  * clutter_value_get_shader_matrix:
  * @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 a matrix of floating point values stored inside
  * the passed #GValue. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_MATRIX.
  *
- * Return value: the pointer to a matrix of floating point values.
- *   The returned value is owned by the #GValue and should never
- *   be modified or freed.
+ * Return value: (array length=length) (transfer none): the pointer to a matrix
+ *   of floating point values. The returned value is owned by the #GValue and
+ *   should never be modified or freed.
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter-stage-manager.c b/clutter/clutter-stage-manager.c
index b6cc32a72..65ea52097 100644
--- a/clutter/clutter-stage-manager.c
+++ b/clutter/clutter-stage-manager.c
@@ -161,8 +161,8 @@ clutter_stage_manager_init (ClutterStageManager *stage_manager)
  *
  * Returns the default #ClutterStageManager.
  *
- * Return value: the default stage manager instance. The returned object
- *   is owned by Clutter and you should not reference or unreference it.
+ * Return value: (transfer none): the default stage manager instance. The returned
+ *   object is owned by Clutter and you should not reference or unreference it.
  *
  * Since: 0.8
  */
@@ -207,8 +207,8 @@ clutter_stage_manager_set_default_stage (ClutterStageManager *stage_manager,
  *
  * Returns the default #ClutterStage.
  *
- * Return value: the default stage. The returned object is owned by
- *   Clutter and you should never reference or unreference it
+ * Return value: (transfer none): the default stage. The returned object
+ *   is owned by Clutter and you should never reference or unreference it
  *
  * Since: 0.8
  */
@@ -224,8 +224,8 @@ clutter_stage_manager_get_default_stage (ClutterStageManager *stage_manager)
  *
  * Lists all currently used stages.
  *
- * Return value: a newly allocated list of #ClutterStage objects. Use
- *   g_slist_free() to deallocate it when done.
+ * Return value: (transfer container) (element-type ClutterStage): a newly allocated list
+ *   of #ClutterStage objects. Use g_slist_free() to deallocate it when done.
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c
index 729faea0b..7f6e50425 100644
--- a/clutter/clutter-stage.c
+++ b/clutter/clutter-stage.c
@@ -847,7 +847,7 @@ clutter_stage_init (ClutterStage *self)
  *
  * Clutter guarantess the existence of the default stage.
  *
- * Return value: the main #ClutterStage.  You should never
+ * Return value: (transfer none): the main #ClutterStage.  You should never
  *   destroy or unref the returned actor.
  */
 ClutterActor *
@@ -1333,7 +1333,7 @@ clutter_stage_read_pixels (ClutterStage *stage,
  * Checks the scene at the coordinates @x and @y and returns a pointer
  * to the #ClutterActor at those coordinates.
  *
- * Return value: the actor at the specified coordinates, if any
+ * Return value: (transfer none): the actor at the specified coordinates, if any
  */
 ClutterActor *
 clutter_stage_get_actor_at_pos (ClutterStage *stage,
@@ -1537,7 +1537,7 @@ clutter_stage_set_key_focus (ClutterStage *stage,
  *
  * Retrieves the actor that is currently under key focus.
  *
- * Return value: the actor with key focus, or the stage
+ * Return value: (transfer none): the actor with key focus, or the stage
  *
  * Since: 0.6
  */
diff --git a/clutter/clutter-text.c b/clutter/clutter-text.c
index 1ff3f6a96..0f5c66c06 100644
--- a/clutter/clutter-text.c
+++ b/clutter/clutter-text.c
@@ -2947,7 +2947,7 @@ clutter_text_set_markup (ClutterText *self,
  *
  * Retrieves the current #PangoLayout used by a #ClutterText actor.
  *
- * Return value: a #PangoLayout. The returned object is owned by
+ * Return value: (transfer none): a #PangoLayout. The returned object is owned by
  *   the #ClutterText actor and should not be modified or freed
  *
  * Since: 1.0
@@ -3236,9 +3236,8 @@ clutter_text_set_attributes (ClutterText   *self,
  * Gets the attribute list that was set on the #ClutterText actor
  * clutter_text_set_attributes(), if any.
  *
- * Return value: the attribute list, or %NULL if none was set. The
- *  returned value is owned by the #ClutterText and should not be
- *  unreferenced.
+ * Return value: (transfer none): the attribute list, or %NULL if none was set. The
+ *  returned value is owned by the #ClutterText and should not be unreferenced.
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter-timeline.c b/clutter/clutter-timeline.c
index 33870e8fb..1aa23488e 100644
--- a/clutter/clutter-timeline.c
+++ b/clutter/clutter-timeline.c
@@ -1617,9 +1617,9 @@ clutter_timeline_add_marker_at_time (ClutterTimeline *timeline,
  * negative integer, all the markers attached to @timeline will be
  * returned.
  *
- * Return value: a newly allocated, %NULL terminated string array
- *   containing the names of the markers. Use g_strfreev() when
- *   done.
+ * Return value: (array zero-terminated=1 length=n_markers): a newly
+ *   allocated, %NULL terminated string array containing the names of
+ *   the markers. Use g_strfreev() when done.
  *
  * Since: 0.8
  */
diff --git a/clutter/json/json-array.c b/clutter/json/json-array.c
index c4f15cdde..61c8a4c8f 100644
--- a/clutter/json/json-array.c
+++ b/clutter/json/json-array.c
@@ -160,9 +160,9 @@ json_array_unref (JsonArray *array)
  *
  * Gets the elements of a #JsonArray as a list of #JsonNode<!-- -->s.
  *
- * Return value: a #GList containing the elements of the array. The
- *   contents of the list are owned by the array and should never be
- *   modified or freed. Use g_list_free() on the returned list when
+ * Return value: (transfer container) (element-type JsonNode): a #GList containing
+ *   the elements of the array. The contents of the list are owned by the array and
+ *   should never be  modified or freed. Use g_list_free() on the returned list when
  *   done using it
  */
 GList *
@@ -189,7 +189,7 @@ json_array_get_elements (JsonArray *array)
  * Retrieves the #JsonNode containing the value of the element at @index_
  * inside a #JsonArray.
  *
- * Return value: a pointer to the #JsonNode at the requested index
+ * Return value: (transfer none): a pointer to the #JsonNode at the requested index
  */
 JsonNode *
 json_array_get_element (JsonArray *array,
diff --git a/clutter/json/json-node.c b/clutter/json/json-node.c
index 74fbf58ec..f20f7adc4 100644
--- a/clutter/json/json-node.c
+++ b/clutter/json/json-node.c
@@ -158,7 +158,7 @@ json_node_take_object (JsonNode   *node,
  *
  * Retrieves the #JsonObject stored inside a #JsonNode
  *
- * Return value: the #JsonObject
+ * Return value: (transfer none): the #JsonObject
  */
 JsonObject *
 json_node_get_object (JsonNode *node)
@@ -243,7 +243,7 @@ json_node_take_array (JsonNode  *node,
  *
  * Retrieves the #JsonArray stored inside a #JsonNode
  *
- * Return value: the #JsonArray
+ * Return value: (transfer none): the #JsonArray
  */
 JsonArray *
 json_node_get_array (JsonNode *node)
@@ -391,7 +391,7 @@ json_node_type_name (JsonNode *node)
  *
  * Retrieves the parent #JsonNode of @node.
  *
- * Return value: the parent node, or %NULL if @node is the root node
+ * Return value: (transfer none): the parent node, or %NULL if @node is the root node
  */
 JsonNode *
 json_node_get_parent (JsonNode *node)
diff --git a/clutter/json/json-object.c b/clutter/json/json-object.c
index e5859d967..b7a0b5015 100644
--- a/clutter/json/json-object.c
+++ b/clutter/json/json-object.c
@@ -197,10 +197,11 @@ g_hash_table_get_keys (GHashTable *hash_table)
  * Retrieves all the names of the members of a #JsonObject. You can
  * obtain the value for each member using json_object_get_member().
  *
- * Return value: a #GList of member names. The content of the list
- *   is owned by the #JsonObject and should never be modified or
- *   freed. When you have finished using the returned list, use
- *   g_list_free() to free the resources it has allocated.
+ * Return value: (transfer container) (element-type utf8): a #GList of
+ *   member names. The content of the list is owned by the #JsonObject
+ *   and should never be modified or freed. When you have finished using
+ *   the returned list, use g_list_free() to free the resources it has
+ *   allocated.
  */
 GList *
 json_object_get_members (JsonObject *object)
@@ -218,7 +219,7 @@ json_object_get_members (JsonObject *object)
  * Retrieves the #JsonNode containing the value of @member_name inside
  * a #JsonObject.
  *
- * Return value: a pointer to the node for the requested object
+ * Return value: (transfer none): a pointer to the node for the requested object
  *   member, or %NULL
  */
 JsonNode *
diff --git a/clutter/json/json-parser.c b/clutter/json/json-parser.c
index 9cec9d93a..82ab469c3 100644
--- a/clutter/json/json-parser.c
+++ b/clutter/json/json-parser.c
@@ -1009,8 +1009,8 @@ json_parser_load_from_data (JsonParser   *parser,
  *
  * Retrieves the top level node from the parsed JSON stream.
  *
- * Return value: the root #JsonNode . The returned node is owned by
- *   the #JsonParser and should never be modified or freed.
+ * Return value: (transfer none): the root #JsonNode . The returned node
+ *   is owned by the #JsonParser and should never be modified or freed.
  */
 JsonNode *
 json_parser_get_root (JsonParser *parser)