From 3e74f42f07c0d4a5f830a49274cfe9a78268217f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Fri, 3 Sep 2010 12:14:50 +0100 Subject: [PATCH] introspection: Add annotations Reduce the amount of warnings coming from g-ir-scanner. --- clutter/clutter-actor.c | 9 +++++---- clutter/clutter-alpha.c | 4 +++- clutter/clutter-animator.c | 4 +++- clutter/clutter-behaviour.c | 2 +- clutter/clutter-box.c | 4 +++- clutter/clutter-container.c | 4 ++-- clutter/clutter-event.c | 4 +++- clutter/clutter-interval.c | 4 ++-- clutter/clutter-layout-manager.c | 6 ++++-- clutter/clutter-main.c | 2 +- clutter/clutter-path.c | 2 +- clutter/clutter-script.c | 3 ++- clutter/clutter-shader.c | 12 +++++++++--- clutter/clutter-state.c | 12 ++++++++---- clutter/clutter-texture.c | 16 +++++++++------- clutter/clutter-timeline.c | 9 +++++---- 16 files changed, 61 insertions(+), 36 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index ace3469a3..7fd6520eb 100644 --- a/clutter/clutter-actor.c +++ b/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() - * on the returned value to deallocate its resources + * Return value: (transfer full): the newly created #PangoContext. + * 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() - * when done + * Return value: (transfer full): the newly created #PangoLayout. + * Use g_object_unref() when done * * Since: 1.0 */ diff --git a/clutter/clutter-alpha.c b/clutter/clutter-alpha.c index 5565cd894..f0582814e 100644 --- a/clutter/clutter-alpha.c +++ b/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 diff --git a/clutter/clutter-animator.c b/clutter/clutter-animator.c index 521ec7c68..fd7a7acf6 100644 --- a/clutter/clutter-animator.c +++ b/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 */ diff --git a/clutter/clutter-behaviour.c b/clutter/clutter-behaviour.c index 93bc493fe..3db89971c 100644 --- a/clutter/clutter-behaviour.c +++ b/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. diff --git a/clutter/clutter-box.c b/clutter/clutter-box.c index 694e1a0e6..cbf9b517e 100644 --- a/clutter/clutter-box.c +++ b/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 */ diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c index c47526b9a..b495123e6 100644 --- a/clutter/clutter-container.c +++ b/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" diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c index f71b21312..40be42d83 100644 --- a/clutter/clutter-event.c +++ b/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 */ diff --git a/clutter/clutter-interval.c b/clutter/clutter-interval.c index 224e0f012..1be1c4871 100644 --- a/clutter/clutter-interval.c +++ b/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 diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c index 6e185babb..67d415272 100644 --- a/clutter/clutter-layout-manager.c +++ b/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 - * does not have layout properties + * Return value: (transfer none): a #ClutterLayoutMeta, or %NULL if the + * #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 */ diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c index 91d187144..daa28910c 100644 --- a/clutter/clutter-main.c +++ b/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. diff --git a/clutter/clutter-path.c b/clutter/clutter-path.c index 7f6eafc61..a8f7c4936 100644 --- a/clutter/clutter-path.c +++ b/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. diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c index b5be5267f..6eb13d22d 100644 --- a/clutter/clutter-script.c +++ b/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(). * diff --git a/clutter/clutter-shader.c b/clutter/clutter-shader.c index 6e932c616..c4cfd6707 100644 --- a/clutter/clutter-shader.c +++ b/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 */ diff --git a/clutter/clutter-state.c b/clutter/clutter-state.c index b05338af4..bf963f968 100644 --- a/clutter/clutter-state.c +++ b/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 - * multiple calls + * Return value: (transfer none): the #ClutterState instance, allowing + * chaining of multiple calls * * Since: 1.4 */ diff --git a/clutter/clutter-texture.c b/clutter/clutter-texture.c index 4d28a3e0b..423d4e1cc 100644 --- a/clutter/clutter-texture.c +++ b/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 - * handle then you should call cogl_handle_ref() on it. + * the actor. + * + * 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) diff --git a/clutter/clutter-timeline.c b/clutter/clutter-timeline.c index 5f1789943..1f7c7f1fc 100644 --- a/clutter/clutter-timeline.c +++ b/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 - * allocated, %NULL terminated string array containing the names of - * the markers. Use g_strfreev() when done. + * Return value: (transfer full) (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 */