diff --git a/cogl.h.in b/cogl.h.in
index dc8046038..e26e6eb75 100644
--- a/cogl.h.in
+++ b/cogl.h.in
@@ -910,6 +910,30 @@ cogl_texture_polygon (CoglHandle         handle,
 
 /* Primitives API */
 
+/**
+ * SECTION:cogl-primitives
+ * @short_description: Functions that draw various primitive shapes and
+ * allow for construction of more complex paths.
+ *
+ * There are three levels on which drawing with cogl can be used. The
+ * highest level functions construct various simple primitive shapes
+ * to be either filled or stroked. Using a lower-level set of functions
+ * more complex and arbitrary paths can be constructed by concatenating
+ * straight line, bezier curve and arc segments. Additionally there
+ * are utility functions that draw the most common primitives - rectangles
+ * and trapezoids - in a maximaly optimized fashion.
+ *
+ * When constructing arbitrary paths, the current pen location is
+ * initialized using the move_to command. The subsequent path segments
+ * implicitly use the last pen location as their first vertex and move
+ * the pen location to the last vertex they produce at the end. Also
+ * there are special versions of functions that allow specifying the
+ * vertices of the path segments relative to the last pen location
+ * rather then in the absolute coordinates.
+ */
+
+
+
 /**
  * cogl_color:
  * @color: new current @ClutterColor.
@@ -921,18 +945,49 @@ void
 cogl_color (const ClutterColor *color);
 
 
+/**
+ * cogl_fast_fill_rectangle:
+ * @x: X coordinate of the top-left corner
+ * @y: Y coordinate of the top-left corner
+ * @width: Width of the rectangle
+ * @height: Height of the rectangle
+ *
+ * Fills a rectangle at the given coordinates with the current
+ * drawing color in a highly optimizied fashion.
+ **/
 void
 cogl_fast_fill_rectangle (gint x,
                           gint y,
                           guint width,
                           guint height);
 
+/**
+ * cogl_fast_fill_rectanglex:
+ * @x: X coordinate of the top-left corner
+ * @y: Y coordinate of the top-left corner
+ * @width: Width of the rectangle
+ * @height: Height of the rectangle
+ *
+ * A fixed-point version of cogl_fast_fill_rectangle.
+ **/
 void
 cogl_fast_fill_rectanglex (ClutterFixed x,
 			   ClutterFixed y,
 			   ClutterFixed width,
 			   ClutterFixed height);
 
+/**
+ * cogl_fast_fill_trapezoid:
+ * @y1: Y coordinate of the top two vertices.
+ * @x11: X coordinate of the top-left vertex.
+ * @x21: X coordinate of the top-right vertex.
+ * @y2: Y coordinate of the bottom two vertices.
+ * @x12: X coordinate of the bottom-left vertex.
+ * @x22: X coordinate of the bottom-right vertex.
+ *
+ * Fills a trapezoid at the given coordinates with the current
+ * drawing color in a highly optimized fashion.
+ **/
 void
 cogl_fast_fill_trapezoid (gint y1,
 			  gint x11,
@@ -941,6 +996,17 @@ cogl_fast_fill_trapezoid (gint y1,
 			  gint x12,
 			  gint x22);
 
+/**
+ * cogl_fast_fill_trapezoidx:
+ * @y1: Y coordinate of the top two vertices.
+ * @x11: X coordinate of the top-left vertex.
+ * @x21: X coordinate of the top-right vertex.
+ * @y2: Y coordinate of the bottom two vertices.
+ * @x12: X coordinate of the bottom-left vertex.
+ * @x22: X coordinate of the bottom-right vertex.
+ *
+ * A fixed-point version of cogl_fast_fill_trapezoid.
+ **/
 void
 cogl_fast_fill_trapezoidx (ClutterFixed y1,
 			   ClutterFixed x11,
@@ -949,40 +1015,132 @@ cogl_fast_fill_trapezoidx (ClutterFixed y1,
 			   ClutterFixed x12,
 			   ClutterFixed x22);
 
+/**
+ * cogl_fill:
+ *
+ * Fills the constructed shape using the current drawing color.
+ **/
 void
 cogl_fill (void);
 
+/**
+ * cogl_stroke:
+ *
+ * Strokes the constructed shape using the current drawing color
+ * and a width of 1 pixel (regardless of the current transformation
+ * matrix).
+ **/
 void
 cogl_stroke (void);
 
+
+/**
+ * cogl_path_move_to:
+ * @x: X coordinate of the pen location to move to.
+ * @y: Y coordinate of the pen location to move to.
+ *
+ * Clears the previously constructed shape and begins a new path
+ * contour by moving the pen to the given coordinates.
+ **/
 void
 cogl_path_move_to (ClutterFixed x,
 		   ClutterFixed y);
 
+
+/**
+ * cogl_path_move_to_rel:
+ * @x: X offset from the current pen location to move the pen to.
+ * @y: Y offset from the current pen location to move the pen to.
+ *
+ * Clears the previously constructed shape and begins a new path
+ * contour by moving the pen to the given coordinates relative
+ * to the current pen location.
+ **/
 void
 cogl_path_move_to_rel (ClutterFixed x,
 		       ClutterFixed y);
 
+/**
+ * cogl_path_line_to:
+ * @x: X coordinate of the end line vertex
+ * @y: Y coordinate of the end line vertex
+ *
+ * Adds a straight line segment to the current path that ends at the
+ * given coordinates.
+ **/
 void
 cogl_path_line_to (ClutterFixed x,
 		   ClutterFixed y);
 
+/**
+ * cogl_path_line_to_rel:
+ * @x: X offset from the current pen location of the end line vertex
+ * @y: Y offset from the current pen location of the end line vertex
+ *
+ * Adds a straight line segment to the current path that ends at the
+ * given coordinates relative to the current pen location.
+ **/
 void
 cogl_path_line_to_rel (ClutterFixed x,
 		       ClutterFixed y);
 
+/**
+ * cogl_path_h_line_to:
+ * @x: X coordinate of the end line vertex
+ *
+ * Adds a straight horizontal line segment to the current path that
+ * ends at the given X coordinate and current pen Y coordinate.
+ **/
 void
 cogl_path_h_line_to (ClutterFixed x);
 
+/**
+ * cogl_path_v_line_to:
+ * @y: Y coordinate of the end line vertex
+ *
+ * Adds a stright vertical line segment to the current path that ends
+ * at the current pen X coordinate and the given Y coordinate.
+ **/
 void
 cogl_path_v_line_to (ClutterFixed y);
 
+/**
+ * cogl_path_h_line_to_rel:
+ * @x: X offset from the current pen location of the end line vertex
+ *
+ * Adds a straight horizontal line segment to the current path that
+ * ends at the given X coordinate relative to the current pen location
+ * and current pen Y coordinate.
+ **/
 void
 cogl_path_h_line_to_rel (ClutterFixed x);
 
+/**
+ * cogl_path_v_line_to_rel:
+ * @y: Y offset from the current pen location of the end line vertex
+ *
+ * Adds a stright vertical line segment to the current path that ends
+ * at the current pen X coordinate and the given Y coordinate relative
+ * to the current pen location.
+ **/
 void
 cogl_path_v_line_to_rel (ClutterFixed y);
 
+
+/**
+ * cogl_path_arc:
+ * @center_x: X coordinate of the elliptical arc center
+ * @center_y: Y coordinate of the elliptical arc center
+ * @radius_x: X radius of the elliptical arc
+ * @radius_y: Y radious of the elliptical arc
+ * @angle_1: Angle in the unit-circle at which the arc begin
+ * @angle_2: Angle in the unit-circle at which the arc ends
+ * @angle_step: Angle increment resolution for subdivision
+ *
+ * Adds an elliptical arc segment to the current path. A straight line
+ * segment will link the current pen location with the first vertex
+ * of the arc.
+ **/
 void
 cogl_path_arc (ClutterFixed center_x,
 	       ClutterFixed center_y,
@@ -992,6 +1150,22 @@ cogl_path_arc (ClutterFixed center_x,
 	       ClutterAngle angle_2,
 	       ClutterAngle angle_step);
 
+/**
+ * cogl_path_arc_rel:
+ * @center_x: X offset from the current pen location of the elliptical
+ * arc center
+ * @center_y: Y offset from the current pen location of the elliptical
+ * arc center
+ * @radius_x: X radius of the elliptical arc
+ * @radius_y: Y radious of the elliptical arc
+ * @angle_1: Angle in the unit-circle at which the arc begin
+ * @angle_2: Angle in the unit-circle at which the arc ends
+ * @angle_step: Angle increment resolution for subdivision
+ *
+ * Adds an elliptical arc segment to the current path. A straight line
+ * segment will link the current pen location with the first vertex
+ * of the arc.
+ **/
 void
 cogl_path_arc_rel (ClutterFixed center_x,
 		   ClutterFixed center_y,
@@ -1001,18 +1175,55 @@ cogl_path_arc_rel (ClutterFixed center_x,
 		   ClutterAngle angle_2,
 		   ClutterAngle angle_step);
 
+/**
+ * cogl_path_bezier2_to:
+ * @x1: X coordinate of the second bezier control point
+ * @y1: Y coordinate of the second bezier control point
+ * @x2: X coordinate of the third bezier control point
+ * @y2: Y coordinate of the third bezier control point
+ *
+ * Adds a quadratic bezier curve segment to the current path with the given
+ * second and third control points and using current pen location as the
+ * first control point.
+ **/
 void
 cogl_path_bezier2_to (ClutterFixed x1,
 		      ClutterFixed y1,
 		      ClutterFixed x2,
 		      ClutterFixed y2);
 
+
+/**
+ * cogl_path_bezier2_to_rel:
+ * @x1: X coordinate of the second bezier control point
+ * @y1: Y coordinate of the second bezier control point
+ * @x2: X coordinate of the third bezier control point
+ * @y2: Y coordinate of the third bezier control point
+ *
+ * Adds a quadratic bezier curve segment to the current path with the given
+ * second and third control points and using current pen location as the
+ * first control point. The given coordinates are relative to the current
+ * pen location.
+ **/
 void
 cogl_path_bezier2_to_rel (ClutterFixed x1,
 			  ClutterFixed y1,
 			  ClutterFixed x2,
 			  ClutterFixed y2);
 
+/**
+ * cogl_path_bezier3_to:
+ * @x1: X coordinate of the second bezier control point
+ * @y1: Y coordinate of the second bezier control point
+ * @x2: X coordinate of the third bezier control point
+ * @y2: Y coordinate of the third bezier control point
+ * @x3: X coordinate of the fourth bezier control point
+ * @y3: Y coordinate of the fourth bezier control point
+ *
+ * Adds a cubic bezier curve segment to the current path with the given
+ * second, third and fourth control points and using current pen location
+ * as the first control point.
+ **/
 void
 cogl_path_bezier3_to (ClutterFixed x1,
 		      ClutterFixed y1,
@@ -1021,6 +1232,20 @@ cogl_path_bezier3_to (ClutterFixed x1,
 		      ClutterFixed x3,
 		      ClutterFixed y3);
 
+/**
+ * cogl_path_bezier3_to_rel:
+ * @x1: X coordinate of the second bezier control point
+ * @y1: Y coordinate of the second bezier control point
+ * @x2: X coordinate of the third bezier control point
+ * @y2: Y coordinate of the third bezier control point
+ * @x3: X coordinate of the fourth bezier control point
+ * @y3: Y coordinate of the fourth bezier control point
+ *
+ * Adds a cubic bezier curve segment to the current path with the given
+ * second, third and fourth control points and using current pen location
+ * as the first control point. The given coordinates are relative to the
+ * current pen location.
+ */
 void
 cogl_path_bezier3_to_rel (ClutterFixed x1,
 			  ClutterFixed y1,
@@ -1029,29 +1254,101 @@ cogl_path_bezier3_to_rel (ClutterFixed x1,
 			  ClutterFixed x3,
 			  ClutterFixed y3);
 
+/**
+ * cogl_path_close:
+ *
+ * Closes the path being constructed by adding a straight line segment
+ * to it that ends at the first vertex of the path.
+ **/
 void
 cogl_path_close (void);
 
+/**
+ * cogl_line:
+ * @x1: X coordinate of the start line vertex
+ * @y1: Y coordinate of the start line vertex
+ * @x2: X coordinate of the end line vertex
+ * @y2: Y coordinate of the end line vertex
+ *
+ * Clears the previously constructed shape and constructs a straight
+ * line shape start and ending at the given coordinates.
+ **/
 void
 cogl_line (ClutterFixed x1,
            ClutterFixed y1,
            ClutterFixed x2,
            ClutterFixed y2);
 
+/**
+ * cogl_polyline:
+ * @coords: A pointer to the first element of an array of fixed-point
+ * values that specify the vertex coordinates.
+ * @num_points: The total number of vertices.
+ *
+ * Clears the previously constructed shape and constructs a series of straight
+ * line segments, starting from the first given vertex coordinate. Each
+ * subsequent segment stars where the previous one ended and ends at the next
+ * given vertex coordinate.
+ *
+ * The coords array must contain 2 * num_points values. The first value
+ * represents the X coordinate of the first vertex, the second value
+ * represents the Y coordinate of the first vertex, continuing in the same
+ * fashion for the rest of the vertices. (num_points - 1) segments will
+ * be constructed.
+ **/
 void
 cogl_polyline (ClutterFixed *coords,
 	       gint          num_points);
 
+
+/**
+ * cogl_polygon:
+ * @coords: A pointer to the first element of an array of fixed-point
+ * values that specify the vertex coordinates.
+ * @num_points: The total number of vertices.
+ *
+ * Clears the previously constructed shape and constructs a polygonal
+ * shape of the given number of vertices.
+ *
+ * The coords array must contain 2 * num_points values. The first value
+ * represents the X coordinate of the first vertex, the second value
+ * represents the Y coordinate of the first vertex, continuing in the same
+ * fashion for the rest of the vertices.
+ **/
 void
 cogl_polygon (ClutterFixed *coords,
 	      gint          num_points);
 
+
+/**
+ * cogl_rectangle:
+ * @x: X coordinate of the top-left corner.
+ * @y: Y coordinate of the top-left corner.
+ * @width: Rectangle width.
+ * @height: Rectangle height.
+ *
+ * Clears the previously constructed shape and constructs a rectangular
+ * shape at the given coordinates.
+ **/
 void
 cogl_rectangle (ClutterFixed x,
 		ClutterFixed y,
 		ClutterFixed width,
 		ClutterFixed height);
 
+/**
+ * cogl_arc:
+ * @center_x: X coordinate of the elliptical arc center
+ * @center_y: Y coordinate of the elliptical arc center
+ * @radius_x: X radius of the elliptical arc
+ * @radius_y: Y radious of the elliptical arc
+ * @angle_1: Angle in the unit-circle at which the arc begin
+ * @angle_2: Angle in the unit-circle at which the arc ends
+ * @angle_step: Angle increment resolution for subdivision
+ *
+ * Clears the previously constructed shape and constructs and elliptical arc
+ * shape.
+ **/
 void
 cogl_arc (ClutterFixed center_x,
 	  ClutterFixed center_y,
@@ -1061,6 +1358,18 @@ cogl_arc (ClutterFixed center_x,
 	  ClutterAngle angle_2,
 	  ClutterAngle angle_step);
 
+
+/**
+ * cogl_ellipse:
+ * @center_x: X coordinate of the ellipse center
+ * @center_y: Y coordinate of the ellipse center
+ * @radius_x: X radius of the ellipse
+ * @radius_y: Y radius of the ellipse
+ * @angle_step: Angle increment resolution for subdivision
+ *
+ * Clears the previously constructed shape and constructs an ellipse
+ * shape.
+ **/
 void
 cogl_ellipse (ClutterFixed center_x,
 	      ClutterFixed center_y,
@@ -1068,6 +1377,20 @@ cogl_ellipse (ClutterFixed center_x,
 	      ClutterFixed radius_y,
 	      ClutterAngle angle_step);
 
+
+/**
+ * cogl_round_rectangle:
+ * @x: X coordinate of the top-left corner
+ * @y: Y coordinate of the top-left corner
+ * @width: Width of the rectangle
+ * @height: Height of the rectangle
+ * @radius: Radius of the corner arcs.
+ * @arc_step: Angle increment resolution for subdivision of
+ * the corner arcs.
+ *
+ * Clears the previously constructed shape and constructs a rectangular
+ * shape with rounded corners.
+ **/
 void
 cogl_round_rectangle (ClutterFixed x,
 		      ClutterFixed y,
diff --git a/gl/cogl-primitives.c b/gl/cogl-primitives.c
index 352ad46d3..3528c2b5d 100644
--- a/gl/cogl-primitives.c
+++ b/gl/cogl-primitives.c
@@ -36,38 +36,6 @@
 
 #define _COGL_MAX_BEZ_RECURSE_DEPTH 16
 
-/**
- * SECTION:cogl-primitives
- * @short_description: Functions that draw various primitive shapes and
- * allow for construction of more complex paths.
- *
- * There are three levels on which drawing with cogl can be used. The
- * highest level functions construct various simple primitive shapes
- * to be either filled or stroked. Using a lower-level set of functions
- * more complex and arbitrary paths can be constructed by concatenating
- * straight line, bezier curve and arc segments. Additionally there
- * are utility functions that draw the most common primitives - rectangles
- * and trapezoids - in a maximaly optimized fashion.
- *
- * When constructing arbitrary paths, the current pen location is
- * initialized using the move_to command. The subsequent path segments
- * implicitly use the last pen location as their first vertex and move
- * the pen location to the last vertex they produce at the end. Also
- * there are special versions of functions that allow specifying the
- * vertices of the path segments relative to the last pen location
- * rather then in the absolute coordinates.
- */
-
-/**
- * cogl_fast_fill_rectangle:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- *
- * Fills a rectangle at the given coordinates with the current
- * drawing color in a highly optimizied fashion.
- **/
 void
 cogl_fast_fill_rectangle (gint x,
 			  gint y,
@@ -82,15 +50,7 @@ cogl_fast_fill_rectangle (gint x,
   GE( glRecti (x, y, x + width, y + height) );
 }
 
-/**
- * cogl_fast_fill_rectanglex:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- *
- * A fixed-point version of cogl_fast_fill_rectangle.
- **/
+
 void
 cogl_fast_fill_rectanglex (ClutterFixed x,
 			   ClutterFixed y,
@@ -108,18 +68,6 @@ cogl_fast_fill_rectanglex (ClutterFixed x,
 	       CLUTTER_FIXED_TO_FLOAT (y + height)) );
 }
 
-/**
- * cogl_fast_fill_trapezoid:
- * @y1: Y coordinate of the top two vertices.
- * @x11: X coordinate of the top-left vertex.
- * @x21: X coordinate of the top-right vertex.
- * @y2: Y coordinate of the bottom two vertices.
- * @x12: X coordinate of the bottom-left vertex.
- * @x22: X coordinate of the bottom-right vertex.
- *
- * Fills a trapezoid at the given coordinates with the current
- * drawing color in a highly optimized fashion.
- **/
 void
 cogl_fast_fill_trapezoid (gint y1,
 			  gint x11,
@@ -141,17 +89,6 @@ cogl_fast_fill_trapezoid (gint y1,
   GE( glEnd () );
 }
 
-/**
- * cogl_fast_fill_trapezoidx:
- * @y1: Y coordinate of the top two vertices.
- * @x11: X coordinate of the top-left vertex.
- * @x21: X coordinate of the top-right vertex.
- * @y2: Y coordinate of the bottom two vertices.
- * @x12: X coordinate of the bottom-left vertex.
- * @x22: X coordinate of the bottom-right vertex.
- *
- * A fixed-point version of cogl_fast_fill_trapezoid.
- **/
 void
 cogl_fast_fill_trapezoidx (ClutterFixed y1,
 			   ClutterFixed x11,
@@ -280,11 +217,6 @@ _cogl_path_fill_nodes ()
   GE( glDisable (GL_STENCIL_TEST) );
 }
 
-/**
- * cogl_fill:
- *
- * Fills the constructed shape using the current drawing color.
- **/
 void
 cogl_fill ()
 {
@@ -297,13 +229,6 @@ cogl_fill ()
   
 }
 
-/**
- * cogl_stroke:
- *
- * Strokes the constructed shape using the current drawing color
- * and a width of 1 pixel (regardless of the current transformation
- * matrix).
- **/
 void
 cogl_stroke ()
 {
@@ -315,14 +240,6 @@ cogl_stroke ()
   _cogl_path_stroke_nodes();
 }
 
-/**
- * cogl_path_move_to:
- * @x: X coordinate of the pen location to move to.
- * @y: Y coordinate of the pen location to move to.
- *
- * Clears the previously constructed shape and begins a new path
- * contour by moving the pen to the given coordinates.
- **/
 void
 cogl_path_move_to (ClutterFixed x,
 		   ClutterFixed y)
@@ -340,15 +257,6 @@ cogl_path_move_to (ClutterFixed x,
   ctx->path_pen = ctx->path_start;
 }
 
-/**
- * cogl_path_move_to_rel:
- * @x: X offset from the current pen location to move the pen to.
- * @y: Y offset from the current pen location to move the pen to.
- *
- * Clears the previously constructed shape and begins a new path
- * contour by moving the pen to the given coordinates relative
- * to the current pen location.
- **/
 void
 cogl_path_move_to_rel (ClutterFixed x,
 		       ClutterFixed y)
@@ -359,14 +267,6 @@ cogl_path_move_to_rel (ClutterFixed x,
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_line_to:
- * @x: X coordinate of the end line vertex
- * @y: Y coordinate of the end line vertex
- *
- * Adds a straight line segment to the current path that ends at the
- * given coordinates.
- **/
 void
 cogl_path_line_to (ClutterFixed x,
 		   ClutterFixed y)
@@ -379,14 +279,6 @@ cogl_path_line_to (ClutterFixed x,
   ctx->path_pen.y = y;
 }
 
-/**
- * cogl_path_line_to:
- * @x: X offset from the current pen location of the end line vertex
- * @y: Y offset from the current pen location of the end line vertex
- *
- * Adds a straight line segment to the current path that ends at the
- * given coordinates relative to the current pen location.
- **/
 void
 cogl_path_line_to_rel (ClutterFixed x,
 		       ClutterFixed y)
@@ -397,13 +289,6 @@ cogl_path_line_to_rel (ClutterFixed x,
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_h_line_to:
- * @x: X coordinate of the end line vertex
- *
- * Adds a straight horizontal line segment to the current path that
- * ends at the given X coordinate and current pen Y coordinate.
- **/
 void
 cogl_path_h_line_to (ClutterFixed x)
 {
@@ -413,13 +298,6 @@ cogl_path_h_line_to (ClutterFixed x)
 		     ctx->path_pen.y);
 }
 
-/**
- * cogl_path_v_line_to:
- * @y: Y coordinate of the end line vertex
- *
- * Adds a stright vertical line segment to the current path that ends
- * at the current pen X coordinate and the given Y coordinate.
- **/
 void
 cogl_path_v_line_to (ClutterFixed y)
 {
@@ -429,14 +307,6 @@ cogl_path_v_line_to (ClutterFixed y)
 		     y);
 }
 
-/**
- * cogl_path_h_line_to_rel:
- * @x: X offset from the current pen location of the end line vertex
- *
- * Adds a straight horizontal line segment to the current path that
- * ends at the given X coordinate relative to the current pen location
- * and current pen Y coordinate.
- **/
 void
 cogl_path_h_line_to_rel (ClutterFixed x)
 {
@@ -446,14 +316,6 @@ cogl_path_h_line_to_rel (ClutterFixed x)
 		     ctx->path_pen.y);
 }
 
-/**
- * cogl_path_v_line_to_rel:
- * @y: Y offset from the current pen location of the end line vertex
- *
- * Adds a stright vertical line segment to the current path that ends
- * at the current pen X coordinate and the given Y coordinate relative
- * to the current pen location.
- **/
 void
 cogl_path_v_line_to_rel (ClutterFixed y)
 {
@@ -463,12 +325,7 @@ cogl_path_v_line_to_rel (ClutterFixed y)
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_close:
- *
- * Closes the path being constructed by adding a straight line segment
- * to it that ends at the first vertex of the path.
- **/
+
 void
 cogl_path_close ()
 {
@@ -478,16 +335,7 @@ cogl_path_close ()
   ctx->path_pen = ctx->path_start;
 }
 
-/**
- * cogl_line:
- * @x1: X coordinate of the start line vertex
- * @y1: Y coordinate of the start line vertex
- * @x2: X coordinate of the end line vertex
- * @y2: Y coordinate of the end line vertex
- *
- * Clears the previously constructed shape and constructs a straight
- * line shape start and ending at the given coordinates.
- **/
+
 void
 cogl_line (ClutterFixed x1,
 	   ClutterFixed y1,
@@ -498,23 +346,6 @@ cogl_line (ClutterFixed x1,
   cogl_path_line_to (x2, y2);
 }
 
-/**
- * cogl_polyline:
- * @coords: A pointer to the first element of an array of fixed-point
- * values that specify the vertex coordinates.
- * @num_points: The total number of vertices.
- *
- * Clears the previously constructed shape and constructs a series of straight
- * line segments, starting from the first given vertex coordinate. Each
- * subsequent segment stars where the previous one ended and ends at the next
- * given vertex coordinate.
- *
- * The coords array must contain 2 * num_points values. The first value
- * represents the X coordinate of the first vertex, the second value
- * represents the Y coordinate of the first vertex, continuing in the same
- * fashion for the rest of the vertices. (num_points - 1) segments will
- * be constructed.
- **/
 void
 cogl_polyline (ClutterFixed *coords,
 	       gint num_points)
@@ -527,21 +358,6 @@ cogl_polyline (ClutterFixed *coords,
     cogl_path_line_to (coords[2*c], coords[2*c+1]);
 }
 
-
-/**
- * cogl_polygon:
- * @coords: A pointer to the first element of an array of fixed-point
- * values that specify the vertex coordinates.
- * @num_points: The total number of vertices.
- *
- * Clears the previously constructed shape and constructs a polygonal
- * shape of the given number of vertices.
- *
- * The coords array must contain 2 * num_points values. The first value
- * represents the X coordinate of the first vertex, the second value
- * represents the Y coordinate of the first vertex, continuing in the same
- * fashion for the rest of the vertices.
- **/
 void
 cogl_polygon (ClutterFixed *coords,
 	      gint num_points)
@@ -550,16 +366,6 @@ cogl_polygon (ClutterFixed *coords,
   cogl_path_close ();
 }
 
-/**
- * cogl_rectangle:
- * @x: X coordinate of the top-left corner.
- * @y: Y coordinate of the top-left corner.
- * @width: Rectangle width.
- * @height: Rectangle height.
- *
- * Clears the previously constructed shape and constructs a rectangular
- * shape at the given coordinates.
- **/
 void
 cogl_rectangle (ClutterFixed x,
 		ClutterFixed y,
@@ -622,20 +428,6 @@ _cogl_arc (ClutterFixed center_x,
     }
 }
 
-/**
- * cogl_path_arc:
- * @center_x: X coordinate of the elliptical arc center
- * @center_y: Y coordinate of the elliptical arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Adds an elliptical arc segment to the current path. A straight line
- * segment will link the current pen location with the first vertex
- * of the arc.
- **/
 void
 cogl_path_arc (ClutterFixed center_x,
 	       ClutterFixed center_y,
@@ -651,22 +443,7 @@ cogl_path_arc (ClutterFixed center_x,
 	     angle_step, 0 /* no move */);
 }
 
-/**
- * cogl_path_arc_rel:
- * @center_x: X offset from the current pen location of the elliptical
- * arc center
- * @center_y: Y offset from the current pen location of the elliptical
- * arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Adds an elliptical arc segment to the current path. A straight line
- * segment will link the current pen location with the first vertex
- * of the arc.
- **/
+
 void
 cogl_path_arc_rel (ClutterFixed center_x,
 		   ClutterFixed center_y,
@@ -685,19 +462,7 @@ cogl_path_arc_rel (ClutterFixed center_x,
 	     angle_step, 0 /* no move */);
 }
 
-/**
- * cogl_arc:
- * @center_x: X coordinate of the elliptical arc center
- * @center_y: Y coordinate of the elliptical arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Clears the previously constructed shape and constructs and elliptical arc
- * shape.
- **/
+
 void
 cogl_arc (ClutterFixed center_x,
 	  ClutterFixed center_y,
@@ -713,17 +478,6 @@ cogl_arc (ClutterFixed center_x,
 	     angle_step, 1 /* move first */);
 }
 
-/**
- * cogl_ellipse:
- * @center_x: X coordinate of the ellipse center
- * @center_y: Y coordinate of the ellipse center
- * @radius_x: X radius of the ellipse
- * @radius_y: Y radius of the ellipse
- * @angle_step: Angle increment resolution for subdivision
- *
- * Clears the previously constructed shape and constructs an ellipse
- * shape.
- **/
 void
 cogl_ellipse (ClutterFixed center_x,
 	      ClutterFixed center_y,
@@ -743,19 +497,6 @@ cogl_ellipse (ClutterFixed center_x,
   cogl_path_close();
 }
 
-/**
- * cogl_round_rectangle:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- * @radius: Radius of the corner arcs.
- * @arc_step: Angle increment resolution for subdivision of
- * the corner arcs.
- *
- * Clears the previously constructed shape and constructs a rectangular
- * shape with rounded corners.
- **/
 void
 cogl_round_rectangle (ClutterFixed x,
 		      ClutterFixed y,
@@ -955,17 +696,6 @@ _cogl_path_bezier3_sub (CoglBezCubic *cubic)
     }
 }
 
-/**
- * cogl_path_bezier2_to:
- * @x1: X coordinate of the second bezier control point
- * @y1: Y coordinate of the second bezier control point
- * @x2: X coordinate of the third bezier control point
- * @y2: Y coordinate of the third bezier control point
- *
- * Adds a quadratic bezier curve segment to the current path with the given
- * second and third control points and using current pen location as the
- * first control point.
- **/
 void
 cogl_path_bezier2_to (ClutterFixed x1,
 		      ClutterFixed y1,
@@ -991,19 +721,7 @@ cogl_path_bezier2_to (ClutterFixed x1,
   ctx->path_pen = quad.p3;
 }
 
-/**
- * cogl_path_bezier3_to:
- * @x1: X coordinate of the second bezier control point
- * @y1: Y coordinate of the second bezier control point
- * @x2: X coordinate of the third bezier control point
- * @y2: Y coordinate of the third bezier control point
- * @x3: X coordinate of the fourth bezier control point
- * @y3: Y coordinate of the fourth bezier control point
- *
- * Adds a cubic bezier curve segment to the current path with the given
- * second, third and fourth control points and using current pen location
- * as the first control point.
- **/
+
 void
 cogl_path_bezier3_to (ClutterFixed x1,
 		      ClutterFixed y1,
@@ -1033,18 +751,6 @@ cogl_path_bezier3_to (ClutterFixed x1,
   ctx->path_pen = cubic.p4;
 }
 
-/**
- * cogl_path_bezier2_to_rel:
- * @x1: X coordinate of the second bezier control point
- * @y1: Y coordinate of the second bezier control point
- * @x2: X coordinate of the third bezier control point
- * @y2: Y coordinate of the third bezier control point
- *
- * Adds a quadratic bezier curve segment to the current path with the given
- * second and third control points and using current pen location as the
- * first control point. The given coordinates are relative to the current
- * pen location.
- **/
 void
 cogl_path_bezier2_to_rel (ClutterFixed x1,
 			  ClutterFixed y1,
@@ -1059,20 +765,6 @@ cogl_path_bezier2_to_rel (ClutterFixed x1,
 			ctx->path_pen.y + y2);
 }
 
-/**
- * cogl_path_bezier3_to_rel:
- * @x1: X coordinate of the second bezier control point
- * @y1: Y coordinate of the second bezier control point
- * @x2: X coordinate of the third bezier control point
- * @y2: Y coordinate of the third bezier control point
- * @x3: X coordinate of the fourth bezier control point
- * @y3: Y coordinate of the fourth bezier control point
- *
- * Adds a cubic bezier curve segment to the current path with the given
- * second, third and fourth control points and using current pen location
- * as the first control point. The given coordinates are relative to the
- * current pen location.
- **/
 void
 cogl_path_bezier3_to_rel (ClutterFixed x1,
 			  ClutterFixed y1,
diff --git a/gles/cogl-primitives.c b/gles/cogl-primitives.c
index 1bba58f55..006833743 100644
--- a/gles/cogl-primitives.c
+++ b/gles/cogl-primitives.c
@@ -36,38 +36,6 @@
 
 #define _COGL_MAX_BEZ_RECURSE_DEPTH 16
 
-/**
- * SECTION:cogl-primitives
- * @short_description: Functions that draw various primitive shapes and
- * allow for construction of more complex paths.
- *
- * There are three levels on which drawing with cogl can be used. The
- * highest level functions construct various simple primitive shapes
- * to be either filled or stroked. Using a lower-level set of functions
- * more complex and arbitrary paths can be constructed by concatenating
- * straight line, bezier curve and arc segments. Additionally there
- * are utility functions that draw the most common primitives - rectangles
- * and trapezoids - in a maximaly optimized fashion.
- *
- * When constructing arbitrary paths, the current pen location is
- * initialized using the move_to command. The subsequent path segments
- * implicitly use the last pen location as their first vertex and move
- * the pen location to the last vertex they produce at the end. Also
- * there are special versions of functions that allow specifying the
- * vertices of the path segments relative to the last pen location
- * rather then in the absolute coordinates.
- */
-
-/**
- * cogl_fast_fill_rectangle:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- *
- * Fills a rectangle at the given coordinates with the current
- * drawing color in a highly optimizied fashion.
- **/
 void
 cogl_fast_fill_rectangle (gint x,
 			  gint y,
@@ -95,15 +63,6 @@ cogl_fast_fill_rectangle (gint x,
   GE( glDrawArrays (GL_TRIANGLE_STRIP, 0, 4) );
 }
 
-/**
- * cogl_fast_fill_rectanglex:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- *
- * A fixed-point version of cogl_fast_fill_rectangle.
- **/
 void
 cogl_fast_fill_rectanglex (ClutterFixed x,
 			   ClutterFixed y,
@@ -127,18 +86,6 @@ cogl_fast_fill_rectanglex (ClutterFixed x,
   GE( glDrawArrays (GL_TRIANGLE_STRIP, 0, 4) );
 }
 
-/**
- * cogl_fast_fill_trapezoid:
- * @y1: Y coordinate of the top two vertices.
- * @x11: X coordinate of the top-left vertex.
- * @x21: X coordinate of the top-right vertex.
- * @y2: Y coordinate of the bottom two vertices.
- * @x12: X coordinate of the bottom-left vertex.
- * @x22: X coordinate of the bottom-right vertex.
- *
- * Fills a trapezoid at the given coordinates with the current
- * drawing color in a highly optimized fashion.
- **/
 void
 cogl_fast_fill_trapezoid (gint y1,
 			  gint x11,
@@ -164,17 +111,6 @@ cogl_fast_fill_trapezoid (gint y1,
   GE( glDrawArrays (GL_TRIANGLE_STRIP, 0, 4) );
 }
 
-/**
- * cogl_fast_fill_trapezoidx:
- * @y1: Y coordinate of the top two vertices.
- * @x11: X coordinate of the top-left vertex.
- * @x21: X coordinate of the top-right vertex.
- * @y2: Y coordinate of the bottom two vertices.
- * @x12: X coordinate of the bottom-left vertex.
- * @x22: X coordinate of the bottom-right vertex.
- *
- * A fixed-point version of cogl_fast_fill_trapezoid.
- **/
 void
 cogl_fast_fill_trapezoidx (ClutterFixed y1,
 			   ClutterFixed x11,
@@ -302,11 +238,6 @@ _cogl_path_fill_nodes ()
   GE( glDisable (GL_STENCIL_TEST) );
 }
 
-/**
- * cogl_fill:
- *
- * Fills the constructed shape using the current drawing color.
- **/
 void
 cogl_fill ()
 {
@@ -318,13 +249,6 @@ cogl_fill ()
   _cogl_path_fill_nodes();
 }
 
-/**
- * cogl_stroke:
- *
- * Strokes the constructed shape using the current drawing color
- * and a width of 1 pixel (regardless of the current transformation
- * matrix).
- **/
 void
 cogl_stroke ()
 {
@@ -336,14 +260,6 @@ cogl_stroke ()
   _cogl_path_stroke_nodes();
 }
 
-/**
- * cogl_path_move_to:
- * @x: X coordinate of the pen location to move to.
- * @y: Y coordinate of the pen location to move to.
- *
- * Clears the previously constructed shape and begins a new path
- * contour by moving the pen to the given coordinates.
- **/
 void
 cogl_path_move_to (ClutterFixed x,
 		   ClutterFixed y)
@@ -361,15 +277,6 @@ cogl_path_move_to (ClutterFixed x,
   ctx->path_pen = ctx->path_start;
 }
 
-/**
- * cogl_path_move_to_rel:
- * @x: X offset from the current pen location to move the pen to.
- * @y: Y offset from the current pen location to move the pen to.
- *
- * Clears the previously constructed shape and begins a new path
- * contour by moving the pen to the given coordinates relative
- * to the current pen location.
- **/
 void
 cogl_path_move_to_rel (ClutterFixed x,
 		       ClutterFixed y)
@@ -380,14 +287,6 @@ cogl_path_move_to_rel (ClutterFixed x,
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_line_to:
- * @x: X coordinate of the end line vertex
- * @y: Y coordinate of the end line vertex
- *
- * Adds a straight line segment to the current path that ends at the
- * given coordinates.
- **/
 void
 cogl_path_line_to (ClutterFixed x,
 		   ClutterFixed y)
@@ -400,14 +299,6 @@ cogl_path_line_to (ClutterFixed x,
   ctx->path_pen.y = y;
 }
 
-/**
- * cogl_path_line_to:
- * @x: X offset from the current pen location of the end line vertex
- * @y: Y offset from the current pen location of the end line vertex
- *
- * Adds a straight line segment to the current path that ends at the
- * given coordinates relative to the current pen location.
- **/
 void
 cogl_path_line_to_rel (ClutterFixed x,
 		       ClutterFixed y)
@@ -418,13 +309,6 @@ cogl_path_line_to_rel (ClutterFixed x,
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_h_line_to:
- * @x: X coordinate of the end line vertex
- *
- * Adds a straight horizontal line segment to the current path that
- * ends at the given X coordinate and current pen Y coordinate.
- **/
 void
 cogl_path_h_line_to (ClutterFixed x)
 {
@@ -434,13 +318,6 @@ cogl_path_h_line_to (ClutterFixed x)
 		     ctx->path_pen.y);
 }
 
-/**
- * cogl_path_v_line_to:
- * @y: Y coordinate of the end line vertex
- *
- * Adds a stright vertical line segment to the current path that ends
- * at the current pen X coordinate and the given Y coordinate.
- **/
 void
 cogl_path_v_line_to (ClutterFixed y)
 {
@@ -450,14 +327,6 @@ cogl_path_v_line_to (ClutterFixed y)
 		     y);
 }
 
-/**
- * cogl_path_h_line_to_rel:
- * @x: X offset from the current pen location of the end line vertex
- *
- * Adds a straight horizontal line segment to the current path that
- * ends at the given X coordinate relative to the current pen location
- * and current pen Y coordinate.
- **/
 void
 cogl_path_h_line_to_rel (ClutterFixed x)
 {
@@ -467,14 +336,6 @@ cogl_path_h_line_to_rel (ClutterFixed x)
 		     ctx->path_pen.y);
 }
 
-/**
- * cogl_path_v_line_to_rel:
- * @y: Y offset from the current pen location of the end line vertex
- *
- * Adds a stright vertical line segment to the current path that ends
- * at the current pen X coordinate and the given Y coordinate relative
- * to the current pen location.
- **/
 void
 cogl_path_v_line_to_rel (ClutterFixed y)
 {
@@ -484,12 +345,6 @@ cogl_path_v_line_to_rel (ClutterFixed y)
 		     ctx->path_pen.y + y);
 }
 
-/**
- * cogl_path_close:
- *
- * Closes the path being constructed by adding a straight line segment
- * to it that ends at the first vertex of the path.
- **/
 void
 cogl_path_close ()
 {
@@ -499,16 +354,6 @@ cogl_path_close ()
   ctx->path_pen = ctx->path_start;
 }
 
-/**
- * cogl_line:
- * @x1: X coordinate of the start line vertex
- * @y1: Y coordinate of the start line vertex
- * @x2: X coordinate of the end line vertex
- * @y2: Y coordinate of the end line vertex
- *
- * Clears the previously constructed shape and constructs a straight
- * line shape start and ending at the given coordinates.
- **/
 void
 cogl_line (ClutterFixed x1,
 	   ClutterFixed y1,
@@ -519,23 +364,6 @@ cogl_line (ClutterFixed x1,
   cogl_path_line_to (x2, y2);
 }
 
-/**
- * cogl_polyline:
- * @coords: A pointer to the first element of an array of fixed-point
- * values that specify the vertex coordinates.
- * @num_points: The total number of vertices.
- *
- * Clears the previously constructed shape and constructs a series of straight
- * line segments, starting from the first given vertex coordinate. Each
- * subsequent segment stars where the previous one ended and ends at the next
- * given vertex coordinate.
- *
- * The coords array must contain 2 * num_points values. The first value
- * represents the X coordinate of the first vertex, the second value
- * represents the Y coordinate of the first vertex, continuing in the same
- * fashion for the rest of the vertices. (num_points - 1) segments will
- * be constructed.
- **/
 void
 cogl_polyline (ClutterFixed *coords,
 	       gint num_points)
@@ -548,20 +376,6 @@ cogl_polyline (ClutterFixed *coords,
     cogl_path_line_to(coords[2*c], coords[2*c+1]);
 }
 
-/**
- * cogl_polygon:
- * @coords: A pointer to the first element of an array of fixed-point
- * values that specify the vertex coordinates.
- * @num_points: The total number of vertices.
- *
- * Clears the previously constructed shape and constructs a polygonal
- * shape of the given number of vertices.
- *
- * The coords array must contain 2 * num_points values. The first value
- * represents the X coordinate of the first vertex, the second value
- * represents the Y coordinate of the first vertex, continuing in the same
- * fashion for the rest of the vertices.
- **/
 void
 cogl_polygon (ClutterFixed *coords,
 	      gint num_points)
@@ -570,16 +384,6 @@ cogl_polygon (ClutterFixed *coords,
   cogl_path_close ();
 }
 
-/**
- * cogl_rectangle:
- * @x: X coordinate of the top-left corner.
- * @y: Y coordinate of the top-left corner.
- * @width: Rectangle width.
- * @height: Rectangle height.
- *
- * Clears the previously constructed shape and constructs a rectangular
- * shape at the given coordinates.
- **/
 void
 cogl_rectangle (ClutterFixed x,
 		ClutterFixed y,
@@ -642,20 +446,6 @@ _cogl_arc (ClutterFixed center_x,
     }
 }
 
-/**
- * cogl_path_arc:
- * @center_x: X coordinate of the elliptical arc center
- * @center_y: Y coordinate of the elliptical arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Adds an elliptical arc segment to the current path. A straight line
- * segment will link the current pen location with the first vertex
- * of the arc.
- **/
 void
 cogl_path_arc (ClutterFixed center_x,
 	       ClutterFixed center_y,
@@ -671,22 +461,6 @@ cogl_path_arc (ClutterFixed center_x,
 	     angle_step, 0 /* no move */);
 }
 
-/**
- * cogl_path_arc_rel:
- * @center_x: X offset from the current pen location of the elliptical
- * arc center
- * @center_y: Y offset from the current pen location of the elliptical
- * arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Adds an elliptical arc segment to the current path. A straight line
- * segment will link the current pen location with the first vertex
- * of the arc.
- **/
 void
 cogl_path_arc_rel (ClutterFixed center_x,
 		   ClutterFixed center_y,
@@ -705,19 +479,6 @@ cogl_path_arc_rel (ClutterFixed center_x,
 	     angle_step, 0 /* no move */);
 }
 
-/**
- * cogl_arc:
- * @center_x: X coordinate of the elliptical arc center
- * @center_y: Y coordinate of the elliptical arc center
- * @radius_x: X radius of the elliptical arc
- * @radius_y: Y radious of the elliptical arc
- * @angle_1: Angle in the unit-circle at which the arc begin
- * @angle_2: Angle in the unit-circle at which the arc ends
- * @angle_step: Angle increment resolution for subdivision
- *
- * Clears the previously constructed shape and constructs and elliptical arc
- * shape.
- **/
 void
 cogl_arc (ClutterFixed center_x,
 	  ClutterFixed center_y,
@@ -733,17 +494,6 @@ cogl_arc (ClutterFixed center_x,
 	     angle_step, 1 /* move first */);
 }
 
-/**
- * cogl_ellipse:
- * @center_x: X coordinate of the ellipse center
- * @center_y: Y coordinate of the ellipse center
- * @radius_x: X radius of the ellipse
- * @radius_y: Y radius of the ellipse
- * @angle_step: Angle increment resolution for subdivision
- *
- * Clears the previously constructed shape and constructs an ellipse
- * shape.
- **/
 void
 cogl_ellipse (ClutterFixed center_x,
 	      ClutterFixed center_y,
@@ -763,19 +513,6 @@ cogl_ellipse (ClutterFixed center_x,
   cogl_path_close();
 }
 
-/**
- * cogl_round_rectangle:
- * @x: X coordinate of the top-left corner
- * @y: Y coordinate of the top-left corner
- * @width: Width of the rectangle
- * @height: Height of the rectangle
- * @radius: Radius of the corner arcs.
- * @arc_step: Angle increment resolution for subdivision of
- * the corner arcs.
- *
- * Clears the previously constructed shape and constructs a rectangular
- * shape with rounded corners.
- **/
 void
 cogl_round_rectangle (ClutterFixed x,
 		      ClutterFixed y,