[docs] Various gtk-doc fixes for COGL

Try to keep the gtk-doc errors down to a minimum.

cogl-bitmap.h

@@ -47,11 +47,11 @@ G_BEGIN_DECLS
  * @filename: the file to load.
  * @error: a #GError or %NULL.
  *
- * Load an image file from disk. This function can be safely called from
+ * Loads an image file from disk. This function can be safely called from
  * within a thread.
  *
- * Returns: A CoglBitmap to the new loaded image data, or %NULL if loading
+ * Returns: a #CoglHandle to the new loaded image data, or
- * the image failed.
+ *   %COGL_INVALID_HANDLE if loading the image failed.
  *
  * Since: 1.0
  */
@@ -67,6 +67,8 @@ CoglHandle      cogl_bitmap_new_from_file     (const gchar    *filename,
  * Parses an image file enough to extract the width and height
  * of the bitmap.
  *
+ * Returns: %TRUE if the image was successfully parsed
+ *
  * Since: 1.0
  */
 gboolean        cogl_bitmap_get_size_from_file (const gchar   *filename,

cogl-material.h

@@ -500,7 +500,9 @@ void cogl_material_set_blend_constant (CoglHandle             material,
 
 /**
  * cogl_material_set_layer:
- * @material: A CoglMaterial object
+ * @material: A #CoglHandle for a material object
+ * @layer_index: the index of the layer
+ * @texture: a #CoglHandle for the layer object
  *
  * In addition to the standard OpenGL lighting model a Cogl material may have
  * one or more layers comprised of textures that can be blended together in
@@ -510,8 +512,8 @@ void cogl_material_set_blend_constant (CoglHandle             material,
  * The index values of multiple layers do not have to be consecutive; it is
  * only their relative order that is important.
  *
- * XXX: In the future, we may define other types of material layers, such
+ * <note>In the future, we may define other types of material layers, such
- * as purely GLSL based layers.
+ * as purely GLSL based layers.</note>
  *
  * Since 1.0
  */
@@ -627,16 +629,16 @@ cogl_material_set_layer_combine (CoglHandle material,
  * @material: A CoglMaterial object
  * @layer_index: Specifies the layer you want to specify a constant used
  *               for texture combining
- * @color_constant: The constant color you want
+ * @constant: The constant color you want
  *
  * When you are using the 'CONSTANT' color source in a layer combine
  * description then you can use this function to define its value.
  *
  * Since 1.0
  */
-void cogl_material_set_layer_combine_constant (CoglHandle                     material,
+void cogl_material_set_layer_combine_constant (CoglHandle  material,
-                                               int                            layer_index,
+                                               int         layer_index,
-                                               CoglColor                     *constant);
+                                               CoglColor  *constant);
 
 /**
  * cogl_material_set_layer_matrix:
@@ -659,7 +661,7 @@ void cogl_material_set_layer_matrix (CoglHandle  material,
  * Returns: A list of #CoglHandle<!-- -->'s that can be passed to the
  *          cogl_material_layer_* functions.
  */
-const GList *cogl_material_get_layers (CoglHandle material_handle);
+const GList *cogl_material_get_layers (CoglHandle material);
 
 /**
  * CoglMaterialLayerType:
@@ -680,10 +682,14 @@ typedef enum _CoglMaterialLayerType
  * cogl_material_layer_get_type:
  * @layer_handle: A Cogl material layer handle
  *
+ * Retrieves the type of the layer
+ *
  * Currently there is only one type of layer defined:
- * COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
+ * %COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
  * based layers in the future, you should write code that checks the type
  * first.
+ *
+ * Return value: the type of the layer
  */
 CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);
 

cogl-matrix.h

@@ -54,21 +54,24 @@ G_BEGIN_DECLS
  * applied.
  *
  * The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:
- * <programlisting>
+ *
- * x_new = xx * x + xy * y + xz * z + xw * w
+ * |[
- * y_new = yx * x + yy * y + yz * z + yw * w
+ *   x_new = xx * x + xy * y + xz * z + xw * w
- * z_new = zx * x + zy * y + zz * z + zw * w
+ *   y_new = yx * x + yy * y + yz * z + yw * w
- * w_new = wx * x + wy * y + wz * z + ww * w
+ *   z_new = zx * x + zy * y + zz * z + zw * w
- * </programlisting>
+ *   w_new = wx * x + wy * y + wz * z + ww * w
+ * ]|
+ *
  * Where w is normally 1
  *
- * Note: You must consider the members of the CoglMatrix structure read only,
+ * <note>You must consider the members of the CoglMatrix structure read only,
  * and all matrix modifications must be done via the cogl_matrix API. This
  * allows Cogl to annotate the matrices internally. Violation of this will give
  * undefined results. If you need to initialize a matrix with a constant other
- * than the identity matrix you can use cogl_matrix_init_from_array().
+ * than the identity matrix you can use cogl_matrix_init_from_array().</note>
  */
 typedef struct _CoglMatrix {
+    /*< private >*/
 
     /* column 0 */
     float xx;
@@ -94,8 +97,6 @@ typedef struct _CoglMatrix {
     float zw;
     float ww;
 
-    /*< private >*/
-
     /* Note: we may want to extend this later with private flags
      * and a cache of the inverse transform matrix. */
     float   _padding0[16];
@@ -184,11 +185,10 @@ void cogl_matrix_scale (CoglMatrix *matrix,
  * @right: coord of right vertical clipping plane
  * @bottom: coord of bottom horizontal clipping plane
  * @top: coord of top horizontal clipping plane
- * @near: positive distance to near depth clipping plane
+ * @z_near: positive distance to near depth clipping plane
- * @far: positive distance to far depth clipping plane
+ * @z_far: positive distance to far depth clipping plane
  *
  * Multiplies the matrix by the given frustum perspective matrix.
- *
  */
 void cogl_matrix_frustum (CoglMatrix *matrix,
                           float       left,
@@ -210,7 +210,7 @@ void cogl_matrix_frustum (CoglMatrix *matrix,
  *
  * Multiplies the matrix by the described perspective matrix
  *
- * Note: you should be careful not to have to great a z_far / z_near ratio
+ * Note: you should be careful not to have to great a @z_far / @z_near ratio
  * since that will reduce the effectiveness of depth testing since there wont
  * be enough precision to identify the depth of objects near to each other.
  */
@@ -259,8 +259,10 @@ void cogl_matrix_init_from_array (CoglMatrix *matrix, const float *array);
  *
  * This casts a CoglMatrix to a float array which can be directly passed to
  * OpenGL.
+ *
+ * Return value: a pointer to the float array
  */
-const float *cogl_matrix_get_array (const CoglMatrix *matrix);
+G_CONST_RETURN float *cogl_matrix_get_array (const CoglMatrix *matrix);
 
 /**
  * cogl_matrix_transform_point:

cogl-offscreen.h

@@ -55,10 +55,10 @@ G_BEGIN_DECLS
  *
  * Note: This does not work with sliced Cogl textures.
  *
- * Returns: a CoglHandle for the new offscreen buffer or COGL_INVALID_HANDLE
+ * Returns: a #CoglHandle for the new offscreen buffer or %COGL_INVALID_HANDLE
  *          if it wasn't possible to create the buffer.
  */
-CoglHandle      cogl_offscreen_new_to_texture (CoglHandle         texhandle);
+CoglHandle      cogl_offscreen_new_to_texture (CoglHandle         handle);
 
 /**
  * cogl_offscreen_ref:

cogl-vertex-buffer.h

@@ -79,8 +79,9 @@ G_BEGIN_DECLS
  * cogl_vertex_buffer_new:
  * @n_vertices: The number of vertices that your attributes will correspond to.
  *
- * This creates a Cogl handle for a new vertex buffer that you can then start
+ * Creates a new vertex buffer that you can use to add attributes.
- * to add attributes too.
+ *
+ * Return value: a new #CoglHandle
  */
 CoglHandle
 cogl_vertex_buffer_new (guint n_vertices);
@@ -89,7 +90,9 @@ cogl_vertex_buffer_new (guint n_vertices);
  * cogl_vertex_buffer_get_n_vertices:
  * @handle: A vertex buffer handle
  *
- * This returns the number of vertices that @handle represents
+ * Retrieves the number of vertices that @handle represents
+ *
+ * Return value: the number of vertices
  */
 guint
 cogl_vertex_buffer_get_n_vertices (CoglHandle handle);

cogl.h.in

@@ -334,7 +334,7 @@ void            cogl_set_projection_matrix    (CoglMatrix *matrix);
 void            cogl_get_viewport             (float        v[4]);
 
 /**
- * cogl_set_depth_test_enable:
+ * cogl_set_depth_test_enabled:
  * @setting: %TRUE to enable depth testing or %FALSE to disable.
  *
  * Sets whether depth testing is enabled. If it is disabled then the
@@ -343,7 +343,7 @@ void            cogl_get_viewport             (float        v[4]);
  * clutter_actor_lower(), otherwise it will also take into account the
  * actor's depth. Depth testing is disabled by default.
  */
-void            cogl_set_depth_test_enable    (gboolean setting);
+void            cogl_set_depth_test_enabled   (gboolean setting);
 
 /**
  * cogl_get_depth_test_enable:
@@ -352,7 +352,7 @@ void            cogl_set_depth_test_enable    (gboolean setting);
  *
  * Returns: TRUE if depth testing is enabled else FALSE
  */
-gboolean        cogl_get_depth_test_enable    (void);
+gboolean        cogl_get_depth_test_enabled   (void);
 
 /**
  * cogl_set_backface_culling_enabled:

doc/reference/cogl/Makefile.am

@@ -54,11 +54,9 @@ CFILE_GLOB=\
 # Header files to ignore when scanning.
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
 IGNORE_HFILES=\
-	cogl-bitmap.h \
 	cogl-defines-gl.h \
         cogl-defines-gles.h \
 	cogl-handle.h \
-        cogl-primitives.h \
 	gl \
 	gles
 

doc/reference/cogl/cogl-sections.txt

@@ -3,6 +3,10 @@
 <TITLE>General API</TITLE>
 COGL_INVALID_HANDLE
 CoglHandle
+cogl_handle_ref
+cogl_handle_unref
+
+<SUBSECTION>
 CoglFuncPtr
 COGL_PIXEL_FORMAT_24
 COGL_PIXEL_FORMAT_32
@@ -14,12 +18,18 @@ COGL_UNORDERED_MASK
 COGL_UNPREMULT_MASK
 CoglPixelFormat
 CoglBufferTarget
+CoglBufferBit
+CoglAttributeType
+
 <SUBSECTION>
 CoglFeatureFlags
 cogl_get_features
 cogl_features_available
 cogl_check_extension
 cogl_get_proc_address
+cogl_get_option_group
+cogl_gl_error_to_string
+
 <SUBSECTION>
 cogl_push_matrix
 cogl_pop_matrix
@@ -29,14 +39,15 @@ cogl_rotate
 cogl_frustum
 cogl_perspective
 cogl_ortho
+
 <SUBSECTION>
 cogl_get_modelview_matrix
 cogl_set_modelview_matrix
 cogl_get_projection_matrix
 cogl_set_projection_matrix
 cogl_viewport
-cogl_setup_viewport
 cogl_get_viewport
+
 <SUBSECTION>
 cogl_clear
 cogl_get_bitmasks
@@ -44,18 +55,61 @@ cogl_set_depth_test_enabled
 cogl_get_depth_test_enabled
 cogl_set_backface_culling_enabled
 cogl_get_backface_culling_enabled
+
 <SUBSECTION>
 CoglFogMode
 cogl_set_fog
 cogl_disable_fog
+
 <SUBSECTION>
 cogl_set_source
 cogl_set_source_color
 cogl_set_source_color4ub
 cogl_set_source_color4f
 cogl_set_source_texture
+
+<SUBSECTION Standard>
+COGL_TYPE_ATTRIBUTE_TYPE
+COGL_TYPE_BUFFER_BIT
+COGL_TYPE_BUFFER_TARGET
+COGL_TYPE_DEBUG_FLAGS
+COGL_TYPE_FEATURE_FLAGS
+COGL_TYPE_FIXED
+COGL_TYPE_FOG_MODE
+COGL_TYPE_HANDLE
+COGL_TYPE_INDICES_TYPE
+COGL_TYPE_MATERIAL_ALPHA_FUNC
+COGL_TYPE_MATERIAL_FILTER
+COGL_TYPE_MATERIAL_LAYER_TYPE
+COGL_TYPE_MATRIX_MODE
+COGL_TYPE_PIXEL_FORMAT
+COGL_TYPE_SHADER_TYPE
+COGL_TYPE_TEXTURE_FLAGS
+COGL_TYPE_VERTICES_MODE
+
 <SUBSECTION Private>
 cogl_util_next_p2
+cogl_attribute_type_get_type
+cogl_buffer_bit_get_type
+cogl_buffer_target_get_type
+cogl_debug_flags_get_type
+cogl_feature_flags_get_type
+cogl_fixed_get_type
+cogl_fog_mode_get_type
+cogl_handle_get_type
+cogl_indices_type_get_type
+cogl_material_alpha_func_get_type
+cogl_material_filter_get_type
+cogl_material_layer_type_get_type
+cogl_matrix_mode_get_type
+cogl_pixel_format_get_type
+cogl_shader_type_get_type
+cogl_texture_flags_get_type
+cogl_vertices_mode_get_type
+GE
+COGL_NOTE
+CoglDebugFlags
+cogl_debug_flags
 </SECTION>
 
 <SECTION>
@@ -64,6 +118,7 @@ CoglClipStackState
 cogl_clip_push
 cogl_clip_push_from_path
 cogl_clip_push_from_path_preserve
+cogl_clip_push_window_rect
 cogl_clip_pop
 cogl_clip_stack_save
 cogl_clip_stack_restore
@@ -75,6 +130,7 @@ cogl_clip_ensure
 <TITLE>Primitives</TITLE>
 <SUBSECTION>
 cogl_rectangle
+cogl_rectangles
 cogl_rectangle_with_texture_coords
 cogl_rectangles_with_texture_coords
 cogl_rectangle_with_multitexture_coords
@@ -141,6 +197,7 @@ cogl_texture_set_region
 <SECTION>
 <FILE>cogl-shaders</FILE>
 <TITLE>Shaders and Programmable Pipeline</TITLE>
+CoglShaderType
 cogl_create_shader
 cogl_shader_ref
 cogl_shader_unref
@@ -150,6 +207,7 @@ cogl_shader_compile
 cogl_shader_get_info_log
 cogl_shader_get_type
 cogl_shader_is_compiled
+
 <SUBSECTION>
 cogl_create_program
 cogl_program_ref
@@ -174,8 +232,8 @@ cogl_offscreen_ref
 cogl_offscreen_unref
 cogl_is_offscreen
 cogl_set_draw_buffer
-<SUBSECTION Private>
+cogl_pop_draw_buffer
-cogl_offscreen_new_multisample
+cogl_push_draw_buffer
 </SECTION>
 
 <SECTION>
@@ -192,6 +250,7 @@ COGL_FIXED_FROM_FLOAT
 COGL_FIXED_TO_FLOAT
 COGL_FIXED_FROM_INT
 COGL_FIXED_TO_INT
+COGL_FIXED_FROM_DOUBLE
 COGL_FIXED_TO_DOUBLE
 COGL_FLOAT_TO_INT
 COGL_FLOAT_TO_UINT
@@ -306,8 +365,10 @@ cogl_vertex_buffer_submit
 cogl_vertex_buffer_disable
 cogl_vertex_buffer_enable
 cogl_vertex_buffer_draw
+
+<SUBSECTION>
 CoglIndicesType
-cogl_vertex_buffer_add_indices
+cogl_vertex_buffer_indices_new
 cogl_vertex_buffer_delete_indices
 cogl_vertex_buffer_draw_elements
 cogl_vertex_buffer_indices_get_for_quads
@@ -321,7 +382,13 @@ COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
 <FILE>cogl-matrix</FILE>
 <TITLE>Matrices</TITLE>
 CoglMatrix
+CoglMatrixMode
+CoglMatrixStack
 cogl_matrix_init_identity
+cogl_matrix_frustum
+cogl_matrix_ortho
+cogl_matrix_perspective
+cogl_matrix_transform_point
 cogl_matrix_multiply
 cogl_matrix_rotate
 cogl_matrix_translate
@@ -354,7 +421,12 @@ cogl_material_set_shininess
 cogl_material_get_shininess
 CoglMaterialAlphaFunc
 cogl_material_set_alpha_test_function
-CoglMaterialBlendFactor
+CoglBlendStringChannelMask
+CoglBlendStringColorSourceType
+CoglBlendStringContext
+CoglBlendStringError
+CoglBlendStringFunctionType
+COGL_BLEND_STRING_ERROR
 cogl_material_set_blend
 cogl_material_set_blend_constant
 cogl_material_set_layer
@@ -372,6 +444,7 @@ cogl_material_layer_get_mag_filter
 <SUBSECTION Private>
 CoglMaterial
 CoglMaterialFlags
+CoglMaterialLayerFlags
 CoglMaterialLayerPrivFlags
 </SECTION>