Update the documentation

12 files changed, 1413 insertions, 152 deletions

diff --git a/ChangeLog b/ChangeLog
index 7aed77d..376c680 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2010-11-03  Mark Vender  <markv743@yahoo.co.uk>
+
+	Update the documentation.
+
+	Based on the documentation of the C API.
+	Bug #47142
+
 1.10.0:
 
 2010-11-03  Murray Cumming  <murrayc@murrayc.com>
diff --git a/cairomm/context.h b/cairomm/context.h
index 56efb57..f6b8c29 100644
--- a/cairomm/context.h
+++ b/cairomm/context.h
@@ -36,7 +36,11 @@
 namespace Cairo
 {
 
-/** Context is the main class used to draw in cairomm.
+/**
+ * Context is the main class used to draw in cairomm. It contains the current
+ * state of the rendering device, including coordinates of yet to be drawn 
+ * shapes.
+ * 
  * In the simplest case, create a Context with its target Surface, set its
  * drawing options (line width, color, etc), create shapes with methods like
  * move_to() and line_to(), and then draw the shapes to the Surface using
@@ -172,7 +176,10 @@ public:
    * tolerance. The default value is 0.1. A larger value will give better
    * performance, a smaller value, better appearance. (Reducing the value from
    * the default value of 0.1 is unlikely to improve appearance significantly.)
-   *
+   * The accuracy of paths within Cairo is limited by the precision of its 
+   * internal arithmetic, and the prescribed @tolerance is restricted to the 
+   * smallest representable internal value.
+   * 
    * @param tolerance	the tolerance, in device units (typically pixels)
    */
   void set_tolerance(double tolerance);
@@ -180,7 +187,7 @@ public:
   /** Set the antialiasing mode of the rasterizer used for drawing shapes. This
    * value is a hint, and a particular backend may or may not support a
    * particular value. At the current time, no backend supports
-   * CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
+   * Cairo::ANTIALIAS_SUBPIXEL when drawing shapes.
    *
    * Note that this option does not affect text rendering, instead see
    * FontOptions::set_antialias().
@@ -195,16 +202,30 @@ public:
    * clip(). See FillRule for details on the semantics of each available fill
    * rule.
    *
+   * The default fill rule is Cairo::FILL_RULE_WINDING.
+   * 
    * @param fill_rule	a fill rule, specified as a FillRule
    */
   void set_fill_rule(FillRule fill_rule);
 
   /** Sets the current line width within the cairo Context. The line width
-   * specifies the diameter of a pen that is circular in user-space.
+   * specifies the diameter of a pen that is circular in user-space, (though 
+   * device-space pen may be an ellipse in general due to scaling/shear/rotation 
+   * of the CTM).
+   *
+   * Note: When the description above refers to user space and CTM it refers to
+   * the user space and CTM in effect at the time of the stroking operation,
+   * not the user space and CTM in effect at the time of the call to
+   * set_line_width(). The simplest usage makes both of these spaces
+   * identical. That is, if there is no change to the CTM between a call to
+   * set_line_width() and the stroking operation, then one can just pass
+   * user-space values to set_line_width() and ignore this note.
    *
    * As with the other stroke parameters, the current line cap style is
    * examined by stroke(), stroke_extents(), and stroke_to_path(), but does not
    * have any effect during path construction.
+   * 
+   * The default line width value is 2.0.
    *
    * @param width	a line width, as a user-space value
    */
@@ -216,6 +237,8 @@ public:
    * As with the other stroke parameters, the current line cap style is
    * examined by stroke(), stroke_extents(), and stroke_to_path(), but does not
    * have any effect during path construction.
+   * 
+   * The default line cap style is Cairo::LINE_CAP_BUTT.
    *
    * @param line_cap	a line cap style, as a LineCap
    */
@@ -228,6 +251,8 @@ public:
    * examined by stroke(), stroke_extents(), and stroke_to_path(), but does not
    * have any effect during path construction.
    *
+   * The default line join style is Cairo::LINE_JOIN_MITER.
+   *
    * @param line_join	a line joint style, as a LineJoin
    */
   void set_line_join(LineJoin line_join);
@@ -274,7 +299,16 @@ public:
    * length of altenate "on" and "off" portions of the stroke. The offset
    * specifies an offset into the pattern at which the stroke begins.
    *
-   * If dashes is empty dashing is disabled.  If the size of dashes is 1, a
+   * Each "on" segment will have caps applied as if the segment were a separate
+   * sub-path. In particular, it is valid to use an "on" length of 0.0 with
+   * Cairo::LINE_CAP_ROUND or Cairo::LINE_CAP_SQUARE in order to distributed
+   * dots or squares along a path.
+   *
+   * Note: The length values are in user-space units as evaluated at the time
+   * of stroking. This is not necessarily the same as the user space at the
+   * time of set_dash().
+   *
+   * If dashes is empty dashing is disabled. If the size of dashes is 1, a
    * symmetric pattern is assumed with alternating on and off portions of the
    * size specified by the single value in dashes.
    *
@@ -291,12 +325,36 @@ public:
   /** This function disables a dash pattern that was set with set_dash()
    */
   void unset_dash();
+  
+  /**
+   * Sets the current miter limit within the cairo context.
+   *
+   * If the current line join style is set to Cairo::LINE_JOIN_MITER (see
+   * set_line_join()), the miter limit is used to determine whether the lines
+   * should be joined with a bevel instead of a miter. Cairo divides the length
+   * of the miter by the line width. If the result is greater than the miter
+   * limit, the style is converted to a bevel.
+   *
+   * As with the other stroke parameters, the current line miter limit is
+   * examined by stroke(), stroke_extents(), and stroke_to_path(), but does not
+   * have any effect during path construction.
+   *
+   * The default miter limit value is 10.0, which will convert joins with
+   * interior angles less than 11 degrees to bevels instead of miters. For
+   * reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and
+   * a miter limit of 1.414 makes the cutoff at 90 degrees.
+   *
+   * A miter limit for a desired angle can be computed as: miter_limit =
+   * 1/sin(angle/2)
+   *
+   * @param limit miter limit to set
+   **/
   void set_miter_limit(double limit);
 
   /** Modifies the current transformation matrix (CTM) by translating the
    * user-space origin by (tx, ty). This offset is interpreted as a user-space
    * coordinate according to the CTM in place before the new call to
-   * cairo_translate. In other words, the translation of the user-space origin
+   * translate. In other words, the translation of the user-space origin
    * takes place after any existing transformation.
    *
    * @param tx	amount to translate in the X direction
@@ -450,6 +508,8 @@ public:
    * subpath with one of the arc() calls. This makes things easier as it is no
    * longer necessary to manually compute the arc's initial coordinates for a
    * call to move_to().
+   *
+   * @since 1.2
    */
   void begin_new_sub_path();
 
@@ -463,6 +523,9 @@ public:
 
   /** Adds a line to the path from the current point to position (x, y) in
    * user-space coordinates. After this call the current point will be (x, y).
+   * 
+   * If there is no current point before the call to line_to()
+   * this function will behave as move_to(x, y).
    *
    * @param x	the X coordinate of the end of the new line
    * @param y	the Y coordinate of the end of the new line
@@ -473,6 +536,10 @@ public:
    * (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the
    * control points. After this call the current point will be (x3, y3).
    *
+   * If there is no current point before the call to curve_to()
+   * this function will behave as if preceded by a call to
+   * move_to(x1, y1).
+   * 
    * @param x1	the X coordinate of the first control point
    * @param y1	the Y coordinate of the first control point
    * @param x2	the X coordinate of the second control point
@@ -635,13 +702,18 @@ public:
 
   /** Adds a line segment to the path from the current point to the beginning
    * of the current subpath, (the most recent point passed to move_to()), and
-   * closes this subpath.
+   * closes this subpath. After this call the current point will be at the 
+   * joined endpoint of the sub-path.
    *
    * The behavior of close_path() is distinct from simply calling line_to()
    * with the equivalent coordinate in the case of stroking.  When a closed
    * subpath is stroked, there are no caps on the ends of the subpath. Instead,
    * there is a line join connecting the final and initial segments of the
    * subpath.
+   * 
+   * If there is no current point before the call to close_path(),
+   * this function will have no effect.
+   *
    */
   void close_path();
 
@@ -686,6 +758,26 @@ public:
    * @sa set_line_cap()
    * @sa set_dash()
    * @sa stroke_preserve().
+   * 
+   * Note: Degenerate segments and sub-paths are treated specially and
+   * provide a useful result. These can result in two different
+   * situations:
+   *
+   * 1. Zero-length "on" segments set in set_dash(). If the cap style is
+   * Cairo::LINE_CAP_ROUND or Cairo::LINE_CAP_SQUARE then these segments will
+   * be drawn as circular dots or squares respectively. In the case of
+   * Cairo::LINE_CAP_SQUARE, the orientation of the squares is determined by
+   * the direction of the underlying path.
+   *
+   * 2. A sub-path created by move_to() followed by either a close_path() or
+   * one or more calls to line_to() to the same coordinate as the move_to(). If
+   * the cap style is Cairo::LINE_CAP_ROUND then these sub-paths will be drawn
+   * as circular dots. Note that in the case of Cairo::LINE_CAP_SQUARE a
+   * degenerate sub-path will not be drawn at all, (since the correct
+   * orientation is indeterminate).
+   *
+   * In no case will a cap style of Cairo::LINE_CAP_BUTT cause anything to be
+   * drawn in the case of either degenerate segments or sub-paths.
    */
   void stroke();
 
@@ -719,12 +811,135 @@ public:
    * @sa fill().
    */
   void fill_preserve();
+  
+  /**
+   * Emits the current page for backends that support multiple pages, but
+   * doesn't clear it, so, the contents of the current page will be retained
+   * for the next page too.  Use show_page() if you want to get an
+   * empty page after the emission.
+   *
+   * This is a convenience function that simply calls Surface::copy_page() on
+   * @a cr's target.
+   */
   void copy_page();
+  
+  /**
+   * Emits and clears the current page for backends that support multiple
+   * pages.  Use copy_page() if you don't want to clear the page.
+   *
+   * This is a convenience function that simply calls
+   * Surface::show_page() on @a cr's target.
+   */
   void show_page();
+  
+  /**
+   * Tests whether the given point is inside the area that would be
+   * affected by a stroke() operation given the current path and
+   * stroking parameters. Surface dimensions and clipping are not taken
+   * into account.
+   *
+   * @param x X coordinate of the point to test
+   * @param y Y coordinate of the point to test
+   * @returns A non-zero value if the point is inside, or zero if outside.
+   *
+   * @sa stroke()
+   * @sa set_line_width()
+   * @sa set_line_join()
+   * @sa set_line_cap()
+   * @sa set_dash()
+   * @sa stroke_preserve().
+   *
+   */
   bool in_stroke(double x, double y) const;
+
+  /**
+   * Tests whether the given point is inside the area that would be
+   * affected by a fill() operation given the current path and
+   * filling parameters. Surface dimensions and clipping are not taken
+   * into account.
+   *
+   * @param x X coordinate of the point to test
+   * @param y Y coordinate of the point to test
+   * @returns A non-zero value if the point is inside, or zero if outside.
+   *
+   * @sa fill()
+   * @sa set_fill_rule()
+   * @sa fill_preserve()
+   */
   bool in_fill(double x, double y) const;
+
+  /**
+   * Tests whether the given point is inside the area that would be visible
+   * through the current clip, i.e. the area that would be filled by a paint()
+   * operation.
+   *
+   * Return value: A non-zero value if the point is inside, or zero if outside.
+   *
+   * @param x X coordinate of the point to test
+   * @param y Y coordinate of the point to test
+   *
+   * @sa clip()
+   * @sa clip_preserve()
+   *
+   * @since 1.10
+   */
   bool in_clip(double x, double y) const;
+
+  /**
+   * Computes a bounding box in user coordinates covering the area that would
+   * be affected, (the "inked" area), by a stroke() operation given the current
+   * path and stroke parameters. If the current path is empty, returns an empty
+   * rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken
+   * into account.
+   *
+   * Note that if the line width is set to exactly zero, then stroke_extents()
+   * will return an empty rectangle. Contrast with path_extents() which can be
+   * used to compute the non-empty bounds as the line width approaches zero.
+   *
+   * Note that stroke_extents() must necessarily do more work to compute the
+   * precise inked areas in light of the stroke parameters, so path_extents()
+   * may be more desirable for sake of performance if non-inked path extents
+   * are desired.
+   *
+   * @param x1 left of the resulting extents
+   * @param y1 top of the resulting extents
+   * @param x2 right of the resulting extents
+   * @param y2 bottom of the resulting extents
+   *
+   * @sa stroke()
+   * @sa set_line_width()
+   * @sa set_line_join()
+   * @sa set_line_cap()
+   * @sa set_dash()
+   * @sa stroke_preserve()
+   */
   void get_stroke_extents(double& x1, double& y1, double& x2, double& y2) const;
+
+  /**
+   * Computes a bounding box in user coordinates covering the area that would
+   * be affected, (the "inked" area), by a fill() operation given the current
+   * path and fill parameters. If the current path is empty, returns an empty
+   * rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken
+   * into account.
+   *
+   * Contrast with path_extents(), which is similar, but returns non-zero
+   * extents for some paths with no inked area, (such as a simple line
+   * segment).
+   *
+   * Note that fill_extents() must necessarily do more work to compute the
+   * precise inked areas in light of the fill rule, so path_extents() may be
+   * more desirable for sake of performance if the non-inked path extents are
+   * desired.
+   *
+   * @param x1 left of the resulting extents
+   * @param y1 top of the resulting extents
+   * @param x2 right of the resulting extents
+   * @param y2 bottom of the resulting extents
+   *
+   * @sa fill()
+   * @sa set_fill_rule()
+   * @sa full_preserve()
+   */
   void get_fill_extents(double& x1, double& y1, double& x2, double& y2) const;
 
   /** Reset the current clip region to its original, unrestricted state. That
@@ -751,7 +966,7 @@ public:
    *
    * Calling clip() can only make the clip region smaller, never larger.  But
    * the current clip is part of the graphics state, so a temporary restriction
-   * of the clip region can be achieved by calling cairo_clip() within a
+   * of the clip region can be achieved by calling clip() within a
    * save()/restore() pair. The only other means of increasing the size of the
    * clip region is reset_clip().
    *
@@ -763,7 +978,7 @@ public:
    * with the current path as it would be filled by fill() and according to the
    * current fill rule.
    *
-   * Unlike clip(), cairo_clip_preserve preserves the path within the cairo
+   * Unlike clip(), clip_preserve preserves the path within the cairo
    * Context.
    *
    * @sa clip()
@@ -790,65 +1005,303 @@ public:
    * This function will throw an exception if the clip region cannot be
    * represented as a list of user-space rectangles.
    *
-   * @Since 1.4
-   **/
-   void copy_clip_rectangle_list(std::vector<Rectangle>& rectangles) const;
+   * @param rectangles a vector to store the rectangles into
+   *
+   * @exception
+   *
+   * @since 1.4
+   */
+  void copy_clip_rectangle_list(std::vector<Rectangle>& rectangles) const;
 
+  /**
+   * Selects a family and style of font from a simplified description as a
+   * family name, slant and weight. Cairo provides no operation to list
+   * available family names on the system (this is a "toy", remember), but the
+   * standard CSS2 generic family names, ("serif", "sans-serif", "cursive",
+   * "fantasy", "monospace"), are likely to work as expected.
+   *
+   * Note: The select_font_face() function call is part of what the cairo
+   * designers call the "toy" text API. It is convenient for short demos and
+   * simple programs, but it is not expected to be adequate for serious
+   * text-using applications.
+   *
+   * If @a family starts with the string "@cairo:", or if no native font
+   * backends are compiled in, cairo will use an internal font family. The
+   * internal font family recognizes many modifiers in the @family string, most
+   * notably, it recognizes the string "monospace". That is, the family name
+   * "@cairo:monospace" will use the monospace version of the internal font
+   * family.
+   *
+   * For "real" font selection, see the font-backend-specific
+   * Cairo::FontFace::create functions for the font backend you are using. (For
+   * example, if you are using the freetype-based cairo-ft font backend, see
+   * Cairo::FtFontFace::create().) The resulting font face could then be used
+   * with Cairo::ScaledFont::create() and set_scaled_font().
+   *
+   * Similarly, when using the "real" font support, you can call directly into
+   * the underlying font system, (such as fontconfig or freetype), for
+   * operations such as listing available fonts, etc.
+   *
+   * It is expected that most applications will need to use a more
+   * comprehensive font handling and text layout library, (for example, pango),
+   * in conjunction with cairo.
+   *
+   * If text is drawn without a call to select_font_face(), (nor
+   * set_font_face() nor set_scaled_font()), the default family is
+   * platform-specific, but is essentially "sans-serif". Default slant is
+   * Cairo::FONT_SLANT_NORMAL, and default weight is Cairo::FONT_WEIGHT_NORMAL.
+   *
+   * This function is equivalent to a call to Cairo::ToyFontFace::create()
+   * followed by set_font_face().
+   *
+   * @param family a font family name, encoded in UTF-8
+   * @param slant the slant for the font
+   * @param weight the weight for the font
+   *
+   **/
   void select_font_face(const std::string& family, FontSlant slant, FontWeight weight);
+
+  /**
+   * Sets the current font matrix to a scale by a factor of @a size, replacing
+   * any font matrix previously set with set_font_size() or set_font_matrix().
+   * This results in a font size of @a size user space units. (More precisely,
+   * this matrix will result in the font's em-square being a @size by @a size
+   * square in user space.)
+   *
+   * If text is drawn without a call to set_font_size(), (nor set_font_matrix()
+   * nor set_scaled_font()), the default font size is 10.0.
+   *
+   * @param size the new font size, in user space units)
+   */
   void set_font_size(double size);
+
+  /**
+   * Sets the current font matrix to @matrix. The font matrix gives a
+   * transformation from the design space of the font (in this space, the
+   * em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is
+   * used (see set_font_size()), but a more complex font matrix can be used to
+   * shear the font or stretch it unequally along the two axes
+   *
+   * @param matrix a Cairo::Matrix describing a transform to be applied to the
+   * current font.
+   */
   void set_font_matrix(const Matrix& matrix);
+
+  /**
+   * Returns the current font matrix
+   *
+   * @param matrix a Cairo::Matrix to store the results into (in/out parameter)
+   * @sa set_font_matrix()
+   */
   void get_font_matrix(Matrix& matrix) const;
+
+  /**
+   * Sets a set of custom font rendering options. Rendering options are derived
+   * by merging these options with the options derived from underlying surface;
+   * if the value in @a options has a default value (like
+   * Cairo::ANTIALIAS_DEFAULT), then the value from the surface is used.
+   *
+   * @param options font options to use
+   */
   void set_font_options(const FontOptions& options);
 
   /* To keep 1.6.x ABI  */
   void set_font_matrix(const cairo_matrix_t& matrix);
   void get_font_matrix(cairo_matrix_t& matrix) const;
 
-  //TODO: Documentation.
+
   /**
+   * Retrieves font rendering options set via set_font_options(). Note that the
+   * returned options do not include any options derived from the underlying
+   * surface; they are literally the options passed to set_font_options().
+   *
+   * @param options a FontOptions object into which to store the retrieved
+   *   options. All existing values are overwritten
    * @since 1.8
    */
   void get_font_options(FontOptions& options) const;
 
-  //TODO: Documentation.
   /**
+   * Replaces the current font face, font matrix, and font options in the
+   * context with those of the @a scaled_font. Except for some translation, the
+   * current CTM of the context should be the same as that of the
+   * #cairo_scaled_font_t, which can be accessed using
+   * Cairo::ScaledFont::get_ctm().
+   *
+   * @param scaled_font a scaled font
    * @since 1.8
    */
   void set_scaled_font(const RefPtr<const ScaledFont>& scaled_font);
 
-  //TODO: Documentation.
-  /**
+  /** Gets the current scaled font.
+   *
    * @since 1.8
-   */
+   **/
   RefPtr<ScaledFont> get_scaled_font();
 
-  //TODO: Documentation:
+  /**
+   * A drawing operator that generates the shape from a string of UTF-8
+   * characters, rendered according to the current font_face, font_size
+   * (font_matrix), and font_options.
+   *
+   * This function first computes a set of glyphs for the string of text. The
+   * first glyph is placed so that its origin is at the current point. The
+   * origin of each subsequent glyph is offset from that of the previous glyph
+   * by the advance values of the previous glyph.
+   *
+   * After this call the current point is moved to the origin of where the
+   * next glyph would be placed in this same progression. That is, the current
+   * point will be at the origin of the final glyph offset by its advance
+   * values. This allows for easy display of a single logical string with
+   * multiple calls to show_text().
+   *
+   * Note: The show_text() function call is part of what the cairo
+   * designers call the "toy" text API. It is convenient for short demos and
+   * simple programs, but it is not expected to be adequate for serious
+   * text-using applications. See show_glyphs() for the "real" text
+   * display API in cairo.
+   *
+   * @param utf8 a string containing text encoded in UTF-8
+   */
   void show_text(const std::string& utf8);
+
+  /**
+   * A drawing operator that generates the shape from an array of glyphs,
+   * rendered according to the current font face, font size (font matrix), and
+   * font options.
+   *
+   * @param glyphs vector of glyphs to show
+   * @param num_glyphs number of glyphs to show
+   **/
   void show_glyphs(const std::vector<Glyph>& glyphs);
-  /** @since 1.8 */
+
+  /**
+   * This operation has rendering effects similar to show_glyphs() but, if the
+   * target surface supports it, uses the provided text and cluster mapping to
+   * embed the text for the glyphs shown in the output. If the target does not
+   * support the extended attributes, this function acts like the basic
+   * show_glyphs() as if it had been passed @a glyphs and @a num_glyphs.
+   *
+   * The mapping between @a utf8 and @a glyphs is provided by an array of
+   * <firstterm>clusters</firstterm>. Each cluster covers a number of text
+   * bytes and glyphs, and neighboring clusters cover neighboring areas of @a
+   * utf8 and @a glyphs. The clusters should collectively cover @a utf8 and @a
+   * glyphs in entirety.
+   *
+   * The first cluster always covers bytes from the beginning of @a utf8. If @a
+   * cluster_flags do not have the Cairo::TEXT_CLUSTER_FLAG_BACKWARD set, the
+   * first cluster also covers the beginning of @a glyphs, otherwise it covers
+   * the end of the @a glyphs array and following clusters move backward.
+   *
+   * See Cairo::TextCluster for constraints on valid clusters.
+   *
+   * @param utf8: a string of text encoded in UTF-8
+   * @param glyphs: vector of glyphs to show
+   * @param clusters: vector of cluster mapping information
+   * @param cluster_flags: cluster mapping flags
+   *
+   * @since 1.8
+   **/
   void show_text_glyphs(const std::string& utf8,
                         const std::vector<Glyph>& glyphs,
                         const std::vector<TextCluster>& clusters,
                         TextClusterFlags cluster_flags);
-
+  /// @{
+  /** Gets the current font face
+   **/
   RefPtr<FontFace> get_font_face();
   RefPtr<const FontFace> get_font_face() const;
+  /// @}
 
+  /**
+   * Gets the font extents for the currently selected font.
+   *
+   * @param extents a Cairo::FontExtents object
+   */
   void get_font_extents(FontExtents& extents) const;
+
+  /**
+   * Replaces the current font face in the context with @a font_face
+   * @a font_face. The replaced font face in the context will be destroyed if
+   * there are no other references to it.
+   *
+   * @param font_face a font face
+   */
+  //FIXME: C API acceps NULL to restore the default font. Does C++ API support that?
   void set_font_face(const RefPtr<const FontFace>& font_face);
+
+  /**
+   * Gets the extents for a string of text. The extents describe a user-space
+   * rectangle that encloses the "inked" portion of the text, (as it would be
+   * drawn by show_text()). Additionally, the x_advance and y_advance values
+   * indicate the amount by which the current point would be advanced by
+   * show_text().
+   *
+   * Note that whitespace characters do not directly contribute to the size of
+   * the rectangle (extents.width and extents.height). They do contribute
+   * indirectly by changing the position of non-whitespace characters. In
+   * particular, trailing whitespace characters are likely to not affect the
+   * size of the rectangle, though they will affect the x_advance and y_advance
+   * values.
+   *
+   * @param utf8 a string of text encoded in UTF-8
+   * @param extents a TextExtents object
+   */
   void get_text_extents(const std::string& utf8, TextExtents& extents) const;
+
+  /**
+   * Gets the extents for an array of glyphs. The extents describe a user-space
+   * rectangle that encloses the "inked" portion of the glyphs, (as they would
+   * be drawn by show_glyphs()). Additionally, the x_advance and y_advance
+   * values indicate the amount by which the current point would be advanced by
+   * show_glyphs().
+   *
+   * Note that whitespace glyphs do not contribute to the size of the rectangle
+   * (extents.width and extents.height).
+   *
+   * @param glyphs a vector of glyphs
+   * @param extents a TextExtents object
+   */
   void get_glyph_extents(const std::vector<Glyph>& glyphs, TextExtents& extents) const;
+
+  /**
+   * Adds closed paths for text to the current path. The generated path if
+   * filled, achieves an effect similar to that of show_text().
+   *
+   * Text conversion and positioning is done similar to show_text().
+   *
+   * Like show_text(), After this call the current point is moved to the origin
+   * of where the next glyph would be placed in this same progression. That is,
+   * the current point will be at the origin of the final glyph offset by its
+   * advance values. This allows for chaining multiple calls to to text_path()
+   * without having to set current point in between.
+   *
+   * Note: The text_path() function call is part of what the cairo designers
+   * call the "toy" text API. It is convenient for short demos and simple
+   * programs, but it is not expected to be adequate for serious text-using
+   * applications. See glyph_path() for the "real" text path API in cairo.
+   *
+   * @param utf8 a string of text encoded in UTF-8
+   */
   void text_path(const std::string& utf8);
+
+  /** Adds closed paths for the glyphs to the current path. The generated path
+   * if filled, achieves an effect similar to that of show_glyphs().
+   *
+   * @param glyphs a vector of glyphs
+   */
   void glyph_path(const std::vector<Glyph>& glyphs);
 
   /** Gets the current compositing operator for a cairo Context
    */
   Operator get_operator() const;
 
+  /// @{
   /** Gets the current source pattern for the Context
    */
   RefPtr<Pattern> get_source();
   RefPtr<const Pattern> get_source() const;
+  /// @}
 
   /** Gets the current tolerance value, as set by set_tolerance()
    */
@@ -862,21 +1315,34 @@ public:
    * final point reached by the path so far.
    *
    * The current point is returned in the user-space coordinate system. If
-   * there is no defined current point then x and y will both be set to 0.0.
+   * there is no defined current point then x and y will both be set to 0.0. It
+   * is possible to check this in advance with has_current_point().
    *
    * Most path construction functions alter the current point. See the
    * following for details on how they affect the current point: clear_path(),
    * move_to(), line_to(), curve_to(), arc(), rel_move_to(), rel_line_to(),
    * rel_curve_to(), arc(), and text_path()
    *
+   * Some functions use and alter the current point but do not otherwise change
+   * current path: show_text().
+   *
+   * Some functions unset the current path and as a result, current point:
+   * fill(), stroke().
+   *
    * @param x	return value for X coordinate of the current point
    * @param y	return value for Y coordinate of the current point
    *
-   * @see has_current_point
+   * @sa has_current_point()
    */
   void get_current_point (double& x, double& y) const;
 
-  /** Checks if there is a current point defined
+  /**
+   * Checks if there is a current point defined. See get_current_point() for
+   * details on the current point.
+   *
+   * @returns @c true if a current point is defined.
+   *
+   * @since 1.6
    */
   bool has_current_point() const;
 
@@ -884,7 +1350,10 @@ public:
    */
   FillRule get_fill_rule() const;
 
-  /** Gets the current line width, as set by set_line_width()
+  /**
+   * Gets the current line width, as set by set_line_width(). Note that the
+   * value is unchanged even if the CTM has changed between the calls to
+   * set_line_width() and get_line_width().
    */
   double get_line_width() const;
 
@@ -906,35 +1375,34 @@ public:
    * @param dashes return value for the dash array.
    * @param offset return value for the current dash offset.
    *
-   * Since: 1.4
+   * @since 1.4
    **/
   void get_dash(std::vector<double>& dashes, double& offset) const;
 
 
   /** Stores the current transformation matrix (CTM) into matrix.
    *
-   * @param matrix	return value for the matrix
+   * @param matrix return value for the matrix
    */
   void get_matrix(Matrix& matrix);
 
   /* To keep 1.6.x ABI  */
   void get_matrix(cairo_matrix_t& matrix);
 
-  /** @since 1.8
+  /**
+   * Returns the current transformation matrix (CTM)
+   * @since 1.8
    */
   Matrix get_matrix() const;
 
+  /// @{
   /** Gets the target surface associated with this Context.
    *
    * @exception
    */
   RefPtr<Surface> get_target();
-
-  /** Gets the target surface associated with this Context.
-   *
-   * @exception
-   */
   RefPtr<const Surface> get_target() const;
+  /// @}
 
   //TODO: Copy or reference-count a Path somethow instead of asking the caller to delete it?
   /** Creates a copy of the current path and returns it to the user.
@@ -947,34 +1415,34 @@ public:
    */
   Path* copy_path() const;
 
-/**
- * Computes a bounding box in user-space coordinates covering the points on
- * the current path. If the current path is empty, returns an empty rectangle
- * ((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and
- * clipping are not taken into account.
- *
- * Contrast with fill_extents() and stroke_extents() which return the extents
- * of only the area that would be "inked" by the corresponding drawing
- * operations.
- *
- * The result of path_extents() is defined as equivalent to the limit of
- * stroke_extents() with Cairo::LINE_CAP_ROUND as the line width approaches
- * 0.0, (but never reaching the empty-rectangle returned by stroke_extents()
- * for a line width of 0.0).
- *
- * Specifically, this means that zero-area sub-paths such as
- * move_to();line_to() segments, (even degenerate cases where the coordinates
- * to both calls are identical), will be considered as contributing to the
- * extents. However, a lone move_to() will not contribute to the results of
- * path_extents().
- *
- * @param x1 left of the resulting extents
- * @param y1 top of the resulting extents
- * @param x2 right of the resulting extents
- * @param y2 bottom of the resulting extents
- *
- * @since 1.6
- **/
+  /**
+   * Computes a bounding box in user-space coordinates covering the points on
+   * the current path. If the current path is empty, returns an empty rectangle
+   * ((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and
+   * clipping are not taken into account.
+   *
+   * Contrast with fill_extents() and stroke_extents() which return the extents
+   * of only the area that would be "inked" by the corresponding drawing
+   * operations.
+   *
+   * The result of path_extents() is defined as equivalent to the limit of
+   * stroke_extents() with LINE_CAP_ROUND as the line width approaches 0.0, (but
+   * never reaching the empty-rectangle returned by stroke_extents() for a line
+   * width of 0.0).
+   *
+   * Specifically, this means that zero-area sub-paths such as
+   * move_to();line_to() segments, (even degenerate cases where the coordinates
+   * to both calls are identical), will be considered as contributing to the
+   * extents. However, a lone move_to() will not contribute to the results of
+   * path_extents().
+   *
+   * @param x1 left of the resulting extents
+   * @param y1 top of the resulting extents
+   * @param x2 right of the resulting extents
+   * @param y2 bottom of the resulting extents
+   *
+   * @since 1.6
+   */
   void get_path_extents(double& x1, double& y1, double& x2, double& y2) const;
 
   /** Gets a flattened copy of the current path and returns it to the user
@@ -1037,6 +1505,8 @@ public:
    * cr->pop_group_to_source();
    * cr->paint_with_alpha(alpha);
    * @endcode
+   *
+   * @since 1.2
    */
   void push_group();
 
@@ -1052,6 +1522,8 @@ public:
    * which you should see for a more detailed description of group rendering.
    *
    * @param content indicates the type of group that will be created
+   *
+   * @since 1.2
    */
   void push_group_with_content(Content content);
 
@@ -1066,6 +1538,8 @@ public:
    *
    * @return a (surface) pattern containing the results of all drawing
    * operations performed to the group.
+   *
+   * @since 1.2
    **/
   RefPtr<Pattern> pop_group();
 
@@ -1087,6 +1561,8 @@ public:
    * The pop_group() function calls restore(), (balancing a call to save() by
    * the push_group function), so that any changes to the graphics state will
    * not be visible outside the group.
+   *
+   * @since 1.2
    **/
   void pop_group_to_source();
 
@@ -1100,11 +1576,13 @@ public:
    *
    * @exception
    *
+   * @since 1.2
    **/
   RefPtr<Surface> get_group_target();
 
-  /**
-   * Same as the non-const version but returns a reference to a const Surface
+  /** Same as the non-const version but returns a reference to a const Surface
+   *
+   * @since 1.2
    */
   RefPtr<const Surface> get_group_target() const;
 
diff --git a/cairomm/device.h b/cairomm/device.h
index 396e0ab..3cb1e7c 100644
--- a/cairomm/device.h
+++ b/cairomm/device.h
@@ -50,6 +50,8 @@ namespace Cairo
  * released in an exception-safe manner.
  *
  * This is a reference-counted object that should be used via Cairo::RefPtr.
+ *
+ * @since 1.10
  */
 class Device
 {
diff --git a/cairomm/enums.h b/cairomm/enums.h
index f20044c..26102c0 100644
--- a/cairomm/enums.h
+++ b/cairomm/enums.h
@@ -30,133 +30,458 @@ namespace Cairo
 typedef cairo_status_t ErrorStatus;
 #endif //DOXYGEN_IGNORE_THIS
 
-
+/**
+ * Cairo::Operator is used to set the compositing operator for all cairo
+ * drawing operations.
+ *
+ * The default operator is Cairo::OPERATOR_OVER.
+ *
+ * The operators marked as @a unbounded modify their destination even outside
+ * of the mask layer (that is, their effect is not bound by the mask layer).
+ * However, their effect can still be limited by way of clipping.
+ *
+ * To keep things simple, the operator descriptions here document the behavior
+ * for when both source and destination are either fully transparent or fully
+ * opaque. The actual implementation works for translucent layers too. For a
+ * more detailed explanation of the effects of each operator, including the
+ * mathematical definitions, see
+ * <a href="http://cairographics.org/operators/">this</a>
+ *
+ **/
 typedef enum
 {
+    /**
+     * Clear destination layer (bounded)
+     */
     OPERATOR_CLEAR = CAIRO_OPERATOR_CLEAR,
 
+    /**
+     * Replace destination layer (bounded)
+     */
     OPERATOR_SOURCE = CAIRO_OPERATOR_SOURCE,
+
+    /**
+     * Draw source layer on top of destination layer (bounded)
+     */
     OPERATOR_OVER = CAIRO_OPERATOR_OVER,
+
+    /**
+     * Draw source where there was destination content (unbounded)
+     */
     OPERATOR_IN = CAIRO_OPERATOR_IN,
+
+    /**
+     * Draw source where there was no destination content (unbounded)
+     */
     OPERATOR_OUT = CAIRO_OPERATOR_OUT,
+
+    /**
+     * Draw source on top of destination content and only there
+     */
     OPERATOR_ATOP = CAIRO_OPERATOR_ATOP,
 
+    /**
+     * Ignore the source
+     */
     OPERATOR_DEST = CAIRO_OPERATOR_DEST,
+
+    /**
+     * Draw destination on top of source
+     */
     OPERATOR_DEST_OVER = CAIRO_OPERATOR_DEST_OVER,
+
+    /**
+     * Leave destination only where there was source content (unbounded)
+     */
     OPERATOR_DEST_IN = CAIRO_OPERATOR_DEST_IN,
+
+    /**
+     * Leave destination only where there was no source content
+     */
     OPERATOR_DEST_OUT = CAIRO_OPERATOR_DEST_OUT,
+
+    /**
+     * Leave destination on top of source content and only there (unbounded)
+     */
     OPERATOR_DEST_ATOP = CAIRO_OPERATOR_DEST_ATOP,
 
+    /**
+     * Source and destination are shown where there is only one of them
+     */
     OPERATOR_XOR = CAIRO_OPERATOR_XOR,
+
+    /**
+     * Source and destination layers are accumulated
+     */
     OPERATOR_ADD = CAIRO_OPERATOR_ADD,
+
+    /**
+     * Like over, but assuming source and dest are disjoint geometries
+     */
     OPERATOR_SATURATE = CAIRO_OPERATOR_SATURATE
 } Operator;
 
 
+/**
+ * Specifies the type of antialiasing to do when rendering text or shapes.
+ *
+ * The interpretation of Cairo::ANTIALIAS_DEFAULT is left entirely up to
+ * the backend.
+ */
 typedef enum
 {
+    /**
+     * Use the default antialiasing for the subsystem and target device
+     */
     ANTIALIAS_DEFAULT = CAIRO_ANTIALIAS_DEFAULT,
+
+    /**
+     * Use bilevel alpha mask
+     */
     ANTIALIAS_NONE = CAIRO_ANTIALIAS_NONE,
+
+    /**
+     * Perform single-color antialiasing (using shades of gray for black text on
+     * white background, for example).
+     */
     ANTIALIAS_GRAY = CAIRO_ANTIALIAS_GRAY,
+
+    /**
+     * Perform antialiasing by taing advantage of the order of subpixel elements
+     * on devices such as LCD panels
+     */
     ANTIALIAS_SUBPIXEL = CAIRO_ANTIALIAS_SUBPIXEL
 } Antialias;
 
+/**
+ * Cairo::FillRule is used to select how paths are filled. For both fill rules,
+ * whether or not a point is included in the fill is determined by taking a ray
+ * from that point to infinity and looking at intersections with the path. The
+ * ray can be in any direction, as long as it doesn't pass through the end
+ * point of a segment or have a tricky intersection such as intersecting
+ * tangent to the path. (Note that filling is not actually implemented in this
+ * way. This is just a description of the rule that is applied.)
+ *
+ * The default fill rule is Cairo::FILL_RULE_WINDING.
+ *
+ * New entries may be added in future versions.
+ **/
 typedef enum
 {
+    /**
+     * If the path crosses the ray from left-to-right, counts +1. If the path
+     * crosses the ray from right to left, counts -1. (Left and right are
+     * determined from the perspective of looking along the ray from the
+     * starting point.) If the total count is non-zero, the point will be
+     * filled.
+     */
     FILL_RULE_WINDING = CAIRO_FILL_RULE_WINDING,
+
+    /**
+     * Counts the total number of intersections, without regard to the
+     * orientation of the contour. If the total number of intersections is odd,
+     * the point will be filled.
+     */
     FILL_RULE_EVEN_ODD = CAIRO_FILL_RULE_EVEN_ODD
 } FillRule;
 
-
+/**
+ * Specifies how to render the endpoints of the path when stroking.
+ *
+ * The default line cap style is Cairo::LINE_CAP_BUTT.
+ **/
 typedef enum
 {
+    /**
+     * Start(stop) the line exactly at the start(end) point
+     */
     LINE_CAP_BUTT = CAIRO_LINE_CAP_BUTT,
+
+    /**
+     * Use a round ending, the center of teh circle is teh end point
+     */
     LINE_CAP_ROUND = CAIRO_LINE_CAP_ROUND,
+
+    /**
+     * Use squared ending, the center of teh square is the end point
+     */
     LINE_CAP_SQUARE = CAIRO_LINE_CAP_SQUARE
 } LineCap;
 
-
+/**
+ * Specifies how to render the junction of two lines when stroking.
+ *
+ * The default line join style is Cairo::LINE_JOIN_MITER.
+ */
 typedef enum
 {
+    /**
+     * Use a sharp (angled) corner, see Context::set_miter_limit()
+     */
     LINE_JOIN_MITER = CAIRO_LINE_JOIN_MITER,
+
+    /**
+     * Use a rounded join, the center of teh circle is the joint point
+     */
     LINE_JOIN_ROUND = CAIRO_LINE_JOIN_ROUND,
+
+    /**
+     * Use cut-off join, the join is cut off at half the line width from the
+     * join point
+     */
     LINE_JOIN_BEVEL = CAIRO_LINE_JOIN_BEVEL
 } LineJoin;
 
-
+/**
+ * Specifies variants of a font face based on their slant.
+ */
 typedef enum
 {
-  FONT_SLANT_NORMAL = CAIRO_FONT_SLANT_NORMAL,
-  FONT_SLANT_ITALIC = CAIRO_FONT_SLANT_ITALIC,
-  FONT_SLANT_OBLIQUE = CAIRO_FONT_SLANT_OBLIQUE
+    /**
+     * Upright font style
+     */
+    FONT_SLANT_NORMAL = CAIRO_FONT_SLANT_NORMAL,
+
+    /**
+     * Italic font style
+     */
+    FONT_SLANT_ITALIC = CAIRO_FONT_SLANT_ITALIC,
+
+    /**
+     * Oblique font style
+     */
+    FONT_SLANT_OBLIQUE = CAIRO_FONT_SLANT_OBLIQUE
 } FontSlant;
 
+/**
+ * Specifies variants of a font face based on their weight.
+ */
 typedef enum
 {
-  FONT_WEIGHT_NORMAL = CAIRO_FONT_WEIGHT_NORMAL,
-  FONT_WEIGHT_BOLD = CAIRO_FONT_WEIGHT_BOLD
+    /**
+     * Normal font weight
+     */
+    FONT_WEIGHT_NORMAL = CAIRO_FONT_WEIGHT_NORMAL,
+
+    /**
+     * Bold font weight
+     */
+    FONT_WEIGHT_BOLD = CAIRO_FONT_WEIGHT_BOLD
 } FontWeight;
 
-
+/**
+ * Cairo::Content is used to describe the content that a surface will contain,
+ * whether color information, alpha information (translucence vs. opacity), or
+ * both.
+ */
 typedef enum
 {
+    /**
+     * The surface will hold color content only.
+     */
     CONTENT_COLOR = CAIRO_CONTENT_COLOR,
+
+    /**
+     * The surface will hold alpha content only.
+     */
     CONTENT_ALPHA = CAIRO_CONTENT_ALPHA,
+
+    /**
+     * The surface will hold color and alpha content.
+     */
     CONTENT_COLOR_ALPHA = CAIRO_CONTENT_COLOR_ALPHA
 } Content;
 
-//TODO: Mark as new in 1.10
+/**
+ * @since 1.10
+ */
+
 typedef enum
 {
+    /**
+     *
+     */
     DEVICE_TYPE_DRM = CAIRO_DEVICE_TYPE_DRM,
+
+    /**
+     *
+     */
     DEVICE_TYPE_GL = CAIRO_DEVICE_TYPE_GL,
+
+    /**
+     *
+     */
     DEVICE_TYPE_SCRIPT = CAIRO_DEVICE_TYPE_SCRIPT,
+
+    /**
+     *
+     */
     DEVICE_TYPE_XCB = CAIRO_DEVICE_TYPE_XCB,
+
+    /**
+     *
+     */
     DEVICE_TYPE_XLIB = CAIRO_DEVICE_TYPE_XLIB,
+
+    /**
+     *
+     */
     DEVICE_TYPE_XML = CAIRO_DEVICE_TYPE_XML
 } DeviceType;
 
+/**
+ * Cairo::Format is used to identify the memory format of
+ * image data.
+ *
+ * New entries may be added in future versions.
+ **/
 typedef enum
 {
+    /**
+     * Each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then
+     * red, then green, then blue. The 32-bit quantities are stored
+     * native-endian. Pre-multiplied alpha is used. (That is, 50% transparent
+     * red is 0x80800000,
+     */
     FORMAT_ARGB32 = CAIRO_FORMAT_ARGB32,
+
+    /**
+     * Each pixel is a 32-bit quantity, with the upper 8 bits unused. Red,
+     * Green, and Blue are stored in the remaining 24 bits in that order.
+     */
     FORMAT_RGB24 = CAIRO_FORMAT_RGB24,
+
+    /**
+     * Each pixel is a 8-bit quantity holding an alpha value
+     */
     FORMAT_A8 = CAIRO_FORMAT_A8,
+
+    /**
+     * Each pikel is a 1-bit quentity holding an alpha value. Pixels are packed
+     * together into 32-bit quantities. The ordering of the bits matches the
+     * endianess of the platform. On a big-endian machine, the first pixel is in
+     * the uppermost bit, on a little endian machine the first pixel is in the
+     * least-significant bit.
+     */
     FORMAT_A1 = CAIRO_FORMAT_A1,
-    FORMAT_RGB16_565 = CAIRO_FORMAT_RGB16_565 /* @< @deprecated This format value is deprecated. It has never been properly implemented in cairo and is unnecessary. */
+
+    /**
+     * Each fixel is a 16-bit quantity with red in the upper 5 bits, then green
+     * in the middle 6 bits, and blue in the lower 5 bits
+     */
+    FORMAT_RGB16_565 = CAIRO_FORMAT_RGB16_565
 } Format;
 
 
+/**
+ * Cairo::Extend is used to describe how pattern color/alpha will be determined
+ * for areas "outside" the pattern's natural area, (for example, outside the
+ * surface bounds or outside the gradient geometry).
+ *
+ * Mesh patterns are not affected by the extend mode.
+ *
+ * The default extend mode is Cairo::EXTEND_NONE for surface patterns and
+ * Cairo::EXTEND_PAD for gradient patterns.
+ *
+ * New entries may be added in future versions.
+ **/
 typedef enum
 {
+    /**
+     * Pixels outside of the source pattern are fully transparent
+     */
     EXTEND_NONE = CAIRO_EXTEND_NONE,
+
+    /**
+     * The pattern is tiled by repeating
+     */
     EXTEND_REPEAT = CAIRO_EXTEND_REPEAT,
+
+    /**
+     * The pattern is tiled by reflecting at the edges (Implemented for surface
+     * patterns since 1.6)
+     */
     EXTEND_REFLECT = CAIRO_EXTEND_REFLECT,
+
+    /**
+     * Pixels outside of the pattern copy the closest pixel from the source
+     * (Since 1.2; but only implemented for surface patterns since 1.6)
+     */
     EXTEND_PAD = CAIRO_EXTEND_PAD
 } Extend;
 
-
+/**
+ * Cairo::Filter is used to indicate what filtering should be applied when
+ * reading pixel values from patterns. See Cairo::SurfacePattern::set_filter()
+ * for indicating the desired filter to be used with a particular pattern.
+ */
 typedef enum
 {
+    /**
+     * A high-performance filter, with quality similar to Cairo::FILTER_NEAREST
+     */
     FILTER_FAST = CAIRO_FILTER_FAST,
+
+    /**
+     * A reasonable-performance filter, with quality similar to
+     * Cairo::FILTER_BILINEAR
+     */
     FILTER_GOOD = CAIRO_FILTER_GOOD,
+
+    /**
+     * The highest-quality available, performance may not be suitable for
+     * interactive use.
+     */
     FILTER_BEST = CAIRO_FILTER_BEST,
+
+    /**
+     * Nearest-neighbor filtering
+     */
     FILTER_NEAREST = CAIRO_FILTER_NEAREST,
+
+    /**
+     * Linear interpolation in two dimensions
+     */
     FILTER_BILINEAR = CAIRO_FILTER_BILINEAR,
+
+    /**
+     * This filter value is currently unimplemented, and should not be used in
+     * current code.
+     */
     FILTER_GAUSSIAN = CAIRO_FILTER_GAUSSIAN
 } Filter;
 
 /**
  * The subpixel order specifies the order of color elements within each pixel on
  * the display device when rendering with an antialiasing mode of
- * ANTIALIAS_SUBPIXEL.
+ * Cairo::ANTIALIAS_SUBPIXEL.
  **/
 typedef enum
 {
-    SUBPIXEL_ORDER_DEFAULT = CAIRO_SUBPIXEL_ORDER_DEFAULT, /**< Use the default subpixel order for for the target device */
-    SUBPIXEL_ORDER_RGB = CAIRO_SUBPIXEL_ORDER_RGB, /**< Subpixel elements are arranged horizontally with red at the left */
-    SUBPIXEL_ORDER_BGR = CAIRO_SUBPIXEL_ORDER_BGR, /**<  Subpixel elements are arranged horizontally with blue at the left */
-    SUBPIXEL_ORDER_VRGB = CAIRO_SUBPIXEL_ORDER_VRGB, /**< Subpixel elements are arranged vertically with red at the top */
-    SUBPIXEL_ORDER_VBGR = CAIRO_SUBPIXEL_ORDER_VBGR /**< Subpixel elements are arranged vertically with blue at the top */
+    /**
+     * Use the default subpixel order for for the target device
+     */
+    SUBPIXEL_ORDER_DEFAULT = CAIRO_SUBPIXEL_ORDER_DEFAULT,
+
+    /**
+     * Subpixel elements are arranged horizontally with red at the left
+     */
+    SUBPIXEL_ORDER_RGB = CAIRO_SUBPIXEL_ORDER_RGB,
+
+    /**
+     * Subpixel elements are arranged horizontally with blue at the left
+     */
+    SUBPIXEL_ORDER_BGR = CAIRO_SUBPIXEL_ORDER_BGR,
+
+    /**
+     * Subpixel elements are arranged vertically with red at the top
+     */
+    SUBPIXEL_ORDER_VRGB = CAIRO_SUBPIXEL_ORDER_VRGB,
+
+    /**
+     * Subpixel elements are arranged vertically with blue at the top
+     */
+    SUBPIXEL_ORDER_VBGR = CAIRO_SUBPIXEL_ORDER_VBGR
 } SubpixelOrder;
 
 
@@ -171,11 +496,32 @@ typedef enum
  **/
 typedef enum
 {
-    HINT_STYLE_DEFAULT = CAIRO_HINT_STYLE_DEFAULT, /**< Use the default hint style for font backend and target device */
-    HINT_STYLE_NONE = CAIRO_HINT_STYLE_NONE, /**< Do not hint outlines */
-    HINT_STYLE_SLIGHT = CAIRO_HINT_STYLE_SLIGHT, /**< Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes. */
-    HINT_STYLE_MEDIUM = CAIRO_HINT_STYLE_MEDIUM, /**< Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast */
-    HINT_STYLE_FULL = CAIRO_HINT_STYLE_FULL /**< Hint outlines to maximize contrast */
+    /**
+     * Use the default hint style for font backend and target device
+     */
+    HINT_STYLE_DEFAULT = CAIRO_HINT_STYLE_DEFAULT,
+
+    /**
+     * Do not hint outlines
+     */
+    HINT_STYLE_NONE = CAIRO_HINT_STYLE_NONE,
+
+    /**
+     * Hint outlines slightly to improve contrast while retaining food fidelity
+     * to the original shapes
+     */
+    HINT_STYLE_SLIGHT = CAIRO_HINT_STYLE_SLIGHT,
+
+    /**
+     * Hint outlines with medium strength giving a compromise between fidelity
+     * to the original shapes and contrast
+     */
+    HINT_STYLE_MEDIUM = CAIRO_HINT_STYLE_MEDIUM,
+
+    /**
+     * Hint outlines to maximize contrast
+     */
+    HINT_STYLE_FULL = CAIRO_HINT_STYLE_FULL
 } HintStyle;
 
 
@@ -187,58 +533,247 @@ typedef enum
  **/
 typedef enum
 {
+    /**
+     * Hint metrics in the default manner for the font backend and target device
+     */
     HINT_METRICS_DEFAULT = CAIRO_HINT_METRICS_DEFAULT,
-    /**< Hint metrics in the default manner for the font backend and target device */
+
+    /**
+     * Do not hint font metrics
+     */
     HINT_METRICS_OFF = CAIRO_HINT_METRICS_OFF,
-    /**< Do not hint font metrics */
+
+    /**
+     * Hint font metrics
+     */
     HINT_METRICS_ON = CAIRO_HINT_METRICS_ON
-    /**< Hint font metrics */
 } HintMetrics;
 
+/**
+ * Cairo::SurfaceType is used to describe the type of a given surface. The
+ * surface types are also known as "backends" or "surface backends" within
+ * cairo.
+ *
+ * The surface type can be queried with Surface::get_type()
+ *
+ * The various Cairo::Surface functions can be used with surfaces of
+ * any type, but some backends also provide type-specific functions
+ * that must only be called with a surface of the appropriate
+ * type.
+ *
+ * New entries may be added in future versions.
+ *
+ * @since 1.2
+ **/
 typedef enum
 {
+    /**
+     * The surface is of type image
+     */
     SURFACE_TYPE_IMAGE = CAIRO_SURFACE_TYPE_IMAGE,
+
+    /**
+     * The surface is of type pdf
+     */
     SURFACE_TYPE_PDF = CAIRO_SURFACE_TYPE_PDF,
+
+    /**
+     * The surface is of type ps
+     */
     SURFACE_TYPE_PS = CAIRO_SURFACE_TYPE_PS,
+
+    /**
+     * The surface is of type xlim
+     */
     SURFACE_TYPE_XLIB = CAIRO_SURFACE_TYPE_XLIB,
+
+    /**
+     * The surface is of type xcb
+     */
     SURFACE_TYPE_XCB = CAIRO_SURFACE_TYPE_XCB,
+
+    /**
+     * The surface is of type glitz
+     */
     SURFACE_TYPE_GLITZ = CAIRO_SURFACE_TYPE_GLITZ,
+
+    /**
+     * The surface is of type quartz
+     */
     SURFACE_TYPE_QUARTZ = CAIRO_SURFACE_TYPE_QUARTZ,
+
+    /**
+     * The surface is of type win32
+     */
     SURFACE_TYPE_WIN32 = CAIRO_SURFACE_TYPE_WIN32,
+
+    /**
+     * The surface is of type beos
+     */
     SURFACE_TYPE_BEOS = CAIRO_SURFACE_TYPE_BEOS,
+
+    /**
+     * The surface is of type directfb
+     */
     SURFACE_TYPE_DIRECTFB = CAIRO_SURFACE_TYPE_DIRECTFB,
+
+    /**
+     * The surface is of type svg
+     */
     SURFACE_TYPE_SVG = CAIRO_SURFACE_TYPE_SVG,
+
+    /**
+     * The surface is of type os2
+     */
     SURFACE_TYPE_OS2 = CAIRO_SURFACE_TYPE_OS2,
+
+    /**
+     * The surface is a win32 printing surface
+     */
     SURFACE_TYPE_WIN32_PRINTING = CAIRO_SURFACE_TYPE_WIN32_PRINTING,
+
+    /**
+     * The surface is of type quartz_image
+     */
     SURFACE_TYPE_QUARTZ_IMAGE = CAIRO_SURFACE_TYPE_QUARTZ_IMAGE,
-    SURFACE_TYPE_SCRIPT = CAIRO_SURFACE_TYPE_SCRIPT, /*!< @since: 1.10 */
-    SURFACE_TYPE_QT = CAIRO_SURFACE_TYPE_QT, /*!< @since: 1.10 */
-    SURFACE_TYPE_RECORDING = CAIRO_SURFACE_TYPE_RECORDING, /*!< @since: 1.10 */
-    SURFACE_TYPE_VG = CAIRO_SURFACE_TYPE_VG, /*!< @since: 1.10 */
-    SURFACE_TYPE_GL = CAIRO_SURFACE_TYPE_GL, /*!< @since: 1.10 */
-    SURFACE_TYPE_DRM = CAIRO_SURFACE_TYPE_DRM, /*!< @since: 1.10 */
-    SURFACE_TYPE_TEE = CAIRO_SURFACE_TYPE_TEE, /*!< @since: 1.10 */
-    SURFACE_TYPE_XML = CAIRO_SURFACE_TYPE_XML, /*!< @since: 1.10 */
-    SURFACE_TYPE_SKIA = CAIRO_SURFACE_TYPE_SKIA, /*!< @since: 1.10 */
-    SURFACE_TYPE_SUBSURFACE = CAIRO_SURFACE_TYPE_SUBSURFACE /*!< @since: 1.10 */
+
+    /**
+     * The surface is of type script
+     * @since 1.10
+     */
+    SURFACE_TYPE_SCRIPT = CAIRO_SURFACE_TYPE_SCRIPT,
+
+    /**
+     * The surface is of type Qt
+     * @since 1.10
+     */
+    SURFACE_TYPE_QT = CAIRO_SURFACE_TYPE_QT,
+
+    /**
+     * The surface is of type recording
+     * @since 1.10
+     */
+    SURFACE_TYPE_RECORDING = CAIRO_SURFACE_TYPE_RECORDING,
+
+    /**
+     * The surface is a OpenVg surface
+     * @since 1.10
+     */
+    SURFACE_TYPE_VG = CAIRO_SURFACE_TYPE_VG,
+
+    /**
+     * The surface is of type OpenGl
+     * @since 1.10
+     */
+    SURFACE_TYPE_GL = CAIRO_SURFACE_TYPE_GL,
+
+    /**
+     * The surface is of type Direct Render Manager
+     * @since 1.10
+     */
+    SURFACE_TYPE_DRM = CAIRO_SURFACE_TYPE_DRM,
+
+    /**
+     * The surface is of type script 'tee' (a multiplexing surface)
+     * @since 1.10
+     */
+    SURFACE_TYPE_TEE = CAIRO_SURFACE_TYPE_TEE,
+
+    /**
+     * The surface is of type XML (for debugging)
+     * @since 1.10
+     */
+    SURFACE_TYPE_XML = CAIRO_SURFACE_TYPE_XML,
+
+    /**
+     * The surface is of type Skia
+     * @since 1.10
+     */
+    SURFACE_TYPE_SKIA = CAIRO_SURFACE_TYPE_SKIA,
+
+    /**
+     * The surface is of type The surface is a subsurface created with
+     * Surface::create()
+     * @since 1.10
+     */
+    SURFACE_TYPE_SUBSURFACE = CAIRO_SURFACE_TYPE_SUBSURFACE
 
 } SurfaceType;
 
+
+/**
+ * Cairo::PatternType is used to describe the type of a given pattern.
+ *
+ * The pattern type can be queried with Pattern::get_type().
+ *
+ * New entries may be added in future versions.
+ *
+ * @since 1.2
+ **/
 typedef enum
 {
+    /**
+     * The pattern is a solid (uniform) color. It may be opaque or translucent.
+     */
     PATTERN_TYPE_SOLID = CAIRO_PATTERN_TYPE_SOLID,
+
+    /**
+     * The pattern is a based on a surface (an image)
+     */
     PATTERN_TYPE_SURFACE = CAIRO_PATTERN_TYPE_SURFACE,
+
+    /**
+     * The pattern is a linear gradient.
+     */
     PATTERN_TYPE_LINEAR = CAIRO_PATTERN_TYPE_LINEAR,
+
+    /**
+     * The pattern is a radial gradient.
+     */
     PATTERN_TYPE_RADIAL = CAIRO_PATTERN_TYPE_RADIAL
 } PatternType;
 
+
+/**
+ * Cairo::FontType is used to describe the type of a given font face or scaled
+ * font. The font types are also known as "font backends" within cairo.
+ *
+ * New entries may be added in future versions.
+ *
+ * @since 1.2
+ **/
 typedef enum
 {
+    /**
+     * The font was created using cairo's toy font api
+     */
     FONT_TYPE_TOY = CAIRO_FONT_TYPE_TOY,
+
+    /**
+     * The font is of type FreeType
+     */
     FONT_TYPE_FT = CAIRO_FONT_TYPE_FT,
+
+    /**
+     * The font is of type Win32
+     */
     FONT_TYPE_WIN32 = CAIRO_FONT_TYPE_WIN32,
-    FONT_TYPE_ATSUI = CAIRO_FONT_TYPE_QUARTZ, /**< @deprecated Use FONT_TYPE_QUARTZ instead. */
+
+    /**
+     * @deprecated Use FONT_TYPE_QUARTZ instead.
+     */
+    FONT_TYPE_ATSUI = CAIRO_FONT_TYPE_QUARTZ,
+
+    /**
+     * The font is of type Quartz
+     * @since 1.6
+     */
     FONT_TYPE_QUARTZ = CAIRO_FONT_TYPE_QUARTZ,
+
+    /**
+     * The font was created using cairo's user font api
+     * @since 1.8
+     */
     FONT_TYPE_USER = CAIRO_FONT_TYPE_USER
 } FontType;
 
@@ -248,14 +783,30 @@ typedef enum
  **/
 typedef enum
 {
-    TEXT_CLUSTER_FLAG_BACKWARD = CAIRO_TEXT_CLUSTER_FLAG_BACKWARD /**< The clusters in the cluster array map to glyphs in the glyph array from end to start. */
+    /**
+     * The clusters in the cluster array map to glyphs in the glyph array from
+     * end to start.
+     */
+    TEXT_CLUSTER_FLAG_BACKWARD = CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
 } TextClusterFlags;
 
+//TODO: Documentation
 typedef enum
 {
-    REGION_OVERLAP_IN = CAIRO_REGION_OVERLAP_IN,		/**< completely inside region */
-    REGION_OVERLAP_OUT = CAIRO_REGION_OVERLAP_OUT,		/**< completely outside region */
-    REGION_OVERLAP_PART = CAIRO_REGION_OVERLAP_PART		/**< partly inside region */
+    /**
+     * Completely inside region
+     */
+    REGION_OVERLAP_IN = CAIRO_REGION_OVERLAP_IN,
+
+    /**
+     * Completely outside region
+     */
+    REGION_OVERLAP_OUT = CAIRO_REGION_OVERLAP_OUT,
+
+    /**
+     * Partly inside region
+     */
+    REGION_OVERLAP_PART = CAIRO_REGION_OVERLAP_PART
 } RegionOverlap;
 
 } // namespace Cairo
diff --git a/cairomm/fontface.h b/cairomm/fontface.h
index c7d2e83..007b40f 100644
--- a/cairomm/fontface.h
+++ b/cairomm/fontface.h
@@ -75,6 +75,9 @@ public:
   void set_user_data(const cairo_user_data_key_t *key, void *user_data, cairo_destroy_func_t destroy);
   */
 
+  /**
+   * Returns the type of the backend used to create a font face
+   */
   FontType get_type() const;
 
   typedef cairo_font_face_t cobject;
diff --git a/cairomm/fontoptions.h b/cairomm/fontoptions.h
index a487937..a2430db 100644
--- a/cairomm/fontoptions.h
+++ b/cairomm/fontoptions.h
@@ -29,7 +29,11 @@
 namespace Cairo
 {
 
-/** How a font should be rendered.
+/**
+ * The font options specify how fonts should be rendered.  Most of the
+ * time the font options implied by a surface are just right and do not
+ * need any changes, but for pixel-based targets tweaking font options
+ * may result in superior output on a particular display.
  */
 class FontOptions
 {
@@ -80,9 +84,10 @@ public:
 
   /**
    * Sets the subpixel order for the font options object. The subpixel order
-   * specifies the order of color elements within each pixel on the display device
-   * when rendering with an antialiasing mode of ANTIALIAS_SUBPIXEL. See the
-   * documentation for SubpixelOrder for full details.
+   * specifies the order of color elements within each pixel on the display
+   * device when rendering with an antialiasing mode of
+   * Cairo::ANTIALIAS_SUBPIXEL. See the documentation for SubpixelOrder for
+   * full details.
    *
    * @param subpixel_order the new subpixel order.
    **/
diff --git a/cairomm/matrix.h b/cairomm/matrix.h
index f7de82b..fe2fef9 100644
--- a/cairomm/matrix.h
+++ b/cairomm/matrix.h
@@ -112,8 +112,10 @@ public:
    * transformation matrices have inverses; if the matrix collapses points
    * together (it is degenerate), then it has no inverse and this function will
    * throw an exception.
+   *
+   * @exception
    */
-  void invert(); // throws exception
+  void invert();
 
   /** Multiplies the affine transformations in a and b together and stores the
    * result in this matrix. The effect of the resulting transformation is to first
diff --git a/cairomm/pattern.h b/cairomm/pattern.h
index 28df65e..2af1a73 100644
--- a/cairomm/pattern.h
+++ b/cairomm/pattern.h
@@ -35,6 +35,10 @@ struct ColorStop
 class Matrix;
 
 /**
+ * Cairo::Pattern is the paint with which cairo draws. The primary use of
+ * patterns is as the source for all cairo drawing operations, although they
+ * can also be used as masks, that is, as the brush too.
+ *
  * This is a reference-counted object that should be used via Cairo::RefPtr.
  */
 class Pattern
@@ -54,14 +58,54 @@ public:
 
   virtual ~Pattern();
 
+  /**
+   * Sets the pattern's transformation matrix to @matrix. This matrix is a
+   * transformation from user space to pattern space.
+   *
+   * When a pattern is first created it always has the identity matrix for its
+   * transformation matrix, which means that pattern space is initially
+   * identical to user space.
+   *
+   * Important: Please note that the direction of this transformation matrix is
+   * from user space to pattern space. This means that if you imagine the flow
+   * from a pattern to user space (and on to device space), then coordinates in
+   * that flow will be transformed by the inverse of the pattern matrix.
+   *
+   * For example, if you want to make a pattern appear twice as large as it
+   * does by default the correct code to use is:
+   *
+   * @code
+   * pattern->set_matrix(scaling_matrix(0.5, 0.5));
+   * @endcode
+   *
+   * Meanwhile, using values of 2.0 rather than 0.5 in the code above
+   * would cause the pattern to appear at half of its default size.
+   *
+   * Also, please note the discussion of the user-space locking semantics of
+   * set_source().
+   **/
   void set_matrix(const Matrix& matrix);
+
+  /**
+   * Returns the pattern's transformation matrix
+   */
   void get_matrix(Matrix& matrix) const;
-  /** @since 1.8
+
+  /**
+   * Returns the pattern's transformation matrix
+   * @since 1.8
    */
   Matrix get_matrix() const;
+
   /* To keep 1.6.x ABI  */
   void set_matrix(const cairo_matrix_t& matrix);
   void get_matrix(cairo_matrix_t& matrix) const;
+
+  /**
+   * Returns the type of the pattern
+   *
+   * @since 1.2
+   */
   PatternType get_type() const;
 
   typedef cairo_pattern_t cobject;
@@ -110,13 +154,30 @@ public:
    *
    * @since 1.4
    **/
-  void get_rgba (double& red, double& green,
-                 double& blue, double& alpha) const;
+  void get_rgba(double& red, double& green,
+                double& blue, double& alpha) const;
 
-  //TODO: Documentation
+  /**
+   * Creates a new Cairo::Pattern corresponding to an opaque color. The color
+   * components are floating point numbers in the range 0 to 1. If the values
+   * passed in are outside that range, they will be clamped.
+   *
+   * @param red red component of the color
+   * @param green green component of the color
+   * @param blue blue component of the color
+   */
   static RefPtr<SolidPattern> create_rgb(double red, double green, double blue);
 
-  //TODO: Documentation
+  /**
+   * Creates a new Cairo::Pattern corresponding to a translucent color. The color
+   * components are floating point numbers in the range 0 to 1. If the values
+   * passed in are outside that range, they will be clamped.
+   *
+   * @param red red component of the color
+   * @param green green component of the color
+   * @param blue blue component of the color
+   * @param alpha alpha component of the color
+   */
   static RefPtr<SolidPattern> create_rgba(double red, double green,
                                           double blue, double alpha);
 
@@ -140,27 +201,59 @@ public:
    */
   explicit SurfacePattern(cairo_pattern_t* cobject, bool has_reference = false);
 
+  /// @{
   /**
    * Gets the surface associated with this pattern
    *
    * @since 1.4
    **/
   RefPtr<const Surface> get_surface () const;
-
-  /**
-   * Gets the surface associated with this pattern
-   *
-   * @since 1.4
-   **/
   RefPtr<Surface> get_surface ();
+  /// @}
 
   virtual ~SurfacePattern();
 
+  /**
+   * Create a new Cairo::Pattern for the given surface.
+   */
   static RefPtr<SurfacePattern> create(const RefPtr<Surface>& surface);
 
+  /**
+   * Sets the mode to be used for drawing outside the area of a pattern. See
+   * Cairo::Extend for details on the semantics of each extend strategy.
+   *
+   * The default extend mode is Cairo::EXTEND_NONE for surface patterns.
+   *
+   * @param Cairo::Extend describing how the area outsize of the pattern will
+   *   be drawn
+   */
   void set_extend(Extend extend);
+
+  /**
+   * Gets the current extend mode See Cairo::Extend for details on the
+   * semantics of each extend strategy.
+   */
   Extend get_extend() const;
+
+  /**
+   * Sets the filter to be used for resizing when using this pattern.
+   * See Cairo::Filter for details on each filter.
+   *
+   * Note that you might want to control filtering even when you do not have an
+   * explicit Cairo::Pattern object, (for example when using
+   * Cairo::Context::set_source_surface()). In these cases, it is convenient to
+   * use Cairo::Context::get_source() to get access to the pattern that cairo
+   * creates implicitly.
+   *
+   * @param filter Cairo::Filter describing the filter to use for resizing the
+   *   pattern
+   */
   void set_filter(Filter filter);
+
+  /**
+   * Gets the current filter for a pattern. See Cairo::Filter for details on
+   * each filter.
+   */
   Filter get_filter() const;
 };
 
@@ -190,6 +283,12 @@ public:
    *
    * The color is specified in the same way as in Context::set_source_rgb().
    *
+   * If two (or more) stops are specified with identical offset values,
+   * they will be sorted according to the order in which the stops are
+   * added, (stops added earlier will compare less than stops added
+   * later). This can be useful for reliably making sharp color
+   * transitions instead of the typical blend.
+   *
    * @param offset an offset in the range [0.0 .. 1.0]
    * @param red red component of color
    * @param green green component of color
@@ -206,6 +305,12 @@ public:
    *
    * The color is specified in the same way as in Context::set_source_rgba().
    *
+   * If two (or more) stops are specified with identical offset values,
+   * they will be sorted according to the order in which the stops are
+   * added, (stops added earlier will compare less than stops added
+   * later). This can be useful for reliably making sharp color
+   * transitions instead of the typical blend.
+   *
    * @param offset an offset in the range [0.0 .. 1.0]
    * @param red red component of color
    * @param green green component of color
@@ -214,7 +319,7 @@ public:
    */
   void add_color_stop_rgba(double offset, double red, double green, double blue, double alpha);
 
-  /*
+  /**
    * Gets the color stops and offsets for this Gradient
    *
    * @since 1.4
@@ -251,11 +356,26 @@ public:
    * @since 1.4
    **/
   void get_linear_points(double &x0, double &y0,
-                          double &x1, double &y1) const;
+                         double &x1, double &y1) const;
 
   //TODO?: LinearGradient(cairo_pattern_t *target);
   virtual ~LinearGradient();
 
+  /**
+   * Create a new linear gradient Cairo::Pattern along the line defined by (x0,
+   * y0) and (x1, y1). Before using the gradient pattern, a number of color
+   * stops should be defined using Cairo::Gradient::add_color_stop_rgb() or
+   * Cairo::Gradient::add_color_stop_rgba().
+   *
+   * Note: The coordinates here are in pattern space. For a new pattern,
+   * pattern space is identical to user space, but the relationship between the
+   * spaces can be changed with Cairo::Pattern::set_matrix().
+   *
+   * @param x0 x coordinate of the start point
+   * @param y0 y coordinate of the start point
+   * @param x1 x coordinate of the end point
+   * @param y1 y coordinate of the end point
+   */
   static RefPtr<LinearGradient> create(double x0, double y0, double x1, double y1);
 };
 
