2007-12-15 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/clutter-actor.c:
	* clutter/clutter-alpha.h:
	* clutter/clutter-event.h:
	* clutter/clutter-fixed.[ch]:
	* clutter/clutter-model.h:
	* clutter/clutter-shader.[ch]:
	* clutter/clutter-stage.c: Documentation fixes.

ChangeLog

@@ -1,3 +1,13 @@
+2007-12-15  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-actor.c:
+	* clutter/clutter-alpha.h:
+	* clutter/clutter-event.h:
+	* clutter/clutter-fixed.[ch]:
+	* clutter/clutter-model.h:
+	* clutter/clutter-shader.[ch]:
+	* clutter/clutter-stage.c: Documentation fixes.
+
 2007-12-15  Emmanuele Bassi <ebassi@openedhand.com>
 
 	* clutter/clutter-model-default.c:

clutter/clutter-actor.c

@@ -501,7 +501,7 @@ clutter_actor_should_pick_paint (ClutterActor *self)
  *
  * Matrix: 4x4 of ClutterFixed
  */
-#define M(m,row,col)  (m)[col*4+row]
+#define M(m,row,col)  (m)[(col) * 4 + (row)]
 
 /* Transform point (x,y,z) by matrix */
 static void
@@ -533,6 +533,8 @@ mtx_transform (ClutterFixed m[16],
      */
 }
 
+#undef M
+
 /* Applies the transforms associated with this actor and its ancestors,
  * retrieves the resulting OpenGL modelview matrix, and uses the matrix
  * to transform the supplied point
@@ -4738,6 +4740,17 @@ destroy_shader_data (ClutterActor *self)
   actor_priv->shader_data = NULL;
 }
 
+/**
+ * clutter_actor_apply_shader:
+ * @self: a #ClutterActor
+ * @shader: a #ClutterShader or %NULL
+ *
+ * Sets the #ClutterShader to be applied on @self.
+ *
+ * Return value: %TRUE if the shader was successfully applied
+ *
+ * Since: 0.6
+ */
 gboolean
 clutter_actor_apply_shader (ClutterActor  *self,
                             ClutterShader *shader)
@@ -4850,8 +4863,19 @@ clutter_actor_shader_post_paint (ClutterActor *actor)
     }
 }
 
+/**
+ * clutter_actor_set_shader_param:
+ * @self: a #ClutterActor
+ * @param: the name of the parameter
+ * @value: the value of the parameter
+ *
+ * Sets the value for a named parameter of the shader applied
+ * to @actor.
+ *
+ * Since: 0.6
+ */
 void
