26 files changed, 68 insertions, 75 deletions
diff --git a/src/cairo-array.c b/src/cairo-array.c
index 6940b401a..a6918b2be 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -40,7 +40,7 @@
 /**
  * _cairo_array_init:
  *
- * Initialize a new cairo_array object to store objects each of size
+ * Initialize a new #cairo_array_t object to store objects each of size
  * @element_size.
  *
  * The #cairo_array_t object provides grow-by-doubling storage. It
diff --git a/src/cairo-base85-stream.c b/src/cairo-base85-stream.c
index b7dc9b14b..2b8a8beeb 100644
--- a/src/cairo-base85-stream.c
+++ b/src/cairo-base85-stream.c
@@ -25,8 +25,7 @@
  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  * the specific language governing rights and limitations.
  *
- * The Original Code is cairo_output_stream.c as distributed with the
- *   cairo graphics library.
+ * The Original Code is the cairo graphics library.
  *
  * The Initial Developer of the Original Code is Red Hat, Inc.
  *
diff --git a/src/cairo-beos-surface.cpp b/src/cairo-beos-surface.cpp
index 193fa43fd..69dfd8348 100644
--- a/src/cairo-beos-surface.cpp
+++ b/src/cairo-beos-surface.cpp
@@ -965,7 +965,7 @@ cairo_beos_surface_create (BView* view)
  * before the surface.
  *
  * For views that draw to a bitmap (as opposed to a screen), use this function
- * rather than cairo_beos_surface_create. Not using this function WILL lead to
+ * rather than cairo_beos_surface_create(). Not using this function WILL lead to
  * incorrect behaviour.
  *
  * For now, only views that draw to the entire area of bmp are supported.
diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h
index e2e2056e8..65a8aee83 100644
--- a/src/cairo-cache-private.h
+++ b/src/cairo-cache-private.h
@@ -55,7 +55,7 @@
  *	} my_entry_t;
  *
  * which then allows a pointer to my_entry_t to be passed to any of
- * the cairo_cache functions as follows without requiring a cast:
+ * the #cairo_cache_t functions as follows without requiring a cast:
  *
  *	_cairo_cache_insert (cache, &my_entry->base, size);
  *
@@ -78,7 +78,7 @@
  * Which parts of the entry make up the "key" and which part make up
  * the value are entirely up to the caller, (as determined by the
  * computation going into base.hash as well as the keys_equal
- * function). A few of the cairo_cache functions accept an entry which
+ * function). A few of the #cairo_cache_t functions accept an entry which
  * will be used exclusively as a "key", (indicated by a parameter name
  * of key). In these cases, the value-related fields of the entry need
  * not be initialized if so desired.
diff --git a/src/cairo-debug.c b/src/cairo-debug.c
index cdd3ce949..c4b7edfe3 100644
--- a/src/cairo-debug.c
+++ b/src/cairo-debug.c
@@ -44,9 +44,9 @@
  *
  * This function is intended to be useful when using memory-checking
  * tools such as valgrind. When valgrind's memcheck analyzes a
- * cairo-using program without a call to cairo_debug_reset_static_data,
+ * cairo-using program without a call to cairo_debug_reset_static_data(),
  * it will report all data reachable via cairo's static objects as
- * "still reachable". Calling cairo_debug_reset_static_data just prior
+ * "still reachable". Calling cairo_debug_reset_static_data() just prior
  * to program termination will make it easier to get squeaky clean
  * reports from valgrind.
  *
diff --git a/src/cairo-deflate-stream.c b/src/cairo-deflate-stream.c
index 8734b1782..9feb46de1 100644
--- a/src/cairo-deflate-stream.c
+++ b/src/cairo-deflate-stream.c
@@ -25,8 +25,7 @@
  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  * the specific language governing rights and limitations.
  *
- * The Original Code is cairo_output_stream.c as distributed with the
- *   cairo graphics library.
+ * The Original Code is the cairo graphics library.
  *
  * The Initial Developer of the Original Code is Adrian Johnson.
  *
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index a566fac61..bcb41b29e 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -361,7 +361,7 @@ _cairo_unscaled_font_is_ft (cairo_unscaled_font_t *unscaled_font)
  * Free all data associated with a #cairo_ft_unscaled_font_t.
  *
  * CAUTION: The unscaled->face field must be %NULL before calling this
- * function. This is because the cairo_ft_unscaled_font_map keeps a
+ * function. This is because the #cairo_ft_unscaled_font_t_map keeps a
  * count of these faces (font_map->num_open_faces) so it maintains the
  * unscaled->face field while it has its lock held. See
  * _font_map_release_face_lock_held().
@@ -390,7 +390,7 @@ _cairo_ft_unscaled_font_keys_equal (const void *key_a,
 	    unscaled_a->id == unscaled_b->id);
 }
 
-/* Finds or creates a cairo_ft_unscaled_font for the filename/id from
+/* Finds or creates a #cairo_ft_unscaled_font_t for the filename/id from
  * pattern.  Returns a new reference to the unscaled font.
  */
 static cairo_ft_unscaled_font_t *
diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index ba0ce6aea..c85a2b4bc 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -358,7 +358,7 @@ _cairo_image_surface_create_with_pixman_format (unsigned char		*data,
  * but not belonging to the given format are undefined).
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -461,7 +461,7 @@ cairo_format_stride_for_width (cairo_format_t	format,
  * cairo_format_stride_for_width() for example code.
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
diff --git a/src/cairo-output-stream-private.h b/src/cairo-output-stream-private.h
index ac874475b..1fc9b8ef3 100644
--- a/src/cairo-output-stream-private.h
+++ b/src/cairo-output-stream-private.h
@@ -25,8 +25,7 @@
  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  * the specific language governing rights and limitations.
  *
- * The Original Code is cairo_output_stream.c as distributed with the
- *   cairo graphics library.
+ * The Original Code is the cairo graphics library.
  *
  * The Initial Developer of the Original Code is Red Hat, Inc.
  *
diff --git a/src/cairo-output-stream.c b/src/cairo-output-stream.c
index 2cb9e03bc..22245f755 100644
--- a/src/cairo-output-stream.c
+++ b/src/cairo-output-stream.c
@@ -25,8 +25,7 @@
  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  * the specific language governing rights and limitations.
  *
- * The Original Code is cairo_output_stream.c as distributed with the
- *   cairo graphics library.
+ * The Original Code is the cairo graphics library.
  *
  * The Initial Developer of the Original Code is Red Hat, Inc.
  *
diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h
index 48e646d63..4b10601e5 100644
--- a/src/cairo-paginated-private.h
+++ b/src/cairo-paginated-private.h
@@ -69,7 +69,7 @@ struct _cairo_paginated_surface_backend {
 			 cairo_box_t	*bbox);
 };
 
-/* A cairo_paginated_surface provides a very convenient wrapper that
+/* A #cairo_paginated_surface_t provides a very convenient wrapper that
  * is well-suited for doing the analysis common to most surfaces that
  * have paginated output, (that is, things directed at printers, or
  * for saving content in files such as PostScript or PDF files).
diff --git a/src/cairo-path-fixed-private.h b/src/cairo-path-fixed-private.h
index f506c3449..9fcb2e18b 100644
--- a/src/cairo-path-fixed-private.h
+++ b/src/cairo-path-fixed-private.h
@@ -45,7 +45,7 @@ enum cairo_path_op {
 /* we want to make sure a single byte is used for thie enum */
 typedef char cairo_path_op_t;
 
-/* make cairo_path_fixed fit a 512 bytes.  about 50 items */
+/* make _cairo_path_fixed fit a 512 bytes.  about 50 items */
 #define CAIRO_PATH_BUF_SIZE ((512 - 4 * sizeof (void*) - sizeof (cairo_path_buf_t)) \
 			   / (2 * sizeof (cairo_point_t) + sizeof (cairo_path_op_t)))
 