@@ -274,6 +394,9 @@ public:
   explicit RadialGradient(cairo_pattern_t* cobject, bool has_reference = false);
 
   /**
+   * Gets the gradient endpoint circles for a radial gradient, each
+   * specified as a center coordinate and a radius.
+   *
    * @param x0 return value for the x coordinate of the center of the first (inner) circle
    * @param y0 return value for the y coordinate of the center of the first (inner) circle
    * @param r0 return value for the radius of the first (inner) circle
@@ -281,17 +404,33 @@ public:
    * @param y1 return value for the y coordinate of the center of the second (outer) circle
    * @param r1 return value for the radius of the second (outer) circle
    *
-   * Gets the gradient endpoint circles for a radial gradient, each
-   * specified as a center coordinate and a radius.
-   *
    * @since 1.4
-   **/
+   */
   void get_radial_circles(double& x0, double& y0, double& r0,
-                           double& x1, double& y1, double& r1) const;
+                          double& x1, double& y1, double& r1) const;
 
   //TODO?: RadialGradient(cairo_pattern_t *target);
   virtual ~RadialGradient();
 
+
+  /**
+   * Creates a new radial gradient #cairo_pattern_t between the two circles
+   * defined by (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the
+   * gradient pattern, a number of color stops should be defined using
+   * Cairo::Gradient::add_color_stop_rgb() or
+   * Cairo::Gradient::add_color_stop_rgba().
+   *
+   * @note The coordinates here are in pattern space. For a new pattern,
+   * pattern space is identical to user space, but the relationship between the
+   * spaces can be changed with Cairo::Pattern::set_matrix().
+   *
+   * @param cx0 x coordinate for the center of the start circle
+   * @param cy0 y coordinate for the center of the start circle
+   * @param radius0 radius of the start circle
+   * @param cx1 x coordinate for the center of the end circle
+   * @param cy1 y coordinate for the center of the end circle
+   * @param radius1 radius of the end circle
+   */
   static RefPtr<RadialGradient> create(double cx0, double cy0, double radius0, double cx1, double cy1, double radius1);
 };
 
