2007-11-23 Emmanuele Bassi <ebassi@openedhand.com>

	* clutter/clutter-actor.c:
	* clutter/clutter-alpha.c:
	* clutter/clutter-effect.c:
	* clutter/clutter-event.c:
	* clutter/clutter-event.h:
	* clutter/clutter-group.h:
	* clutter/clutter-model.c:,
	* clutter/clutter-script.c:
	* clutter/clutter-scriptable.h:
	* clutter/clutter-stage.c: Documentation fixes.

	* clutter/clutter-score.c: Fix implementation.

11 files changed, 238 insertions, 35 deletions

diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 6e8b683e2..142bd2b77 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -62,6 +62,62 @@
  * </orderedlist>
  */
 
+/**
+ * CLUTTER_ACTOR_IS_MAPPED:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_MAPPED flag is set.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_REALIZED:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_REALIZED flag is set.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_VISIBLE:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the actor is both realized and mapped.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_REACTIVE:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_REACTIVE flag is set.
+ *
+ * Since: 0.6
+ */
+
+/**
+ * CLUTTER_ACTOR_SET_FLAGS:
+ * @e: a #ClutterActor
+ * @f: the flags to set
+ *
+ * Sets flags on the given #ClutterActor
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_UNSET_FLAGS:
+ * @e: a #ClutterActor
+ * @f: the flags to unset
+ *
+ * Unsets flags on the given #ClutterActor
+ *
+ * Since: 0.2
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/clutter/clutter-alpha.c b/clutter/clutter-alpha.c
index cc44b385d..e7186200a 100644
--- a/clutter/clutter-alpha.c
+++ b/clutter/clutter-alpha.c
@@ -398,6 +398,14 @@ clutter_alpha_new_full (ClutterTimeline  *timeline,
 }
 
 /**
+ * CLUTTER_ALPHA_RAMP_INC:
+ *
+ * Convenience symbol for clutter_ramp_inc_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_ramp_inc_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -425,6 +433,14 @@ clutter_ramp_inc_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_RAMP_DEC:
+ *
+ * Convenience symbol for clutter_ramp_dec_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_ramp_dec_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -454,6 +470,14 @@ clutter_ramp_dec_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_RAMP:
+ *
+ * Convenience symbol for clutter_ramp_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_ramp_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -575,6 +599,14 @@ sinc_func (ClutterAlpha *alpha,
 #endif
 
 /**
+ * CLUTTER_ALPHA_SINE:
+ *
+ * Convenience symbol for clutter_sine_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_sine_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -599,6 +631,14 @@ clutter_sine_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_SINE_INC:
+ *
+ * Convenience symbol for clutter_sine_inc_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_sine_inc_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -633,6 +673,14 @@ clutter_sine_inc_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_SINE_DEC:
+ *
+ * Convenience symbol for clutter_sine_dec_func().
+ *
+ * Since: 0.2
+ */
+
+/**
  * clutter_sine_dec_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -667,6 +715,14 @@ clutter_sine_dec_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_SINE_HALF:
+ *
+ * Convenience symbol for clutter_sine_half_func().
+ *
+ * Since: 0.4
+ */
+
+/**
  * clutter_sine_half_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -701,6 +757,14 @@ clutter_sine_half_func (ClutterAlpha *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_SQUARE:
+ *
+ * Convenience symbol for clutter_square_func().
+ *
+ * Since: 0.4
+ */
+
+/**
  * clutter_square_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -728,6 +792,13 @@ clutter_square_func (ClutterAlpha *alpha,
                                               : 0;
 }
 
+/**
+ * CLUTTER_ALPHA_SMOOTHSTEP_INC:
+ *
+ * Convenience symbol for clutter_smoothstep_inc_func().
+ *
+ * Since: 0.4
+ */
 
 /**
  * clutter_smoothstep_inc_func:
@@ -777,6 +848,14 @@ clutter_smoothstep_inc_func (ClutterAlpha  *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_SMOOTHSTEP_DEC:
+ *
+ * Convenience symbol for clutter_smoothstep_dec_func().
+ *
+ * Since: 0.4
+ */
+
+/**
  * clutter_smoothstep_dec_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused
@@ -796,6 +875,14 @@ clutter_smoothstep_dec_func (ClutterAlpha  *alpha,
 }
 
 /**
+ * CLUTTER_ALPHA_EXP_INC:
+ *
+ * Convenience symbol for clutter_exp_inc_func()
+ *
+ * Since: 0.4
+ */
+
+/**
  * clutter_exp_inc_func:
  * @alpha: a #ClutterAlpha
  * @dummy: unused argument
@@ -838,6 +925,13 @@ clutter_exp_inc_func (ClutterAlpha *alpha,
   return result;
 }
 
+/**
+ * CLUTTER_ALPHA_EXP_DEC:
+ *
+ * Convenience symbold for clutter_exp_dec_func().
+ *
+ * Since: 0.4
+ */
 
 /**
  * clutter_exp_dec_func:
diff --git a/clutter/clutter-effect.c b/clutter/clutter-effect.c
index 3193b4966..f1d8e844a 100644
--- a/clutter/clutter-effect.c
+++ b/clutter/clutter-effect.c
@@ -753,7 +753,7 @@ clutter_effect_scale (ClutterEffectTemplate     *template_,
  * @actor: a #ClutterActor to apply the effect to.
  * @axis: axis of rotation
  * @angle: final angle to apply to actor
- * @center_z: position on Z axis to rotate about.
+ * @center_x: position on X axis to rotate about.
  * @center_y: position on Y axis to rotate about.
  * @center_z: position on Z axis to rotate about.
  * @direction: a #ClutterRotateDirection for the rotation.
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index ddc10aaf6..1ab98faa3 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -168,6 +168,8 @@ 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
+ *
  * Since: 0.6
  */
 ClutterActor*
diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index e918358a9..ae74f0dac 100644
--- a/clutter/clutter-event.h
+++ b/clutter/clutter-event.h
@@ -30,7 +30,23 @@
 #include <clutter/clutter-types.h>
 
 #define CLUTTER_TYPE_EVENT	(clutter_event_get_type ())
+
+/**
+ * CLUTTER_PRIORITY_EVENTS:
+ *
+ * Priority for event handling.
+ *
+ * Since: 0.4
+ */
 #define CLUTTER_PRIORITY_EVENTS (G_PRIORITY_DEFAULT)
+
+/**
+ * CLUTTER_CURRENT_TIME:
+ *
+ * Default value for "now".
+ *
+ * Since: 0.4
+ */
 #define CLUTTER_CURRENT_TIME    0L
 
 G_BEGIN_DECLS
diff --git a/clutter/clutter-group.h b/clutter/clutter-group.h
index d36f6a285..ab2b7e355 100644
--- a/clutter/clutter-group.h
+++ b/clutter/clutter-group.h
@@ -102,8 +102,6 @@ void          clutter_group_add_many_valist  (ClutterGroup    *group,
                                               va_list          var_args);
 void          clutter_group_remove           (ClutterGroup    *group,
                                               ClutterActor    *actor);
-ClutterActor *clutter_group_find_child_by_id (ClutterGroup    *self,
-					      guint            id);
 void          clutter_group_raise            (ClutterGroup    *self,
 					      ClutterActor    *actor, 
 					      ClutterActor    *sibling);
diff --git a/clutter/clutter-model.c b/clutter/clutter-model.c
index e2cc8727d..9e6632fb6 100644
--- a/clutter/clutter-model.c
+++ b/clutter/clutter-model.c
@@ -916,8 +916,10 @@ clutter_model_get_last_iter (ClutterModel *model)
  * clutter_model_get_n_rows:
  * @model: a #ClutterModel
  *
- * Return value: The length of the @model. If there is a filter set, then the
- * length of the filtered @model is returned.
+ * Retrieves the number of rows inside @model.
+ *
+ * Return value: The length of the @model. If there is a filter set, then
+ *   thelength of the filtered @model is returned.
  *
  * Since 0.6
  */
@@ -974,6 +976,7 @@ clutter_model_set_sorting_column (ClutterModel *model,
       g_warning ("%s: Invalid column id value %d\n", G_STRLOC, column);
       return;
     }
+
   priv->sort_column = column;
 
   _model_sort (model);
