docs: Fixes for Cogl API reference

  98% symbol docs coverage.
  335 symbols documented.
  0 symbols incomplete.
  8 not documented.

Not bad, if I may say so.

7 files changed, 80 insertions, 19 deletions

diff --git a/cogl/cogl-buffer.h b/cogl/cogl-buffer.h
index ddad4bc3..3d90d1ef 100644
--- a/cogl/cogl-buffer.h
+++ b/cogl/cogl-buffer.h
@@ -93,7 +93,7 @@ typedef enum { /*< prefix=COGL_BUFFER_USAGE_HINT >*/
  * @handle: a buffer handle
  * @hint: the new hint
  *
- * Set the usage hint on a buffer. See #CoglBufferUsageHint for a description
+ * Sets the usage hint on a buffer. See #CoglBufferUsageHint for a description
  * of the available hints.
  *
  * Since: 1.2
@@ -107,6 +107,8 @@ cogl_buffer_set_usage_hint (CoglHandle          handle,
  * cogl_buffer_get_usage_hint:
  * @handle: a buffer handle
  *
+ * Retrieves the usage hint set using cogl_buffer_set_usage_hint()
+ *
  * Return value: the #CoglBufferUsageHint currently used by the buffer
  *
  * Since: 1.2
@@ -122,7 +124,7 @@ cogl_buffer_get_usage_hint (CoglHandle handle);
  * @COGL_BUFFER_UPDATE_HINT_STREAM: the buffer will be used once or a couple of
  *   times
  *
- * The update hint on a buffer allows the user to give some clue on how often
+ * The update hint on a buffer allows the user to give some detail on how often
  * the buffer data is going to be updated.
  *
  * Since: 1.2
@@ -139,7 +141,7 @@ typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/
  * @handle: a buffer handle
  * @hint: the new hint
  *
- * Set the update hint on a buffer. See #CoglBufferUpdateHint for a description
+ * Sets the update hint on a buffer. See #CoglBufferUpdateHint for a description
  * of the available hints.
  *
  * Since: 1.2
@@ -153,6 +155,8 @@ cogl_buffer_set_update_hint (CoglHandle          handle,
  * cogl_buffer_get_update_hint:
  * @handle: a buffer handle
  *
+ * Retrieves the update hints set using cogl_buffer_set_update_hint()
+ *
  * Return value: the #CoglBufferUpdateHint currently used by the buffer
  *
  * Since: 1.2
@@ -168,6 +172,8 @@ cogl_buffer_get_update_hint (CoglHandle handle);
  * @COGL_BUFFER_ACCESS_READ_WRITE: the buffer will be used for both reading and
  *   writing
  *
+ * The access hints for cogl_buffer_set_update_hint()
+ *
  * Since: 1.2
  * Stability: Unstable
  */
diff --git a/cogl/cogl-color.h b/cogl/cogl-color.h
index cb7d5333..abc0e644 100644
--- a/cogl/cogl-color.h
+++ b/cogl/cogl-color.h
@@ -21,6 +21,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:cogl-color
+ * @short_description: A generic color definition
+ *
+ * #CoglColor is a simple structure holding the definition of a color such
+ * that it can be efficiently used by GL
+ *
+ * Since: 1.0
+ */
+
 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
 #error "Only <cogl/cogl.h> can be included directly."
 #endif
@@ -32,8 +42,39 @@
 
 G_BEGIN_DECLS
 
+/**
+ * cogl_color_new:
+ *
+ * Creates a new (empty) color
+ *
+ * Return value: a newly-allocated #CoglColor. Use cogl_color_free()
+ *   to free the allocated resources
+ *
+ * Since: 1.0
+ */
 CoglColor *cogl_color_new  (void);
+
+/**
+ * cogl_color_copy:
+ * @color: the color to copy
+ *
+ * Creates a copy of @color
+ *
+ * Return value: a newly-allocated #CoglColor. Use cogl_color_free()
+ *   to free the allocate resources
+ *
+ * Since: 1.0
+ */
 CoglColor *cogl_color_copy (const CoglColor *color);
+
+/**
+ * cogl_color_free:
+ * @color: the color to free
+ *
+ * Frees the resources allocated by cogl_color_new() and cogl_color_copy()
+ *
+ * Since: 1.0
+ */
 void       cogl_color_free (CoglColor       *color);
 
 /**
diff --git a/cogl/cogl-fixed.h b/cogl/cogl-fixed.h
index 904913ea..86843517 100644
--- a/cogl/cogl-fixed.h
+++ b/cogl/cogl-fixed.h
@@ -304,7 +304,7 @@ G_BEGIN_DECLS
 #define COGL_FIXED_FROM_DOUBLE(x)       (cogl_double_to_fixed (x))
 
 /**
- * COGL_FIXED_TO_FLOAT:
+ * COGL_FIXED_TO_DOUBLE:
  * @x: a #CoglFixed number
  *
  * Converts @x from a fixed point to a floating point notation, in
diff --git a/cogl/cogl-material-private.h b/cogl/cogl-material-private.h
index a9cf77a1..a5a846fa 100644
--- a/cogl/cogl-material-private.h
+++ b/cogl/cogl-material-private.h
@@ -148,7 +148,7 @@ struct _CoglMaterial
 /*
  * SECTION:cogl-material-internals
  * @short_description: Functions for creating custom primitives that make use
- *                     of Cogl materials for filling.
+ *    of Cogl materials for filling.
  *
  * Normally you shouldn't need to use this API directly, but if you need to
  * developing a custom/specialised primitive - probably using raw OpenGL - then
diff --git a/cogl/cogl-matrix.h b/cogl/cogl-matrix.h
index 451233d1..eb5215a1 100644
--- a/cogl/cogl-matrix.h
+++ b/cogl/cogl-matrix.h
@@ -151,7 +151,8 @@ void cogl_matrix_rotate (CoglMatrix *matrix,
 			 float y,
 			 float z);
 
-/* cogl_matrix_translate:
+/**
+ * cogl_matrix_translate:
  * @matrix: A 4x4 transformation matrix
  * @x: The X translation you want to apply
  * @y: The Y translation you want to apply
diff --git a/cogl/cogl-types.h b/cogl/cogl-types.h
index 816d240e..2bc68650 100644
--- a/cogl/cogl-types.h
+++ b/cogl/cogl-types.h
@@ -283,8 +283,10 @@ struct _CoglTextureVertex
  *   the mipmap pyramid from the base level image whenever it is
  *   updated. The mipmaps are only generated when the texture is
  *   rendered with a mipmap filter so it should be free to leave out
- *   this flag when using other filtering modes.
+ *   this flag when using other filtering modes
  * @COGL_TEXTURE_NO_SLICING: Disables the slicing of the texture
+ * @COGL_TEXTURE_NO_ATLAS: Disables the insertion of the texture inside
+ *   the texture atlas used by Cogl
  *
  * Flags to pass to the cogl_texture_new_* family of functions.
  *
@@ -331,8 +333,27 @@ typedef enum {
   COGL_FOG_MODE_EXPONENTIAL_SQUARED
 } CoglFogMode;
 
+/**
+ * COGL_BLEND_STRING_ERROR:
+ *
+ * #GError domain for blend string parser errors
+ *
+ * Since: 1.0
+ */
 #define COGL_BLEND_STRING_ERROR (cogl_blend_string_error_quark ())
 
+/**
+ * CoglBlendStringError:
+ * @COGL_BLEND_STRING_ERROR_PARSE_ERROR: Generic parse error
+ * @COGL_BLEND_STRING_ERROR_ARGUMENT_PARSE_ERROR: Argument parse error
+ * @COGL_BLEND_STRING_ERROR_INVALID_ERROR: Internal parser error
+ * @COGL_BLEND_STRING_ERROR_GPU_UNSUPPORTED_ERROR: Blend string not
+ *   supported by the GPU
+ *
+ * Error enumeration for the blend strings parser
+ *
+ * Since: 1.0
+ */
 typedef enum { /*< prefix=COGL_BLEND_STRING_ERROR >*/
   COGL_BLEND_STRING_ERROR_PARSE_ERROR,
   COGL_BLEND_STRING_ERROR_ARGUMENT_PARSE_ERROR,
diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt
index c2678dcf..7c9fab80 100644
--- a/doc/reference/cogl/cogl-sections.txt
+++ b/doc/reference/cogl/cogl-sections.txt
@@ -184,7 +184,6 @@ cogl_is_bitmap
 <SECTION>
 <FILE>cogl-texture</FILE>
 <TITLE>Textures</TITLE>
-COGL_TEXTURE_MAX_WASTE
 CoglTextureVertex
 CoglTextureFlags
 cogl_texture_new_with_size
@@ -207,6 +206,9 @@ cogl_texture_is_sliced
 cogl_texture_get_gl_texture
 cogl_texture_get_data
 cogl_texture_set_region
+
+<SUBSECTION Private>
+COGL_TEXTURE_MAX_WASTE
 </SECTION>
 
 <SECTION>
@@ -247,7 +249,7 @@ cogl_offscreen_ref
 cogl_offscreen_unref
 cogl_is_offscreen
 cogl_set_framebuffer
-cogl_push_frameffer
+cogl_push_framebuffer
 cogl_pop_framebuffer
 cogl_set_draw_buffer
 cogl_pop_draw_buffer
@@ -443,7 +445,6 @@ cogl_material_get_shininess
 CoglMaterialAlphaFunc
 cogl_material_set_alpha_test_function
 CoglBlendStringError
-COGL_BLEND_STRING_ERROR
 cogl_material_set_blend
 cogl_material_set_blend_constant
 cogl_material_set_layer
@@ -465,15 +466,6 @@ cogl_blend_string_error_quark
 </SECTION>
 
 <SECTION>
-<FILE>cogl-material-internals</FILE>
-<TITLE>Material Internals</TITLE>
-cogl_material_get_layers
-CoglMaterialLayerType
-cogl_material_layer_get_type
-cogl_material_layer_get_texture
-</SECTION>
-
-<SECTION>
 <FILE>cogl-buffer</FILE>
 <TITLE>Buffers</TITLE>
 cogl_is_buffer