[docs] Fixes for the API reference

* Add unused symbols

* Document and sync argument names with their gtk-doc counterpart

* Add missing descriptions

diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h
index 38039a6..086b64d 100644 (file)
--- a/clutter/clutter-actor.h
+++ b/clutter/clutter-actor.h
@@ -180,6 +180,10 @@ struct _ClutterActor
  *   it should chain up to the parent's implementation
  * @unrealize: virtual function, used to deallocate resources allocated
  *   in ::realize; it should chain up to the parent's implementation
+ * @map: virtual function for containers and composite actors, to
+ *   map their children; it must chain up to the parent's implementation
+ * @unmap: virtual function for containers and composite actors, to
+ *   unmap their children; it must chain up to the parent's implementation
  * @paint: virtual function, used to paint the actor
  * @get_preferred_width: virtual function, used when querying the minimum
  *   and natural widths of an actor for a given height; it is used by

diff --git a/clutter/clutter-animation.c b/clutter/clutter-animation.c
index 5cba385..d1bd5b8 100644 (file)
--- a/clutter/clutter-animation.c
+++ b/clutter/clutter-animation.c
@@ -389,7 +389,7 @@ clutter_animation_class_init (ClutterAnimationClass *klass)
                   G_TYPE_NONE, 0);
 
   /**
-   * ClutterAniamtion::completed:
+   * ClutterAnimation::completed:
    * @animation: the animation that emitted the signal
    *
    * The ::completed signal is emitted once the animation has

diff --git a/clutter/clutter-container.h b/clutter/clutter-container.h
index dc1a601..083bba1 100644 (file)
--- a/clutter/clutter-container.h
+++ b/clutter/clutter-container.h
@@ -52,6 +52,11 @@ typedef struct _ClutterContainerIface   ClutterContainerIface;
  *   implementation of this virtual function is required.
  * @foreach: virtual function for iterating over the container's children.
  *   The implementation of this virtual function is required.
+ * @foreach_with_internals: virtual functions for iterating over the
+ *   container's children, both added using the #ClutterContainer API
+ *   and internal children. The implementation of this virtual function
+ *   is required only if the #ClutterContainer implementation has
+ *   internal children.
  * @raise: virtual function for raising a child
  * @lower: virtual function for lowering a child
  * @sort_depth_order: virtual function for sorting the children of a

diff --git a/clutter/clutter-main.h b/clutter/clutter-main.h
index a5365f0..d6f1099 100644 (file)
--- a/clutter/clutter-main.h
+++ b/clutter/clutter-main.h
@@ -140,7 +140,7 @@ guint            clutter_threads_add_frame_source_full (gint           priority,
 guint            clutter_threads_add_repaint_func      (GSourceFunc    func,
                                                         gpointer       data,
                                                         GDestroyNotify notify);
-void             clutter_threads_remove_repaint_func   (guint          handler_id);
+void             clutter_threads_remove_repaint_func   (guint          handle_id);
 
 void             clutter_set_motion_events_enabled   (gboolean enable);
 gboolean         clutter_get_motion_events_enabled   (void);

diff --git a/clutter/clutter-texture.c b/clutter/clutter-texture.c
index 3bb1e64..956d005 100644 (file)
--- a/clutter/clutter-texture.c
+++ b/clutter/clutter-texture.c
@@ -2718,7 +2718,7 @@ clutter_texture_get_keep_aspect_ratio (ClutterTexture *texture)
 /**
  * clutter_texture_set_load_async:
  * @texture: a #ClutterTexture
- * @load_sync: %TRUE if the texture should asynchronously load data
+ * @load_async: %TRUE if the texture should asynchronously load data
  *   from a filename
  *
  * Sets whether @texture should use a worker thread to load the data

diff --git a/clutter/cogl/cogl-material.h b/clutter/cogl/cogl-material.h
index da82256..504c173 100644 (file)
--- a/clutter/cogl/cogl-material.h
+++ b/clutter/cogl/cogl-material.h
@@ -616,6 +616,11 @@ const GList *cogl_material_get_layers (CoglHandle material_handle);
  * CoglMaterialLayerType:
  * @COGL_MATERIAL_LAYER_TYPE_TEXTURE: The layer represents a
  * <link linkend="cogl-Textures">Cogl texture</link>
+ *
+ * Available types of layers for a #CoglMaterial. This enumeration
+ * might be expanded in later versions.
+ *
+ * Since: 1.0
  */
 typedef enum _CoglMaterialLayerType
 {

diff --git a/clutter/cogl/cogl-shader.h b/clutter/cogl/cogl-shader.h
index 59c75ed..f528072 100644 (file)
--- a/clutter/cogl/cogl-shader.h
+++ b/clutter/cogl/cogl-shader.h
@@ -46,6 +46,10 @@ G_BEGIN_DECLS
  * CoglShaderType:
  * @COGL_SHADER_TYPE_VERTEX: A program for proccessing vertices
  * @COGL_SHADER_TYPE_FRAGMENT: A program for processing fragments
+ *
+ * Types of shaders
+ *
+ * Since: 1.0
  */
 typedef enum _CoglShaderType
 {
@@ -132,8 +136,10 @@ void            cogl_shader_get_info_log      (CoglHandle         handle,
  * cogl_shader_get_type:
  * @handle: #CoglHandle for a shader.
  *
- * Returns: COGL_SHADER_TYPE_VERTEX if the shader is a vertex processor
- *          or COGL_SHADER_TYPE_FRAGMENT if the shader is a frament processor
+ * Retrieves the type of a shader #CoglHandle
+ *
+ * Return value: %COGL_SHADER_TYPE_VERTEX if the shader is a vertex processor
+ *          or %COGL_SHADER_TYPE_FRAGMENT if the shader is a frament processor
  */
 CoglShaderType  cogl_shader_get_type          (CoglHandle          handle);
 
@@ -141,7 +147,9 @@ CoglShaderType  cogl_shader_get_type          (CoglHandle          handle);
  * cogl_shader_is_compiled:
  * @handle: #CoglHandle for a shader.
  *
- * Returns: TRUE if the shader object has sucessfully be compiled else FALSE
+ * Retrieves whether a shader #CoglHandle has been compiled
+ *
+ * Return value: %TRUE if the shader object has sucessfully be compiled
  */
 gboolean        cogl_shader_is_compiled       (CoglHandle          handle);
 

diff --git a/clutter/cogl/cogl-vertex-buffer.h b/clutter/cogl/cogl-vertex-buffer.h
index ba2cef8..ab37dbc 100644 (file)
--- a/clutter/cogl/cogl-vertex-buffer.h
+++ b/clutter/cogl/cogl-vertex-buffer.h
@@ -96,12 +96,17 @@ cogl_vertex_buffer_get_n_vertices (CoglHandle handle);
 
 /**
  * CoglAttributeType:
- * @COGL_ATTRIBUTE_TYPE_BYTE:
- * @COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE:
- * @COGL_ATTRIBUTE_TYPE_SHORT:
- * @COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT:
- * @COGL_ATTRIBUTE_TYPE_FLOAT:
+ * @COGL_ATTRIBUTE_TYPE_BYTE: Data is the same size of a byte
+ * @COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE: Data is the same size of an
+ *   unsigned byte
+ * @COGL_ATTRIBUTE_TYPE_SHORT: Data is the same size of a short integer
+ * @COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT: Data is the same size of
+ *   an unsigned short integer
+ * @COGL_ATTRIBUTE_TYPE_FLOAT: Data is the same size of a float
  *
+ * Data types for the components of cogl_vertex_buffer_add()
+ *
+ * Since: 1.0
  */
 typedef enum _CoglAttributeType
 {
@@ -245,14 +250,18 @@ cogl_vertex_buffer_enable (CoglHandle  handle,
 
 /**
  * CoglVerticesMode:
- * COGL_VERTICES_MODE_POINTS:
- * COGL_VERTICES_MODE_LINE_STRIP:
- * COGL_VERTICES_MODE_LINE_LOOP:
- * COGL_VERTICES_MODE_LINES:
- * COGL_VERTICES_MODE_TRIANGLE_STRIP:
- * COGL_VERTICES_MODE_TRIANGLE_FAN:
- * COGL_VERTICES_MODE_TRIANGLES:
- *
+ * @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to %GL_POINTS
+ * @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to %GL_LINE_STRIP
+ * @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to %GL_LINE_LOOP
+ * @COGL_VERTICES_MODE_LINES: FIXME, equivalent to %GL_LINES
+ * @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to %GL_TRIANGLE_STRIP
+ * @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to %GL_TRIANGLE_FAN
+ * @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to %GL_TRIANGLES
+ *
+ * How vertices passed to cogl_vertex_buffer_draw() and
+ * cogl_vertex_buffer_draw_elements() should be interpreted
+ *
+ * Since: 1.0
  */
 typedef enum _CoglVerticesMode
 {

diff --git a/clutter/cogl/cogl.h.in b/clutter/cogl/cogl.h.in
index a671aa0..611d358 100644 (file)
--- a/clutter/cogl/cogl.h.in
+++ b/clutter/cogl/cogl.h.in
@@ -412,6 +412,10 @@ void            cogl_disable_fog              (void);
  * @COGL_BUFFER_BIT_COLOR: Selects the primary color buffer
  * @COGL_BUFFER_BIT_DEPTH: Selects the depth buffer
  * @COGL_BUFFER_BIT_STENCIL: Selects the stencil buffer
+ *
+ * Types of auxiliary buffers
+ *
+ * Since: 1.0
  */
 typedef enum _CoglBufferBit
 {

diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt
index 2045772..67c1eb8 100644 (file)
--- a/doc/reference/clutter/clutter-sections.txt
+++ b/doc/reference/clutter/clutter-sections.txt
@@ -47,6 +47,7 @@ CLUTTER_UNITS_FROM_EM
 clutter_units_mm
 clutter_units_pt
 clutter_units_em
+clutter_units_em_for_font
 clutter_units_pixels
 clutter_units_to_pixels
 
@@ -438,10 +439,9 @@ clutter_texture_set_from_yuv_data
 clutter_texture_set_area_from_rgb_data
 clutter_texture_get_base_size
 clutter_texture_get_pixel_format
+clutter_texture_get_max_tile_waste
 clutter_texture_get_filter_quality
 clutter_texture_set_filter_quality
-clutter_texture_get_max_tile_waste
-clutter_texture_set_max_tile_waste
 clutter_texture_get_cogl_texture
 clutter_texture_set_cogl_texture
 clutter_texture_get_cogl_material
@@ -1016,6 +1016,8 @@ clutter_threads_add_timeout
 clutter_threads_add_timeout_full
 clutter_threads_add_frame_source
 clutter_threads_add_frame_source_full
+clutter_threads_add_repaint_func
+clutter_threads_remove_repaint_func
 
 <SUBSECTION>
 clutter_get_keyboard_grab
@@ -1508,6 +1510,7 @@ clutter_cairo_texture_get_surface_size
 <SUBSECTION>
 clutter_cairo_texture_create
 clutter_cairo_texture_create_region
+clutter_cairo_texture_clear
 
 <SUBSECTION>
 clutter_cairo_set_source_color

diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt
index c34585f..9d49ea5 100644 (file)
--- a/doc/reference/cogl/cogl-sections.txt
+++ b/doc/reference/cogl/cogl-sections.txt
@@ -376,15 +376,9 @@ CoglMaterialLayerPrivFlags
 <SECTION>
 <FILE>cogl-material-internals</FILE>
 <TITLE>Material Internals</TITLE>
-cogl_material_get_cogl_enable_flags
-CoglMaterialFlushOption
-cogl_material_flush_gl_state
 CoglMaterialLayer
 cogl_material_get_layers
 CoglMaterialLayerType
 cogl_material_layer_get_type
-CoglMaterialLayerFlags
-cogl_material_layer_get_flags
 cogl_material_layer_get_texture
-cogl_material_layer_flush_gl_sampler_state
 </SECTION>