@@ -984,19 +987,18 @@ clutter_model_set_sorting_column (ClutterModel *model,
  * clutter_model_get_sorting_column:
  * @model: a #ClutterModelIter
  *
- * Return value: The column number that the @model sorts.
+ * Retrieves the number of column used for sorting the @model.
+ *
+ * Return value: a column number
  *
  * Since 0.6
  */
 guint              
 clutter_model_get_sorting_column (ClutterModel *model)
 {
-  ClutterModelPrivate *priv;
-
   g_return_val_if_fail (CLUTTER_IS_MODEL_ITER (model), 0);
-  priv = model->priv;
 
-  return priv->sort_column;
+  return model->priv->sort_column;
 }
 
 /**
@@ -1924,8 +1926,11 @@ clutter_model_iter_set_value (ClutterModelIter *iter,
 /**
  * clutter_model_iter_is_first:
  * @iter: a #ClutterModelIter
- * 
- * Return value: #TRUE if @iter is the first iter in the filtered model.
+ *
+ * Gets whether the current iterator is at the beginning of the model
+ * to which it belongs.
+ *
+ * Return value: #TRUE if @iter is the first iter in the filtered model
  *
  * Since 0.6
  */
@@ -1946,6 +1951,9 @@ clutter_model_iter_is_first (ClutterModelIter *iter)
  * clutter_model_iter_is_last:
  * @iter: a #ClutterModelIter
  * 
+ * Gets whether the iterator is at the end of the model to which it
+ * belongs.
+ *
  * Return value: #TRUE if @iter is the last iter in the filtered model.
  *
  * Since 0.6
diff --git a/clutter/clutter-score.c b/clutter/clutter-score.c
index 9a39c5893..69d38b3da 100644
--- a/clutter/clutter-score.c
+++ b/clutter/clutter-score.c
@@ -35,7 +35,7 @@
  *   {
  *     Timeline *base;
  *     GList    *next_timelines; - to start on completion of base,
- *                                 (points to score entrys)
+ *                                 (points to score entries)
  *     Callback  id;
  *     delay
  *   }
@@ -48,6 +48,8 @@
  * @short_description: Sequencing multiple #ClutterTimelines in order
  *
  * #ClutterScore is a base class for sequencing multiple timelines in order.
+ *
+ * #ClutterScore is available since Clutter 0.6
  */
 
 #ifdef HAVE_CONFIG_H
@@ -150,6 +152,9 @@ clutter_score_get_property (GObject    *object,
 static void
 clutter_score_finalize (GObject *object)
 {
+  ClutterScorePrivate *priv = CLUTTER_SCORE (object)->priv;
+
+  g_hash_table_destroy (priv->running_timelines);
   G_OBJECT_CLASS (clutter_score_parent_class)->finalize (object);
 }
 
@@ -161,11 +166,6 @@ clutter_score_dispose (GObject *object)
 
   priv = self->priv;
 
-  if (priv != NULL)
-    {
-
-    }
-
   G_OBJECT_CLASS (clutter_score_parent_class)->dispose (object);
 }
 
@@ -254,12 +254,9 @@ clutter_score_set_loop (ClutterScore *score,
 
   if (score->priv->loop != loop)
     {
-      g_object_ref (score);
-
       score->priv->loop = loop;
 
       g_object_notify (G_OBJECT (score), "loop");
-      g_object_unref (score);
     }
 }
 
@@ -294,7 +291,7 @@ clutter_score_is_playing (ClutterScore *score)
 
   /* FIXME: paused state currently counts as playing */
 
-  return !!g_hash_table_size(score->priv->running_timelines);
+  return !!g_hash_table_size (score->priv->running_timelines);
 }
 
 static void
