docs: Increase consistency in Cogl documentation

clutter/cogl/cogl/cogl-texture.h

@@ -68,7 +68,7 @@ CoglHandle      cogl_texture_new_with_size    (guint            width,
  * @filename: the file to load
  * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
  * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
- *    texture. If COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
  *    format similar to the format of the source data will be used. The
  *    default blending equations of Cogl expect premultiplied color data;
  *    the main use of passing a non-premultiplied format here is if you
@@ -173,7 +173,7 @@ CoglHandle      cogl_texture_new_from_bitmap (CoglHandle       bmp_handle,
  *
  * Gets whether the given handle references an existing texture object.
  *
- * Returns: %TRUE if the handle references a texture,
+ * Return value: %TRUE if the handle references a texture, and
  *   %FALSE otherwise
  */
 gboolean        cogl_is_texture               (CoglHandle          handle);
@@ -182,9 +182,9 @@ gboolean        cogl_is_texture               (CoglHandle          handle);
  * cogl_texture_get_width:
  * @handle: a #CoglHandle for a texture.
  *
- * Query the width of a cogl texture.
+ * Queries the width of a cogl texture.
  *
- * Returns: the width of the GPU side texture in pixels:
+ * Return value: the width of the GPU side texture in pixels
  */
 guint           cogl_texture_get_width        (CoglHandle          handle);
 
@@ -192,9 +192,9 @@ guint           cogl_texture_get_width        (CoglHandle          handle);
  * cogl_texture_get_height:
  * @handle: a #CoglHandle for a texture.
  *
- * Query the height of a cogl texture.
+ * Queries the height of a cogl texture.
  *
- * Returns: the height of the GPU side texture in pixels:
+ * Return value: the height of the GPU side texture in pixels
  */
 guint           cogl_texture_get_height       (CoglHandle          handle);
 
@@ -202,9 +202,9 @@ guint           cogl_texture_get_height       (CoglHandle          handle);
  * cogl_texture_get_format:
  * @handle: a #CoglHandle for a texture.
  *
- * Query the #CoglPixelFormat of a cogl texture.
+ * Queries the #CoglPixelFormat of a cogl texture.
  *
- * Returns: the #CoglPixelFormat of the GPU side texture.
+ * Return value: the #CoglPixelFormat of the GPU side texture
  */
 CoglPixelFormat cogl_texture_get_format       (CoglHandle          handle);
 
@@ -213,9 +213,9 @@ CoglPixelFormat cogl_texture_get_format       (CoglHandle          handle);
  * cogl_texture_get_rowstride:
  * @handle: a #CoglHandle for a texture.
  *
- * Query the rowstride of a cogl texture.
+ * Queries the rowstride of a cogl texture.
  *
- * Returns: the offset in bytes between each consequetive row of pixels.
+ * Return value: the offset in bytes between each consequetive row of pixels
  */
 guint           cogl_texture_get_rowstride    (CoglHandle          handle);
 
@@ -223,10 +223,10 @@ guint           cogl_texture_get_rowstride    (CoglHandle          handle);
  * cogl_texture_get_max_waste:
  * @handle: a #CoglHandle for a texture.
  *
- * Query the maximum wasted (unused) pixels in one dimension of a GPU side
+ * Queries the maximum wasted (unused) pixels in one dimension of a GPU side
  * texture.
  *
- * Returns: the maximum waste.
+ * Return value: the maximum waste
  */
 gint            cogl_texture_get_max_waste    (CoglHandle          handle);
 
@@ -234,11 +234,11 @@ gint            cogl_texture_get_max_waste    (CoglHandle          handle);
  * cogl_texture_is_sliced:
  * @handle: a #CoglHandle for a texture.
  *
- * Query if a texture is sliced (stored as multiple GPU side tecture
+ * Queries if a texture is sliced (stored as multiple GPU side tecture
  * objects).
  *
- * Returns: %TRUE if the texture is sliced, %FALSE if the texture
+ * Return value: %TRUE if the texture is sliced, %FALSE if the texture
- * is stored as a single GPU texture.
+ *   is stored as a single GPU texture
  */
 gboolean        cogl_texture_is_sliced        (CoglHandle          handle);
 
@@ -250,12 +250,13 @@ gboolean        cogl_texture_is_sliced        (CoglHandle          handle);
  * @out_gl_target: (out) (allow-none): pointer to return location for the
  *   GL target type, or %NULL.
  *
- * Query the GL handles for a GPU side texture through it's #CoglHandle,
+ * Queries the GL handles for a GPU side texture through its #CoglHandle.
- * if the texture is spliced the data for the first sub texture will be
+ *
+ * If the texture is spliced the data for the first sub texture will be
  * queried.
  *
- * Returns: %TRUE if the handle was successfully retrieved %FALSE
+ * Return value: %TRUE if the handle was successfully retrieved, %FALSE
- * if the handle was invalid.
+ *   if the handle was invalid
  */
 gboolean        cogl_texture_get_gl_texture   (CoglHandle         handle,
                                                GLuint            *out_gl_handle,
@@ -270,10 +271,10 @@ gboolean        cogl_texture_get_gl_texture   (CoglHandle         handle,
  * @data: memory location to write contents of buffer, or %NULL if we're
  * only querying the data size through the return value.
  *
- * Copy the pixel data from a cogl texture to system memory.
+ * Copies the pixel data from a cogl texture to system memory.
  *
- * Returns: the size of the texture data in bytes (or 0 if the texture
+ * Return value: the size of the texture data in bytes, or 0 if the texture
- * is not valid.)
+ *   is not valid
  */
 gint            cogl_texture_get_data         (CoglHandle          handle,
                                                CoglPixelFormat     format,
@@ -299,7 +300,8 @@ gint            cogl_texture_get_data         (CoglHandle          handle,
  * Sets the pixels in a rectangular subregion of @handle from an in-memory
  * buffer containing pixel data.
  *
- * Returns: %TRUE if the subregion upload was successful, otherwise %FALSE.
+ * Return value: %TRUE if the subregion upload was successful, and
+ *   %FALSE otherwise
  */
 gboolean        cogl_texture_set_region       (CoglHandle          handle,
                                                gint                src_x,
@@ -314,13 +316,17 @@ gboolean        cogl_texture_set_region       (CoglHandle          handle,
                                                guint               rowstride,
                                                const guchar       *data);
 
+#ifndef COGL_DISABLE_DEPRECATED
+
 /**
  * cogl_texture_ref:
  * @handle: a @CoglHandle.
  *
  * Increment the reference count for a cogl texture.
  *
- * Returns: the @handle.
+ * Deprecated: 1.2: Use cogl_handle_ref() instead
+ *
+ * Return value: the @handle.
  */
 CoglHandle      cogl_texture_ref              (CoglHandle          handle);
 
@@ -328,10 +334,14 @@ CoglHandle      cogl_texture_ref              (CoglHandle          handle);
  * cogl_texture_unref:
  * @handle: a @CoglHandle.
  *
- * Deccrement the reference count for a cogl texture.
+ * Decrement the reference count for a cogl texture.
+ *
+ * Deprecated: 1.2: Use cogl_handle_unref() instead
  */
 void            cogl_texture_unref            (CoglHandle          handle);
 
+#endif /* COGL_DISABLE_DEPRECATED */
+
 /**
  * cogl_rectangle_with_texture_coords:
  * @x1: x coordinate upper left on screen.
@@ -364,8 +374,8 @@ void cogl_rectangle_with_texture_coords (float  x1,
  * @y1: y coordinate upper left on screen.
  * @x2: x coordinate lower right on screen.
  * @y2: y coordinate lower right on screen.
- * @tex_coords: (in) (array) (transfer none): An array containing groups of 4
+ * @tex_coords: (in) (array) (transfer none): An array containing groups of
- *   float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture
+ *   4 float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture
  *   coordinates; one for the upper left texel, and one for the lower right
  *   texel. Each value should be between 0.0 and 1.0, where the coordinate
  *   (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the

clutter/cogl/cogl/cogl-vertex-buffer.h

@@ -39,8 +39,7 @@ G_BEGIN_DECLS
 /**
  * SECTION:cogl-vertex-buffer
  * @short_description: An API for submitting extensible arrays of vertex
- *		       attributes to be mapped into the GPU for fast
+ *   attributes to be mapped into the GPU for fast drawing.
- *		       drawing.
  *
  * For example to describe a textured triangle, you could create a new cogl
  * vertex buffer with 3 vertices, and then you might add 2 attributes for each
@@ -111,8 +110,7 @@ cogl_vertex_buffer_get_n_vertices (CoglHandle handle);
  *
  * Since: 1.0
  */
-typedef enum _CoglAttributeType
+typedef enum {
-{
   COGL_ATTRIBUTE_TYPE_BYTE = GL_BYTE,
   COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE = GL_UNSIGNED_BYTE,
   COGL_ATTRIBUTE_TYPE_SHORT = GL_SHORT,
@@ -124,51 +122,53 @@ typedef enum _CoglAttributeType
  * cogl_vertex_buffer_add:
  * @handle: A vertex buffer handle
  * @attribute_name: The name of your attribute. It should be a valid GLSL
- *		    variable name and standard attribute types must use one
+ *   variable name and standard attribute types must use one of following
- *		    of following built-in names: (Note: they correspond to the
+ *   built-in names: (Note: they correspond to the built-in names of GLSL)
- *		    built-in names of GLSL)
  *   <itemizedlist>
  *     <listitem>"gl_Color"</listitem>
  *     <listitem>"gl_Normal"</listitem>
  *     <listitem>"gl_MultiTexCoord0, gl_MultiTexCoord1, ..."</listitem>
  *     <listitem>"gl_Vertex"</listitem>
  *   </itemizedlist>
- *		    To support adding multiple variations of the same attribute
+ *   To support adding multiple variations of the same attribute the name
- *		    the name can have a detail component, E.g.
+ *   can have a detail component, E.g. "gl_Color::active" or
- *		    "gl_Color::active" or "gl_Color::inactive"
+ *   "gl_Color::inactive"
- * @n_components: The number of components per attribute and must be 1,2,3 or 4
+ * @n_components: The number of components per attribute and must be 1, 2,
+ *   3 or 4
  * @type: a #CoglAttributeType specifying the data type of each component.
- * @normalized: If GL_TRUE, this specifies that values stored in an integer
+ * @normalized: If %TRUE, this specifies that values stored in an integer
  *   format should be mapped into the range [-1.0, 1.0] or [0.0, 1.0]
- *		for unsigned values. If GL_FALSE they are converted to floats
+ *   for unsigned values. If %FALSE they are converted to floats
  *   directly.
  * @stride: This specifies the number of bytes from the start of one attribute
- *	    value to the start of the next value (for the same attribute). So
+ *   value to the start of the next value (for the same attribute). So, for
- *	    for example with a position interleved with color like this:
+ *   example, with a position interleved with color like this:
  *   XYRGBAXYRGBAXYRGBA, then if each letter represents a byte, the
  *   stride for both attributes is 6. The special value 0 means the
  *   values are stored sequentially in memory.
- * @pointer: This addresses the first attribute in the vertex array. (This
+ * @pointer: This addresses the first attribute in the vertex array. This
- *	     must remain valid until you either call
+ *   must remain valid until you either call cogl_vertex_buffer_submit() or
- *	     cogl_vertex_buffer_submit() or issue a draw call.)
+ *   issue a draw call.
  *
- * This function lets you add an attribute to a buffer. You either use one
+ * Adds an attribute to a buffer.
- * of the built-in names such as "gl_Vertex", or "gl_MultiTexCoord0" to add
+ *
- * standard attributes, like positions, colors and normals or you can add
+ * You either can use one of the built-in names such as "gl_Vertex", or
- * custom attributes for use in shaders.
+ * "gl_MultiTexCoord0" to add standard attributes, like positions, colors
+ * and normals, or you can add custom attributes for use in shaders.
  *
  * The number of vertices declared when calling cogl_vertex_buffer_new()
- * determines how many attribute values will be read from the supplied pointer.
+ * determines how many attribute values will be read from the supplied
+ * @pointer.
  *
  * The data for your attribute isn't copied anywhere until you call
- * cogl_vertex_buffer_submit(), (or issue a draw call which automatically
+ * cogl_vertex_buffer_submit(), or issue a draw call which automatically
- * submits pending attribute changes) so the supplied pointer must remain
+ * submits pending attribute changes. so the supplied pointer must remain
  * valid until then. If you are updating an existing attribute (done by
- * re-adding it) then you still need to re-call cogl_vertex_buffer_submit() to
+ * re-adding it) then you still need to re-call cogl_vertex_buffer_submit()
- * commit the changes to the GPU. (Be carefull to minimize the number of calls
+ * to commit the changes to the GPU. Be carefull to minimize the number
- * to cogl_vertex_buffer_submit though.)
+ * of calls to cogl_vertex_buffer_submit(), though.
  *
- * Note: If you are interleving attributes it is assumed that each interleaved
+ * <note>If you are interleving attributes it is assumed that each interleaved
  * attribute starts no farther than +- stride bytes from the other attributes
  * it is interleved with. I.e. this is ok:
  * <programlisting>
@@ -178,7 +178,7 @@ typedef enum _CoglAttributeType
  * <programlisting>
  * |- - - - -0-0-0-0-0-0 0 0 0 0|
  * </programlisting>
- * (Though you can have multiple groups of interleved attributes)
+ * (Though you can have multiple groups of interleved attributes)</note>
  */
 void
 cogl_vertex_buffer_add (CoglHandle         handle,
@@ -194,8 +194,8 @@ cogl_vertex_buffer_add (CoglHandle         handle,
  * @handle: A vertex buffer handle
  * @attribute_name: The name of a previously added attribute
  *
- * This function deletes an attribute from a buffer. You will need to
+ * Deletes an attribute from a buffer. You will need to call
- * call cogl_vertex_buffer_submit() or issue a draw call to commit this
+ * cogl_vertex_buffer_submit() or issue a draw call to commit this
  * change to the GPU.
  */
 void
@@ -206,8 +206,8 @@ cogl_vertex_buffer_delete (CoglHandle   handle,
  * cogl_vertex_buffer_submit:
  * @handle: A vertex buffer handle
  *
- * This function submits all the user added attributes to the GPU; once
+ * Submits all the user added attributes to the GPU; once submitted, the
- * submitted the attributes can be used for drawing.
+ * attributes can be used for drawing.
  *
  * You should aim to minimize calls to this function since it implies
  * validating your data; it potentially incurs a transport cost (especially if
@@ -222,13 +222,14 @@ cogl_vertex_buffer_submit (CoglHandle handle);
  * @handle: A vertex buffer handle
  * @attribute_name: The name of the attribute you want to disable
  *
- * This function disables a previosuly added attribute.
+ * Disables a previosuly added attribute.
  *
  * Since it can be costly to add and remove new attributes to buffers; to make
  * individual buffers more reuseable it is possible to enable and disable
  * attributes before using a buffer for drawing.
  *
- * You don't need to call cogl_vertex_buffer_submit() after using this function.
+ * You don't need to call cogl_vertex_buffer_submit() after using this
+ * function.
  */
 void
 cogl_vertex_buffer_disable (CoglHandle  handle,
@@ -239,7 +240,7 @@ cogl_vertex_buffer_disable (CoglHandle  handle,
  * @handle: A vertex buffer handle
  * @attribute_name: The name of the attribute you want to enable
  *
- * This function enables a previosuly disabled attribute.
+ * Enables a previosuly disabled attribute.
  *
  * Since it can be costly to add and remove new attributes to buffers; to make
  * individual buffers more reuseable it is possible to enable and disable
@@ -266,8 +267,7 @@ cogl_vertex_buffer_enable (CoglHandle  handle,
  *
  * Since: 1.0
  */
-typedef enum _CoglVerticesMode
+typedef enum {
-{
   COGL_VERTICES_MODE_POINTS = GL_POINTS,
   COGL_VERTICES_MODE_LINE_STRIP = GL_LINE_STRIP,
   COGL_VERTICES_MODE_LINE_LOOP = GL_LINE_LOOP,
@@ -285,7 +285,7 @@ typedef enum _CoglVerticesMode
  * @first: Specifies the index of the first vertex you want to draw with
  * @count: Specifies the number of vertices you want to draw.
  *
- * This function lets you draw geometry using all or a subset of the
+ * Allows you to draw geometry using all or a subset of the
  * vertices in a vertex buffer.
  *
  * Any un-submitted attribute changes are automatically submitted before
@@ -306,8 +306,7 @@ cogl_vertex_buffer_draw (CoglHandle       handle,
  * range, since it reduces the size of your index array and can help
  * reduce the demand on memory bandwidth.
  */
-typedef enum _CoglIndicesType
+typedef enum {
-{
   COGL_INDICES_TYPE_UNSIGNED_BYTE,
   COGL_INDICES_TYPE_UNSIGNED_SHORT,
 } CoglIndicesType;
@@ -316,7 +315,8 @@ typedef enum _CoglIndicesType
  * cogl_vertex_buffer_indices_new:
  * @indices_type: a #CoglIndicesType specifying the data type used for
  *    the indices.
- * @indices_array: Specifies the address of your array of indices
+ * @indices_array: (array length=indices_len): Specifies the address of
+ *   your array of indices
  * @indices_len: The number of indices in indices_array
  *
  * Depending on how much geometry you are submitting it can be worthwhile
@@ -324,7 +324,7 @@ typedef enum _CoglIndicesType
  * array allows you to reference vertices multiple times, for example
  * during triangle strips.
  *
- * Returns: A CoglHandle for the indices which you can pass to
+ * Return value: A CoglHandle for the indices which you can pass to
  *   cogl_vertex_buffer_draw_elements().
  */
 CoglHandle
@@ -372,13 +372,17 @@ cogl_vertex_buffer_draw_elements (CoglHandle       handle,
                                   int              indices_offset,
                                   int              count);
 
+#ifndef COGL_DISABLE_DEPRECATED
+
 /**
  * cogl_vertex_buffer_ref:
  * @handle: a @CoglHandle.
  *
  * Increment the reference count for a vertex buffer
  *
- * Returns: the @handle.
+ * Return value: the @handle.
+ *
+ * Deprecated: 1.2: Use cogl_handle_ref() instead
  */
 CoglHandle
 cogl_vertex_buffer_ref (CoglHandle handle);
@@ -388,10 +392,14 @@ cogl_vertex_buffer_ref (CoglHandle handle);
  * @handle: a @CoglHandle.
  *
  * Decrement the reference count for a vertex buffer
+ *
+ * Deprecated: 1.2: Use cogl_handle_unref() instead
  */
 void
 cogl_vertex_buffer_unref (CoglHandle handle);
 
+#endif /* COGL_DISABLE_DEPRECATED */
+
 /**
  * cogl_vertex_buffer_indices_get_for_quads:
  * @n_indices: the number of indices in the vertex buffer.

clutter/cogl/cogl/cogl.h

@@ -115,17 +115,17 @@ CoglFuncPtr     cogl_get_proc_address         (const gchar        *name);
  *
  * Check whether @name occurs in list of extensions in @ext.
  *
- * Returns: %TRUE if the extension occurs in the list, %FALSE otherwize.
+ * Return value: %TRUE if the extension occurs in the list, %FALSE otherwize.
  */
 gboolean        cogl_check_extension          (const gchar        *name,
                                                const gchar        *ext);
 
 /**
  * cogl_get_bitmasks:
- * @red: Return location for the number of red bits or %NULL
+ * @red: (out): Return location for the number of red bits or %NULL
- * @green: Return location for the number of green bits or %NULL
+ * @green: (out): Return location for the number of green bits or %NULL
- * @blue: Return location for the number of blue bits or %NULL
+ * @blue: (out): Return location for the number of blue bits or %NULL
- * @alpha: Return location for the number of alpha bits or %NULL
+ * @alpha: (out): Return location for the number of alpha bits or %NULL
  *
  * Gets the number of bitplanes used for each of the color components
  * in the color buffer. Pass %NULL for any of the arguments if the
@@ -240,12 +240,12 @@ void            cogl_viewport                 (guint               width,
 
 /**
  * cogl_set_viewport:
- * @x: viewport X offset
+ * @x: X offset of the viewport
- * @x: viewport Y offset
+ * @y: Y offset of the viewport
  * @width: Width of the viewport
  * @height: Height of the viewport
  *
- * Replace the current viewport with the given values.
+ * Replaces the current viewport with the given values.
  *
  * Since: 1.2
  */
@@ -257,7 +257,7 @@ void            cogl_set_viewport             (int x,
 /**
  * cogl_push_matrix:
  *
- * Store the current model-view matrix on the matrix stack. The matrix
+ * Stores the current model-view matrix on the matrix stack. The matrix
  * can later be restored with cogl_pop_matrix().
  */
 void            cogl_push_matrix              (void);
@@ -265,7 +265,7 @@ void            cogl_push_matrix              (void);
 /**
  * cogl_pop_matrix:
  *
- * Restore the current model-view matrix from the matrix stack.
+ * Restores the current model-view matrix from the matrix stack.
  */
 void            cogl_pop_matrix               (void);
 
@@ -315,7 +315,7 @@ void            cogl_rotate                   (float                angle,
 
 /**
  * cogl_get_modelview_matrix:
- * @matrix: pointer to a CoglMatrix to recieve the matrix
+ * @matrix: (out): return location for the model-view matrix
  *
  * Stores the current model-view matrix in @matrix.
  */
@@ -323,15 +323,15 @@ void            cogl_get_modelview_matrix     (CoglMatrix *matrix);
 
 /**
  * cogl_set_modelview_matrix:
- * @matrix: pointer to a CoglMatrix to set as the new model-view matrix
+ * @matrix: the new model-view matrix
  *
- * Loads matrix as the new model-view matrix.
+ * Loads @matrix as the new model-view matrix.
  */
 void            cogl_set_modelview_matrix     (CoglMatrix *matrix);
 
 /**
  * cogl_get_projection_matrix:
- * @matrix: pointer to a CoglMatrix to recieve the matrix
+ * @matrix: (out): return location for the projection matrix
  *
  * Stores the current projection matrix in @matrix.
  */
@@ -339,7 +339,7 @@ void            cogl_get_projection_matrix    (CoglMatrix *matrix);
 
 /**
  * cogl_set_projection_matrix:
- * @matrix: pointer to a CoglMatrix to set as the new projection matrix
+ * @matrix: the new projection matrix
  *
  * Loads matrix as the new projection matrix.
  */
@@ -347,8 +347,8 @@ void            cogl_set_projection_matrix    (CoglMatrix *matrix);
 
 /**
  * cogl_get_viewport:
- * @v: pointer to a 4 element array of #float<!-- -->s to
+ * @v: (out) (array fixed-size=4): pointer to a 4 element array
- * receive the viewport dimensions.
+ *   of #float<!-- -->s to receive the viewport dimensions.
  *
  * Stores the current viewport in @v. @v[0] and @v[1] get the x and y
  * position of the viewport and @v[2] and @v[3] get the width and
@@ -373,7 +373,7 @@ void            cogl_set_depth_test_enabled   (gboolean setting);
  *
  * Queries if depth testing has been enabled via cogl_set_depth_test_enable()
  *
- * Returns: %TRUE if depth testing is enabled, and %FALSE otherwise
+ * Return value: %TRUE if depth testing is enabled, and %FALSE otherwise
  */
 gboolean        cogl_get_depth_test_enabled   (void);
 
@@ -395,19 +395,19 @@ void            cogl_set_backface_culling_enabled (gboolean setting);
  * Queries if backface culling has been enabled via
  * cogl_set_backface_culling_enabled()
  *
- * Returns: %TRUE if backface culling is enabled, and %FALSE otherwise
+ * Return value: %TRUE if backface culling is enabled, and %FALSE otherwise
  */
 gboolean        cogl_get_backface_culling_enabled (void);
 
 /**
  * cogl_set_fog:
  * @fog_color: The color of the fog
- * @mode: A CoglFogMode that determines the equation used to calculate the
+ * @mode: A #CoglFogMode that determines the equation used to calculate the
  *   fogging blend factor.
- * @density: Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode
+ * @density: Used by %COGL_FOG_MODE_EXPONENTIAL and by
- *           equations.
+ *   %COGL_FOG_MODE_EXPONENTIAL_SQUARED equations.
- * @z_near: Position along z-axis where no fogging should be applied
+ * @z_near: Position along Z axis where no fogging should be applied
- * @z_far: Position along z-axes where full fogging should be applied
+ * @z_far: Position along Z axis where full fogging should be applied
  *
  * Enables fogging. Fogging causes vertices that are further away from the eye
  * to be rendered with a different color. The color is determined according to
@@ -468,14 +468,14 @@ void            cogl_clear                    (const CoglColor *color,
 
 /**
  * cogl_set_source:
- * @material: A CoglMaterial object
+ * @material: A #CoglHandle for a material
  *
  * This function sets the source material that will be used to fill subsequent
  * geometry emitted via the cogl API.
  *
- * Note: in the future we may add the ability to set a front facing material,
+ * <note>In the future we may add the ability to set a front facing material,
  * and a back facing material, in which case this function will set both to the
- * same.
+ * same.</note>
  *
  * Since: 1.0
  */
@@ -867,17 +867,20 @@ void            cogl_flush (void);
  * Note: this doesn't help you modify the behaviour of Cogl drawing functions
  * through the modification of GL state; that will never be reliably supported,
  * but if you are trying to do something like:
- * <programlisting>
+ *
+ * |[
  * {
  *    - setup some OpenGL state.
  *    - draw using OpenGL (e.g. glDrawArrays() )
  *    - reset modified OpenGL state.
  *    - continue using Cogl to draw
  * }
- * </programlisting>
+ * ]|
+ *
  * You should surround blocks of drawing using raw GL with cogl_begin_gl()
  * and cogl_end_gl():
- * <programlisting>
+ *
+ * |[
  * {
  *    cogl_begin_gl ();
  *    - setup some OpenGL state.
@@ -886,16 +889,18 @@ void            cogl_flush (void);
  *    cogl_end_gl ();
  *    - continue using Cogl to draw
  * }
- * </programlisting>
+ * ]|
  *
  * Don't ever try and do:
- * <programlisting>
+ *
+ * |[
  * {
  *    - setup some OpenGL state.
  *    - use Cogl to draw
  *    - reset modified OpenGL state.
  * }
- * </programlisting>
+ * ]|
+ *
  * When the internals of Cogl evolves, this is very liable to break.
  *
  * This function will flush all batched primitives, and subsequently flush
@@ -907,16 +912,16 @@ void            cogl_flush (void);
  * state such as backface culling, depth and fogging enabledness will be sent
  * to OpenGL.
  *
- * Note: no special material state is flushed, so if you want Cogl to setup a
+ * <note>No special material state is flushed, so if you want Cogl to setup a
  * simplified material state it is your responsibility to set a simple source
- * material before calling cogl_begin_gl. E.g. by calling
+ * material before calling cogl_begin_gl(). E.g. by calling
- * cogl_set_source_color4ub().
+ * cogl_set_source_color4ub().</note>
  *
- * Note: It is your responsibility to restore any OpenGL state that you modify
+ * <note>It is your responsibility to restore any OpenGL state that you modify
  * to how it was after calling cogl_begin_gl() if you don't do this then the
- * result of further Cogl calls is undefined.
+ * result of further Cogl calls is undefined.</note>
  *
- * Note: You can not nest begin/end blocks.
+ * <note>You can not nest begin/end blocks.</note>
  *
  * Again we would like to stress, we do not advise the use of this API and if
  * possible we would prefer to improve Cogl than have developers require raw
@@ -951,6 +956,7 @@ void            _cogl_destroy_context          (void);
  * wasn't complete, and so we assume no one is using this yet. Util we
  * have some one with a good usecase, we can't pretend to support breaking
  * out into raw OpenGL. */
+
 #if 0
 /*
  * cogl_flush_gl_state:
@@ -968,7 +974,7 @@ void            _cogl_destroy_context          (void);
 void            cogl_flush_gl_state         (int      flags);
 #endif
 
-/* private */
+/*< private >*/
 #define COGL_DRIVER_ERROR (_cogl_driver_error_quark ())
 
 typedef enum { /*< prefix=COGL_DRIVER_ERROR >*/