2007-07-04 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/*: Loads of fixes for the API reference.

ChangeLog

@@ -1,3 +1,7 @@
+2007-07-04  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/*: Loads of fixes for the API reference.
+
 2007-07-04  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	Merge from clutter/work

clutter/clutter-actor.h

@@ -215,7 +215,7 @@ void                  clutter_actor_hide_all         (ClutterActor          *sel
 void                  clutter_actor_realize          (ClutterActor          *self);
 void                  clutter_actor_unrealize        (ClutterActor          *self);
 void                  clutter_actor_paint            (ClutterActor          *self);
-void                  clutter_actor_pick             (ClutterActor        *actor, 
+void                  clutter_actor_pick             (ClutterActor          *self, 
 						      const ClutterColor    *color);
 void                  clutter_actor_queue_redraw     (ClutterActor          *self);
 void                  clutter_actor_destroy          (ClutterActor          *self);
@@ -345,7 +345,7 @@ void                  clutter_actor_move_by                  (ClutterActor
 void                  clutter_actor_get_vertices             (ClutterActor          *self,
 						              ClutterVertex          verts[4]);
 
-void                  clutter_actor_apply_transform_to_point (ClutterActor          *actor, 
+void                  clutter_actor_apply_transform_to_point (ClutterActor          *self, 
 						              ClutterVertex         *point,
 							      ClutterVertex         *vertex);
      

clutter/clutter-backend.c

@@ -23,6 +23,20 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:clutter-backend
+ * @short_description: Backend abstraction
+ *
+ * Clutter can be compiled against different backends. Each backend
+ * has to implement a set of functions, in order to be used by Clutter.
+ *
+ * #ClutterBackend is the base class abstracting the various implementation;
+ * it provides a basic API to query the backend for generic information
+ * and settings.
+ *
+ * #ClutterBackend is available since Clutter 0.4
+ */
+
 #ifndef HAVE_CONFIG_H
 #include "config.h"
 #endif

clutter/clutter-box.c

@@ -343,6 +343,18 @@ clutter_box_pack_end (ClutterBox   *box,
     clutter_actor_queue_redraw (CLUTTER_ACTOR (box));
 }
 
