diff --git a/cogl/cogl-bitmap.h b/cogl/cogl-bitmap.h
index 2919b869b..4d3eec376 100644
--- a/cogl/cogl-bitmap.h
+++ b/cogl/cogl-bitmap.h
@@ -132,7 +132,7 @@ cogl_bitmap_new_from_buffer (CoglBuffer *buffer,
  *
  * The data for the bitmap will be stored in a newly created
  * #CoglPixelBuffer. You can get a pointer to the pixel buffer using
- * cogl_bitmap_get_pixel_buffer(). The #CoglBuffer API can then be
+ * cogl_bitmap_get_buffer(). The #CoglBuffer API can then be
  * used to fill the bitmap with data.
  *
  * <note>Cogl will try its best to provide a hardware array you can
diff --git a/cogl/cogl-buffer.h b/cogl/cogl-buffer.h
index 8db42a72f..c862c725d 100644
--- a/cogl/cogl-buffer.h
+++ b/cogl/cogl-buffer.h
@@ -250,7 +250,7 @@ cogl_buffer_map (CoglBuffer *buffer,
  * used by the GPU then the driver won't have to stall the CPU and
  * wait for the hardware to finish because it can instead allocate a
  * new buffer to map. You can pass
- * %COGL_BUFFER_MAP_HINT_DISCARD_REGION instead if you want the
+ * %COGL_BUFFER_MAP_HINT_DISCARD_RANGE instead if you want the
  * regions outside of the mapping to be retained.
  *
  * The behaviour is undefined if you access the buffer in a way
diff --git a/cogl/cogl-color.h b/cogl/cogl-color.h
index 513c5d36a..438fed24f 100644
--- a/cogl/cogl-color.h
+++ b/cogl/cogl-color.h
@@ -122,10 +122,10 @@ cogl_color_set_from_4ub (CoglColor *color,
 /**
  * cogl_color_init_from_4f:
  * @color: A pointer to a #CoglColor to initialize
- * @red: value of the red channel, between 0 and %1.0
- * @green: value of the green channel, between 0 and %1.0
- * @blue: value of the blue channel, between 0 and %1.0
- * @alpha: value of the alpha channel, between 0 and %1.0
+ * @red: value of the red channel, between 0 and 1.0
+ * @green: value of the green channel, between 0 and 1.0
+ * @blue: value of the blue channel, between 0 and 1.0
+ * @alpha: value of the alpha channel, between 0 and 1.0
  *
  * Sets the values of the passed channels into a #CoglColor
  *
@@ -288,7 +288,7 @@ cogl_color_get_alpha_float (const CoglColor *color);
  * @color: a #CoglColor
  *
  * Retrieves the red channel of @color as a fixed point
- * value between 0 and %1.0.
+ * value between 0 and 1.0.
  *
  * Return value: the red channel of the passed color
  *
@@ -302,7 +302,7 @@ cogl_color_get_red (const CoglColor *color);
  * @color: a #CoglColor
  *
  * Retrieves the green channel of @color as a fixed point
- * value between 0 and %1.0.
+ * value between 0 and 1.0.
  *
  * Return value: the green channel of the passed color
  *
@@ -316,7 +316,7 @@ cogl_color_get_green (const CoglColor *color);
  * @color: a #CoglColor
  *
  * Retrieves the blue channel of @color as a fixed point
- * value between 0 and %1.0.
+ * value between 0 and 1.0.
  *
  * Return value: the blue channel of the passed color
  *
@@ -330,7 +330,7 @@ cogl_color_get_blue (const CoglColor *color);
  * @color: a #CoglColor
  *
  * Retrieves the alpha channel of @color as a fixed point
- * value between 0 and %1.0.
+ * value between 0 and 1.0.
  *
  * Return value: the alpha channel of the passed color
  *
diff --git a/cogl/cogl-context.h b/cogl/cogl-context.h
index 639fae530..3356440fb 100644
--- a/cogl/cogl-context.h
+++ b/cogl/cogl-context.h
@@ -169,11 +169,11 @@ cogl_is_context (void *object);
  *     %COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and %COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT
  *     features to know if the hardware supports npot texture mipmaps
  *     or repeat modes other than
- *     %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively.
+ *     %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively.
  * @COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP: Mipmapping is supported in
  *     conjuntion with non power of two textures.
  * @COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT: Repeat modes other than
- *     %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the
+ *     %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the
  *     hardware.
  * @COGL_FEATURE_ID_TEXTURE_NPOT: Non power of two textures are supported
  *    by the hardware. This is a equivalent to the
@@ -190,7 +190,7 @@ cogl_is_context (void *object);
  * @COGL_FEATURE_ID_GLSL: GLSL support
  * @COGL_FEATURE_ID_ARBFP: ARBFP support
  * @COGL_FEATURE_ID_UNSIGNED_INT_INDICES: Set if
- *     %COGL_RENDERER_INDICES_TYPE_UNSIGNED_INT is supported in
+ *     %COGL_INDICES_TYPE_UNSIGNED_INT is supported in
  *     cogl_indices_new().
  * @COGL_FEATURE_ID_DEPTH_RANGE: cogl_pipeline_set_depth_range() support
  * @COGL_FEATURE_ID_POINT_SPRITE: Whether
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index cd0bd28e8..e3b7602c8 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -184,7 +184,7 @@ cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer,
  * @framebuffer: A #CoglFramebuffer
  *
  * Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
- * or the default value which is %0.
+ * or the default value which is 0.
  *
  * Return value: The x coordinate of the viewport origin.
  * Since: 1.8
@@ -198,7 +198,7 @@ cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer);
  * @framebuffer: A #CoglFramebuffer
  *
  * Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
- * or the default value which is %0.
+ * or the default value which is 0.
  *
  * Return value: The y coordinate of the viewport origin.
  * Since: 1.8
@@ -654,7 +654,8 @@ cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer,
  * @framebuffer: A #CoglFramebuffer pointer
  *
  * Reverts the clipping region to the state before the last call to
- * cogl_framebuffer_push_clip().
+ * cogl_framebuffer_push_scissor_clip(), cogl_framebuffer_push_rectangle_clip()
+ * cogl_framebuffer_push_path_clip(), or cogl_framebuffer_push_primitive_clip().
  *
  * Since: 1.10
  * Stability: unstable
@@ -1386,7 +1387,7 @@ cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
  * The given texture coordinates should always be normalized such that
  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
  * bottom right. To map an entire texture across the rectangle pass
- * in @s_1=%0, @t_1=%0, @s_2=%1, @t_2=%1.
+ * in @s_1=0, @t_1=0, @s_2=1, @t_2=1.
  *
  * <note>Even if you have associated a #CoglTextureRectangle texture
  * with one of your @pipeline layers which normally implies working
@@ -1460,8 +1461,8 @@ cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
  * The given texture coordinates should always be normalized such that
  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
  * bottom right. To map an entire texture across the rectangle pass
- * in tex_coords[0]=%0, tex_coords[1]=%0, tex_coords[2]=%1,
- * tex_coords[3]=%1.
+ * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1,
+ * tex_coords[3]=1.
  *
  * <note>Even if you have associated a #CoglTextureRectangle texture
  * which normally implies working with non-normalized texture
@@ -1570,8 +1571,8 @@ cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
  * The given texture coordinates should always be normalized such that
  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
  * bottom right. To map an entire texture across the rectangle pass
- * in tex_coords[0]=%0, tex_coords[1]=%0, tex_coords[2]=%1,
- * tex_coords[3]=%1.
+ * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1,
+ * tex_coords[3]=1.
  *
  * <note>Even if you have associated a #CoglTextureRectangle texture
  * which normally implies working with non-normalized texture
diff --git a/cogl/cogl-meta-texture.h b/cogl/cogl-meta-texture.h
index 28ec97905..8d838c634 100644
--- a/cogl/cogl-meta-texture.h
+++ b/cogl/cogl-meta-texture.h
@@ -66,17 +66,18 @@ COGL_BEGIN_DECLS
  * Cogl doesn't aim to pretend that meta-textures are just like real
  * textures because it would get extremely complex to try and emulate
  * low-level GPU semantics transparently for these textures.  The low
- * level drawing APIs of Cogl, such as cogl_draw_attributes() don't
- * actually know anything about the #CoglMetaTexture interface and its
- * the developer's responsibility to resolve all textures referenced by
- * a #CoglPipeline to low-level textures before drawing.
+ * level drawing APIs of Cogl, such as cogl_framebuffer_draw_attributes()
+ * don't actually know anything about the #CoglMetaTexture interface and its
+ * the developer's responsibility to resolve all textures referenced by a
+ * #CoglPipeline to low-level textures before drawing.
  *
- * If you want to develop custom primitive APIs like cogl_rectangle()
- * and you want to support drawing with #CoglAtlasTexture<!-- -->s
- * or #CoglSubTexture<!-- -->s for example, then you will need to use
- * this #CoglMetaTexture interface to be able to resolve high-level
- * textures into low-level textures before drawing with Cogl's
- * low-level drawing APIs such as cogl_draw_attributes().
+ * If you want to develop custom primitive APIs like
+ * cogl_framebuffer_draw_rectangle() and you want to support drawing
+ * with #CoglAtlasTexture<!-- -->s or #CoglSubTexture<!-- -->s for
+ * example, then you will need to use this #CoglMetaTexture interface
+ * to be able to resolve high-level textures into low-level textures
+ * before drawing with Cogl's low-level drawing APIs such as
+ * cogl_framebuffer_draw_attributes().
  *
  * <note>Most developers won't need to use this interface directly
  * but still it is worth understanding the distinction between
@@ -152,7 +153,7 @@ typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
  * internally use this API to resolve the low level textures of any
  * meta textures you have associated with CoglPipeline layers.
  *
- * <note>The low level drawing APIs such as cogl_draw_attributes()
+ * <note>The low level drawing APIs such as cogl_framebuffer_draw_attributes()
  * don't understand the #CoglMetaTexture interface and so it is your
  * responsibility to use this API to resolve all CoglPipeline
  * textures into low-level textures before drawing.</note>
diff --git a/cogl/cogl-onscreen.h b/cogl/cogl-onscreen.h
index 9b86de53b..726052eb9 100644
--- a/cogl/cogl-onscreen.h
+++ b/cogl/cogl-onscreen.h
@@ -228,7 +228,7 @@ cogl_wayland_onscreen_resize (CoglOnscreen *onscreen,
  * @throttled: Whether swap throttling is wanted or not.
  *
  * Requests that the given @onscreen framebuffer should have swap buffer
- * requests (made using cogl_framebuffer_swap_buffers()) throttled either by a
+ * requests (made using cogl_onscreen_swap_buffers()) throttled either by a
  * displays vblank period or perhaps some other mechanism in a composited
  * environment.
  *
@@ -319,7 +319,7 @@ cogl_onscreen_swap_buffers (CoglOnscreen *onscreen);
  * defined by 4 sequential (x, y, width, height) integers.
  *
  * This function also implicitly discards the contents of the color, depth and
- * stencil buffers as if cogl_onscreen_discard_buffers() were used. The
+ * stencil buffers as if cogl_framebuffer_discard_buffers() were used. The
  * significance of the discard is that you should not expect to be able to
  * start a new frame that incrementally builds on the contents of the previous
  * frame.
diff --git a/cogl/cogl-path.h b/cogl/cogl-path.h
index 740c0a3ba..e69466e2c 100644
--- a/cogl/cogl-path.h
+++ b/cogl/cogl-path.h
@@ -75,10 +75,7 @@ typedef struct _CoglPath CoglPath;
  * as if there was an extra line joining the first point and the last
  * point.
  *
- * The default fill rule is %COGL_PATH_FILL_RULE_EVEN_ODD. The fill
- * rule is attached to the current path so preserving a path with
- * cogl_get_path() also preserves the fill rule. Calling
- * cogl_path_new() resets the current fill rule to the default.
+ * The default fill rule when creating a path is %COGL_PATH_FILL_RULE_EVEN_ODD.
  *
  * <figure id="fill-rule-non-zero">
  *   <title>Example of filling various paths using the non-zero rule</title>
diff --git a/cogl/cogl-pipeline-layer-state.h b/cogl/cogl-pipeline-layer-state.h
index 2cee23154..6437ee00b 100644
--- a/cogl/cogl-pipeline-layer-state.h
+++ b/cogl/cogl-pipeline-layer-state.h
@@ -255,7 +255,7 @@ cogl_pipeline_remove_layer (CoglPipeline *pipeline,
  *   <varlistentry>
  *     <term>CONSTANT</term>
  *     <listitem>Use the color from the constant given with
- *     cogl_pipeline_set_layer_constant()</listitem>
+ *     cogl_pipeline_set_layer_combine_constant()</listitem>
  *   </varlistentry>
  *   <varlistentry>
  *     <term>PRIMARY</term>
@@ -278,7 +278,8 @@ cogl_pipeline_remove_layer (CoglPipeline *pipeline,
  *   </programlisting></informalexample>
  *   <para>This could be used to cross-fade between two images, using
  *   the alpha component of a constant as the interpolator. The constant
- *   color is given by calling cogl_pipeline_set_layer_constant.</para>
+ *   color is given by calling
+ *   cogl_pipeline_set_layer_combine_constant().</para>
  *   <informalexample><programlisting>
  *   RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
  *   </programlisting></informalexample>
@@ -429,7 +430,7 @@ cogl_pipeline_get_layer_mag_filter (CoglPipeline *pipeline,
  * have 1.0,1.0. If @enable is %FALSE then the coordinates will be
  * fixed for the entire point.
  *
- * This function will only work if %COGL_FEATURE_POINT_SPRITE is
+ * This function will only work if %COGL_FEATURE_ID_POINT_SPRITE is
  * available. If the feature is not available then the function will
  * return %FALSE and set @error.
  *
diff --git a/cogl/cogl-primitive.h b/cogl/cogl-primitive.h
index e4a564b4b..f1f44985c 100644
--- a/cogl/cogl-primitive.h
+++ b/cogl/cogl-primitive.h
@@ -55,7 +55,7 @@ COGL_BEGIN_DECLS
  * @y: The y component of a position attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v2_attributes().
+ * cogl_primitive_new_p2().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -71,7 +71,7 @@ typedef struct {
  * @z: The z component of a position attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v3_attributes().
+ * cogl_primitive_new_p3().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -90,7 +90,7 @@ typedef struct {
  * @a: The alpha component of a color attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v2c4_attributes().
+ * cogl_primitive_new_p2c4().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -111,7 +111,7 @@ typedef struct {
  * @a: The alpha component of a color attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v3c4_attributes().
+ * cogl_primitive_new_p3c4().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -129,7 +129,7 @@ typedef struct {
  * @t: The t component of a texture coordinate attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v2t2_attributes().
+ * cogl_primitive_new_p2t2().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -148,7 +148,7 @@ typedef struct {
  * @t: The t component of a texture coordinate attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v3t2_attributes().
+ * cogl_primitive_new_p3t2().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -171,7 +171,7 @@ typedef struct {
  * @a: The alpha component of a color attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v3t2c4_attributes().
+ * cogl_primitive_new_p3t2c4().
  *
  * Since: 1.6
  * Stability: Unstable
@@ -195,7 +195,7 @@ typedef struct {
  * @a: The alpha component of a color attribute
  *
  * A convenience vertex definition that can be used with
- * cogl_primitive_new_with_v3t2c4_attributes().
+ * cogl_primitive_new_p3t2c4().
  *
  * Since: 1.6
  * Stability: Unstable
diff --git a/cogl/cogl-renderer.h b/cogl/cogl-renderer.h
index 923950a4a..c7933250d 100644
--- a/cogl/cogl-renderer.h
+++ b/cogl/cogl-renderer.h
@@ -103,7 +103,7 @@ cogl_is_renderer (void *object);
  *
  * While the renderer is unconnected it can be configured so that
  * applications may specify backend constraints, such as "must use
- * x11" for example via cogl_renderer_add_criteria().
+ * x11" for example via cogl_renderer_add_constraint().
  *
  * There are also some platform specific configuration apis such
  * as cogl_xlib_renderer_set_foreign_display() that may also be
diff --git a/cogl/cogl-texture-3d.h b/cogl/cogl-texture-3d.h
index daf79b15c..c2700efa4 100644
--- a/cogl/cogl-texture-3d.h
+++ b/cogl/cogl-texture-3d.h
@@ -61,7 +61,7 @@ typedef struct _CoglTexture3D CoglTexture3D;
  * pixel format.
  *
  * Note that this function will throw a #CoglError if
- * %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
+ * %COGL_FEATURE_ID_TEXTURE_3D is not advertised. It can also fail if the
  * requested dimensions are not supported by the GPU.
  *
  * Return value: a new #CoglTexture3D object or
@@ -108,7 +108,7 @@ cogl_texture_3d_new_with_size (CoglContext *context,
  * between the images using @image_stride.
  *
  * Note that this function will throw a #CoglError if
- * %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
+ * %COGL_FEATURE_ID_TEXTURE_3D is not advertised. It can also fail if the
  * requested dimensions are not supported by the GPU.
  *
  * Return value: the newly created #CoglTexture3D or %NULL if
diff --git a/cogl/cogl-types.h b/cogl/cogl-types.h
index fa1f1f9b2..78640e597 100644
--- a/cogl/cogl-types.h
+++ b/cogl/cogl-types.h
@@ -687,7 +687,7 @@ typedef enum {
  * reduce the demand on memory bandwidth.
  *
  * Note that %COGL_INDICES_TYPE_UNSIGNED_INT is only supported if the
- * %COGL_FEATURE_UNSIGNED_INT_INDICES feature is available. This
+ * %COGL_FEATURE_ID_UNSIGNED_INT_INDICES feature is available. This
  * should always be available on OpenGL but on OpenGL ES it will only
  * be available if the GL_OES_element_index_uint extension is
  * advertized.
@@ -782,7 +782,7 @@ typedef enum { /*< prefix=COGL_RENDERER_ERROR >*/
  *                        processing
  * @COGL_FILTER_REMOVE: Remove the event, stops the processing
  *
- * Return values for the #CoglFilterFunc function.
+ * Return values for the #CoglXlibFilterFunc and #CoglWin32FilterFunc functions.
  *
  * Stability: Unstable
  */
@@ -893,7 +893,7 @@ typedef enum {
  * CoglReadPixelsFlags:
  * @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer
  *
- * Flags for cogl_read_pixels()
+ * Flags for cogl_framebuffer_read_pixels_into_bitmap()
  *
  * Since: 1.0
  */
diff --git a/cogl/cogl-vector.h b/cogl/cogl-vector.h
index 81ff4736d..fb1c34a33 100644
--- a/cogl/cogl-vector.h
+++ b/cogl/cogl-vector.h
@@ -142,7 +142,7 @@ cogl_vector3_copy (const float *vector);
  * @vector: The 3 component you want to free
  *
  * Frees a 3 component vector that was previously allocated with
- * cogl_vector_copy()
+ * cogl_vector3_copy()
  *
  * Since: 1.4
  * Stability: Unstable
diff --git a/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt b/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
index 85f5275cf..b0796e099 100644
--- a/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
+++ b/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
@@ -42,6 +42,9 @@ CoglBufferBit
 CoglAttributeType
 CoglColorMask
 
+<SUBSECTION>
+CoglTextureFlags
+
 <SUBSECTION>
 CoglBool
 </SECTION>
@@ -58,6 +61,14 @@ cogl_renderer_new
 cogl_renderer_get_n_fragment_texture_units
 cogl_renderer_connect
 
+<SUBSECTION>
+CoglWinsysID
+cogl_renderer_set_winsys_id
+cogl_renderer_get_winsys_id
+CoglRendererConstraint
+cogl_renderer_add_constraint
+cogl_renderer_remove_constraint
+
 <SUBSECTION>
 cogl_xlib_renderer_set_foreign_display
 cogl_xlib_renderer_get_foreign_display
@@ -80,6 +91,8 @@ cogl_wayland_renderer_set_foreign_display
 cogl_wayland_renderer_get_display
 cogl_wayland_renderer_set_foreign_compositor
 cogl_wayland_renderer_get_compositor
+cogl_wayland_renderer_set_foreign_shell
+cogl_wayland_renderer_get_shell
 </SECTION>
 
 <SECTION>
@@ -255,6 +268,8 @@ cogl_is_indices
 CoglIndicesType
 cogl_indices_new
 
+<SUBSECTION>
+cogl_get_rectangle_indices
 </SECTION>
 
 <SECTION>
@@ -370,6 +385,9 @@ cogl_bitmap_get_rowstride
 cogl_bitmap_get_buffer
 cogl_bitmap_get_size_from_file
 
+<SUBSECTION>
+cogl_texture_new_from_bitmap
+
 <SUBSECTION>
 COGL_BITMAP_ERROR
 CoglBitmapError
@@ -521,6 +539,7 @@ cogl_framebuffer_stroke_path
 cogl_framebuffer_fill_path
 
 <SUBSECTION>
+cogl_framebuffer_discard_buffers
 cogl_framebuffer_finish
 
 <SUBSECTION>
@@ -546,6 +565,7 @@ cogl_framebuffer_set_projection_matrix
 <SUBSECTION>
 cogl_framebuffer_push_scissor_clip
 cogl_framebuffer_push_rectangle_clip
+cogl_framebuffer_push_path_clip
 cogl_framebuffer_push_primitive_clip
 cogl_framebuffer_pop_clip