introspection: Add annotations

Reduce the amount of warnings coming from g-ir-scanner.

clutter/clutter-actor.c

@@ -10245,8 +10245,9 @@ clutter_actor_get_pango_context (ClutterActor *self)
  *
  * See also clutter_actor_get_pango_context().
  *
- * Return value: the newly created #PangoContext. Use g_object_unref()
+ * Return value: (transfer full): the newly created #PangoContext.
- *   on the returned value to deallocate its resources
+ *   Use g_object_unref() on the returned value to deallocate its
+ *   resources
  *
  * Since: 1.0
  */
@@ -10279,8 +10280,8 @@ clutter_actor_create_pango_context (ClutterActor *self)
  * and #ClutterBackend::resolution-changed signals, and call
  * pango_layout_context_changed() in response to them.
  *
- * Return value: the newly created #PangoLayout. Use g_object_unref()
+ * Return value: (transfer full): the newly created #PangoLayout.
- *   when done
+ *   Use g_object_unref() when done
  *
  * Since: 1.0
  */

clutter/clutter-alpha.c

@@ -1313,7 +1313,7 @@ register_alpha_internal (AlphaData *alpha_data)
 }
 
 /**
- * clutter_alpha_register_func:
+ * clutter_alpha_register_func: (skip):
  * @func: a #ClutterAlphaFunc
  * @data: user data to pass to @func, or %NULL
  *
@@ -1353,6 +1353,8 @@ clutter_alpha_register_func (ClutterAlphaFunc func,
  *
  * The logical id is always greater than %CLUTTER_ANIMATION_LAST.
  *
+ * Rename: clutter_alpha_register_func
+ *
  * Return value: the logical id of the alpha function
  *
  * Since: 1.0

clutter/clutter-animator.c

@@ -1084,7 +1084,9 @@ clutter_animator_get_timeline (ClutterAnimator *animator)
  * Start the ClutterAnimator, this is a thin wrapper that rewinds
  * and starts the animators current timeline.
  *
- * Return value: the #ClutterTimeline that drives the animator.
+ * Return value: (transfer none): the #ClutterTimeline that drives
+ *   the animator. The returned timeline is owned by the #ClutterAnimator
+ *   and it should not be unreferenced
  *
  * Since: 1.2
  */

clutter/clutter-behaviour.c