+/**
+ * clutter_box_query_child:
+ * @box: a #ClutterBox
+ * @actor: child to query
+ * @child: return location for a #ClutterBoxChild or %NULL
+ *
+ * Queries @box for the packing data of @actor.
+ *
+ * Return value: %TRUE if @actor is a child of @box
+ *
+ * Since: 0.4
+ */
 gboolean
 clutter_box_query_child (ClutterBox      *box,
                          ClutterActor    *actor,
@@ -372,6 +384,19 @@ clutter_box_query_child (ClutterBox      *box,
   return FALSE;
 }
 
+/**
+ * clutter_box_query_nth_child:
+ * @box: a #ClutterBox
+ * @index: position of the child
+ * @child: return value for a #ClutterBoxChild, or %NULL
+ *
+ * Queries the child of @box at @index and puts the packing informations
+ * inside @child.
+ *
+ * Return value: %TRUE if an actor was found at @index
+ *
+ * Since: 0.4
+ */
 gboolean
 clutter_box_query_nth_child (ClutterBox      *box,
                              gint             index,
@@ -395,6 +420,16 @@ clutter_box_query_nth_child (ClutterBox      *box,
   return TRUE;
 }
 
+/**
+ * clutter_box_get_spacing:
+ * @box: a #ClutterBox
+ *
+ * Gets the value set using clutter_box_set_spacing().
+ *
+ * Return value: the spacing between children of the box
+ *
+ * Since: 0.4
+ */
 guint
 clutter_box_get_spacing (ClutterBox *box)
 {
@@ -403,6 +438,15 @@ clutter_box_get_spacing (ClutterBox *box)
   return box->spacing;
 }
 
+/**
+ * clutter_box_set_spacing:
+ * @box: a #ClutterBox
+ * @spacing: the spacing between children
+ *
+ * Sets the spacing, in pixels, between the children of @box.
+ *
+ * Since: 0.4
+ */
 void
 clutter_box_set_spacing (ClutterBox *box,
                          guint       spacing)

clutter/clutter-container.c

@@ -142,7 +142,7 @@ clutter_container_get_type (void)
  * clutter_container_add:
  * @container: a #ClutterContainer
  * @first_actor: the first #ClutterActor to add
- * @varargs: %NULL terminated list of actors to add
+ * @Varargs: %NULL terminated list of actors to add
  *
  * Adds a list of #ClutterActor<!-- -->s to @container. Each time and
  * actor is added, the "actor-added" signal is emitted. Each actor should
@@ -156,14 +156,14 @@ clutter_container_add (ClutterContainer *container,
                        ClutterActor     *first_actor,
                        ...)
 {
-  va_list var_args;
+  va_list args;
 
   g_return_if_fail (CLUTTER_IS_CONTAINER (container));
   g_return_if_fail (CLUTTER_IS_ACTOR (first_actor));
 
-  va_start (var_args, first_actor);
+  va_start (args, first_actor);
-  clutter_container_add_valist (container, first_actor, var_args);
+  clutter_container_add_valist (container, first_actor, args);
-  va_end (var_args);
+  va_end (args);
 }
 
 /**
@@ -203,7 +203,7 @@ clutter_container_add_actor (ClutterContainer *container,
 }
 
 /**
- * clutter_container_add:
+ * clutter_container_add_valist:
  * @container: a #ClutterContainer
  * @first_actor: the first #ClutterActor to add
  * @var_args: list of actors to add, followed by %NULL

clutter/clutter-container.h

@@ -69,7 +69,7 @@ void   clutter_container_add_actor     (ClutterContainer *container,
                                         ClutterActor     *actor);
 void   clutter_container_add_valist    (ClutterContainer *container,
                                         ClutterActor     *first_actor,
-                                        va_list           varargs);
+                                        va_list           var_args);
 void   clutter_container_remove        (ClutterContainer *container,
                                         ClutterActor     *first_actor,
                                         ...) G_GNUC_NULL_TERMINATED;
@@ -77,7 +77,7 @@ void   clutter_container_remove_actor  (ClutterContainer *container,
                                         ClutterActor     *actor);
 void   clutter_container_remove_valist (ClutterContainer *container,
                                         ClutterActor     *first_actor,
-                                        va_list           varargs);
+                                        va_list           var_args);
 GList *clutter_container_get_children  (ClutterContainer *container);
 void   clutter_container_foreach       (ClutterContainer *container,
                                         ClutterCallback   callback,

clutter/clutter-effect.c

@@ -171,6 +171,13 @@ clutter_effect_template_class_init (ClutterEffectTemplateClass *klass)
   object_class->set_property = clutter_effect_template_set_property;
   object_class->get_property = clutter_effect_template_get_property;
 
+  /**
+   * ClutterEffectTemplate:alpha-func:
+   *
+   * #ClutterAlphaFunc to be used by the template
+   *
+   * Since: 0.4
+   */
   g_object_class_install_property 
            (object_class,
 	    PROP_ALPHA_FUNC,
@@ -179,7 +186,13 @@ clutter_effect_template_class_init (ClutterEffectTemplateClass *klass)
 				  "Alpha reference Function", 
 				  G_PARAM_CONSTRUCT_ONLY |
 				  CLUTTER_PARAM_READWRITE));
-
+  /**
+   * ClutterEffectTemplate:timeline:
+   *
+   * #ClutterTimeline to be used by the template
+   *
+   * Since: 0.4
+   */
   g_object_class_install_property 
            (object_class,
 	    PROP_TIMELINE,
@@ -199,7 +212,6 @@ clutter_effect_template_init (ClutterEffectTemplate *self)
 
 /**
  * clutter_effect_template_new:
- *
  * @timeline:  A #ClutterTimeline for the template (will be cloned)
  * @alpha_func: An alpha func to use for the template.
  *
@@ -209,7 +221,7 @@ clutter_effect_template_init (ClutterEffectTemplate *self)
  *
  * Since: 0.4
  */
-ClutterEffectTemplate*
+ClutterEffectTemplate *
 clutter_effect_template_new (ClutterTimeline *timeline, 
 			     ClutterAlphaFunc alpha_func)
 {
@@ -275,35 +287,38 @@ on_effect_complete (ClutterTimeline *timeline,
 
 /**
  * clutter_effect_fade:
- *
+ * @template_: A #ClutterEffectTemplate
- * @template: A #ClutterEffectTemplate
  * @actor: A #ClutterActor to apply the effect to.
  * @start_opacity: Initial opacity value to apply to actor
  * @end_opacity: Final opacity value to apply to actor
- * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL
+ * @completed_func: A #ClutterEffectCompleteFunc to call on effect
- * @completed_userdata: Data to pass to supplied  #ClutterEffectCompleteFunc or NULL
+ *   completion or %NULL
+ * @completed_data: Data to pass to supplied  #ClutterEffectCompleteFunc
+ *   or %NULL
+ *
+ * Simple effect for fading a single #ClutterActor.
  *
  * Return value: a #ClutterTimeline for the effect. Will be unrefed by
  * the effect when completed.
  *
  * Since: 0.4
  */
-ClutterTimeline*
+ClutterTimeline *
-clutter_effect_fade (ClutterEffectTemplate     *template,
+clutter_effect_fade (ClutterEffectTemplate     *template_,
 		     ClutterActor              *actor,
 		     guint8                     start_opacity,
 		     guint8                     end_opacity,
 		     ClutterEffectCompleteFunc  completed_func,
-		     gpointer                   completed_userdata)
+		     gpointer                   completed_data)
 {
   ClutterEffectClosure *c;
 
-  c = clutter_effect_closure_new (template,
+  c = clutter_effect_closure_new (template_,
 				  actor, 
 				  G_CALLBACK (on_effect_complete));
 
   c->completed_func = completed_func;
-  c->completed_data = completed_userdata;
+  c->completed_data = completed_data;
 
   c->behave = clutter_behaviour_opacity_new (c->alpha, 
 					     start_opacity, 
@@ -317,35 +332,38 @@ clutter_effect_fade (ClutterEffectTemplate     *template,
 
 /**
  * clutter_effect_move:
- *
+ * @template_: A #ClutterEffectTemplate
- * @template: A #ClutterEffectTemplate
  * @actor: A #ClutterActor to apply the effect to.
  * @knots: An array of #ClutterKnots representing path for the actor
  * @n_knots: Number of #ClutterKnots in passed array.
- * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL
+ * @completed_func: A #ClutterEffectCompleteFunc to call on effect
- * @completed_userdata: Data to pass to supplied  #ClutterEffectCompleteFunc or NULL
+ *   completion or %NULL
+ * @completed_data: Data to pass to supplied  #ClutterEffectCompleteFunc
+ *   or %NULL
  *
- * Return value: a #ClutterTimeline for the effect. Will be unrefed by
+ * Simple effect for moving a single #ClutterActor along a path.
+ *
+ * Return value: a #ClutterTimeline for the effect. Will be unreferenced by
  *   the effect when completed.
  *
  * Since: 0.4
  */
-ClutterTimeline*
+ClutterTimeline *
-clutter_effect_move (ClutterEffectTemplate     *template,
+clutter_effect_move (ClutterEffectTemplate     *template_,
 		     ClutterActor              *actor,
 		     const ClutterKnot         *knots,
 		     guint                      n_knots,
 		     ClutterEffectCompleteFunc  completed_func,
-		     gpointer                   completed_userdata)
+		     gpointer                   completed_data)
 {
   ClutterEffectClosure *c;
 
-  c = clutter_effect_closure_new (template,
+  c = clutter_effect_closure_new (template_,
 				  actor, 
 				  G_CALLBACK (on_effect_complete));
 
   c->completed_func = completed_func;
-  c->completed_data = completed_userdata;
+  c->completed_data = completed_data;
 
   c->behave = clutter_behaviour_path_new (c->alpha, knots, n_knots);
   
@@ -357,37 +375,40 @@ clutter_effect_move (ClutterEffectTemplate     *template,
 
 /**
  * clutter_effect_scale:
- *
+ * @template_: A #ClutterEffectTemplate
- * @template: A #ClutterEffectTemplate
  * @actor: A #ClutterActor to apply the effect to.
  * @scale_begin: Initial scale factor to apply to actor
  * @scale_end: Final scale factor to apply to actor
  * @gravity: A #ClutterGravity for the scale.
- * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL
+ * @completed_func: A #ClutterEffectCompleteFunc to call on effect
- * @completed_userdata: Data to pass to supplied  #ClutterEffectCompleteFunc or NULL
+ *   completion or NULL
+ * @completed_data: Data to pass to supplied  #ClutterEffectCompleteFunc
+ *   or NULL
  *
- * Return value: a #ClutterTimeline for the effect. Will be unrefed by
+ * Simple effect for scaling a single #ClutterActor.
+ *
+ * Return value: a #ClutterTimeline for the effect. Will be unreferenced by
  *   the effect when completed.
  *
  * Since: 0.4
  */
-ClutterTimeline*
+ClutterTimeline *
-clutter_effect_scale (ClutterEffectTemplate     *template,
+clutter_effect_scale (ClutterEffectTemplate     *template_,
 		      ClutterActor              *actor,
 		      gdouble                    scale_begin,
 		      gdouble                    scale_end,
 		      ClutterGravity             gravity,
 		      ClutterEffectCompleteFunc  completed_func,
-		      gpointer                   completed_userdata)
+		      gpointer                   completed_data)
 {
   ClutterEffectClosure *c;
 
-  c = clutter_effect_closure_new (template,
+  c = clutter_effect_closure_new (template_,
 				  actor, 
 				  G_CALLBACK (on_effect_complete));
 
   c->completed_func = completed_func;
-  c->completed_data = completed_userdata;
+  c->completed_data = completed_data;
 
   c->behave = clutter_behaviour_scale_new (c->alpha, 
 					   scale_begin,

clutter/clutter-effect.h

@@ -111,7 +111,7 @@ ClutterTimeline *clutter_effect_scale (ClutterEffectTemplate     *template_,
                                        gdouble                    scale_end,
                                        ClutterGravity             gravity,
                                        ClutterEffectCompleteFunc  completed_func,
-                                       gpointer                   completed_userdata);
+                                       gpointer                   completed_data);
 
 G_END_DECLS
 

clutter/clutter-event.h

@@ -84,13 +84,6 @@ typedef enum
   CLUTTER_STAGE_STATE_OFFSCREEN
 } ClutterStageState;
 
-typedef enum
-{
-  CLUTTER_FILTER_CONTINUE,
-  CLUTTER_FILTER_TRANSLATE,
-  CLUTTER_FILTER_REMOVE
-} ClutterFilterResponse;
-
 typedef union _ClutterEvent ClutterEvent;
 
 typedef struct _ClutterAnyEvent         ClutterAnyEvent;
@@ -102,9 +95,6 @@ typedef struct _ClutterStageStateEvent  ClutterStageStateEvent;
 
 typedef struct _ClutterInputDevice      ClutterInputDevice;
 
-
-typedef ClutterFilterResponse (* ClutterFilterFunc) (ClutterEvent *event,                                                            gpointer      data);
-
 struct _ClutterAnyEvent
 {
   ClutterEventType  type;

clutter/clutter-hbox.c

@@ -162,6 +162,15 @@ clutter_hbox_init (ClutterHBox *box)
 
 }
 
+/**
+ * clutter_hbox_new:
+ *
+ * Creates a new horizontal layout box.
+ *
+ * Return value: the newly created #ClutterHBox
+ *
+ * Since: 0.4
+ */
 ClutterActor *
 clutter_hbox_new (void)
 {

clutter/clutter-main.c

@@ -97,7 +97,6 @@ void
 clutter_redraw (void)
 {
   ClutterMainContext *ctx;
-  ClutterColor        stage_color;
   ClutterActor       *stage;
   static GTimer      *timer = NULL; 
   static guint        timer_n_frames = 0;

clutter/clutter-stage.c

@@ -589,7 +589,10 @@ clutter_stage_set_perspective (ClutterStage       *stage,
 /**
  * clutter_stage_get_perspective
  * @stage: A #ClutterStage
- * @perspective: return location for a #ClutterPerspective
+ * @fovy: FIXME
+ * @aspect: FIXME
+ * @z_near: FIXME
+ * @z_far: FIXME
  * 
  * Retrieves the stage perspective.
  */
@@ -605,10 +608,18 @@ clutter_stage_get_perspective (ClutterStage       *stage,
   g_return_if_fail (CLUTTER_IS_STAGE (stage));
 
   priv = stage->priv;
-  *fovy   = CLUTTER_FIXED_TO_FLOAT(priv->perspective.fovy);
+
-  *aspect = CLUTTER_FIXED_TO_FLOAT(priv->perspective.aspect);
+  if (fovy)
-  *z_near = CLUTTER_FIXED_TO_FLOAT(priv->perspective.z_near);
+    *fovy   = CLUTTER_FIXED_TO_FLOAT (priv->perspective.fovy);
-  *z_far  = CLUTTER_FIXED_TO_FLOAT(priv->perspective.z_far);
+
+  if (aspect)
+    *aspect = CLUTTER_FIXED_TO_FLOAT (priv->perspective.aspect);
+
+  if (z_near)
+    *z_near = CLUTTER_FIXED_TO_FLOAT (priv->perspective.z_near);
+
+  if (z_far)
+    *z_far  = CLUTTER_FIXED_TO_FLOAT (priv->perspective.z_far);
 }
 
 /**

clutter/clutter-stage.h

@@ -135,7 +135,6 @@ void                clutter_perspective_free     (ClutterPerspective       *pers
 GType         clutter_stage_get_type          (void) G_GNUC_CONST;
 
 ClutterActor *clutter_stage_get_default       (void);
-
 void          clutter_stage_set_color         (ClutterStage       *stage,
                                                const ClutterColor *color);
 void          clutter_stage_get_color         (ClutterStage       *stage,

clutter/clutter-texture.c

@@ -149,7 +149,8 @@ un_pre_multiply_alpha (const guchar   *data,
   return ret;
 }
 
-static guchar*
+#ifndef HAVE_COGL_GL
+static guchar *
 rgb_to_bgr (const guchar   *data,
 	    gboolean        has_alpha,
 	    gint            width,
@@ -182,6 +183,7 @@ rgb_to_bgr (const guchar   *data,
 
   return ret;
 }
+#endif /* !HAVE_COGL_GL */
 
 static int
 tile_dimension (int                          to_fill,
@@ -1262,7 +1264,7 @@ clutter_texture_set_from_rgb_data   (ClutterTexture     *texture,
 #else
       /* GLES has no BGR format*/
       copy_data = rgb_to_bgr (data, has_alpha, width, height, rowstride);
-#endif
+#endif /* HAVE_COGL_GL */
     }
 
   if (flags & CLUTTER_TEXTURE_RGB_FLAG_PREMULT)

clutter/clutter-vbox.c

@@ -162,6 +162,15 @@ clutter_vbox_init (ClutterVBox *box)
 
 }
 
+/**
+ * clutter_vbox_new:
+ *
+ * Creates a new vertical layout box.
+ *
+ * Return value: the newly created #ClutterVBox
+ *
+ * Since: 0.4
+ */
 ClutterActor *
 clutter_vbox_new (void)
 {

configure.ac

@@ -258,7 +258,7 @@ AC_SUBST(CLUTTER_DEBUG_CFLAGS)
 
 dnl = GTK Doc check ========================================================
 
-GTK_DOC_CHECK([1.4])
+GTK_DOC_CHECK([1.6])
 
 dnl = Manual ===============================================================