diff --git a/cogl/cogl.h b/cogl/cogl.h
index 4b61d35da..2121851e0 100644
--- a/cogl/cogl.h
+++ b/cogl/cogl.h
@@ -914,10 +914,10 @@ cogl_set_framebuffer (CoglHandle buffer);
  *
  * You should understand that a framebuffer owns the following state:
  * <itemizedlist>
- *  <li>The projection matrix</li>
- *  <li>The modelview matrix stack</li>
- *  <li>The viewport</li>
- *  <li>The clip stack</li>
+ *  <listitem><simpara>The projection matrix</simpara></listitem>
+ *  <listitem><simpara>The modelview matrix stack</simpara></listitem>
+ *  <listitem><simpara>The viewport</simpara></listitem>
+ *  <listitem><simpara>The clip stack</simpara></listitem>
  * </itemizedlist>
  * So these items will automatically be saved and restored when you
  * push and pop between different framebuffers.
@@ -948,34 +948,33 @@ cogl_set_framebuffer (CoglHandle buffer);
  *   cogl_set_viewport (0, 0, width, height);
  *   cogl_perspective (fovy, aspect, z_near, z_far);
  *
- *   cogl_get_projection_matrix (&projection_matrix);
+ *   cogl_get_projection_matrix (&amp;projection_matrix);
  *   z_camera = 0.5 * projection_matrix.xx;
  *
- *   cogl_matrix_init_identity (&mv_matrix);
- *   cogl_matrix_translate (&mv_matrix, -0.5f, -0.5f, -z_camera);
- *   cogl_matrix_scale (&mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
- *   cogl_matrix_translate (&mv_matrix, 0.0f, -1.0 * height, 0.0f);
- *   cogl_set_modelview_matrix (&mv_matrix);
+ *   cogl_matrix_init_identity (&amp;mv_matrix);
+ *   cogl_matrix_translate (&amp;mv_matrix, -0.5f, -0.5f, -z_camera);
+ *   cogl_matrix_scale (&amp;mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
+ *   cogl_matrix_translate (&amp;mv_matrix, 0.0f, -1.0 * height, 0.0f);
+ *   cogl_set_modelview_matrix (&amp;mv_matrix);
  * }
  *
  * static void
- * my_init_framebuffer (CoglHandle framebuffer,
+ * my_init_framebuffer (ClutterStage *stage,
+ *                      CoglHandle framebuffer,
  *                      unsigned int framebuffer_width,
  *                      unsigned int framebuffer_height)
  * {
- *   ClutterActor *stage = clutter_stage_get_default ();
  *   ClutterPerspective perspective;
  *
- *   clutter_stage_get_perspective (CLUTTER_STAGE (stage), &perspective);
+ *   clutter_stage_get_perspective (stage, &perspective);
  *
  *   cogl_push_framebuffer (framebuffer);
  *   setup_viewport (framebuffer_width,
  *                   framebuffer_height,
- *                   perspective->fovy,
+ *                   perspective.fovy,
  *                   perspective.aspect,
  *                   perspective.z_near,
  *                   perspective.z_far);
- *   cogl_pop_framebuffer ();
  * }
  * ]|
  *