@@ -511,7 +511,7 @@ clutter_behaviour_get_nth_actor (ClutterBehaviour *behave,
 /**
  * clutter_behaviour_actors_foreach:
  * @behave: a #ClutterBehaviour
- * @func: a function called for each actor
+ * @func: (scope call): a function called for each actor
  * @data: optional data to be passed to the function, or %NULL
  *
  * Calls @func for every actor driven by @behave.

clutter/clutter-box.c

@@ -591,7 +591,9 @@ clutter_box_set_layout_manager (ClutterBox           *box,
  *
  * Retrieves the #ClutterLayoutManager instance used by @box
  *
- * Return value: a #ClutterLayoutManager
+ * Return value: (transfer none): a #ClutterLayoutManager. The returned
+ *   #ClutterLayoutManager is owned by the #ClutterBox and it should not
+ *   be unreferenced
  *
  * Since: 1.2
  */

clutter/clutter-container.c

@@ -440,7 +440,7 @@ clutter_container_get_children (ClutterContainer *container)
 /**
  * clutter_container_foreach:
  * @container: a #ClutterContainer
- * @callback: a function to be called for each child
+ * @callback: (scope call): a function to be called for each child
  * @user_data: data to be passed to the function, or %NULL
  *
  * Calls @callback for each child of @container that was added
@@ -473,7 +473,7 @@ clutter_container_foreach (ClutterContainer *container,
 /**
  * clutter_container_foreach_with_internals:
  * @container: a #ClutterContainer
- * @callback: a function to be called for each child
+ * @callback: (scope call): a function to be called for each child
  * @user_data: data to be passed to the function, or %NULL
  *
  * Calls @callback for each child of @container, including "internal"

clutter/clutter-event.c

@@ -584,7 +584,9 @@ clutter_event_get_device_type (ClutterEvent *event)
  * The #ClutterInputDevice structure is completely opaque and should
  * be cast to the platform-specific implementation.
  *
- * Return value: the #ClutterInputDevice or %NULL
+ * Return value: (transfer none): the #ClutterInputDevice or %NULL. The
+ *   returned device is owned by the #ClutterEvent and it should not
+ *   be unreferenced
  *
  * Since: 1.0
  */

clutter/clutter-interval.c

@@ -597,7 +597,7 @@ clutter_interval_new_with_values (GType         gtype,
  *
  * Creates a copy of @interval.
  *
- * Return value: the newly created #ClutterInterval
+ * Return value: (transfer full): the newly created #ClutterInterval
  *
  * Since: 1.0
  */
@@ -968,7 +968,7 @@ clutter_interval_compute (ClutterInterval *interval,
 }
 
 /**
- * clutter_interval_register_progress_func:
+ * clutter_interval_register_progress_func: (skip):
  * @value_type: a #GType
  * @func: a #ClutterProgressFunc, or %NULL to unset a previously
  *   set progress function

clutter/clutter-layout-manager.c

@@ -825,8 +825,10 @@ get_child_meta (ClutterLayoutManager *manager,
  * to the @actor child of @container, eventually by creating one if the
  * #ClutterLayoutManager supports layout properties
  *
- * Return value: a #ClutterLayoutMeta, or %NULL if the #ClutterLayoutManager
+ * Return value: (transfer none): a #ClutterLayoutMeta, or %NULL if the
- *   does not have layout properties
+ *   #ClutterLayoutManager does not have layout properties. The returned
+ *   layout meta instance is owned by the #ClutterLayoutManager and it
+ *   should not be unreferenced
  *
  * Since: 1.0
  */

clutter/clutter-main.c

@@ -2603,7 +2603,7 @@ _clutter_process_event (ClutterEvent *event)
 
 
 /**
- * clutter_get_actor_by_gid
+ * clutter_get_actor_by_gid:
  * @id: a #ClutterActor ID.
  *
  * Retrieves the #ClutterActor with @id.

clutter/clutter-path.c

@@ -995,7 +995,7 @@ clutter_path_get_nodes (ClutterPath *path)
 /**
  * clutter_path_foreach:
  * @path: a #ClutterPath
- * @callback: the function to call with each node
+ * @callback: (scope call): the function to call with each node
  * @user_data: user data to pass to the function
  *
  * Calls a function for each node of the path.

clutter/clutter-script.c

@@ -984,7 +984,8 @@ connect_each_object (gpointer key,
  * This function allows to control how the signal handlers are
  * going to be connected to their respective signals. It is meant
  * primarily for language bindings to allow resolving the function
- * names using the native API.
+ * names using the native API, but it can also be used on platforms
+ * that do not support GModule.
  *
  * Applications should use clutter_script_connect_signals().
  *

clutter/clutter-shader.c

@@ -836,7 +836,9 @@ clutter_shader_get_vertex_source (ClutterShader *shader)
  *
  * Retrieves the underlying #CoglHandle for the shader program.
  *
- * Return value: A #CoglHandle for the shader program, or %NULL
+ * Return value: (transfer none): A #CoglHandle for the shader program,
+ *   or %NULL. The handle is owned by the #ClutterShader and it should
+ *   not be unreferenced
  *
  * Since: 1.0
  */
@@ -854,7 +856,9 @@ clutter_shader_get_cogl_program (ClutterShader *shader)
  *
  * Retrieves the underlying #CoglHandle for the fragment shader.
  *
- * Return value: A #CoglHandle for the fragment shader, or %NULL
+ * Return value: (transfer none): A #CoglHandle for the fragment
+ *   shader, or %NULL. The handle is owned by the #ClutterShader
+ *   and it should not be unreferenced
  *
  * Since: 1.0
  */
@@ -872,7 +876,9 @@ clutter_shader_get_cogl_fragment_shader (ClutterShader *shader)
  *
  * Retrieves the underlying #CoglHandle for the vertex shader.
  *
- * Return value: A #CoglHandle for the vertex shader, or %NULL
+ * Return value: (transfer none): A #CoglHandle for the vertex
+ *   shader, or %NULL. The handle is owned by the #ClutterShader
+ *   and it should not be unreferenced
  *
  * Since: 1.0
  */

clutter/clutter-state.c

@@ -568,7 +568,9 @@ clutter_state_change (ClutterState *state,
  * The state will animate during its transition, see
  * #clutter_state_warp_to_state for animation-free state switching.
  *
- * Return value: the #ClutterTimeline that drives the state transition
+ * Return value: (transfer none): the #ClutterTimeline that drives the
+ *   state transition. The returned timeline is owned by the #ClutterState
+ *   and it should not be unreferenced
  *
  * Since: 1.4
  */
@@ -588,7 +590,9 @@ clutter_state_set_state (ClutterState *state,
  *
  * Change to the specified target state immediately with no animation.
  *
- * Return value: the #ClutterTimeline that drives the state transition
+ * Return value: (transfer none): the #ClutterTimeline that drives the
+ *   state transition. The returned timeline is owned by the #ClutterState
+ *   and it should not be unreferenced
  *
  * Since: 1.4
  */
@@ -888,8 +892,8 @@ clutter_state_fetch_state (ClutterState *state,
  * Sets one specific end key for a state_name, object, property_name
  * combination.
  *
- * Return value: the #ClutterState instance, allowing chaining of
+ * Return value: (transfer none): the #ClutterState instance, allowing
- *   multiple calls
+ *   chaining of multiple calls
  *
  * Since: 1.4
  */

clutter/clutter-texture.c

@@ -1248,12 +1248,13 @@ clutter_texture_init (ClutterTexture *self)
  * @texture: A #ClutterTexture
  *
  * Returns a handle to the underlying COGL material used for drawing
- * the actor. No extra reference is taken so if you need to keep the
+ * the actor.
- * handle then you should call cogl_handle_ref() on it.
+ *
+ * Return value: (transfer none): a handle for a #CoglMaterial. The
+ *   material is owned by the #ClutterTexture and it should not be
+ *   unreferenced
  *
  * Since: 1.0
- *
- * Return value: COGL material handle
  */
 CoglHandle
 clutter_texture_get_cogl_material (ClutterTexture *texture)
@@ -1305,7 +1306,7 @@ clutter_texture_set_cogl_material (ClutterTexture *texture,
 }
 
 /**
- * clutter_texture_get_cogl_texture
+ * clutter_texture_get_cogl_texture:
  * @texture: A #ClutterTexture
  *
  * Retrieves the handle to the underlying COGL texture used for drawing
@@ -1317,9 +1318,10 @@ clutter_texture_set_cogl_material (ClutterTexture *texture,
  * layers you should use clutter_texture_get_cogl_material() instead
  * and use the #CoglMaterial API.
  *
- * Since: 0.8
+ * Return value: (transfer none): a #CoglHandle for the texture. The returned
+ *   handle is owned by the #ClutterTexture and it should not be unreferenced
  *
- * Return value: COGL texture handle
+ * Since: 0.8
  */
 CoglHandle
 clutter_texture_get_cogl_texture (ClutterTexture *texture)

clutter/clutter-timeline.c

@@ -965,7 +965,8 @@ clutter_timeline_is_playing (ClutterTimeline *timeline)
  * be started and will not be positioned to the current position of
  * @timeline: you will have to start it with clutter_timeline_start().
  *
- * Return Value: a new #ClutterTimeline, cloned from @timeline
+ * Return Value: (transfer full): a new #ClutterTimeline, cloned
+ *   from @timeline
  *
  * Since: 0.4
  */
@@ -1339,9 +1340,9 @@ collect_markers (const gchar *key,
  * negative integer, all the markers attached to @timeline will be
  * returned.
  *
- * Return value: (array zero-terminated=1 length=n_markers): a newly
+ * Return value: (transfer full) (array zero-terminated=1 length=n_markers):
- *   allocated, %NULL terminated string array containing the names of
+ *   a newly allocated, %NULL terminated string array containing the names
- *   the markers. Use g_strfreev() when done.
+ *   of the markers. Use g_strfreev() when done.
  *
  * Since: 0.8
  */