Further annotation fixes

clutter/clutter-actor.c

@@ -2332,8 +2332,8 @@ _clutter_actor_transform_and_project_box (ClutterActor          *self,
  * @self: A #ClutterActor
  * @ancestor: (allow-none): A #ClutterActor to calculate the vertices
  *   against, or %NULL to use the default #ClutterStage
- * @verts: (out) (array fixed-size=4): return location for an array of
+ * @verts: (out) (array fixed-size=4) (element-type Clutter.Vertex): return
- *   4 #ClutterVertex in which to store the result.
+ *   location for an array of 4 #ClutterVertex in which to store the result
  *
  * Calculates the transformed coordinates of the four corners of the
  * actor in the plane of @ancestor. The returned vertices relate to
@@ -11112,7 +11112,7 @@ clutter_actor_remove_action_by_name (ClutterActor *self,
  *
  * Retrieves the list of actions applied to @self
  *
- * Return value: (transfer container) (element-type ClutterAction): a copy
+ * Return value: (transfer container) (element-type Clutter.Action): a copy
  *   of the list of #ClutterAction<!-- -->s. The contents of the list are
  *   owned by the #ClutterActor. Use g_list_free() to free the resources
  *   allocated by the returned #GList
@@ -11317,7 +11317,7 @@ clutter_actor_remove_constraint_by_name (ClutterActor *self,
  *
  * Retrieves the list of constraints applied to @self
  *
- * Return value: (transfer container) (element-type ClutterConstraint): a copy
+ * Return value: (transfer container) (element-type Clutter.Constraint): a copy
  *   of the list of #ClutterConstraint<!-- -->s. The contents of the list are
  *   owned by the #ClutterActor. Use g_list_free() to free the resources
  *   allocated by the returned #GList
@@ -11573,7 +11573,7 @@ clutter_actor_remove_effect_by_name (ClutterActor *self,
  *
  * Retrieves the #ClutterEffect<!-- -->s applied on @self, if any
  *
- * Return value: (transfer container) (element-type ClutterEffect): a list
+ * Return value: (transfer container) (element-type Clutter.Effect): a list
  *   of #ClutterEffect<!-- -->s, or %NULL. The elements of the returned
  *   list are owned by Clutter and they should not be freed. You should
  *   free the returned list using g_list_free() when done

clutter/clutter-animator.c

@@ -1354,7 +1354,7 @@ clutter_animator_set_key (ClutterAnimator *animator,
  * Returns a list of pointers to opaque structures with accessor functions
  * that describe the keys added to an animator.
  *
- * Return value: (transfer container) (element-type ClutterAnimatorKey): a
+ * Return value: (transfer container) (element-type Clutter.AnimatorKey): a
  *   list of #ClutterAnimatorKey<!-- -->s; the contents of the list are owned
  *   by the #ClutterAnimator, but you should free the returned list when done,
  *   using g_list_free()

clutter/clutter-behaviour.c

@@ -655,7 +655,7 @@ 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: (transfer container) (element-type ClutterActor): a list of
+ * Return value: (transfer container) (element-type Clutter.Actor): a list of
  *   actors. You should free the returned list with g_slist_free() when
  *   finished using it.
  * 

clutter/clutter-color.c

@@ -485,7 +485,7 @@ clutter_color_from_string (ClutterColor *color,
  * hex digits representing the red, green, blue and alpha components
  * respectively.
  *
- * Return value: a newly-allocated text string
+ * Return value: (transfer full): a newly-allocated text string
  *
  * Since: 0.2
  */
@@ -599,8 +599,8 @@ clutter_color_free (ClutterColor *color)
  *
  * Creates a new #ClutterColor with the given values.
  *
- * Return value: the newly allocated color. Use clutter_color_free()
+ * Return value: (transfer full): the newly allocated color.
- *   when done
+ *   Use clutter_color_free() when done
  *
  * Since: 0.8.4
  */
@@ -701,7 +701,7 @@ clutter_value_set_color (GValue             *value,
  *
  * Gets the #ClutterColor contained in @value.
  *
- * Return value: the colors inside the passed #GValue
+ * Return value: (transfer none): the color inside the passed #GValue
  *
  * Since: 0.8.4
  */

clutter/clutter-container.c

@@ -891,7 +891,7 @@ clutter_container_class_find_child_property (GObjectClass *klass,
  *
  * Returns an array of #GParamSpec for all child properties.
  *
- * Return value: (array length=n_properties) (transfer container): an array
+ * Return value: (array length=n_properties) (transfer full): an array
  *   of #GParamSpec<!-- -->s which should be freed after use.
  *
  * Since: 0.8

clutter/clutter-device-manager.c

@@ -212,7 +212,7 @@ clutter_device_manager_get_default (void)
  *
  * Lists all currently registered input devices
  *
- * Return value: (transfer container) (element-type ClutterInputDevice):
+ * Return value: (transfer container) (element-type Clutter.InputDevice):
  *   a newly allocated list of #ClutterInputDevice objects. Use
  *   g_slist_free() to deallocate it when done
  *
@@ -236,7 +236,7 @@ clutter_device_manager_list_devices (ClutterDeviceManager *device_manager)
  *
  * Lists all currently registered input devices
  *
- * Return value: (transfer none) (element-type ClutterInputDevice):
+ * Return value: (transfer none) (element-type Clutter.InputDevice):
  *   a pointer to the internal list of #ClutterInputDevice objects. The
  *   returned list is owned by the #ClutterDeviceManager and should never
  *   be modified or freed

clutter/clutter-frame-source.c

@@ -80,6 +80,8 @@ static GSourceFuncs clutter_frame_source_funcs =
  * multiple times to catch up missing frames if @func takes more than
  * @interval ms to execute.
  *
+ * Rename to: clutter_frame_source_add
+ *
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 0.8
@@ -115,7 +117,7 @@ clutter_frame_source_add_full (gint           priority,
 }
 
 /**
- * clutter_frame_source_add:
+ * clutter_frame_source_add: (skip)
  * @fps: the number of times per second to call the function
  * @func: function to call
  * @data: data to pass to the function

clutter/clutter-layout-manager.c

@@ -1230,9 +1230,9 @@ clutter_layout_manager_find_child_property (ClutterLayoutManager *manager,
  * Retrieves all the #GParamSpec<!-- -->s for the layout properties
  * stored inside the #ClutterLayoutMeta sub-class used by @manager
  *
- * Return value: (transfer full): the newly-allocated, %NULL-terminated
+ * Return value: (transfer full) (array length=n_pspecs): the newly-allocated,
- *   array of #GParamSpec<!-- -->s. Use g_free() to free the resources
+ *   %NULL-terminated array of #GParamSpec<!-- -->s. Use g_free() to free the
- *   allocated for the array
+ *   resources allocated for the array
  *
  * Since: 1.2
  */

clutter/clutter-list-model.c

@@ -799,7 +799,7 @@ clutter_list_model_new (guint n_columns,
  * Non-vararg version of clutter_list_model_new(). This function is
  * useful for language bindings.
  *
- * Return value: a new default #ClutterModel
+ * Return value: (transfer full): a new default #ClutterModel
  *
  * Since: 0.6
  */

clutter/clutter-main.c

@@ -1223,6 +1223,8 @@ clutter_threads_dispatch_free (gpointer data)
  *                                  NULL);
  * ]|
  *
+ * Rename to: clutter_threads_add_idle
+ *
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 0.4
@@ -1248,7 +1250,7 @@ clutter_threads_add_idle_full (gint           priority,
 }
 
 /**
- * clutter_threads_add_idle:
+ * clutter_threads_add_idle: (skip)
  * @func: function to call
  * @data: data to pass to the function
  *
@@ -1295,6 +1297,8 @@ clutter_threads_add_idle (GSourceFunc func,
  *
  * See also clutter_threads_add_idle_full().
  *
+ * Rename to: clutter_threads_add_timeout
+ *
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 0.4
@@ -1322,7 +1326,7 @@ clutter_threads_add_timeout_full (gint           priority,
 }
 
 /**
- * clutter_threads_add_timeout:
+ * clutter_threads_add_timeout: (skip)
  * @interval: the time between calls to the function, in milliseconds
  * @func: function to call
  * @data: data to pass to the function
@@ -1373,6 +1377,8 @@ clutter_threads_add_timeout (guint       interval,
  *
  * See also clutter_threads_add_idle_full().
  *
+ * Rename to: clutter_threads_add_frame_source
+ *
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 0.8
@@ -1400,7 +1406,7 @@ clutter_threads_add_frame_source_full (gint           priority,
 }
 
 /**
- * clutter_threads_add_frame_source:
+ * clutter_threads_add_frame_source: (skip)
  * @fps: the number of times per second to call the function
  * @func: function to call
  * @data: data to pass to the function

clutter/clutter-model.c

@@ -1461,7 +1461,7 @@ clutter_model_get_sorting_column (ClutterModel *model)
 /**
  * clutter_model_foreach:
  * @model: a #ClutterModel
- * @func: a #ClutterModelForeachFunc
+ * @func: (scope call): a #ClutterModelForeachFunc
  * @user_data: user data to pass to @func
  *
  * Calls @func for each row in the model. 
@@ -2262,7 +2262,7 @@ clutter_model_iter_get_row (ClutterModelIter *iter)
  *
  * Copies the passed iterator.
  *
- * Return value: a copy of the iterator, or %NULL
+ * Return value: (transfer full): a copy of the iterator, or %NULL
  *
  * Since: 0.8
  */

clutter/clutter-path.c

@@ -976,7 +976,8 @@ clutter_path_get_node (ClutterPath     *path,
  * list to become invalid so you should copy them if you want to keep
  * the list.
  *
- * Return value: (transfer container) (element-type ClutterPathNode): a list of nodes in the path.
+ * Return value: (transfer container) (element-type Clutter.PathNode): a
+ *   list of nodes in the path.
  *
  * Since: 1.0
  */

clutter/clutter-score.c

@@ -860,7 +860,7 @@ clutter_score_clear (ClutterScore *score)
 /**
  * clutter_score_append:
  * @score: a #ClutterScore
- * @parent: a #ClutterTimeline in the score, or %NULL
+ * @parent: (allow-none): a #ClutterTimeline in the score, or %NULL
  * @timeline: a #ClutterTimeline
  *
  * Appends a timeline to another one existing in the score; the newly
@@ -1109,10 +1109,10 @@ clutter_score_get_timeline (ClutterScore *score,
  *
  * Retrieves a list of all the #ClutterTimelines managed by @score.
  *
- * Return value: (transfer container) (element-type ClutterTimeline): a #GSList
+ * Return value: (transfer container) (element-type Clutter.Timeline): a
- *   containing all the timelines in the score. This function does not increase
+ *   #GSList containing all the timelines in the score. This function does
- *   the reference count of the returned timelines. Use g_slist_free() on the
+ *   not increase the reference count of the returned timelines. Use
- *   returned list to deallocate its resources.
+ *   g_slist_free() on the returned list to deallocate its resources.
  *
  * Since: 0.6
  */

clutter/clutter-script.c

@@ -1148,9 +1148,10 @@ clutter_script_lookup_filename (ClutterScript *script,
  * Note: this function does not increment the reference count of the
  * objects it returns.
  *
- * Return value: (transfer container) (element-type GObject): a list of #GObject<!-- -->s,
+ * Return value: (transfer container) (element-type GObject.Object): a list
- *   or %NULL. The objects are owned by the #ClutterScript instance. Use g_list_free() on the
+ *   of #GObject<!-- -->s, or %NULL. The objects are owned by the
- *   returned value when done.
+ *   #ClutterScript instance. Use g_list_free() on the returned list when
+ *   done.
  *
  * Since: 0.8.2
  */

clutter/clutter-stage-manager.c

@@ -260,7 +260,7 @@ clutter_stage_manager_get_default_stage (ClutterStageManager *stage_manager)
  *
  * Lists all currently used stages.
  *
- * Return value: (transfer container) (element-type ClutterStage): a newly
+ * Return value: (transfer container) (element-type Clutter.Stage): a newly
  *   allocated list of #ClutterStage objects. Use g_slist_free() to
  *   deallocate it when done.
  *
@@ -278,7 +278,7 @@ clutter_stage_manager_list_stages (ClutterStageManager *stage_manager)
  *
  * Lists all currently used stages.
  *
- * Return value: (transfer none) (element-type ClutterStage): a pointer
+ * Return value: (transfer none) (element-type Clutter.Stage): a pointer
  *   to the internal list of #ClutterStage objects. The returned list
  *   is owned by the #ClutterStageManager and should never be modified
  *   or freed

clutter/clutter-stage-window.h

@@ -10,11 +10,27 @@ G_BEGIN_DECLS
 #define CLUTTER_IS_STAGE_WINDOW(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_STAGE_WINDOW))
 #define CLUTTER_STAGE_WINDOW_GET_IFACE(obj)     (G_TYPE_INSTANCE_GET_INTERFACE ((obj), CLUTTER_TYPE_STAGE_WINDOW, ClutterStageWindowIface))
 
+/**
+ * ClutterStageWindow:
+ *
+ * <structname>ClutterStageWindow</structname> is an opaque structure
+ * whose members should not be accessed directly
+ *
+ * Since: 0.8
+ */
 typedef struct _ClutterStageWindow      ClutterStageWindow; /* dummy */
 typedef struct _ClutterStageWindowIface ClutterStageWindowIface;
 
+/**
+ * ClutterStageWindowIface:
+ *
+ * The interface implemented by backends for stage windows
+ *
+ * Since: 0.8
+ */
 struct _ClutterStageWindowIface
 {
+  /*< private >*/
   GTypeInterface parent_iface;
 
   ClutterActor *(* get_wrapper)           (ClutterStageWindow *stage_window);

clutter/clutter-state.c

@@ -981,7 +981,7 @@ clutter_state_get_states (ClutterState *state)
  * Returns a list of pointers to opaque structures with accessor functions
  * that describe the keys added to an animator.
  *
- * Return value: (transfer container) (element-type ClutterStateKey): a
+ * Return value: (transfer container) (element-type Clutter.StateKey): a
  *   newly allocated #GList of #ClutterStateKey<!-- -->s. The contents of
  *   the returned list are owned by the #ClutterState and should not be
  *   modified or freed. Use g_list_free() to free the resources allocated

clutter/clutter-timeout-pool.h

@@ -39,6 +39,10 @@
 
 G_BEGIN_DECLS
 
+/**
+ * ClutterTimeoutPool: (skip)
+ *
+ */
 typedef struct _ClutterTimeoutPool    ClutterTimeoutPool;
 
 ClutterTimeoutPool *clutter_timeout_pool_new    (gint                priority);