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.

diff --git a/ChangeLog b/ChangeLog
index edacfa0..b21c30f 100644 (file)
--- a/ChangeLog
+++ b/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:

diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 53b7cdc..601d502 100644 (file)
--- a/clutter/clutter-actor.c
+++ b/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

diff --git a/clutter/clutter-alpha.h b/clutter/clutter-alpha.h
index a540fc8..7787866 100644 (file)
--- a/clutter/clutter-alpha.h
+++ b/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);

diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index 2e435a0..28bb5c0 100644 (file)
--- a/clutter/clutter-event.h
+++ b/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;

diff --git a/clutter/clutter-fixed.c b/clutter/clutter-fixed.c
index fefe44a..891dc1a 100644 (file)
--- a/clutter/clutter-fixed.c
+++ b/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)

diff --git a/clutter/clutter-fixed.h b/clutter/clutter-fixed.h
index 88ac4f6..7433b4e 100644 (file)
--- a/clutter/clutter-fixed.h
+++ b/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);

diff --git a/clutter/clutter-model.h b/clutter/clutter-model.h
index b93c799..c71c42b 100644 (file)
--- a/clutter/clutter-model.h
+++ b/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

diff --git a/clutter/clutter-shader.c b/clutter/clutter-shader.c
index 00775f9..f06b7e1 100644 (file)
--- a/clutter/clutter-shader.c
+++ b/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
  *

diff --git a/clutter/clutter-shader.h b/clutter/clutter-shader.h
index 7aeedd7..73347a0 100644 (file)
--- a/clutter/clutter-shader.h
+++ b/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,

diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c
index d0f28e7..1e398b7 100644 (file)
--- a/clutter/clutter-stage.c
+++ b/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)
 {

diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog
index 79cea58..30c42c4 100644 (file)
--- a/doc/reference/ChangeLog
+++ b/doc/reference/ChangeLog
@@ -1,5 +1,10 @@
 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.
 
 2007-12-14  Emmanuele Bassi  <ebassi@openedhand.com>

diff --git a/doc/reference/clutter-sections.txt b/doc/reference/clutter-sections.txt
index 87fa151..4ac7272 100644 (file)
--- a/doc/reference/clutter-sections.txt
+++ b/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>