[docs] Fixes for the API reference

* Add unused symbols

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

* Add missing descriptions

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
 {

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
+ * Retrieves the type of a shader #CoglHandle
- *          or COGL_SHADER_TYPE_FRAGMENT if the shader is a frament processor
+ *
+ * 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);
 

cogl-vertex-buffer.h

@@ -96,12 +96,17 @@ cogl_vertex_buffer_get_n_vertices (CoglHandle handle);
 
 /**
  * CoglAttributeType:
- * @COGL_ATTRIBUTE_TYPE_BYTE:
+ * @COGL_ATTRIBUTE_TYPE_BYTE: Data is the same size of a byte
- * @COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE:
+ * @COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE: Data is the same size of an
- * @COGL_ATTRIBUTE_TYPE_SHORT:
+ *   unsigned byte
- * @COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT:
+ * @COGL_ATTRIBUTE_TYPE_SHORT: Data is the same size of a short integer
- * @COGL_ATTRIBUTE_TYPE_FLOAT:
+ * @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_POINTS: FIXME, equivalent to %GL_POINTS
- * COGL_VERTICES_MODE_LINE_STRIP:
+ * @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to %GL_LINE_STRIP
- * COGL_VERTICES_MODE_LINE_LOOP:
+ * @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to %GL_LINE_LOOP
- * COGL_VERTICES_MODE_LINES:
+ * @COGL_VERTICES_MODE_LINES: FIXME, equivalent to %GL_LINES
- * COGL_VERTICES_MODE_TRIANGLE_STRIP:
+ * @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to %GL_TRIANGLE_STRIP
- * COGL_VERTICES_MODE_TRIANGLE_FAN:
+ * @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to %GL_TRIANGLE_FAN
- * COGL_VERTICES_MODE_TRIANGLES:
+ * @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
 {

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
 {

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>