diff --git a/cairomm/quartz_font.h b/cairomm/quartz_font.h
index d293741..5c3ddb2 100644
--- a/cairomm/quartz_font.h
+++ b/cairomm/quartz_font.h
@@ -28,7 +28,10 @@
 namespace Cairo
 {
 
-/** Font support for Quartz (CGFont) fonts on OS X.
+/**
+ * The Quartz font backend is primarily used to render text on Apple
+ * MacOS X systems.  The CGFont API is used for the internal
+ * implementation of the font backend methods.
  *
  * @since 1.8
  */
diff --git a/cairomm/quartz_surface.h b/cairomm/quartz_surface.h
index 246a45a..c7cf987 100644
--- a/cairomm/quartz_surface.h
+++ b/cairomm/quartz_surface.h
@@ -36,6 +36,8 @@ namespace Cairo
  *
  * @note For this Surface to be available, cairo must have been compiled with
  * (native) Quartz support (requires Cairo > 1.4.0)
+ *
+ * @since 1.4
  */
 class QuartzSurface : public Surface
 {
@@ -47,6 +49,8 @@ public:
    * @param cobject The C instance.
    * @param has_reference whether we already have a reference. Otherwise, the
    * constructor will take an extra reference.
+   *
+   * @since 1.4
    */
   explicit QuartzSurface(cairo_surface_t* cobject, bool has_reference = false);
   virtual ~QuartzSurface();
@@ -55,24 +59,46 @@ public:
    * returns NULL if the surface is not a Quartz surface.
    *
    * @return CGContextRef or NULL if no CGContextRef available.
+   *
+   * @since 1.4
    */
   CGContextRef get_cg_context() const;
 
-  /** Creates a cairo surface that targets the given CGContext.
+  /**
+   * Creates a Quartz surface that wraps the given CGContext. The CGContext is
+   * assumed to be in the standard Cairo coordinate space (that is, with the
+   * origin at the upper left and the Y axis increasing downward). If the
+   * CGContext is in the Quartz coordinate space (with the origin at the bottom
+   * left), then it should be flipped before this function is called. The flip
+   * can be accomplished using a translate and a scale; for example:
+   *
+   * @code
+   * CGContextTranslateCTM (cgContext, 0.0, height);
+   * CGContextScaleCTM (cgContext, 1.0, -1.0);
+   * @endcode
+   *
+   * All Cairo operations are implemented in terms of Quartz operations,
+   * as long as Quartz-compatible elements are used (such as Quartz fonts).
    *
    * @param cg_context the CGContext to create a surface for
    * @return the newly created surface
+   *
+   * @since 1.4
    */
   static RefPtr<QuartzSurface> create(CGContextRef cg_context, int width, int height);
 
-  /** Creates a device-independent-bitmap surface not associated with any
-   * particular existing surface or device context. The created bitmap will be
-   * unititialized.
+  /**
+   * Creates a Quartz surface backed by a CGBitmap. The surface is created
+   * using the Device RGB (or Device Gray, for A8) color space. All Cairo
+   * operations, including those that require software rendering, will succeed
+   * on this surface.
    *
    * @param format format of pixels in the surface to create
    * @param width width of the surface, in pixels
    * @param height height of the surface, in pixels
    * @return the newly created surface
+   *
+   * @since 1.4
    */
   static RefPtr<QuartzSurface> create(Format format, int width, int height);
 
diff --git a/cairomm/region.h b/cairomm/region.h
index 91de639..686d3f1 100644
--- a/cairomm/region.h
+++ b/cairomm/region.h
@@ -83,7 +83,8 @@ public:
   bool empty() const;
 
   /** Checks whether @a rectangle is inside, outside, or partially contained in
-   * the region */
+   * the region
+   */
   RegionOverlap contains_rectangle(const RectangleInt& rectangle) const;
 
   /** Checks whether (x,y) is contained in the region */
diff --git a/cairomm/surface.h b/cairomm/surface.h
index 8079dc0..64412cb 100644
--- a/cairomm/surface.h
+++ b/cairomm/surface.h
@@ -65,6 +65,11 @@ namespace Cairo
  * different subtypes of cairo surface for different drawing backends.  This
  * class is a base class for all subtypes and should not be used directly
  *
+ * Most surface types allow accessing the surface without using Cairo
+ * functions. If you do this, keep in mind that it is mandatory that you call
+ * Cairo::Surface::flush() before reading from or writing to the surface and that
+ * you must use Cairo::Surface::mark_dirty() after modifying it.
+ *
  * Surfaces are reference-counted objects that should be used via Cairo::RefPtr.
  */
 class Surface
@@ -109,11 +114,15 @@ public:
 
   virtual ~Surface();
 
-  /** Return mime data previously attached to surface using the specified mime type. If no data has been attached with the given mime type then this returns 0.
+  /**
+   * Return mime data previously attached to surface using the specified mime
+   * type. If no data has been attached with the given mime type then this
+   * returns 0.
    *
    * @param mime_type The MIME type of the image data.
    * @param length This will be set to the length of the image data.
-   * @result The image data attached to the surface.
+   * @returns The image data attached to the surface.
+   * @since 1.10
    */
   const unsigned char* get_mime_data(const std::string& mime_type, unsigned long& length);
 
@@ -138,12 +147,15 @@ public:
    * it can handle. Caution: the associated MIME data will be discarded if you
    * draw on the surface afterwards. Use this function with care.
    *
-   * @param mime_type The MIME type of the image data.
-   * @param data The image data to attach to the surface.
-   * @param length The length of the image data.
-   * @param slot_destroy A callback slot that will be called when the Surface no longer needs the data. For instance, when the Surface is destroyed or when new image data is attached using the same MIME tpe.
+   * @param mime_type The MIME type of the image data. param data The image
+   * @data to attach to the surface. param length The length of the image data.
+   * @param slot_destroy A callback slot that will be called when the Surface
+   *   no longer needs the data. For instance, when the Surface is destroyed or
+   *   when new image data is attached using the same MIME tpe.
+   * @since 1.10
    */
-  void set_mime_data(const std::string& mime_type, unsigned char* data, unsigned long length, const SlotDestroy& slot_destroy);
+  void set_mime_data(const std::string& mime_type, unsigned char* data,
+                     unsigned long length, const SlotDestroy& slot_destroy);
 
   /** Remove the data from a surface. See set_mime_data().
    */
@@ -221,10 +233,34 @@ public:
    */
   void get_device_offset(double& x_offset, double& y_offset) const;
 
-  /** Sets the fallback resolution of the image in dots per inch
+  /**
+   * Set the horizontal and vertical resolution for image fallbacks.
+   *
+   * When certain operations aren't supported natively by a backend, cairo will
+   * fallback by rendering operations to an image and then overlaying that
+   * image onto the output. For backends that are natively vector-oriented,
+   * this function can be used to set the resolution used for these image
+   * fallbacks, (larger values will result in more detailed images, but also
+   * larger file sizes).
+   *
+   * Some examples of natively vector-oriented backends are the ps, pdf, and
+   * svg backends.
+   *
+   * For backends that are natively raster-oriented, image fallbacks are still
+   * possible, but they are always performed at the native device resolution.
+   * So this function has no effect on those backends.
+   *
+   * Note: The fallback resolution only takes effect at the time of completing
+   * a page (with Context::show_page() or Context::copy_page()) so there is
+   * currently no way to have more than one fallback resolution in effect on a
+   * single page.
+   *
+   * The default fallback resoultion is 300 pixels per inch in both dimensions.
    *
    * @param x_pixels_per_inch   Pixels per inch in the x direction
    * @param y_pixels_per_inch   Pixels per inch in the y direction
+   *
+   * @since 1.2
    */
   void set_fallback_resolution(double x_pixels_per_inch, double y_pixels_per_inch);
 
@@ -240,7 +276,8 @@ public:
 
   SurfaceType get_type() const;
 
-  /**This function returns the content type of surface which indicates whether
+  /**
+   * This function returns the content type of surface which indicates whether
    * the surface contains color and/or alpha information.
    *
    * @since 1.8
@@ -421,32 +458,39 @@ public:
    */
   int get_height() const;
 
+  /// @{
   /**
    * Get a pointer to the data of the image surface, for direct
    * inspection or modification.
    *
    * Return value: a pointer to the image data of this surface or NULL
    * if @surface is not an image surface.
+   *
+   * @since 1.2
    */
   unsigned char* get_data();
   const unsigned char* get_data() const;
+  /// @}
 
-  /** gets the format of the surface
+  /**
+   * Gets the format of the surface
+   * @since 1.2
    */
   Format get_format() const;
 
   /**
-   * Return value: the stride of the image surface in bytes (or 0 if
-   * @surface is not an image surface). The stride is the distance in
-   * bytes from the beginning of one row of the image data to the
-   * beginning of the next row.
+   * Returns the stride of the image surface in bytes (or 0 if surface is not
+   * an image surface). The stride is the distance in bytes from the beginning
+   * of one row of the image data to the beginning of the next row.
+   *
+   * @since 1.2
    */
   int get_stride() const;
 
   /**
-   * This function provides a stride value that will respect all
-   * alignment requirements of the accelerated image-rendering code
-   * within cairo. Typical usage will be of the form:
+   * This function provides a stride value that will respect all alignment
+   * requirements of the accelerated image-rendering code within cairo. Typical
+   * usage will be of the form:
    *
    * @code
    * int stride;
@@ -465,7 +509,7 @@ public:
    *
    * @since 1.6
    **/
-  static int format_stride_for_width (Cairo::Format format, int width);
+  static int format_stride_for_width(Cairo::Format format, int width);
 
   /**
    * Creates an image surface of the specified format and dimensions. Initially
@@ -576,6 +620,7 @@ public:
    * @param filename    The name of the PDF file to save the surface to
    * @param width_in_points   The width of the PDF document in points
    * @param height_in_points   The height of the PDF document in points
+   * @since 1.2
    */
   static RefPtr<PdfSurface> create(std::string filename, double width_in_points, double height_in_points);
 
@@ -586,7 +631,6 @@ public:
    * write data to an output stream
    * @param width_in_points   The width of the PDF document in points
    * @param height_in_points   The height of the PDF document in points
-   *
    * @since 1.8
    */
   static RefPtr<PdfSurface> create_for_stream(const SlotWriteFunc& write_func, double width_in_points, double height_in_points);