@@ -361,9 +358,9 @@ on_foreach_running_timeline_start (gpointer key,
  * clutter_score_start:
  * @score: A #ClutterScore
  *
- * Query state of a #ClutterScore instance.
+ * Starts the score.
  *
- * Return Value: TRUE if score is currently playing, FALSE if not.
+ * Since: 0.6
  */
 void
 clutter_score_start (ClutterScore *score)
@@ -536,7 +533,6 @@ clutter_score_append (ClutterScore    *score,
  * @timeline: A #ClutterTimeline
  *
  * Adds a new initial timeline to start when the score is started.
- *
  */
 void
 clutter_score_add (ClutterScore    *score,
@@ -559,11 +555,11 @@ clutter_score_add (ClutterScore    *score,
 }
 
 static void
-remove_entrys (GSList *list)
+remove_entries (GSList *list)
 {
-  GSList             *item;
+  GSList *item;
 
-  if (list == NULL)
+  if (!list)
     return;
 
   for (item = list; item != NULL; item = item->next)
@@ -573,7 +569,7 @@ remove_entrys (GSList *list)
       g_object_unref (entry->timeline);
 
       if (entry->child_entries)
-	remove_entrys (entry->child_entries);
+	remove_entries (entry->child_entries);
 
       g_slist_free (entry->child_entries);
       g_free(entry);
@@ -588,22 +584,32 @@ clutter_score_remove (ClutterScore    *score,
 
 }
 
+/**
+ * clutter_score_remove_all:
+ * @score: a #ClutterScore
+ *
+ * Removes all the timelines inside @score.
+ *
+ * Since: 0.6
+ */
 void
 clutter_score_remove_all (ClutterScore *score)
 {
   clutter_score_stop (score);
-  remove_entrys (score->priv->entries);
+  remove_entries (score->priv->entries);
 }
 
 /**
  * clutter_score_new:
  *
- * Create a new #ClutterScore instance.
+ * Creates a new #ClutterScore.
+ *
+ * Return value: the newly created #ClutterScore
  *
- * Return Value: a new #ClutterScore
+ * Since: 0.6
  */
-ClutterScore*
-clutter_score_new ()
+ClutterScore *
+clutter_score_new (void)
 {
   return g_object_new (CLUTTER_TYPE_SCORE,  NULL);
 }
diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c
index 8e0c345a3..966a605d7 100644
--- a/clutter/clutter-script.c
+++ b/clutter/clutter-script.c
@@ -1815,7 +1815,7 @@ clutter_script_unmerge_objects (ClutterScript *script,
 }
 
 /**
- * clutter_script_ensure_object:
+ * clutter_script_ensure_objects:
  * @script: a #ClutterScript
  *
  * Ensure that every object defined inside @script is correctly
diff --git a/clutter/clutter-scriptable.h b/clutter/clutter-scriptable.h
index 5330907b2..fe786065a 100644
--- a/clutter/clutter-scriptable.h
+++ b/clutter/clutter-scriptable.h
@@ -57,8 +57,10 @@ typedef struct _ClutterScriptableIface          ClutterScriptableIface;
  */
 struct _ClutterScriptableIface
 {
+  /*< private >*/
   GTypeInterface g_iface;
 
+  /*< public >*/
   void         (* set_id)              (ClutterScriptable *scriptable,
                                         const gchar       *name);
   const gchar *(* get_id)              (ClutterScriptable *scriptable);
diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c
index 38b637971..a25938277 100644
--- a/clutter/clutter-stage.c
+++ b/clutter/clutter-stage.c
@@ -971,6 +971,17 @@ on_key_focused_weak_notify (gpointer data,
   clutter_stage_set_key_focus (stage, NULL);
 }
 
+/**
+ * clutter_stage_set_key_focus:
+ * @stage: the #ClutterStage
+ * @actor: the actor to set key focus to, or %NULL
+ *
+ * Sets the key focus on @actor. An actor with key focus will receive
+ * all the key events. If @actor is %NULL, the stage will receive
+ * focus.
+ *
+ * Since: 0.6
+ */
 void
 clutter_stage_set_key_focus (ClutterStage *stage,
 			     ClutterActor *actor)
@@ -1010,6 +1021,16 @@ clutter_stage_set_key_focus (ClutterStage *stage,
     g_signal_emit_by_name (stage, "focus-in");
 }
 
+/**
+ * clutter_stage_get_key_focus:
+ * @stage: the #ClutterStage
+ *
+ * Retrieves the actor that is currently under key focus.
+ *
+ * Return value: the actor with key focus, or the stage
+ *
+ * Since: 0.6
+ */
 ClutterActor *
 clutter_stage_get_key_focus (ClutterStage *stage)
 {