diff --git a/src/cairo-path.c b/src/cairo-path.c
index f480b627c..e0b21ef70 100644
--- a/src/cairo-path.c
+++ b/src/cairo-path.c
@@ -363,7 +363,7 @@ _cairo_path_create_internal (cairo_path_fixed_t *path_fixed,
  * to cairo_path_destroy() the @path pointer is no longer valid and
  * should not be used further.
  *
- * NOTE: cairo_path_destroy function should only be called with a
+ * NOTE: cairo_path_destroy() should only be called with a
  * pointer to a #cairo_path_t returned by a cairo function. Any path
  * that is created manually (ie. outside of cairo) should be destroyed
  * manually as well.
@@ -390,7 +390,7 @@ cairo_path_destroy (cairo_path_t *path)
  * conversion.
  *
  * Return value: the new copy of the path. If there is insufficient
- * memory a pointer to a special static cairo_path_nil will be
+ * memory a pointer to a special static nil #cairo_path_t will be
  * returned instead with status==%CAIRO_STATUS_NO_MEMORY and
  * data==%NULL.
  **/
@@ -412,7 +412,7 @@ _cairo_path_create (cairo_path_fixed_t *path,
  * accuracy of the flattening.
  *
  * Return value: the flattened copy of the path. If there is insufficient
- * memory a pointer to a special static cairo_path_nil will be
+ * memory a pointer to a special static nil #cairo_path_t will be
  * returned instead with status==%CAIRO_STATUS_NO_MEMORY and
  * data==%NULL.
  **/
diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c
index 2b8f74585..1de471479 100644
--- a/src/cairo-pdf-surface.c
+++ b/src/cairo-pdf-surface.c
@@ -332,7 +332,7 @@ BAIL0:
  * incrementally to the stream represented by @write_func and @closure.
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -368,7 +368,7 @@ cairo_pdf_surface_create_for_stream (cairo_write_func_t		 write_func,
  * to @filename.
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index 844156ec0..2473eb897 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -1032,7 +1032,7 @@ _cairo_ps_surface_create_for_stream_internal (cairo_output_stream_t *stream,
  * vary. See cairo_ps_surface_set_size().
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -1073,7 +1073,7 @@ cairo_ps_surface_create (const char		*filename,
  * output can vary. See cairo_ps_surface_set_size().
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -1214,7 +1214,7 @@ cairo_ps_level_to_string (cairo_ps_level_t level)
  * This function should only be called before any drawing operations
  * have been performed on the current page. The simplest way to do
  * this is to call this function immediately after creating the
- * surface. An Encapsulated Postscript file should never contain more
+ * surface. An Encapsulated PostScript file should never contain more
  * than one page.
  *
  * Since: 1.6
diff --git a/src/cairo-quartz-surface.c b/src/cairo-quartz-surface.c
index f3fb36b78..9aff1c3ad 100644
--- a/src/cairo-quartz-surface.c
+++ b/src/cairo-quartz-surface.c
@@ -445,7 +445,7 @@ _cairo_quartz_surface_to_quartz (cairo_surface_t *target,
     return CAIRO_STATUS_SUCCESS;
 }
 
-/* Generic cairo_pattern -> CGPattern function */
+/* Generic #cairo_pattern_t -> CGPattern function */
 static void
 SurfacePatternDrawFunc (void *info, CGContextRef context)
 {
diff --git a/src/cairo-scaled-font-subsets-private.h b/src/cairo-scaled-font-subsets-private.h
index fe6c23ad3..bccd0de12 100644
--- a/src/cairo-scaled-font-subsets-private.h
+++ b/src/cairo-scaled-font-subsets-private.h
@@ -54,7 +54,7 @@ typedef struct _cairo_scaled_font_subsets_glyph {
  * Create a new #cairo_scaled_font_subsets_t object which can be used
  * to create subsets of any number of #cairo_scaled_font_t
  * objects. This allows the (arbitrarily large and sparse) glyph
- * indices of a cairo_scaled_font to be mapped to one or more font
+ * indices of a #cairo_scaled_font_t to be mapped to one or more font
  * subsets with glyph indices packed into the range
  * [0 .. max_glyphs_per_subset).
  *
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index 33d83c965..ed01b1fe2 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -48,9 +48,9 @@
  *
  *  A device_transform converts from device space (a conceptual space) to
  *  surface space.  For simple cases of translation only, it's called a
- *  device_offset and is public API (cairo_surface_[gs]et_device_offset).
+ *  device_offset and is public API (cairo_surface_[gs]et_device_offset()).
  *  A possibly better name for those functions could have been
- *  cairo_surface_[gs]et_origing.  So, that's what they do: they set where
+ *  cairo_surface_[gs]et_origin().  So, that's what they do: they set where
  *  the device-space origin (0,0) is in the surface.  If the origin is inside
  *  the surface, device_offset values are positive.  It may look like this:
  *
@@ -283,9 +283,9 @@ slim_hidden_def (cairo_scaled_font_status);
  * unreferenced fonts (holdovers) which are expired in
  * least-recently-used order.
  *
- * The cairo_scaled_font_create code gets to treat this like a regular
+ * The cairo_scaled_font_create() code gets to treat this like a regular
  * hash table. All of the magic for the little holdover cache is in
- * cairo_scaled_font_reference and cairo_scaled_font_destroy.
+ * cairo_scaled_font_reference() and cairo_scaled_font_destroy().
  */
 
 /* This defines the size of the holdover array ... that is, the number
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 3227dbe4e..074be10e0 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -280,7 +280,7 @@ _cairo_surface_create_similar_scratch (cairo_surface_t *other,
  * have transparency, black otherwise.)
  *
  * Return value: a pointer to the newly allocated surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -1159,7 +1159,7 @@ _cairo_surface_snapshot (cairo_surface_t *surface)
  *
  * The definition of "similar" depends on the backend. In
  * general, it means that the surface is equivalent to one
- * that would have been generated by a call to cairo_surface_create_similar.
+ * that would have been generated by a call to cairo_surface_create_similar().
  *
  * Return value: %TRUE if the surfaces are similar.
  **/
@@ -2008,7 +2008,7 @@ _cairo_surface_set_clip (cairo_surface_t *surface, cairo_clip_t *clip)
  * NOTE: The coordinates returned are in "backend" space rather than
  * "surface" space. That is, they are relative to the true (0,0)
  * origin rather than the device_transform origin. This might seem a
- * bit inconsistent with other cairo_surface interfaces, but all
+ * bit inconsistent with other #cairo_surface_t interfaces, but all
  * current callers are within the surface layer where backend space is
  * desired.
  *
diff --git a/src/cairo-svg-surface.c b/src/cairo-svg-surface.c
index 712b8aba5..6cd5e08dd 100644
--- a/src/cairo-svg-surface.c
+++ b/src/cairo-svg-surface.c
@@ -159,7 +159,7 @@ static const cairo_paginated_surface_backend_t cairo_svg_surface_paginated_backe
  * incrementally to the stream represented by @write_func and @closure.
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
@@ -193,7 +193,7 @@ cairo_svg_surface_create_for_stream (cairo_write_func_t		 write_func,
  * to @filename.
  *
  * Return value: a pointer to the newly created surface. The caller
- * owns the surface and should call cairo_surface_destroy when done
+ * owns the surface and should call cairo_surface_destroy() when done
  * with it.
  *
  * This function always returns a valid pointer, but it will return a
diff --git a/src/cairo-traps.c b/src/cairo-traps.c
index 195ae880d..8b009b1c9 100644
--- a/src/cairo-traps.c
+++ b/src/cairo-traps.c
@@ -34,7 +34,7 @@
  *	Keith R. Packard <keithp@keithp.com>
  *	Carl D. Worth <cworth@cworth.org>
  *
- * 2002-07-15: Converted from XRenderCompositeDoublePoly to cairo_trap. Carl D. Worth
+ * 2002-07-15: Converted from XRenderCompositeDoublePoly to #cairo_trap_t. Carl D. Worth
  */
 
 #include "cairoint.h"
diff --git a/src/cairo-types-private.h b/src/cairo-types-private.h
index 42713dd62..0b847740a 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -72,7 +72,7 @@ typedef cairo_array_t cairo_user_data_array_t;
  *	} my_entry_t;
  *
  * which then allows a pointer to my_entry_t to be passed to any of
- * the cairo_hash_table functions as follows without requiring a cast:
+ * the #cairo_hash_table_t functions as follows without requiring a cast:
  *
  *	_cairo_hash_table_insert (hash_table, &my_entry->base);
  *
@@ -86,7 +86,7 @@ typedef cairo_array_t cairo_user_data_array_t;
  * Which parts of the entry make up the "key" and which part make up
  * the value are entirely up to the caller, (as determined by the
  * computation going into base.hash as well as the keys_equal
- * function). A few of the cairo_hash_table functions accept an entry
+ * function). A few of the #cairo_hash_table_t functions accept an entry
  * which will be used exclusively as a "key", (indicated by a
  * parameter name of key). In these cases, the value-related fields of
  * the entry need not be initialized if so desired.
diff --git a/src/cairo-unicode.c b/src/cairo-unicode.c
index 18b9143d9..5f91de338 100644
--- a/src/cairo-unicode.c
+++ b/src/cairo-unicode.c
@@ -30,8 +30,7 @@
  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  * the specific language governing rights and limitations.
  *
- * The Original Code is cairo_unicode.c as distributed with the
- *   cairo graphics library.
+ * The Original Code is the cairo graphics library.
  *
  * The Initial Developer of the Original Code is Tom Tromey.
  *  and Red Hat, Inc.
diff --git a/src/cairo.c b/src/cairo.c
index 1db90a576..864177d5c 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -172,7 +172,7 @@ slim_hidden_def (cairo_version_string);
  * default values and with @target as a target surface. The target
  * surface should be constructed with a backend-specific function such
  * as cairo_image_surface_create() (or any other
- * <literal>cairo_&lt;backend&gt;_surface_create</literal> variant).
+ * cairo_<emphasis>backend</emphasis>_surface_create variant).
  *
  * This function references @target, so you can immediately
  * call cairo_surface_destroy() on it if you don't need to
@@ -1035,7 +1035,7 @@ cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
  * @dashes.
  *
  * If any value in @dashes is negative, or if all values are 0, then
- * @cairo_t will be put into an error state with a status of
+ * @cr will be put into an error state with a status of
  * #%CAIRO_STATUS_INVALID_DASH.
  **/
 void
@@ -1145,7 +1145,7 @@ cairo_set_miter_limit (cairo_t *cr, 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
+ * call to cairo_translate(). In other words, the translation of the
  * user-space origin takes place after any existing transformation.
  **/
 void
@@ -1844,10 +1844,10 @@ cairo_stroke_to_path (cairo_t *cr)
  * the ends of the sub-path. Instead, there is a line join connecting
  * the final and initial segments of the sub-path.
  *
- * If there is no current point before the call to cairo_close_path,
+ * If there is no current point before the call to cairo_close_path(),
  * this function will have no effect.
  *
- * Note: As of cairo version 1.2.4 any call to cairo_close_path will
+ * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
  * place an explicit MOVE_TO element into the path immediately after
  * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
  * example). This can simplify path processing in some cases as it may
@@ -2089,7 +2089,7 @@ cairo_stroke (cairo_t *cr)
  *
  * A drawing operator that strokes the current path according to the
  * current line width, line join, line cap, and dash settings. Unlike
- * cairo_stroke(), cairo_stroke_preserve preserves the path within the
+ * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
  * cairo context.
  *
  * See cairo_set_line_width(), cairo_set_line_join(),
@@ -2116,7 +2116,7 @@ slim_hidden_def(cairo_stroke_preserve);
  *
  * A drawing operator that fills the current path according to the
  * current fill rule, (each sub-path is implicitly closed before being
- * filled). After cairo_fill, the current path will be cleared from
+ * filled). After cairo_fill(), the current path will be cleared from
  * the cairo context. See cairo_set_fill_rule() and
  * cairo_fill_preserve().
  **/
@@ -2134,7 +2134,7 @@ cairo_fill (cairo_t *cr)
  *
  * A drawing operator that fills the current path according to the
  * current fill rule, (each sub-path is implicitly closed before being
- * filled). Unlike cairo_fill(), cairo_fill_preserve preserves the
+ * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
  * path within the cairo context.
  *
  * See cairo_set_fill_rule() and cairo_fill().
@@ -2355,7 +2355,7 @@ cairo_fill_extents (cairo_t *cr,
  * region with the current path as it would be filled by cairo_fill()
  * and according to the current fill rule (see cairo_set_fill_rule()).
  *
- * After cairo_clip, the current path will be cleared from the cairo
+ * After cairo_clip(), the current path will be cleared from the cairo
  * context.
  *
  * The current clip region affects all drawing operations by
@@ -2385,7 +2385,7 @@ cairo_clip (cairo_t *cr)
  * region with the current path as it would be filled by cairo_fill()
  * and according to the current fill rule (see cairo_set_fill_rule()).
  *
- * Unlike cairo_clip(), cairo_clip_preserve preserves the path within
+ * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
  * the cairo context.
  *
  * The current clip region affects all drawing operations by
@@ -2502,10 +2502,8 @@ _cairo_rectangle_list_create_in_error (cairo_status_t status)
  * user-space rectangles. The status may have other values to indicate
  * other errors.
  *
- * The caller must always call cairo_rectangle_list_destroy on the result of
- * this function.
- *
- * Returns: the current clip region as a list of rectangles in user coordinates.
+ * Returns: the current clip region as a list of rectangles in user coordinates,
+ * which should be destroyed using cairo_rectangle_list_destroy().
  *
  * Since: 1.4
  **/
@@ -2610,7 +2608,7 @@ cairo_set_font_face (cairo_t           *cr,
  * this nil object will cause its error state to propagate to other
  * objects it is passed to, (for example, calling
  * cairo_set_font_face() with a nil font will trigger an error that
- * will shutdown the cairo_t object).
+ * will shutdown the #cairo_t object).
  **/
 cairo_font_face_t *
 cairo_get_font_face (cairo_t *cr)
@@ -2816,7 +2814,7 @@ BAIL:
  * this nil object will cause its error state to propagate to other
  * objects it is passed to, (for example, calling
  * cairo_set_scaled_font() with a nil font will trigger an error that
- * will shutdown the cairo_t object).
+ * will shutdown the #cairo_t object).
  *
  * Since: 1.4
  **/
diff --git a/src/cairo.h b/src/cairo.h
index 873a1ce5c..bcef13a5d 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -140,9 +140,9 @@ typedef struct _cairo_matrix {
  * cairo_pattern_create_rgb() creates a pattern for a solid
  * opaque color.
  *
- * Other than various cairo_pattern_create_<emphasis>type</emphasis>
+ * Other than various cairo_pattern_create_<emphasis>type</emphasis>()
  * functions, some of the pattern types can be implicitly created
- * using various cairo_set_source_<emphasis>type</emphasis> functions;
+ * using various cairo_set_source_<emphasis>type</emphasis>() functions;
  * for example cairo_set_source_rgb().
  *
  * The type of a pattern can be queried with cairo_pattern_get_type().
@@ -180,7 +180,7 @@ typedef struct _cairo_user_data_key {
  * cairo_status_t
  * @CAIRO_STATUS_SUCCESS: no error has occurred
  * @CAIRO_STATUS_NO_MEMORY: out of memory
- * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore without matching cairo_save
+ * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save()
  * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop
  * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined
  * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible)
@@ -1147,18 +1147,18 @@ cairo_font_face_status (cairo_font_face_t *font_face);
  * cairo_<emphasis>type</emphasis>_font_face_create. The font face type can be queried
  * with cairo_font_face_get_type()
  *
- * The various cairo_font_face functions can be used with a font face
+ * The various #cairo_font_face_t functions can be used with a font face
  * of any type.
  *
  * The type of a scaled font is determined by the type of the font
- * face passed to cairo_scaled_font_create. The scaled font type can
+ * face passed to cairo_scaled_font_create(). The scaled font type can
  * be queried with cairo_scaled_font_get_type()
  *
- * The various cairo_scaled_font functions can be used with scaled
+ * The various #cairo_scaled_font_t functions can be used with scaled
  * fonts of any type, but some font backends also provide
  * type-specific functions that must only be called with a scaled font
  * of the appropriate type. These functions have names that begin with
- * cairo_<emphasis>type</emphasis>_scaled_font such as cairo_ft_scaled_font_lock_face.
+ * cairo_<emphasis>type</emphasis>_scaled_font such as cairo_ft_scaled_font_lock_face().
  *
  * The behavior of calling a type-specific function with a scaled font
  * of the wrong type is undefined.
@@ -1482,12 +1482,12 @@ cairo_surface_status (cairo_surface_t *surface);
  * backends" within cairo.
  *
  * The type of a surface is determined by the function used to create
- * it, which will generally be of the form cairo_<emphasis>type</emphasis>_surface_create,
- * (though see cairo_surface_create_similar as well).
+ * it, which will generally be of the form cairo_<emphasis>type</emphasis>_surface_create(),
+ * (though see cairo_surface_create_similar() as well).
  *
  * The surface type can be queried with cairo_surface_get_type()
  *
- * The various cairo_surface functions can be used with surfaces of
+ * The various #cairo_surface_t 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. These functions have names that begin with
@@ -1725,7 +1725,7 @@ cairo_pattern_set_user_data (cairo_pattern_t		 *pattern,
  *
  * The pattern type can be queried with cairo_pattern_get_type()
  *
- * Most cairo_pattern functions can be called with a pattern of any
+ * Most #cairo_pattern_t functions can be called with a pattern of any
  * type, (though trying to change the extend or filter for a solid
  * pattern will have no effect). A notable exception is
  * cairo_pattern_add_color_stop_rgb() and
diff --git a/src/cairoint.h b/src/cairoint.h
index db6a98cc5..61c59ff42 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -701,7 +701,7 @@ struct _cairo_image_surface {
 
 extern const cairo_private cairo_surface_backend_t cairo_image_surface_backend;
 
-/* XXX: Right now, the cairo_color structure puts unpremultiplied
+/* XXX: Right now, the _cairo_color structure puts unpremultiplied
    color in the doubles and premultiplied color in the shorts. Yes,
    this is crazy insane, (but at least we don't export this
    madness). I'm still working on a cleaner API, but in the meantime,
@@ -1760,14 +1760,14 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
  * neglected to adjust this macro. The net effect is that it's
  * impossible to externally create an image surface with this
  * format. This is perhaps a good thing since we also neglected to fix
- * up things like cairo_surface_write_to_png for the new format
+ * up things like cairo_surface_write_to_png() for the new format
  * (-Wswitch-enum will tell you where). Is it obvious that format was
  * added in haste?
  *
  * The reason for the new format was to allow the xlib backend to be
  * used on X servers with a 565 visual. So the new format did its job
  * for that, even without being considered "valid" for the sake of
- * things like cairo_image_surface_create.
+ * things like cairo_image_surface_create().
  *
  * Since 1.2.0 we ran into the same situtation with X servers with BGR
  * visuals. This time we invented #cairo_internal_format_t instead,
@@ -1783,7 +1783,7 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
  * If we do decide to start fully supporting RGB16_565 as an external
  * format, then %CAIRO_FORMAT_VALID needs to be adjusted to include
  * it. But that should not happen before all necessary code is fixed
- * to support it (at least cairo_surface_write_to_png and a few spots
+ * to support it (at least cairo_surface_write_to_png() and a few spots
  * in cairo-xlib-surface.c--again see -Wswitch-enum).
  */
 #define CAIRO_FORMAT_INVALID ((unsigned int) -1)