-clutter_actor_set_shader_param (ClutterActor *actor,
+clutter_actor_set_shader_param (ClutterActor *self,
                                 const gchar  *param,
                                 gfloat        value)
 {
@@ -4859,10 +4883,10 @@ clutter_actor_set_shader_param (ClutterActor *actor,
   ShaderData *shader_data;
   BoxedFloat *box;
 
-  g_return_if_fail (CLUTTER_IS_ACTOR (actor));
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
   g_return_if_fail (param != NULL);
 
-  priv = actor->priv;
+  priv = self->priv;
   shader_data = priv->shader_data;
 
   if (!shader_data)
@@ -4872,5 +4896,3 @@ clutter_actor_set_shader_param (ClutterActor *actor,
   box->value = value;
   g_hash_table_insert (shader_data->float1f_hash, g_strdup (param), box);
 }
-
-#undef M

clutter/clutter-alpha.h

@@ -77,6 +77,15 @@ typedef struct _ClutterAlphaPrivate ClutterAlphaPrivate;
 typedef guint32 (*ClutterAlphaFunc) (ClutterAlpha *alpha,
                                      gpointer      user_data); 
 
+/**
+ * ClutterAlpha:
+ *
+ * #ClutterAlpha combines a #ClutterTimeline and a function.
+ * The contents of the #ClutterAlpha structure are private and should
+ * only be accessed using the provided API.
+ *
+ * Since: 0.2
+ */
 struct _ClutterAlpha
 {
   /*< private >*/
@@ -84,8 +93,16 @@ struct _ClutterAlpha
   ClutterAlphaPrivate *priv;
 };
 
+/**
+ * ClutterAlphaClass:
+ *
+ * Base class for #ClutterAlpha
+ *
+ * Since: 0.2
+ */
 struct _ClutterAlphaClass
 {
+  /*< private >*/
   GInitiallyUnownedClass parent_class;
   
   void (*_clutter_alpha_1) (void);

clutter/clutter-event.h

@@ -184,6 +184,17 @@ typedef struct _ClutterCrossingEvent    ClutterCrossingEvent;
 
 typedef struct _ClutterInputDevice      ClutterInputDevice;
 
+/**
+ * ClutterAnyEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @source: event source actor
+ *
+ * Common members for a #ClutterEvent
+ *
+ * Since: 0.2
+ */
 struct _ClutterAnyEvent
 {
   ClutterEventType  type;
@@ -192,6 +203,20 @@ struct _ClutterAnyEvent
   ClutterActor *source;
 };
 
+/**
+ * ClutterKeyEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @source: event source actor
+ * @modifier_state: key modifiers
+ * @keyval: raw key value
+ * @hardware_keycode: raw hardware key value
+ *
+ * Key event
+ *
+ * Since: 0.2
+ */
 struct _ClutterKeyEvent
 {
   ClutterEventType type;
@@ -203,6 +228,25 @@ struct _ClutterKeyEvent
   guint16 hardware_keycode;
 };
 
+/**
+ * ClutterButtonEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @source: event source actor
+ * @x: event X coordinate
+ * @y: event Y coordinate
+ * @modifier_state: button modifiers
+ * @button: event button
+ * @click_count: number of button presses within the default time
+ *   and radius
+ * @axes: reserved for future use
+ * @device: reserved for future use
+ *
+ * Button event
+ *
+ * Since: 0.2
+ */
 struct _ClutterButtonEvent
 {
   ClutterEventType type;

clutter/clutter-fixed.c

@@ -706,14 +706,14 @@ clutter_sqrti (gint number)
  * @op1: #ClutterFixed
  * @op2: #ClutterFixed
  *
- * Return value: #ClutterFixed.
- *
  * Multiplies two fixed values using 64bit arithmetic; this provides
  * significantly better precission than the #CLUTTER_FIXED_MUL macro,
  * but at performance cost (about 2.7 times slowdown on ARMv5e, and 2 times
  * on x86).
  *
- * Since: 0.3
+ * Return value: the result of the operation
+ *
+ * Since: 0.4
  */
 ClutterFixed
 clutter_qmulx (ClutterFixed op1, ClutterFixed op2)

clutter/clutter-fixed.h

@@ -269,11 +269,13 @@ typedef gint32 ClutterAngle;    /* angle such that 1024 == 2*PI */
 
 /* Some handy fixed point short aliases to avoid exessively long lines */
 /* FIXME: Remove from public API */
+/*< private >*/
 #define CFX_INT         CLUTTER_FIXED_INT
 #define CFX_MUL         CLUTTER_FIXED_MUL
 #define CFX_DIV         CLUTTER_FIXED_DIV
 #define CFX_QMUL(x,y)   clutter_qmulx (x,y)
 
+/*< public >*/
 /* Fixed point math routines */
 extern inline
 ClutterFixed clutter_qmulx (ClutterFixed op1, ClutterFixed op2);

clutter/clutter-model.h

@@ -285,6 +285,10 @@ struct _ClutterModelIter
  *   at the last row in the model
  * @is_first: Virtual function for knowing whether the iterator points
  *   at the first row in the model
+ * @next: Virtual function for moving the iterator to the following
+ *   row in the model
+ * @prev: Virtual function for moving the iterator toe the previous
+ *   row in the model
  * @get_model: Virtual function for getting the model to which the
  *   iterator belongs to
  * @get_row: Virtual function for getting the row to which the iterator

clutter/clutter-shader.c

@@ -24,6 +24,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:clutter-shader
+ * @short_description: Programmable pipeline abstraction
+ *
+ * #ClutterShader is an object providing an abstraction over the
+ * OpenGL programmable pipeline. By using #ClutterShader<!-- -->s is
+ * possible to override the drawing pipeline by using small programs
+ * also known as "shaders".
+ *
+ * #ClutterShader is available since Clutter 0.6
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -438,6 +450,7 @@ bind_glsl_shader (ClutterShader  *self,
 /**
  * clutter_shader_bind:
  * @shader: a #ClutterShader
+ * @error: return location for a #GError, or %NULL
  *
  * FIXME
  *

clutter/clutter-shader.h

@@ -41,6 +41,16 @@ G_BEGIN_DECLS
 
 #define CLUTTER_SHADER_ERROR        (clutter_shader_error_quark ())
 
+/**
+ * ClutterShaderError:
+ * @CLUTTER_SHADER_ERROR_NO_ASM: No ASM shaders support
+ * @CLUTTER_SHADER_ERROR_NO_GLSL: No GLSL shaders support
+ * @CLUTTER_SHADER_ERROR_COMPILE: Compilation error
+ *
+ * #ClutterShader error enumeration
+ *
+ * Since: 0.6
+ */
 typedef enum {
   CLUTTER_SHADER_ERROR_NO_ASM,
   CLUTTER_SHADER_ERROR_NO_GLSL,

clutter/clutter-stage.c

@@ -1216,6 +1216,17 @@ clutter_stage_get_fogx (ClutterStage *stage,
   *fog = stage->priv->fog;
 }
 
+/**
+ * clutter_stage_get_resolution:
+ * @stage: the #ClutterStage
+ *
+ * Retrieves the resolution (in DPI) of the stage from the default
+ * backend.
+ *
+ * Return value: the resolution of the stage
+ *
+ * Since: 0.6
+ */
 gdouble
 clutter_stage_get_resolution (ClutterStage *stage)
 {
@@ -1227,6 +1238,16 @@ clutter_stage_get_resolution (ClutterStage *stage)
   return clutter_backend_get_resolution (context->backend);
 }
 
+/**
+ * clutter_stage_get_resolutionx:
+ * @stage: the #ClutterStage
+ *
+ * Fixed point version of clutter_stage_get_resolution().
+ *
+ * Return value: the resolution of the stage
+ *
+ * Since: 0.6
+ */
 ClutterFixed
 clutter_stage_get_resolutionx (ClutterStage *stage)
 {

doc/reference/ChangeLog

@@ -1,3 +1,8 @@
+2007-12-15  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter-sections.txt: Move the shorthand fixed point macros
+	in the private section
+
 2007-12-15  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter-sections.txt: Added all the unused symbols.

doc/reference/clutter-sections.txt

@@ -781,9 +781,9 @@ clutter_feature_get_all
 ClutterFixed
 CFX_Q
 CFX_ONE
+CFX_HALF
 CFX_MAX
 CFX_MIN
-ClutterAngle
 CFX_PI
 CFX_2PI
 CFX_PI_2
@@ -794,11 +794,6 @@ CFX_240
 CFX_360
 CFX_60
 CFX_255
-CFX_DIV
-CFX_INT
-CFX_MUL
-CFX_HALF
-CFX_QMUL
 CLUTTER_FIXED_TO_INT
 CLUTTER_FIXED_TO_FLOAT
 CLUTTER_FIXED_TO_DOUBLE
@@ -812,6 +807,7 @@ CLUTTER_FIXED_FLOOR
 CLUTTER_FIXED_CEIL
 CLUTTER_FIXED_MUL
 CLUTTER_FIXED_DIV
+ClutterAngle
 CLUTTER_ANGLE_FROM_DEG
 CLUTTER_ANGLE_FROM_DEGF
 CLUTTER_ANGLE_FROM_DEGX
@@ -833,6 +829,11 @@ clutter_pow2x
 clutter_powx
 clutter_qmulx
 clutter_tani
+<SUBSECTION Private>
+CFX_DIV
+CFX_INT
+CFX_MUL
+CFX_QMUL
 </SECTION>
 
 <SECTION>