diff --git a/cogl/cogl-matrix.h b/cogl/cogl-matrix.h
index 78a653193..11e133383 100644
--- a/cogl/cogl-matrix.h
+++ b/cogl/cogl-matrix.h
@@ -252,12 +252,16 @@ cogl_matrix_look_at (CoglMatrix *matrix,
 /**
  * cogl_matrix_frustum:
  * @matrix: A 4x4 transformation matrix
- * @left: coord of left vertical clipping plane
- * @right: coord of right vertical clipping plane
- * @bottom: coord of bottom horizontal clipping plane
- * @top: coord of top horizontal clipping plane
- * @z_near: positive distance to near depth clipping plane
- * @z_far: positive distance to far depth clipping plane
+ * @left: X position of the left clipping plane where it
+ *   intersects the near clipping plane
+ * @right: X position of the right clipping plane where it
+ *   intersects the near clipping plane
+ * @bottom: Y position of the bottom clipping plane where it
+ *   intersects the near clipping plane
+ * @top: Y position of the top clipping plane where it intersects
+ *   the near clipping plane
+ * @z_near: The distance to the near clipping plane (Must be positive)
+ * @z_far: The distance to the far clipping plane (Must be positive)
  *
  * Multiplies @matrix by the given frustum perspective matrix.
  */
@@ -273,19 +277,18 @@ cogl_matrix_frustum (CoglMatrix *matrix,
 /**
  * cogl_matrix_perspective:
  * @matrix: A 4x4 transformation matrix
- * @fov_y: A field of view angle for the Y axis
- * @aspect: The ratio of width to height determining the field of view angle
- *   for the x axis.
- * @z_near: The distance to the near clip plane. Never pass 0 and always pass
- *   a positive number.
- * @z_far: The distance to the far clip plane. (Should always be positive)
+ * @fovy: Vertical field of view angle in degrees.
+ * @aspect: The (width over height) aspect ratio for display
+ * @z_near: The distance to the near clipping plane (Must be positive,
+ *   and must not be 0)
+ * @z_far: The distance to the far clipping plane (Must be positive)
  *
  * Multiplies @matrix by the described perspective matrix
  *
- * <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.</note>
+ * <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.</note>
  */
 void
 cogl_matrix_perspective (CoglMatrix *matrix,
@@ -331,10 +334,12 @@ cogl_matrix_orthographic (CoglMatrix *matrix,
  * @right: The coordinate for the right clipping plane
  * @bottom: The coordinate for the bottom clipping plane
  * @top: The coordinate for the top clipping plane
- * @z_near: The coordinate for the near clipping plane (may be negative if
- *   the plane is behind the viewer)
- * @z_far: The coordinate for the far clipping plane (may be negative if
- *   the plane is behind the viewer)
+ * @near: The <emphasis>distance</emphasis> to the near clipping
+ *   plane (will be <emphasis>negative</emphasis> if the plane is
+ *   behind the viewer)
+ * @far: The <emphasis>distance</emphasis> to the far clipping
+ *   plane (will be <emphasis>negative</emphasis> if the plane is
+ *   behind the viewer)
  *
  * Multiplies @matrix by a parallel projection matrix.
  *
@@ -346,8 +351,8 @@ cogl_matrix_ortho (CoglMatrix *matrix,
                    float       right,
                    float       bottom,
                    float       top,
-                   float       z_near,
-                   float       z_far);
+                   float       near,
+                   float       far);
 
 #ifdef COGL_ENABLE_EXPERIMENTAL_API
 #define cogl_matrix_view_2d_in_frustum cogl_matrix_view_2d_in_frustum_EXP