[cairo-commit] 11 commits - doc/public src/cairo-array.c src/cairo-base85-stream.c src/cairo-bentley-ottmann.c src/cairo-beos-surface.cpp src/cairo.c src/cairo-cache.c src/cairo-cache-private.h src/cairo-debug.c src/cairo-deflate-stream.c src/cairo-deprecated.h src/cairo-directfb.h src/cairo-fixed-type-private.h src/cairo-font-face.c src/cairo-font-options.c src/cairo-freelist-private.h src/cairo-ft-font.c src/cairo-gstate.c src/cairo.h src/cairo-hash.c src/cairo-image-surface.c src/cairoint.h src/cairo-lzw.c src/cairo-matrix.c src/cairo-meta-surface.c src/cairo-mutex-private.h src/cairo-mutex-type-private.h src/cairo-os2.h src/cairo-output-stream.c src/cairo-output-stream-private.h src/cairo-paginated-private.h src/cairo-path.c src/cairo-path-fill.c src/cairo-path-fixed-private.h src/cairo-pattern.c src/cairo-pdf-surface.c src/cairo-pen.c src/cairo-png.c src/cairo-ps.h src/cairo-ps-surface.c src/cairo-quartz-surface.c src/cairo-rectangle.c src/cairo-region.c src/cairo-region-private.h src/cairo-scaled-font.c src/cairo-scaled-font-subsets-private.h src/cairo-slope.c src/cairo-surface.c src/cairo-surface-fallback.c src/cairo-svg.h src/cairo-svg-surface.c src/cairo-traps.c src/cairo-types-private.h src/cairo-unicode.c src/cairo-win32-font.c src/cairo-win32-surface.c src/cairo-xcb-surface.c src/cairo-xlib-surface.c src/check-doc-syntax.sh src/Makefile.am src/test-fallback-surface.c

Behdad Esfahbod behdad at kemper.freedesktop.org
Mon Jan 28 19:10:34 PST 2008


 doc/public/Makefile.am                  |    2 
 doc/public/check-doc-coverage.sh        |   43 +++++++++++++++++++
 doc/public/tmpl/cairo-beos.sgml         |    4 -
 doc/public/tmpl/cairo-font.sgml         |    7 ++-
 doc/public/tmpl/cairo-matrix.sgml       |    2 
 doc/public/tmpl/cairo-pattern.sgml      |   12 ++++-
 doc/public/tmpl/cairo-status.sgml       |    5 +-
 doc/public/tmpl/cairo-surface.sgml      |    8 +++
 doc/public/tmpl/cairo-xcb-xrender.sgml  |    3 -
 doc/public/tmpl/cairo-xcb.sgml          |    3 -
 doc/public/tmpl/cairo-xlib-xrender.sgml |    3 -
 doc/public/tmpl/cairo-xlib.sgml         |    3 -
 src/Makefile.am                         |    2 
 src/cairo-array.c                       |   12 ++---
 src/cairo-base85-stream.c               |    3 -
 src/cairo-bentley-ottmann.c             |   14 +++---
 src/cairo-beos-surface.cpp              |    2 
 src/cairo-cache-private.h               |    8 +--
 src/cairo-cache.c                       |   12 ++---
 src/cairo-debug.c                       |    4 -
 src/cairo-deflate-stream.c              |    3 -
 src/cairo-deprecated.h                  |    2 
 src/cairo-directfb.h                    |    4 -
 src/cairo-fixed-type-private.h          |    4 -
 src/cairo-font-face.c                   |   14 +++---
 src/cairo-font-options.c                |    2 
 src/cairo-freelist-private.h            |    4 -
 src/cairo-ft-font.c                     |   30 ++++++-------
 src/cairo-gstate.c                      |   18 ++++----
 src/cairo-hash.c                        |   38 ++++++++--------
 src/cairo-image-surface.c               |   22 ++++-----
 src/cairo-lzw.c                         |   18 ++++----
 src/cairo-matrix.c                      |   10 ++--
 src/cairo-meta-surface.c                |    6 +-
 src/cairo-mutex-private.h               |    4 -
 src/cairo-mutex-type-private.h          |   30 ++++++-------
 src/cairo-os2.h                         |    6 +-
 src/cairo-output-stream-private.h       |   11 ++--
 src/cairo-output-stream.c               |    3 -
 src/cairo-paginated-private.h           |   18 ++++----
 src/cairo-path-fill.c                   |    2 
 src/cairo-path-fixed-private.h          |    2 
 src/cairo-path.c                        |   18 ++++----
 src/cairo-pattern.c                     |   12 ++---
 src/cairo-pdf-surface.c                 |    8 +--
 src/cairo-pen.c                         |    4 -
 src/cairo-png.c                         |   12 ++---
 src/cairo-ps-surface.c                  |   32 +++++++-------
 src/cairo-ps.h                          |    2 
 src/cairo-quartz-surface.c              |    4 -
 src/cairo-rectangle.c                   |    8 +--
 src/cairo-region-private.h              |    2 
 src/cairo-region.c                      |    2 
 src/cairo-scaled-font-subsets-private.h |   68 +++++++++++++++---------------
 src/cairo-scaled-font.c                 |   24 +++++-----
 src/cairo-slope.c                       |    2 
 src/cairo-surface-fallback.c            |    6 +-
 src/cairo-surface.c                     |   20 ++++----
 src/cairo-svg-surface.c                 |    8 +--
 src/cairo-svg.h                         |    2 
 src/cairo-traps.c                       |    4 -
 src/cairo-types-private.h               |   10 ++--
 src/cairo-unicode.c                     |    3 -
 src/cairo-win32-font.c                  |    6 +-
 src/cairo-win32-surface.c               |   16 +++----
 src/cairo-xcb-surface.c                 |    6 +-
 src/cairo-xlib-surface.c                |   30 ++++++++-----
 src/cairo.c                             |   66 ++++++++++++++---------------
 src/cairo.h                             |   72 ++++++++++++++++----------------
 src/cairoint.h                          |   20 ++++----
 src/check-doc-syntax.sh                 |   44 +++++++++++++++++++
 src/test-fallback-surface.c             |    4 -
 72 files changed, 513 insertions(+), 405 deletions(-)

New commits:
commit 52cc603db1a805a0b3a8d7eba3171cd2785f10a7
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 22:10:20 2008 -0500

    [doc] Stricter syntax check for type names, update test

diff --git a/src/cairo-array.c b/src/cairo-array.c
index a6918b2..b547b12 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -331,7 +331,7 @@ _cairo_array_size (cairo_array_t *array)
     return array->size;
 }
 
-/* cairo_user_data_array_t */
+/* #cairo_user_data_array_t */
 
 typedef struct {
     const cairo_user_data_key_t *key;
diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h
index 65a8aee..4ae63ad 100644
--- a/src/cairo-cache-private.h
+++ b/src/cairo-cache-private.h
@@ -46,7 +46,7 @@
  * cairo_cache_entry_t:
  *
  * A #cairo_cache_entry_t contains both a key and a value for
- * cairo_cache_t. User-derived types for #cairo_cache_entry_t must
+ * #cairo_cache_t. User-derived types for #cairo_cache_entry_t must
  * have a #cairo_cache_entry_t as their first field. For example:
  *
  * 	typedef _my_entry {
diff --git a/src/cairo-font-face.c b/src/cairo-font-face.c
index 6a29600..397dd56 100644
--- a/src/cairo-font-face.c
+++ b/src/cairo-font-face.c
@@ -45,7 +45,7 @@
  */
 static const cairo_font_face_backend_t _cairo_toy_font_face_backend;
 
-/* cairo_font_face_t */
+/* #cairo_font_face_t */
 
 const cairo_font_face_t _cairo_font_face_nil = {
     { 0 },			/* hash_entry */
@@ -256,7 +256,7 @@ _cairo_toy_font_face_keys_equal (const void *key_a,
 				 const void *key_b);
 
 /* We maintain a hash table from family/weight/slant =>
- * cairo_font_face_t for #cairo_toy_font_t. The primary purpose of
+ * #cairo_font_face_t for #cairo_toy_font_t. The primary purpose of
  * this mapping is to provide unique #cairo_font_face_t values so that
  * our cache and mapping from #cairo_font_face_t => #cairo_scaled_font_t
  * works. Once the corresponding #cairo_font_face_t objects fall out of
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index 2fce865..00f3b91 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -1244,7 +1244,7 @@ static const cairo_unscaled_font_backend_t cairo_ft_unscaled_font_backend = {
 #endif
 };
 
-/* cairo_ft_scaled_font_t */
+/* #cairo_ft_scaled_font_t */
 
 typedef struct _cairo_ft_scaled_font {
     cairo_scaled_font_t base;
@@ -2192,7 +2192,7 @@ const cairo_scaled_font_backend_t cairo_ft_scaled_font_backend = {
     _cairo_ft_map_glyphs_to_unicode,
 };
 
-/* cairo_ft_font_face_t */
+/* #cairo_ft_font_face_t */
 
 static void
 _cairo_ft_font_face_destroy (void *abstract_face)
diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index c85a2b4..59ea6f2 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -406,7 +406,7 @@ _cairo_image_surface_create_with_content (cairo_content_t	content,
  * <informalexample><programlisting>
  * int stride;
  * unsigned char *data;
- * cairo_surface_t *surface;
+ * #cairo_surface_t *surface;
  *
  * stride = cairo_format_stride_for_width (format, width);
  * data = malloc (stride * height);
diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h
index ab2ee1d..35384c9 100644
--- a/src/cairo-paginated-private.h
+++ b/src/cairo-paginated-private.h
@@ -75,11 +75,11 @@ struct _cairo_paginated_surface_backend {
  * for saving content in files such as PostScript or PDF files).
  *
  * To use the paginated surface, you'll first need to create your
- * 'real' surface using _cairo_surface_init and the standard
- * cairo_surface_backend_t. Then you also call
+ * 'real' surface using _cairo_surface_init() and the standard
+ * #cairo_surface_backend_t. Then you also call
  * _cairo_paginated_surface_create which takes its own, much simpler,
- * cairo_paginated_surface_backend. You are free to return the result
- * of _cairo_paginated_surface_create from your public
+ * #cairo_paginated_surface_backend_t. You are free to return the result
+ * of _cairo_paginated_surface_create() from your public
  * cairo_<foo>_surface_create. The paginated backend will be careful
  * to not let the user see that they really got a "wrapped"
  * surface. See test-paginated-surface.c for a fairly minimal example
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index 2473eb8..65df5a2 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -1366,7 +1366,7 @@ cairo_ps_surface_set_size (cairo_surface_t	*surface,
  * Here is an example sequence showing how this function might be used:
  *
  * <informalexample><programlisting>
- * cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height);
+ * #cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height);
  * ...
  * cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document");
  * cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
diff --git a/src/cairo-ps.h b/src/cairo-ps.h
index f3ac290..720b1b7 100644
--- a/src/cairo-ps.h
+++ b/src/cairo-ps.h
@@ -48,7 +48,7 @@ CAIRO_BEGIN_DECLS
 /* PS-surface functions */
 
 /**
- * cairo_ps_level_t
+ * cairo_ps_level_t:
  * @CAIRO_PS_LEVEL_2: The language level 2 of the PostScript specification.
  * @CAIRO_PS_LEVEL_3: The language level 3 of the PostScript specification.
  *
diff --git a/src/cairo-region-private.h b/src/cairo-region-private.h
index 8fc6567..4e2d723 100644
--- a/src/cairo-region-private.h
+++ b/src/cairo-region-private.h
@@ -41,7 +41,7 @@
 
 #include "cairo-compiler-private.h"
 
-/* cairo_region_t is defined in cairoint.h */
+/* #cairo_region_t is defined in cairoint.h */
 
 struct _cairo_region {
     pixman_region16_t rgn;
diff --git a/src/cairo-scaled-font-subsets-private.h b/src/cairo-scaled-font-subsets-private.h
index bccd0de..733fe1e 100644
--- a/src/cairo-scaled-font-subsets-private.h
+++ b/src/cairo-scaled-font-subsets-private.h
@@ -292,7 +292,7 @@ typedef struct _cairo_cff_subset {
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a
+ * #cairo_scaled_font_t and the font backend in use) generate a
  * cff file corresponding to @font_subset and initialize
  * @cff_subset with information about the subset and the cff
  * data.
@@ -324,7 +324,7 @@ _cairo_cff_subset_fini (cairo_cff_subset_t *cff_subset);
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a cff
+ * #cairo_scaled_font_t and the font backend in use) generate a cff
  * file corresponding to @font_subset and initialize @cff_subset
  * with information about the subset and the cff data.
  *
@@ -366,7 +366,7 @@ typedef struct _cairo_truetype_subset {
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a
+ * #cairo_scaled_font_t and the font backend in use) generate a
  * truetype file corresponding to @font_subset and initialize
  * @truetype_subset with information about the subset and the truetype
  * data.
@@ -411,7 +411,7 @@ typedef struct _cairo_type1_subset {
  * @hex_encode: if true the encrypted portion of the font is hex encoded
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a type1
+ * #cairo_scaled_font_t and the font backend in use) generate a type1
  * file corresponding to @font_subset and initialize @type1_subset
  * with information about the subset and the type1 data.
  *
@@ -452,7 +452,7 @@ _cairo_type1_scaled_font_is_type1 (cairo_scaled_font_t	*scaled_font);
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a type1
+ * #cairo_scaled_font_t and the font backend in use) generate a type1
  * file corresponding to @font_subset and initialize @type1_subset
  * with information about the subset and the type1 data.  The encrypted
  * part of the font is binary encoded.
@@ -473,7 +473,7 @@ _cairo_type1_fallback_init_binary (cairo_type1_subset_t	      *type_subset,
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate a type1
+ * #cairo_scaled_font_t and the font backend in use) generate a type1
  * file corresponding to @font_subset and initialize @type1_subset
  * with information about the subset and the type1 data. The encrypted
  * part of the font is hex encoded.
@@ -512,7 +512,7 @@ typedef struct _cairo_type2_charstrings {
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) generate type2
+ * #cairo_scaled_font_t and the font backend in use) generate type2
  * charstrings to @font_subset and initialize @type2_subset
  * with information about the subset.
  *
@@ -541,7 +541,7 @@ _cairo_type2_charstrings_fini (cairo_type2_charstrings_t *charstrings);
  * @font_subset: the #cairo_scaled_font_subset_t to initialize from
  *
  * If possible (depending on the format of the underlying
- * cairo_scaled_font_t and the font backend in use) assign
+ * #cairo_scaled_font_t and the font backend in use) assign
  * the unicode character of each glyph in font_subset to
  * fontsubset->to_unicode.
  *
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index 469b4dc..43fe29b 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -271,7 +271,7 @@ cairo_scaled_font_status (cairo_scaled_font_t *scaled_font)
 slim_hidden_def (cairo_scaled_font_status);
 
 /* Here we keep a unique mapping from
- * cairo_font_face_t/matrix/ctm/options => #cairo_scaled_font_t.
+ * font_face/matrix/ctm/font_options => #cairo_scaled_font_t.
  *
  * Here are the things that we want to map:
  *
diff --git a/src/cairo-svg.h b/src/cairo-svg.h
index 2c4f5ab..5d18c64 100644
--- a/src/cairo-svg.h
+++ b/src/cairo-svg.h
@@ -39,7 +39,7 @@
 CAIRO_BEGIN_DECLS
 
 /**
- * cairo_svg_version_t
+ * cairo_svg_version_t:
  * @CAIRO_SVG_VERSION_1_1: The version 1.1 of the SVG specification.
  * @CAIRO_SVG_VERSION_1_2: The version 1.2 of the SVG specification.
  *
diff --git a/src/cairo-types-private.h b/src/cairo-types-private.h
index 0b84774..9cb9882 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -61,7 +61,7 @@ typedef cairo_array_t cairo_user_data_array_t;
  * cairo_hash_entry_t:
  *
  * A #cairo_hash_entry_t contains both a key and a value for
- * cairo_hash_table_t. User-derived types for #cairo_hash_entry_t must
+ * #cairo_hash_table_t. User-derived types for #cairo_hash_entry_t must
  * be type-compatible with this structure (eg. they must have an
  * unsigned long as the first parameter. The easiest way to get this
  * is to use:
diff --git a/src/cairo-win32-font.c b/src/cairo-win32-font.c
index 2039264..eb4d3b1 100644
--- a/src/cairo-win32-font.c
+++ b/src/cairo-win32-font.c
@@ -1763,7 +1763,7 @@ const cairo_scaled_font_backend_t cairo_win32_scaled_font_backend = {
     _cairo_win32_scaled_font_map_glyphs_to_unicode,
 };
 
-/* cairo_win32_font_face_t */
+/* #cairo_win32_font_face_t */
 
 typedef struct _cairo_win32_font_face cairo_win32_font_face_t;
 
diff --git a/src/cairo.c b/src/cairo.c
index 7d429f2..d3c5ba4 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -605,7 +605,7 @@ slim_hidden_def(cairo_pop_group);
  * operations:
  *
  * <informalexample><programlisting>
- * cairo_pattern_t *group = cairo_pop_group (cr);
+ * #cairo_pattern_t *group = cairo_pop_group (cr);
  * cairo_set_source (cr, group);
  * cairo_pattern_destroy (group);
  * </programlisting></informalexample>
diff --git a/src/cairo.h b/src/cairo.h
index bcef13a..37a34a6 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -177,7 +177,7 @@ typedef struct _cairo_user_data_key {
 } cairo_user_data_key_t;
 
 /**
- * cairo_status_t
+ * cairo_status_t:
  * @CAIRO_STATUS_SUCCESS: no error has occurred
  * @CAIRO_STATUS_NO_MEMORY: out of memory
  * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save()
@@ -242,7 +242,7 @@ typedef enum _cairo_status {
 } cairo_status_t;
 
 /**
- * cairo_content_t
+ * cairo_content_t:
  * @CAIRO_CONTENT_COLOR: The surface will hold color content only.
  * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only.
  * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content.
@@ -345,7 +345,7 @@ cairo_pop_group_to_source (cairo_t *cr);
 /* Modify state */
 
 /**
- * cairo_operator_t
+ * cairo_operator_t:
  * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded)
  * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded)
  * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer
@@ -441,7 +441,7 @@ cairo_public void
 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
 
 /**
- * cairo_fill_rule_t
+ * cairo_fill_rule_t:
  * @CAIRO_FILL_RULE_WINDING: 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
@@ -475,7 +475,7 @@ cairo_public void
 cairo_set_line_width (cairo_t *cr, double width);
 
 /**
- * cairo_line_cap_t
+ * cairo_line_cap_t:
  * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point
  * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
  * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
@@ -492,7 +492,7 @@ cairo_public void
 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
 
 /**
- * cairo_line_join_t
+ * cairo_line_join_t:
  * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see
  * cairo_set_miter_limit()
  * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the
@@ -1132,7 +1132,7 @@ cairo_public cairo_status_t
 cairo_font_face_status (cairo_font_face_t *font_face);
 
 /**
- * cairo_font_type_t
+ * cairo_font_type_t:
  * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api
  * @CAIRO_FONT_TYPE_FT: The font is of type FreeType
  * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32
@@ -1462,7 +1462,7 @@ cairo_public cairo_status_t
 cairo_surface_status (cairo_surface_t *surface);
 
 /**
- * cairo_surface_type_t
+ * cairo_surface_type_t:
  * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image
  * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf
  * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps
@@ -1586,7 +1586,7 @@ cairo_surface_show_page (cairo_surface_t *surface);
 /* Image-surface functions */
 
 /**
- * cairo_format_t
+ * cairo_format_t:
  * @CAIRO_FORMAT_ARGB32: 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
@@ -1708,7 +1708,7 @@ cairo_pattern_set_user_data (cairo_pattern_t		 *pattern,
 			     cairo_destroy_func_t	  destroy);
 
 /**
- * cairo_pattern_type_t
+ * cairo_pattern_type_t:
  * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform)
  * color. It may be opaque or translucent.
  * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image).
@@ -1767,7 +1767,7 @@ cairo_pattern_get_matrix (cairo_pattern_t *pattern,
 			  cairo_matrix_t  *matrix);
 
 /**
- * cairo_extend_t
+ * cairo_extend_t:
  * @CAIRO_EXTEND_NONE: pixels outside of the source pattern
  *   are fully transparent
  * @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating
@@ -1796,7 +1796,7 @@ cairo_public cairo_extend_t
 cairo_pattern_get_extend (cairo_pattern_t *pattern);
 
 /**
- * cairo_filter_t
+ * cairo_filter_t:
  * @CAIRO_FILTER_FAST: A high-performance filter, with quality similar
  *     to %CAIRO_FILTER_NEAREST
  * @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality
diff --git a/src/cairoint.h b/src/cairoint.h
index 61c59ff..75b646e 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -291,7 +291,7 @@ struct _cairo_unscaled_font_backend {
     void (*destroy)     	    (void		             *unscaled_font);
 };
 
-/* cairo_toy_font_face_t - simple family/slant/weight font faces used for
+/* #cairo_toy_font_face_t - simple family/slant/weight font faces used for
  * the built-in font API
  */
 
diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
index a7e8d5a..7b0908f 100755
--- a/src/check-doc-syntax.sh
+++ b/src/check-doc-syntax.sh
@@ -17,12 +17,13 @@ if grep "$enum_regexp" $FILES; then
 	echo "	sed -i 's@$enum_regexp@\\1%\\2@' *.h *.c *.cpp"
 fi
 
-type_regexp='^\([/ ][*] .*[^#]\)\<\(cairo[0-9a-z_]*_t\>\)'
+type_regexp='^[/ ][*]\( .*[^#]\| \)\<\(cairo[0-9a-z_]*_t\>\($\|[^:]$\|[^:].\)\)'
 if grep "$type_regexp" $FILES; then
 	status=1
-	echo Error: some type names in the docs are not prefixed by hash sign.
-	echo Fix this by running the following sed command as many times as needed:
-	echo "	sed -i 's@$type_regexp@\\1#\\2@' *.h *.c *.cpp"
+	echo Error: some type names in the docs are not prefixed by hash sign,
+	echo neither are the only token in the doc line followed by collon.
+	echo Fix this by searching for the following regexp in the above files:
+	echo "	'$type_regexp'"
 fi
 
 func_regexp='^\([/ ][*] .*[^#]\)\<\(cairo_[][<>/0-9a-z_]*\> \?[^][ <>(]\)'
commit b790c5a6bcdd890c16d21753407188ed200ce445
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:53:44 2008 -0500

    [doc] Replace 'NOTE' by 'Note' and add it to test

diff --git a/src/cairo-bentley-ottmann.c b/src/cairo-bentley-ottmann.c
index 6a591a7..1da9743 100644
--- a/src/cairo-bentley-ottmann.c
+++ b/src/cairo-bentley-ottmann.c
@@ -385,7 +385,7 @@ cairo_bo_event_compare (cairo_bo_event_t const *a,
      * need a different sense for start and stop events based on the
      * shortening rule.
      *
-     * NOTE: Fortunately, we get to ignore errors in the relative
+     * Note: Fortunately, we get to ignore errors in the relative
      * ordering of intersection events. This means we don't even have
      * to look at e2 here, nor worry about which sense of the slope
      * comparison test is used for intersection events.
diff --git a/src/cairo-cache.c b/src/cairo-cache.c
index b0d5bb0..c87e20f 100644
--- a/src/cairo-cache.c
+++ b/src/cairo-cache.c
@@ -172,7 +172,7 @@ _cairo_cache_destroy (cairo_cache_t *cache)
  * add new entries to the cache regardless of how large the cache
  * grows. See _cairo_cache_thaw().
  *
- * NOTE: Multiple calls to _cairo_cache_freeze() will stack, in that
+ * Note: Multiple calls to _cairo_cache_freeze() will stack, in that
  * the cache will remain "frozen" until a corresponding number of
  * calls are made to _cairo_cache_thaw().
  **/
@@ -323,7 +323,7 @@ _cairo_cache_insert (cairo_cache_t	 *cache,
  *
  * Remove an existing entry from the cache.
  *
- * (NOTE: If any caller wanted access to a non-static version of this
+ * (Note: If any caller wanted access to a non-static version of this
  * function, an improved version would require only a key rather than
  * an entry. Fixing that would require fixing _cairo_hash_table_remove
  * to return (a copy of?) the entry being removed.)
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index bcb41b2..2fce865 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -2606,7 +2606,7 @@ cairo_ft_scaled_font_lock_face (cairo_scaled_font_t *abstract_font)
 	return NULL;
     }
 
-    /* NOTE: We deliberately release the unscaled font's mutex here,
+    /* Note: We deliberately release the unscaled font's mutex here,
      * so that we are not holding a lock across two separate calls to
      * cairo function, (which would give the application some
      * opportunity for creating deadlock. This is obviously unsafe,
@@ -2634,7 +2634,7 @@ cairo_ft_scaled_font_unlock_face (cairo_scaled_font_t *abstract_font)
     if (scaled_font->base.status)
 	return;
 
-    /* NOTE: We released the unscaled font's mutex at the end of
+    /* Note: We released the unscaled font's mutex at the end of
      * cairo_ft_scaled_font_lock_face, so we have to acquire it again
      * as _cairo_ft_unscaled_font_unlock_face expects it to be held
      * when we call into it. */
diff --git a/src/cairo-lzw.c b/src/cairo-lzw.c
index fcf90be..d95da8c 100644
--- a/src/cairo-lzw.c
+++ b/src/cairo-lzw.c
@@ -113,7 +113,7 @@ _lzw_buf_grow (lzw_buf_t *buf)
 
 /* Store the lowest num_bits bits of values into buf.
  *
- * NOTE: The bits of value above size_in_bits must be 0, (so don't lie
+ * Note: The bits of value above size_in_bits must be 0, (so don't lie
  * about the size).
  *
  * See also _lzw_buf_store_pending which must be called after the last
@@ -147,7 +147,7 @@ _lzw_buf_store_bits (lzw_buf_t *buf, uint16_t value, int num_bits)
 
 /* Store the last remaining pending bits into the buffer.
  *
- * NOTE: This function must be called after the last call to
+ * Note: This function must be called after the last call to
  * _lzw_buf_store_bits.
  *
  * Sets buf->status to either %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY.
diff --git a/src/cairo-output-stream-private.h b/src/cairo-output-stream-private.h
index 1fc9b8e..2ee43de 100644
--- a/src/cairo-output-stream-private.h
+++ b/src/cairo-output-stream-private.h
@@ -131,7 +131,7 @@ _cairo_output_stream_get_status (cairo_output_stream_t *stream);
  * WRITE_ERROR) while trying to create the output stream this function
  * returns a valid pointer to a nil output stream.
  *
- * NOTE: Even if a nil surface is returned, the caller should still
+ * Note: Even if a nil surface is returned, the caller should still
  * call _cairo_output_stream_destroy (or _cairo_output_stream_close at
  * least) in order to ensure that everything is properly cleaned up.
  */
diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h
index 4b10601..ab2ee1d 100644
--- a/src/cairo-paginated-private.h
+++ b/src/cairo-paginated-private.h
@@ -41,7 +41,7 @@
 struct _cairo_paginated_surface_backend {
     /* Optional. Will be called once for each page.
      *
-     * NOTE: With respect to the order of drawing operations as seen
+     * Note: With respect to the order of drawing operations as seen
      * by the target, this call will occur before any drawing
      * operations for the relevant page. However, with respect to the
      * function calls as made by the user, this call will be *after*
@@ -127,7 +127,7 @@ struct _cairo_paginated_surface_backend {
  * to distinguish fallback images from native rendering in case they
  * need to be handled as a special case.
  *
- * NOTE: The paginated surface layer assumes that the target surface
+ * Note: The paginated surface layer assumes that the target surface
  * is "blank" by default at the beginning of each page, without any
  * need for an explicit erase operation, (as opposed to an image
  * surface, for example, which might have uninitialized content
diff --git a/src/cairo-path.c b/src/cairo-path.c
index e0b21ef..c6639f3 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() 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.
diff --git a/src/cairo-pen.c b/src/cairo-pen.c
index 6291763..cde129c 100644
--- a/src/cairo-pen.c
+++ b/src/cairo-pen.c
@@ -302,7 +302,7 @@ _cairo_pen_compute_slopes (cairo_pen_t *pen)
 /*
  * Find active pen vertex for clockwise edge of stroke at the given slope.
  *
- * NOTE: The behavior of this function is sensitive to the sense of
+ * Note: The behavior of this function is sensitive to the sense of
  * the inequality within _cairo_slope_clockwise/_cairo_slope_counter_clockwise.
  *
  * The issue is that the slope_ccw member of one pen vertex will be
@@ -336,7 +336,7 @@ _cairo_pen_find_active_cw_vertex_index (cairo_pen_t *pen,
 
 /* Find active pen vertex for counterclockwise edge of stroke at the given slope.
  *
- * NOTE: The behavior of this function is sensitive to the sense of
+ * Note: The behavior of this function is sensitive to the sense of
  * the inequality within _cairo_slope_clockwise/_cairo_slope_counter_clockwise.
  */
 void
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index ed01b1f..469b4dc 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -41,7 +41,7 @@
 #include "cairo-scaled-font-private.h"
 
 /*
- *  NOTES:
+ *  Notes:
  *
  *  To store rasterizations of glyphs, we use an image surface and the
  *  device offset to represent the glyph origin.
@@ -1714,7 +1714,7 @@ _cairo_scaled_glyph_set_path (cairo_scaled_glyph_t *scaled_glyph,
  * get INFO_PATH with a bitmapped font), this function will return
  * CAIRO_INT_STATUS_UNSUPPORTED.
  *
- * NOTE: This function must be called with scaled_font->mutex held.
+ * Note: This function must be called with scaled_font->mutex held.
  **/
 cairo_int_status_t
 _cairo_scaled_glyph_lookup (cairo_scaled_font_t *scaled_font,
diff --git a/src/cairo-slope.c b/src/cairo-slope.c
index 78664c5..e8421fc 100644
--- a/src/cairo-slope.c
+++ b/src/cairo-slope.c
@@ -88,7 +88,7 @@ _cairo_slope_compare (cairo_slope_t *a, cairo_slope_t *b)
 
 /* Is a clockwise of b?
  *
- * NOTE: The strict equality here is not significant in and of itself,
+ * Note: The strict equality here is not significant in and of itself,
  * but there are functions up above that are sensitive to it,
  * (cf. _cairo_pen_find_active_cw_vertex_index).
  */
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 074be10..16c48f1 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -882,7 +882,7 @@ slim_hidden_def (cairo_surface_get_device_offset);
  * device resolution. So this function has no effect on those
  * backends.
  *
- * NOTE: The fallback resolution only takes effect at the time of
+ * Note: The fallback resolution only takes effect at the time of
  * completing a page (with cairo_show_page() or cairo_copy_page()) so
  * there is currently no way to have more than one fallback resolution
  * in effect on a single page.
@@ -2005,7 +2005,7 @@ _cairo_surface_set_clip (cairo_surface_t *surface, cairo_clip_t *clip)
  * maximum size at the time of surface_create. So get_extents uses
  * that size.
  *
- * NOTE: The coordinates returned are in "backend" space rather than
+ * 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_t interfaces, but all
diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c
index b222ef4..ca8b87c 100644
--- a/src/cairo-win32-surface.c
+++ b/src/cairo-win32-surface.c
@@ -205,7 +205,7 @@ _create_dc_and_bitmap (cairo_win32_surface_t *surface,
      * break if we do, especially if we don't set up an image
      * fallback.  It could be a bug with using a 24bpp pixman image
      * (and creating one with masks).  So treat them like 32bpp.
-     * NOTE: This causes problems when using BitBlt/AlphaBlend/etc!
+     * Note: This causes problems when using BitBlt/AlphaBlend/etc!
      * see end of file.
      */
     case CAIRO_FORMAT_RGB24:
@@ -1261,7 +1261,7 @@ UNSUPPORTED:
 /* This big function tells us how to optimize operators for the
  * case of solid destination and constant-alpha source
  *
- * NOTE: This function needs revisiting if we add support for
+ * Note: This function needs revisiting if we add support for
  *       super-luminescent colors (a == 0, r,g,b > 0)
  */
 static enum { DO_CLEAR, DO_SOURCE, DO_NOTHING, DO_UNSUPPORTED }
diff --git a/src/cairo-xcb-surface.c b/src/cairo-xcb-surface.c
index 39ca0de..f7ae9d1 100644
--- a/src/cairo-xcb-surface.c
+++ b/src/cairo-xcb-surface.c
@@ -1854,7 +1854,7 @@ _cairo_xcb_screen_from_visual (xcb_connection_t *c, xcb_visualtype_t *visual)
  * The way that colors are represented in the drawable is specified
  * by the provided visual.
  *
- * NOTE: If @drawable is a window, then the function
+ * Note: If @drawable is a window, then the function
  * cairo_xcb_surface_set_size must be called whenever the size of the
  * window changes.
  *
@@ -1916,7 +1916,7 @@ cairo_xcb_surface_create_for_bitmap (xcb_connection_t     *c,
  * The way that colors are represented in the drawable is specified
  * by the provided picture format.
  *
- * NOTE: If @drawable is a Window, then the function
+ * Note: If @drawable is a Window, then the function
  * cairo_xcb_surface_set_size must be called whenever the size of the
  * window changes.
  *
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index d43b5a8..0957faf 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -2070,7 +2070,7 @@ _cairo_xlib_screen_from_visual (Display *dpy, Visual *visual)
  * The way that colors are represented in the drawable is specified
  * by the provided visual.
  *
- * NOTE: If @drawable is a Window, then the function
+ * Note: If @drawable is a Window, then the function
  * cairo_xlib_surface_set_size must be called whenever the size of the
  * window changes.
  *
@@ -2140,7 +2140,7 @@ cairo_xlib_surface_create_for_bitmap (Display  *dpy,
  * The way that colors are represented in the drawable is specified
  * by the provided picture format.
  *
- * NOTE: If @drawable is a Window, then the function
+ * Note: If @drawable is a Window, then the function
  * cairo_xlib_surface_set_size must be called whenever the size of the
  * window changes.
  *
diff --git a/src/cairo.c b/src/cairo.c
index 864177d..7d429f2 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -2959,7 +2959,7 @@ cairo_glyph_extents (cairo_t                *cr,
  * by its advance values. This allows for easy display of a single
  * logical string with multiple calls to cairo_show_text().
  *
- * NOTE: The cairo_show_text() function call is part of what the cairo
+ * Note: The cairo_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 cairo_show_glyphs() for the
@@ -3058,7 +3058,7 @@ cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
  * This allows for chaining multiple calls to to cairo_text_path()
  * without having to set current point in between.
  *
- * NOTE: The cairo_text_path() function call is part of what the cairo
+ * Note: The cairo_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 cairo_glyph_path() for the
diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
index 17e606b..a7e8d5a 100755
--- a/src/check-doc-syntax.sh
+++ b/src/check-doc-syntax.sh
@@ -33,4 +33,11 @@ if grep "$func_regexp" $FILES; then
 	echo "	'$func_regexp'"
 fi
 
+note_regexp='NOTE'
+if grep "$note_regexp" $FILES; then
+	status=1
+	echo Error: some source files contain the string 'NOTE'.
+	echo Be civil and replace it by 'Note' please.
+fi
+
 exit $status
commit f0633f4449c39a8f78c582790fb5dc85899b5d82
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:49:57 2008 -0500

    [doc] Make sure all function names in docs are followed by ()

diff --git a/src/cairo-array.c b/src/cairo-array.c
index 6940b40..a6918b2 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 b7dc9b1..2b8a8be 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 193fa43..69dfd83 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 e2e2056..65a8aee 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 cdd3ce9..c4b7edf 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 8734b17..9feb46d 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 a566fac..bcb41b2 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 ba0ce6a..c85a2b4 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 ac87447..1fc9b8e 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 2cb9e03..22245f7 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 48e646d..4b10601 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 f506c34..9fcb2e1 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 f480b62..e0b21ef 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 2b8f745..1de4714 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 844156e..2473eb8 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 f3fb36b..9aff1c3 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 fe6c23a..bccd0de 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 33d83c9..ed01b1f 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 3227dbe..074be10 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 712b8ab..6cd5e08 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 195ae88..8b009b1 100644
--- a/src/cairo-traps.c
+++ b/src/cairo-traps.c
@@ -34,7 +34,7 @@
  *	Keith R. Packard <keithp at keithp.com>
  *	Carl D. Worth <cworth at 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 42713dd..0b84774 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 18b9143..5f91de3 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 1db90a5..864177d 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 873a1ce..bcef13a 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 db6a98c..61c59ff 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)
commit 9ba8f6b1b0a4fbf2407e0dbd767f043c6920344c
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:49:26 2008 -0500

    [src/check-doc-syntax.sh] Check for various doc syntax consistency rules

diff --git a/src/Makefile.am b/src/Makefile.am
index 510a53e..c1a2361 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -318,7 +318,7 @@ install-data-local:
         fi
 
 TESTS_ENVIRONMENT = srcdir="$(srcdir)" MAKE="$(MAKE)"
-TESTS = check-def.sh check-plt.sh check-headers.sh check-cairoint.sh
+TESTS = check-def.sh check-plt.sh check-headers.sh check-cairoint.sh check-doc-syntax.sh
 EXTRA_DIST += $(TESTS) check-has-hidden-symbols.c
 DISTCLEANFILES += check-has-hidden-symbols.i
 
diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
new file mode 100755
index 0000000..17e606b
--- /dev/null
+++ b/src/check-doc-syntax.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+
+LANG=C
+
+test -z "$srcdir" && srcdir=.
+status=0
+
+echo Checking documentation blocks for missing decorators
+
+FILES=`find "$srcdir" -name '*.h' -or -name '*.c' -or -name '*.cpp'`
+
+enum_regexp='^\([/ ][*] .*[^%@]\)\<\(FALSE\|TRUE\|NULL\|CAIRO_[0-9A-Z_]*[^(0-9A-Z_]\)'
+if grep "$enum_regexp" $FILES; then
+	status=1
+	echo Error: some macros in the docs are not prefixed by percent sign.
+	echo Fix this by running the following sed command as many times as needed:
+	echo "	sed -i 's@$enum_regexp@\\1%\\2@' *.h *.c *.cpp"
+fi
+
+type_regexp='^\([/ ][*] .*[^#]\)\<\(cairo[0-9a-z_]*_t\>\)'
+if grep "$type_regexp" $FILES; then
+	status=1
+	echo Error: some type names in the docs are not prefixed by hash sign.
+	echo Fix this by running the following sed command as many times as needed:
+	echo "	sed -i 's@$type_regexp@\\1#\\2@' *.h *.c *.cpp"
+fi
+
+func_regexp='^\([/ ][*] .*[^#]\)\<\(cairo_[][<>/0-9a-z_]*\> \?[^][ <>(]\)'
+if grep "$func_regexp" $FILES; then
+	status=1
+	echo Error: some function names in the docs are not followed by parantheses.
+	echo Fix this by searching for the following regexp in the above files:
+	echo "	'$func_regexp'"
+fi
+
+exit $status
commit e15fcdd74734e922183afd4732ec4ba090f313c9
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:48:23 2008 -0500

    [doc] Improve syntax

diff --git a/doc/public/tmpl/cairo-font.sgml b/doc/public/tmpl/cairo-font.sgml
index 079c40d..8a4e809 100644
--- a/doc/public/tmpl/cairo-font.sgml
+++ b/doc/public/tmpl/cairo-font.sgml
@@ -8,8 +8,11 @@ Base class for font faces
 <para>
 #cairo_font_face_t represents a particular font at a particular weight,
 slant, and other characteristic but no size, transformation, or size.
-
-Font faces are created using font-backend specific constructors,
+</para>
+<para>
+Font faces are created using <firstterm>font-backend</firstterm>-specific
+constructors, typically of the form
+cairo_<emphasis>backend</emphasis>_font_face_create(),
 or implicitly using the <firstterm>toy</firstterm> text API by way of
 cairo_select_font_face().  The resulting face can be accessed using
 cairo_get_font_face().
diff --git a/doc/public/tmpl/cairo-matrix.sgml b/doc/public/tmpl/cairo-matrix.sgml
index 308a3ba..720cdac 100644
--- a/doc/public/tmpl/cairo-matrix.sgml
+++ b/doc/public/tmpl/cairo-matrix.sgml
@@ -5,7 +5,7 @@ cairo_matrix_t
 Generic matrix operations
 
 <!-- ##### SECTION Long_Description ##### -->
-  <para><indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
+  <para>
     #cairo_matrix_t is used throughout cairo to convert between different
     coordinate spaces.  A #cairo_matrix_t holds an affine transformation,
     such as a scale, rotation, shear, or a combination of these.
diff --git a/doc/public/tmpl/cairo-pattern.sgml b/doc/public/tmpl/cairo-pattern.sgml
index 0deaa63..adcff66 100644
--- a/doc/public/tmpl/cairo-pattern.sgml
+++ b/doc/public/tmpl/cairo-pattern.sgml
@@ -6,9 +6,15 @@ Sources for drawing
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Patterns are 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.
+#cairo_pattern_t 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.
+</para>
+<para>
+A cairo pattern is created by using one of the many constructors,
+of the form cairo_pattern_create_<emphasis>type</emphasis>()
+or implicitly through
+cairo_set_source_<emphasis>type</emphasis>() functions.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/doc/public/tmpl/cairo-status.sgml b/doc/public/tmpl/cairo-status.sgml
index 2ee02ca..9b2bbe1 100644
--- a/doc/public/tmpl/cairo-status.sgml
+++ b/doc/public/tmpl/cairo-status.sgml
@@ -9,10 +9,11 @@ Decoding cairo's status
 Cairo uses a single status type to represent all kinds of errors.  A status
 value of %CAIRO_STATUS_SUCCESS represents no error and has an integer value
 of zero.  All other status values represent an error.
-
+</para>
+<para>
 Cairo's error handling is designed to be easy to use and safe.  All major
 cairo objects <firstterm>retain</firstterm> an error status internally which
-can be queried anytime by the users using cairo_*_status<!---->() calls.  In
+can be queried anytime by the users using cairo*_status() calls.  In
 the mean time, it is safe to call all cairo functions normally even if the
 underlying object is in an error status.  This means that no error handling
 code is required before or after each individual cairo function call.
diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml
index 1e8b693..20d8569 100644
--- a/doc/public/tmpl/cairo-surface.sgml
+++ b/doc/public/tmpl/cairo-surface.sgml
@@ -6,9 +6,15 @@ Base class for surfaces
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Cairo surfaces are target of all drawing operations.  The actual drawings are
+#cairo_surface_t is the abstract type representing all different drawing
+targets that cairo can render to.  The actual drawings are
 performed using a cairo <firstterm>context</firstterm>.
 </para>
+<para>
+A cairo surface is created by using <firstterm>backend</firstterm>-specific
+constructors, typically of the form
+cairo_<emphasis>backend</emphasis>_surface_create().
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
diff --git a/doc/public/tmpl/cairo-xcb-xrender.sgml b/doc/public/tmpl/cairo-xcb-xrender.sgml
index 40aa655..993caff 100644
--- a/doc/public/tmpl/cairo-xcb-xrender.sgml
+++ b/doc/public/tmpl/cairo-xcb-xrender.sgml
@@ -8,7 +8,8 @@ X Window System rendering using the XCB library and the X Render extension
 <para>
 The XCB surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XCB library and its X Render extension.
-
+</para>
+<para>
 Note that the XCB surface automatically takes advantage of the X Render
 extension if it is available.
 </para>
diff --git a/doc/public/tmpl/cairo-xcb.sgml b/doc/public/tmpl/cairo-xcb.sgml
index 5796542..845b9a1 100644
--- a/doc/public/tmpl/cairo-xcb.sgml
+++ b/doc/public/tmpl/cairo-xcb.sgml
@@ -8,7 +8,8 @@ X Window System rendering using the XCB library
 <para>
 The XCB surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XCB library.
-
+</para>
+<para>
 Note that the XCB surface automatically takes advantage of the X render
 extension if it is available.
 </para>
diff --git a/doc/public/tmpl/cairo-xlib-xrender.sgml b/doc/public/tmpl/cairo-xlib-xrender.sgml
index 3d9ebc6..04663ed 100644
--- a/doc/public/tmpl/cairo-xlib-xrender.sgml
+++ b/doc/public/tmpl/cairo-xlib-xrender.sgml
@@ -8,7 +8,8 @@ X Window System rendering using XLib and the X Render extension
 <para>
 The XLib surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XLib and Xrender libraries.
-
+</para>
+<para>
 Note that the XLib surface automatically takes advantage of X Render extension
 if it is available.
 </para>
diff --git a/doc/public/tmpl/cairo-xlib.sgml b/doc/public/tmpl/cairo-xlib.sgml
index b8330a9..e0927d0 100644
--- a/doc/public/tmpl/cairo-xlib.sgml
+++ b/doc/public/tmpl/cairo-xlib.sgml
@@ -8,7 +8,8 @@ X Window System rendering using XLib
 <para>
 The XLib surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XLib library.
-
+</para>
+<para>
 Note that the XLib surface automatically takes advantage of X render extension
 if it is available.
 </para>
commit 587508528c4a318649ecb347b96fbc89a40175ea
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:12:16 2008 -0500

    [doc] Minor improvement

diff --git a/doc/public/tmpl/cairo-beos.sgml b/doc/public/tmpl/cairo-beos.sgml
index 7747e7b..d4fbc09 100644
--- a/doc/public/tmpl/cairo-beos.sgml
+++ b/doc/public/tmpl/cairo-beos.sgml
@@ -6,8 +6,8 @@ BeOS surface support
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The BeOS surface is used to render cairo graphics natively on
-BeOS systems.
+The BeOS surface is used to render cairo graphics to
+BeOS views and bitmaps.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
commit fd5dfedbb75593539eeda92013042ce5423a65c4
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:02:44 2008 -0500

    [doc/public/check-doc-coverage.sh] Test that doc coverage is 100%
    
    Yay!

diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am
index 15e8630..9087147 100644
--- a/doc/public/Makefile.am
+++ b/doc/public/Makefile.am
@@ -70,3 +70,5 @@ include $(top_srcdir)/gtk-doc.make
 # Version information for marking the documentation
 EXTRA_DIST += version.xml.in
 
+TESTS_ENVIRONMENT = srcdir="$(srcdir)" MAKE="$(MAKE)"
+TESTS = check-doc-coverage.sh
diff --git a/doc/public/check-doc-coverage.sh b/doc/public/check-doc-coverage.sh
new file mode 100755
index 0000000..986af6d
--- /dev/null
+++ b/doc/public/check-doc-coverage.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+
+LANG=C
+if test -z "$DOC_MODULE"; then
+	# extract from Makefile
+	eval `grep '^DOC_MODULE' Makefile | sed 's/ //g'`
+	if test -z "$DOC_MODULE"; then
+		echo Failed extracting DOC_MODULE from Makefile 1>&2
+		echo Try setting DOC_MODULE env var manually 1>&2
+		exit 1
+	fi
+fi
+
+
+test -z "$srcdir" && srcdir=.
+status=0
+
+if ! test -f "$DOC_MODULE-undocumented.txt" -a -f "$DOC_MODULE-unused.txt"; then
+	echo At least one of "$DOC_MODULE-undocumented.txt" and "$DOC_MODULE-unused.txt" not found.
+	echo Skipping test.
+	exit 0
+fi
+
+status=0
+
+if test -f "$DOC_MODULE-unused.txt"; then
+	unused=`cat "$DOC_MODULE-unused.txt"`
+	if test -n "$unused"; then
+		echo Unused documentated symbols: 1>&2
+		cat "$DOC_MODULE-unused.txt" 1>&2
+		status=1
+	fi
+fi
+if test -f "$DOC_MODULE-undocumented.txt"; then
+	if ! grep '^0 symbols incomplete' "$DOC_MODULE-undocumented.txt" >/dev/null ||
+	   ! grep '^0 not documented'     "$DOC_MODULE-undocumented.txt" >/dev/null; then
+		echo Incomplete or undocumented symbols: 1>&2
+		cat "$DOC_MODULE-undocumented.txt" 1>&2
+		status=1
+	fi
+fi
+
+exit $status
commit c133ee5acc7c97fcd43d61f5aad160ca96c47941
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 21:00:21 2008 -0500

    [doc] Improve docs for new API

diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index 394e06a..ba0ce6a 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -399,9 +399,6 @@ _cairo_image_surface_create_with_content (cairo_content_t	content,
  * @format: A #cairo_format_t value
  * @width: The desired width of an image surface to be created.
  *
- * Return value: the appropriate stride to use given the desired
- * format and width.
- *
  * 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:
@@ -417,8 +414,11 @@ _cairo_image_surface_create_with_content (cairo_content_t	content,
  *						  width, height);
  * </programlisting></informalexample>
  *
+ * Return value: the appropriate stride to use given the desired
+ * format and width.
+ *
  * Since: 1.6
- */
+ **/
 int
 cairo_format_stride_for_width (cairo_format_t	format,
 			       int		width)
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index ecba6c0..d43b5a8 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -2162,14 +2162,20 @@ cairo_xlib_surface_create_with_xrender_format (Display		    *dpy,
 slim_hidden_def (cairo_xlib_surface_create_with_xrender_format);
 
 /**
- * cairo_xlib_surface_get_xrender_format
- * @surface: an xlib surface created by
- * cairo_xlib_surface_create_with_render_format
+ * cairo_xlib_surface_get_xrender_format:
+ * @surface: an xlib surface
  *
- * Return value: the XRenderPictFormat* with which the surface was
- * originally created, (or %NULL if the surface is not an xlib surface
- * or if the X Render extension is not available).
- */
+ * Gets the X Render picture format that @surface uses for rendering with the
+ * X Render extension. If the surface was created by
+ * cairo_xlib_surface_create_with_xrender_format() originally, the return
+ * value is the format passed to that constructor.
+ *
+ * Return value: the XRenderPictFormat* associated with @surface,
+ * or %NULL if the surface is not an xlib surface
+ * or if the X Render extension is not available.)
+ *
+ * Since: 1.6
+ **/
 XRenderPictFormat *
 cairo_xlib_surface_get_xrender_format (cairo_surface_t *surface)
 {
commit 0d898f2badf41d3b0ae5ee88943c44cf49690f5d
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 20:49:44 2008 -0500

    [doc] Make sure all type names in docs are prefixed by #

diff --git a/src/cairo-array.c b/src/cairo-array.c
index 7af4cf9..6940b40 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -177,7 +177,7 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
  * pointer may be used for further direct indexing with []. For
  * example:
  *
- * 	cairo_array_t array;
+ * 	#cairo_array_t array;
  *	double *values;
  *
  *	_cairo_array_init (&array, sizeof(double));
diff --git a/src/cairo-bentley-ottmann.c b/src/cairo-bentley-ottmann.c
index c2e11bd..6a591a7 100644
--- a/src/cairo-bentley-ottmann.c
+++ b/src/cairo-bentley-ottmann.c
@@ -129,7 +129,7 @@ typedef struct _cairo_bo_event_queue {
     unsigned num_startstop_events;
 } cairo_bo_event_queue_t;
 
-/* This structure extends cairo_skip_list_t, which must come first. */
+/* This structure extends #cairo_skip_list_t, which must come first. */
 typedef struct _cairo_bo_sweep_line {
     cairo_skip_list_t active_edges;
     cairo_bo_edge_t *head;
@@ -1053,7 +1053,7 @@ print_state (const char			*msg,
 }
 #endif
 
-/* Adds the trapezoid, if any, of the left edge to the cairo_traps_t
+/* Adds the trapezoid, if any, of the left edge to the #cairo_traps_t
  * of bo_traps. */
 static cairo_status_t
 _cairo_bo_edge_end_trap (cairo_bo_edge_t	*left,
diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h
index 4b3164a..e2e2056 100644
--- a/src/cairo-cache-private.h
+++ b/src/cairo-cache-private.h
@@ -46,8 +46,8 @@
  * cairo_cache_entry_t:
  *
  * A #cairo_cache_entry_t contains both a key and a value for
- * cairo_cache_t. User-derived types for cairo_cache_entry_t must
- * have a cairo_cache_entry_t as their first field. For example:
+ * cairo_cache_t. User-derived types for #cairo_cache_entry_t must
+ * have a #cairo_cache_entry_t as their first field. For example:
  *
  * 	typedef _my_entry {
  *	    cairo_cache_entry_t base;
diff --git a/src/cairo-cache.c b/src/cairo-cache.c
index fa23da8..b0d5bb0 100644
--- a/src/cairo-cache.c
+++ b/src/cairo-cache.c
@@ -97,7 +97,7 @@ _cairo_cache_fini (cairo_cache_t *cache)
  * the equality of entries.
  *
  * Data is provided to the cache in the form of user-derived version
- * of cairo_cache_entry_t. A cache entry must be able to hold hash
+ * of #cairo_cache_entry_t. A cache entry must be able to hold hash
  * code, a size, and the key/value pair being stored in the
  * cache. Sometimes only the key will be necessary, (as in
  * _cairo_cache_lookup()), and in these cases the value portion of the
diff --git a/src/cairo-fixed-type-private.h b/src/cairo-fixed-type-private.h
index 9c99d3f..d8305ee 100644
--- a/src/cairo-fixed-type-private.h
+++ b/src/cairo-fixed-type-private.h
@@ -64,7 +64,7 @@ typedef cairo_int128_t	cairo_fixed_96_32_t;
 /* A signed type %CAIRO_FIXED_BITS in size; the main fixed point type */
 typedef int32_t cairo_fixed_t;
 
-/* An unsigned type of the same size as cairo_fixed_t */
+/* An unsigned type of the same size as #cairo_fixed_t */
 typedef uint32_t cairo_fixed_unsigned_t;
 
 #endif /* CAIRO_FIXED_TYPE_PRIVATE_H */
diff --git a/src/cairo-font-face.c b/src/cairo-font-face.c
index b944534..6a29600 100644
--- a/src/cairo-font-face.c
+++ b/src/cairo-font-face.c
@@ -256,10 +256,10 @@ _cairo_toy_font_face_keys_equal (const void *key_a,
 				 const void *key_b);
 
 /* We maintain a hash table from family/weight/slant =>
- * cairo_font_face_t for cairo_toy_font_t. The primary purpose of
- * this mapping is to provide unique cairo_font_face_t values so that
- * our cache and mapping from cairo_font_face_t => cairo_scaled_font_t
- * works. Once the corresponding cairo_font_face_t objects fall out of
+ * cairo_font_face_t for #cairo_toy_font_t. The primary purpose of
+ * this mapping is to provide unique #cairo_font_face_t values so that
+ * our cache and mapping from #cairo_font_face_t => #cairo_scaled_font_t
+ * works. Once the corresponding #cairo_font_face_t objects fall out of
  * downstream caches, we don't need them in this hash table anymore.
  *
  * Modifications to this hash table are protected by
@@ -295,11 +295,11 @@ _cairo_toy_font_face_hash_table_unlock (void)
 /**
  * _cairo_toy_font_face_init_key:
  *
- * Initialize those portions of cairo_toy_font_face_t needed to use
+ * Initialize those portions of #cairo_toy_font_face_t needed to use
  * it as a hash table key, including the hash code buried away in
  * font_face->base.hash_entry. No memory allocation is performed here
  * so that no fini call is needed. We do this to make it easier to use
- * an automatic cairo_toy_font_face_t variable as a key.
+ * an automatic #cairo_toy_font_face_t variable as a key.
  **/
 static void
 _cairo_toy_font_face_init_key (cairo_toy_font_face_t *key,
diff --git a/src/cairo-font-options.c b/src/cairo-font-options.c
index 7005790..f9a1059 100644
--- a/src/cairo-font-options.c
+++ b/src/cairo-font-options.c
@@ -241,7 +241,7 @@ slim_hidden_def (cairo_font_options_equal);
  * @options: a #cairo_font_options_t
  *
  * Compute a hash for the font options object; this value will
- * be useful when storing an object containing a cairo_font_options_t
+ * be useful when storing an object containing a #cairo_font_options_t
  * in a hash table.
  *
  * Return value: the hash value for the font options object.
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index 4af0f17..a566fac 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -140,11 +140,11 @@ struct _cairo_ft_font_face {
 static const cairo_unscaled_font_backend_t cairo_ft_unscaled_font_backend;
 
 /*
- * We maintain a hash table to map file/id => cairo_ft_unscaled_font_t.
+ * We maintain a hash table to map file/id => #cairo_ft_unscaled_font_t.
  * The hash table itself isn't limited in size. However, we limit the
  * number of FT_Face objects we keep around; when we've exceeded that
  * limit and need to create a new FT_Face, we dump the FT_Face from a
- * random cairo_ft_unscaled_font_t which has an unlocked FT_Face, (if
+ * random #cairo_ft_unscaled_font_t which has an unlocked FT_Face, (if
  * there are any).
  */
 
@@ -295,9 +295,9 @@ _cairo_ft_unscaled_font_init_key (cairo_ft_unscaled_font_t *key,
 /**
  * _cairo_ft_unscaled_font_init:
  *
- * Initialize a cairo_ft_unscaled_font_t.
+ * Initialize a #cairo_ft_unscaled_font_t.
  *
- * There are two basic flavors of cairo_ft_unscaled_font_t, one
+ * There are two basic flavors of #cairo_ft_unscaled_font_t, one
  * created from an FT_Face and the other created from a filename/id
  * pair. These two flavors are identified as from_face and !from_face.
  *
@@ -309,7 +309,7 @@ _cairo_ft_unscaled_font_init_key (cairo_ft_unscaled_font_t *key,
  *
  * Note that the code handles these two flavors in very distinct
  * ways. For example there is a hash_table mapping
- * filename/id->cairo_unscaled_font_t in the !from_face case, but no
+ * filename/id->#cairo_unscaled_font_t in the !from_face case, but no
  * parallel in the from_face case, (where the calling code would have
  * to do its own mapping to ensure similar sharing).
  **/
@@ -358,7 +358,7 @@ _cairo_unscaled_font_is_ft (cairo_unscaled_font_t *unscaled_font)
 /**
  * _cairo_ft_unscaled_font_fini:
  *
- * Free all data associated with a cairo_ft_unscaled_font_t.
+ * 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
diff --git a/src/cairo-gstate.c b/src/cairo-gstate.c
index 410b237..99f842e 100644
--- a/src/cairo-gstate.c
+++ b/src/cairo-gstate.c
@@ -219,10 +219,10 @@ _cairo_gstate_destroy (cairo_gstate_t *gstate)
  *
  * Create a new #cairo_gstate_t setting all graphics state parameters
  * to the same values as contained in @other. gstate->next will be set
- * to %NULL and may be used by the caller to chain cairo_gstate_t
+ * to %NULL and may be used by the caller to chain #cairo_gstate_t
  * objects together.
  *
- * Return value: a new cairo_gstate_t or %NULL if there is insufficient
+ * Return value: a new #cairo_gstate_t or %NULL if there is insufficient
  * memory.
  **/
 static cairo_gstate_t*
@@ -422,7 +422,7 @@ _cairo_gstate_get_original_target (cairo_gstate_t *gstate)
  * _cairo_gstate_get_clip:
  * @gstate: a #cairo_gstate_t
  *
- * Return value: a pointer to the gstate's cairo_clip_t structure.
+ * Return value: a pointer to the gstate's #cairo_clip_t structure.
  */
 cairo_clip_t *
 _cairo_gstate_get_clip (cairo_gstate_t *gstate)
@@ -1469,7 +1469,7 @@ _cairo_gstate_get_scaled_font (cairo_gstate_t       *gstate,
  * and then ignored by the "scaled-font" layer.
  *
  * In order to perform any action on a font, we must build an object
- * called a cairo_font_scale_t; this contains the central 2x2 matrix
+ * called a #cairo_font_scale_t; this contains the central 2x2 matrix
  * resulting from "font matrix * CTM" (sans the font matrix translation
  * components as stated in the previous paragraph).
  *
diff --git a/src/cairo-hash.c b/src/cairo-hash.c
index 8075ac4..8575499 100644
--- a/src/cairo-hash.c
+++ b/src/cairo-hash.c
@@ -133,7 +133,7 @@ struct _cairo_hash_table {
  *
  * Creates a new hash table which will use the keys_equal() function
  * to compare hash keys. Data is provided to the hash table in the
- * form of user-derived versions of cairo_hash_entry_t. A hash entry
+ * form of user-derived versions of #cairo_hash_entry_t. A hash entry
  * must be able to hold both a key (including a hash code) and a
  * value. Sometimes only the key will be necessary, (as in
  * _cairo_hash_table_remove), and other times both a key and a value
diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index a7908f8..394e06a 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -280,7 +280,7 @@ _pixman_format_to_masks (pixman_format_code_t	 pixman_format,
 /* XXX: This function really should be eliminated. We don't really
  * want to advertise a cairo image surface that supports any possible
  * format. A minimal step would be to replace this function with one
- * that accepts a cairo_internal_format_t rather than mask values. */
+ * that accepts a #cairo_internal_format_t rather than mask values. */
 cairo_surface_t *
 _cairo_image_surface_create_with_masks (unsigned char	       *data,
 					cairo_format_masks_t   *masks,
@@ -396,7 +396,7 @@ _cairo_image_surface_create_with_content (cairo_content_t	content,
 
 /**
  * cairo_format_stride_for_width:
- * @format: A cairo_format_t value
+ * @format: A #cairo_format_t value
  * @width: The desired width of an image surface to be created.
  *
  * Return value: the appropriate stride to use given the desired
diff --git a/src/cairo-matrix.c b/src/cairo-matrix.c
index c3578a2..ebf448e 100644
--- a/src/cairo-matrix.c
+++ b/src/cairo-matrix.c
@@ -68,7 +68,7 @@ slim_hidden_def(cairo_matrix_init_identity);
 
 /**
  * cairo_matrix_init:
- * @matrix: a cairo_matrix_t
+ * @matrix: a #cairo_matrix_t
  * @xx: xx component of the affine transformation
  * @yx: yx component of the affine transformation
  * @xy: xy component of the affine transformation
@@ -137,7 +137,7 @@ _cairo_matrix_get_affine (const cairo_matrix_t *matrix,
 
 /**
  * cairo_matrix_init_translate:
- * @matrix: a cairo_matrix_t
+ * @matrix: a #cairo_matrix_t
  * @tx: amount to translate in the X direction
  * @ty: amount to translate in the Y direction
  *
@@ -157,7 +157,7 @@ slim_hidden_def(cairo_matrix_init_translate);
 
 /**
  * cairo_matrix_translate:
- * @matrix: a cairo_matrix_t
+ * @matrix: a #cairo_matrix_t
  * @tx: amount to translate in the X direction
  * @ty: amount to translate in the Y direction
  *
@@ -179,7 +179,7 @@ slim_hidden_def (cairo_matrix_translate);
 
 /**
  * cairo_matrix_init_scale:
- * @matrix: a cairo_matrix_t
+ * @matrix: a #cairo_matrix_t
  * @sx: scale factor in the X direction
  * @sy: scale factor in the Y direction
  *
@@ -220,7 +220,7 @@ slim_hidden_def(cairo_matrix_scale);
 
 /**
  * cairo_matrix_init_rotate:
- * @matrix: a cairo_matrix_t
+ * @matrix: a #cairo_matrix_t
  * @radians: angle of rotation, in radians. The direction of rotation
  * is defined such that positive angles rotate in the direction from
  * the positive X axis toward the positive Y axis. With the default
diff --git a/src/cairo-mutex-type-private.h b/src/cairo-mutex-type-private.h
index cb00c77..1a29dcb 100644
--- a/src/cairo-mutex-type-private.h
+++ b/src/cairo-mutex-type-private.h
@@ -65,7 +65,7 @@ CAIRO_BEGIN_DECLS
  *   on a win32 system even if you do not compile the win32
  *   surface/backend.
  *
- * - typedef cairo_mutex_t to the proper mutex type on your target
+ * - typedef #cairo_mutex_t to the proper mutex type on your target
  *   system.  Note that you may or may not need to use a pointer,
  *   depending on what kinds of initialization your mutex
  *   implementation supports.  No trailing semicolon needed.
@@ -90,7 +90,7 @@ CAIRO_BEGIN_DECLS
  *          %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
  *
  * - #define %CAIRO_MUTEX_NIL_INITIALIZER to something that can
- *   initialize the cairo_mutex_t type you defined.  Most of the
+ *   initialize the #cairo_mutex_t type you defined.  Most of the
  *   time one of 0, %NULL, or {} works.  At this point
  *   you should be able to compile the following snippet:
  *
@@ -134,7 +134,7 @@ CAIRO_BEGIN_DECLS
  *   #define CAIRO_MUTEX_FINALIZE() CAIRO_MUTEX_NOOP
  *
  * - That is all.  If for any reason you think the above API is
- *   not enough to implement cairo_mutex_t on your system, please
+ *   not enough to implement #cairo_mutex_t on your system, please
  *   stop and write to the cairo mailing list about it.  DO NOT
  *   poke around cairo-mutex-private.h for possible solutions.
  */
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index bb51496..68a3f9f 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -389,7 +389,7 @@ _cairo_pattern_create_in_error (cairo_status_t status)
  * @green: green component of the color
  * @blue: blue component of the color
  *
- * Creates a new cairo_pattern_t corresponding to an opaque color.  The
+ * Creates a new #cairo_pattern_t 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.
@@ -433,7 +433,7 @@ slim_hidden_def (cairo_pattern_create_rgb);
  * @blue: blue component of the color
  * @alpha: alpha component of the color
  *
- * Creates a new cairo_pattern_t corresponding to a translucent color.
+ * Creates a new #cairo_pattern_t 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.
@@ -476,7 +476,7 @@ slim_hidden_def (cairo_pattern_create_rgba);
  * cairo_pattern_create_for_surface:
  * @surface: the surface
  *
- * Create a new cairo_pattern_t for the given surface.
+ * Create a new #cairo_pattern_t for the given surface.
  *
  * Return value: the newly created #cairo_pattern_t if successful, or
  * an error pattern in case of no memory.  The caller owns the
@@ -519,7 +519,7 @@ slim_hidden_def (cairo_pattern_create_for_surface);
  * @x1: x coordinate of the end point
  * @y1: y coordinate of the end point
  *
- * Create a new linear gradient cairo_pattern_t along the line defined
+ * Create a new linear gradient #cairo_pattern_t 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_pattern_add_color_stop_rgb() or
@@ -565,7 +565,7 @@ cairo_pattern_create_linear (double x0, double y0, double x1, double y1)
  * @cy1: y coordinate for the center of the end circle
  * @radius1: radius of the end circle
  *
- * Creates a new radial gradient cairo_pattern_t between the two
+ * 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_pattern_add_color_stop_rgb() or
diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c
index 3c74328..2b8f745 100644
--- a/src/cairo-pdf-surface.c
+++ b/src/cairo-pdf-surface.c
@@ -424,7 +424,7 @@ _extract_pdf_surface (cairo_surface_t		 *surface,
 
 /**
  * cairo_pdf_surface_set_size:
- * @surface: a PDF cairo_surface_t
+ * @surface: a PDF #cairo_surface_t
  * @width_in_points: new surface width, in points (1 point == 1/72.0 inch)
  * @height_in_points: new surface height, in points (1 point == 1/72.0 inch)
  *
diff --git a/src/cairo-png.c b/src/cairo-png.c
index ded83dc..429ebf8 100644
--- a/src/cairo-png.c
+++ b/src/cairo-png.c
@@ -84,7 +84,7 @@ convert_data_to_bytes (png_structp png, png_row_infop row_info, png_bytep data)
 }
 
 /* Use a couple of simple error callbacks that do not print anything to
- * stderr and rely on the user to check for errors via the cairo_status_t
+ * stderr and rely on the user to check for errors via the #cairo_status_t
  * return.
  */
 static void
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index 61b429b..844156e 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -1205,7 +1205,7 @@ cairo_ps_level_to_string (cairo_ps_level_t level)
 
 /**
  * cairo_ps_surface_set_eps:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  * @eps: %TRUE to output EPS format PostScript
  *
  * If @eps is %TRUE, the PostScript surface will output Encapsulated
@@ -1237,7 +1237,7 @@ cairo_ps_surface_set_eps (cairo_surface_t	*surface,
 
 /**
  * cairo_ps_surface_get_eps:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  *
  * Check whether the PostScript surface will output Encapsulated PostScript.
  *
@@ -1262,7 +1262,7 @@ cairo_ps_surface_get_eps (cairo_surface_t	*surface)
 
 /**
  * cairo_ps_surface_set_size:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  * @width_in_points: new surface width, in points (1 point == 1/72.0 inch)
  * @height_in_points: new surface height, in points (1 point == 1/72.0 inch)
  *
@@ -1302,7 +1302,7 @@ cairo_ps_surface_set_size (cairo_surface_t	*surface,
 
 /**
  * cairo_ps_surface_dsc_comment:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  * @comment: a comment string to be emitted into the PostScript output
  *
  * Emit a comment into the PostScript output for the given surface.
@@ -1430,7 +1430,7 @@ cairo_ps_surface_dsc_comment (cairo_surface_t	*surface,
 
 /**
  * cairo_ps_surface_dsc_begin_setup:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  *
  * This function indicates that subsequent calls to
  * cairo_ps_surface_dsc_comment() should direct comments to the Setup
@@ -1464,7 +1464,7 @@ cairo_ps_surface_dsc_begin_setup (cairo_surface_t *surface)
 
 /**
  * cairo_ps_surface_dsc_begin_page_setup:
- * @surface: a PostScript cairo_surface_t
+ * @surface: a PostScript #cairo_surface_t
  *
  * This function indicates that subsequent calls to
  * cairo_ps_surface_dsc_comment() should direct comments to the
diff --git a/src/cairo-quartz-surface.c b/src/cairo-quartz-surface.c
index 166b443..f3fb36b 100644
--- a/src/cairo-quartz-surface.c
+++ b/src/cairo-quartz-surface.c
@@ -393,7 +393,7 @@ CreateGradientFunction (cairo_gradient_pattern_t *gpat)
 			     &callbacks);
 }
 
-/* generic cairo surface -> cairo_quartz_surface_t function */
+/* generic cairo surface -> #cairo_quartz_surface_t function */
 static cairo_int_status_t
 _cairo_quartz_surface_to_quartz (cairo_surface_t *target,
 				 cairo_surface_t *pat_surf,
diff --git a/src/cairo-rectangle.c b/src/cairo-rectangle.c
index bda8224..5c68683 100644
--- a/src/cairo-rectangle.c
+++ b/src/cairo-rectangle.c
@@ -39,15 +39,15 @@
 #include "cairoint.h"
 
 /* XXX We currently have a confusing mix of boxes and rectangles as
- * exemplified by this function.  A cairo_box_t is a rectangular area
+ * exemplified by this function.  A #cairo_box_t is a rectangular area
  * represented by the coordinates of the upper left and lower right
- * corners, expressed in fixed point numbers.  A cairo_rectangle_int_t is
+ * corners, expressed in fixed point numbers.  A #cairo_rectangle_int_t is
  * also a rectangular area, but represented by the upper left corner
  * and the width and the height, as integer numbers.
  *
- * This function converts a cairo_box_t to a cairo_rectangle_int_t by
+ * This function converts a #cairo_box_t to a #cairo_rectangle_int_t by
  * increasing the area to the nearest integer coordinates.  We should
- * standardize on cairo_rectangle_fixed_t and cairo_rectangle_int_t, and
+ * standardize on #cairo_rectangle_fixed_t and #cairo_rectangle_int_t, and
  * this function could be renamed to the more reasonable
  * _cairo_rectangle_fixed_round.
  */
diff --git a/src/cairo-region.c b/src/cairo-region.c
index 7bf4982..d78628e 100644
--- a/src/cairo-region.c
+++ b/src/cairo-region.c
@@ -149,7 +149,7 @@ _cairo_region_boxes_fini (cairo_region_t *region, cairo_box_int_t *boxes)
  * @region: a #cairo_region_t
  * @rect: rectangle into which to store the extents
  *
- * Gets the bounding box of a region as a cairo_rectangle_int_t
+ * Gets the bounding box of a region as a #cairo_rectangle_int_t
  **/
 void
 _cairo_region_get_extents (cairo_region_t *region, cairo_rectangle_int_t *extents)
diff --git a/src/cairo-scaled-font-subsets-private.h b/src/cairo-scaled-font-subsets-private.h
index b42e277..fe6c23a 100644
--- a/src/cairo-scaled-font-subsets-private.h
+++ b/src/cairo-scaled-font-subsets-private.h
@@ -52,7 +52,7 @@ typedef struct _cairo_scaled_font_subsets_glyph {
  * _cairo_scaled_font_subsets_create_scaled:
  *
  * Create a new #cairo_scaled_font_subsets_t object which can be used
- * to create subsets of any number of cairo_scaled_font_t
+ * 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
  * subsets with glyph indices packed into the range
@@ -74,7 +74,7 @@ _cairo_scaled_font_subsets_create_scaled (void);
  *
  * Glyphs with an outline path available will be mapped to one font
  * subset for each font face. Glyphs from bitmap fonts will mapped to
- * separate font subsets for each cairo_scaled_font_t object.
+ * separate font subsets for each #cairo_scaled_font_t object.
  *
  * The maximum number of glyphs per subset is 256. Each subset
  * reserves the first glyph for the .notdef glyph.
@@ -98,7 +98,7 @@ _cairo_scaled_font_subsets_create_simple (void);
  * 65536 glyphs except for Type1 fonts which have a maximum of 256 glyphs.
  *
  * Glyphs from bitmap fonts will mapped to separate font subsets for
- * each cairo_scaled_font_t object. Each unscaled subset has a maximum
+ * each #cairo_scaled_font_t object. Each unscaled subset has a maximum
  * of 256 glyphs.
  *
  * Each subset reserves the first glyph for the .notdef glyph.
@@ -167,7 +167,7 @@ _cairo_scaled_font_subsets_destroy (cairo_scaled_font_subsets_t *font_subsets);
  * used by #cairo_scaled_font_subset_t as provided by
  * _cairo_scaled_font_subsets_foreach.
  *
- * The returned values in the cairo_scaled_font_subsets_glyph_t struct are:
+ * The returned values in the #cairo_scaled_font_subsets_glyph_t struct are:
  *
  * @font_id: The font ID of the mapped glyph
  * @subset_id : The subset ID of the mapped glyph within the @font_id
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index 681edaf..33d83c9 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -271,12 +271,12 @@ cairo_scaled_font_status (cairo_scaled_font_t *scaled_font)
 slim_hidden_def (cairo_scaled_font_status);
 
 /* Here we keep a unique mapping from
- * cairo_font_face_t/matrix/ctm/options => cairo_scaled_font_t.
+ * cairo_font_face_t/matrix/ctm/options => #cairo_scaled_font_t.
  *
  * Here are the things that we want to map:
  *
- *  a) All otherwise referenced cairo_scaled_font_t's
- *  b) Some number of not otherwise referenced cairo_scaled_font_t's
+ *  a) All otherwise referenced #cairo_scaled_font_t's
+ *  b) Some number of not otherwise referenced #cairo_scaled_font_t's
  *
  * The implementation uses a hash table which covers (a)
  * completely. Then, for (b) we have an array of otherwise
@@ -453,7 +453,7 @@ _cairo_scaled_font_keys_equal (const void *abstract_key_a, const void *abstract_
 #define MAX_GLYPHS_CACHED_PER_FONT 256
 
 /*
- * Basic cairo_scaled_font_t object management
+ * Basic #cairo_scaled_font_t object management
  */
 
 cairo_status_t
diff --git a/src/cairo-traps.c b/src/cairo-traps.c
index c3d4329..195ae88 100644
--- a/src/cairo-traps.c
+++ b/src/cairo-traps.c
@@ -92,7 +92,7 @@ _cairo_traps_fini (cairo_traps_t *traps)
  * @box: a box that will be converted to a single trapezoid
  *       to store in @traps.
  *
- * Initializes a cairo_traps_t to contain a single rectangular
+ * Initializes a #cairo_traps_t to contain a single rectangular
  * trapezoid.
  **/
 cairo_status_t
diff --git a/src/cairo-types-private.h b/src/cairo-types-private.h
index af6d42a..42713dd 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -61,7 +61,7 @@ typedef cairo_array_t cairo_user_data_array_t;
  * cairo_hash_entry_t:
  *
  * A #cairo_hash_entry_t contains both a key and a value for
- * cairo_hash_table_t. User-derived types for cairo_hash_entry_t must
+ * cairo_hash_table_t. User-derived types for #cairo_hash_entry_t must
  * be type-compatible with this structure (eg. they must have an
  * unsigned long as the first parameter. The easiest way to get this
  * is to use:
diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c
index 452775b..b222ef4 100644
--- a/src/cairo-win32-surface.c
+++ b/src/cairo-win32-surface.c
@@ -1890,7 +1890,7 @@ cairo_win32_surface_get_dc (cairo_surface_t *surface)
  * as the DIB of the Win32 surface.  If the passed-in win32 surface
  * is not a DIB surface, %NULL is returned.
  *
- * Return value: a #cairo_surface_t (owned by the win32 cairo_surface_t),
+ * Return value: a #cairo_surface_t (owned by the win32 #cairo_surface_t),
  * or %NULL if the win32 surface is not a DIB.
  *
  * Since: 1.4
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index f5bd5e5..ecba6c0 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -2857,7 +2857,7 @@ typedef void (*cairo_xrender_composite_text_func_t)
 	       _Xconst XGlyphElt8           *elts,
 	       int                          nelt);
 
-/* Build a struct of the same size of cairo_glyph_t that can be used both as
+/* Build a struct of the same size of #cairo_glyph_t that can be used both as
  * an input glyph with double coordinates, and as "working" glyph with
  * integer from-current-point offsets. */
 typedef struct {
@@ -2874,7 +2874,7 @@ typedef struct {
   } p;
 } cairo_xlib_glyph_t;
 
-/* compile-time assert that cairo_xlib_glyph_t is the same size as cairo_glyph_t */
+/* compile-time assert that #cairo_xlib_glyph_t is the same size as #cairo_glyph_t */
 typedef int cairo_xlib_glyph_t_size_assertion [sizeof (cairo_xlib_glyph_t) == sizeof (cairo_glyph_t) ? 1 : -1];
 
 #define GLYPH_INDEX_SKIP ((unsigned long) -1)
diff --git a/src/cairo.c b/src/cairo.c
index 2597efc..1db90a5 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -63,7 +63,7 @@ static const cairo_t _cairo_nil = {
 
 #include <assert.h>
 
-/* This has to be updated whenever cairo_status_t is extended.  That's
+/* This has to be updated whenever #cairo_status_t is extended.  That's
  * a bit of a pain, but it should be easy to always catch as long as
  * one adds a new test case to test a trigger of the new status value.
  */
@@ -461,7 +461,7 @@ slim_hidden_def(cairo_push_group);
 /**
  * cairo_push_group_with_content:
  * @cr: a cairo context
- * @content: a %cairo_content_t indicating the type of group that
+ * @content: a %#cairo_content_t indicating the type of group that
  *           will be created
  *
  * Temporarily redirects drawing to an intermediate surface known as a
diff --git a/src/cairo.h b/src/cairo.h
index 0d08497..873a1ce 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -184,7 +184,7 @@ typedef struct _cairo_user_data_key {
  * @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)
- * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input cairo_status_t
+ * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input #cairo_status_t
  * @CAIRO_STATUS_NULL_POINTER: %NULL pointer
  * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8
  * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid
@@ -193,8 +193,8 @@ typedef struct _cairo_user_data_key {
  * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished
  * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation
  * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation
- * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input cairo_content_t
- * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input cairo_format_t
+ * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input #cairo_content_t
+ * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input #cairo_format_t
  * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual*
  * @CAIRO_STATUS_FILE_NOT_FOUND: file not found
  * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting
@@ -251,8 +251,8 @@ typedef enum _cairo_status {
  * contain, whether color information, alpha information (translucence
  * vs. opacity), or both.
  *
- * Note: The large values here are designed to keep cairo_content_t
- * values distinct from cairo_format_t values so that the
+ * Note: The large values here are designed to keep #cairo_content_t
+ * values distinct from #cairo_format_t values so that the
  * implementation can detect the error if users confuse the two types.
  **/
 typedef enum _cairo_content {
@@ -734,7 +734,7 @@ cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);
  * cairo_scaled_font_t:
  *
  * A #cairo_scaled_font_t is a font scaled to a particular size and device
- * resolution. A cairo_scaled_font_t is most useful for low-level font
+ * resolution. A #cairo_scaled_font_t is most useful for low-level font
  * usage where a library or application wants to cache a reference
  * to a scaled font to speed up the computation of metrics.
  *
@@ -1346,8 +1346,8 @@ typedef enum _cairo_path_data_type {
  *
  * <informalexample><programlisting>
  *      int i;
- *      cairo_path_t *path;
- *      cairo_path_data_t *data;
+ *      #cairo_path_t *path;
+ *      #cairo_path_data_t *data;
  * &nbsp;
  *      path = cairo_copy_path (cr);
  * &nbsp;
diff --git a/src/cairoint.h b/src/cairoint.h
index de87ab6..db6a98c 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -244,7 +244,7 @@ _cairo_hash_string (const char *c);
 typedef struct _cairo_unscaled_font_backend cairo_unscaled_font_backend_t;
 
 /*
- * A cairo_unscaled_font_t is just an opaque handle we use in the
+ * A #cairo_unscaled_font_t is just an opaque handle we use in the
  * glyph cache.
  */
 typedef struct _cairo_unscaled_font {
@@ -1770,7 +1770,7 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
  * 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,
+ * visuals. This time we invented #cairo_internal_format_t instead,
  * (see it for more discussion).
  *
  * The punchline is that %CAIRO_FORMAT_VALID must not conside any
commit 9ecde82d35ead4975ce110bb2012264e3ca9d2e1
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 20:48:48 2008 -0500

    [doc] Make sure all macro names in docs are prefixed by %

diff --git a/src/cairo-array.c b/src/cairo-array.c
index 470b327..7af4cf9 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -231,7 +231,7 @@ _cairo_array_copy_element (cairo_array_t *array, int index, void *dst)
  *
  * _cairo_array_index (array, _cairo_array_num_elements (array) - 1);
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
  * operation.
  **/
@@ -251,7 +251,7 @@ _cairo_array_append (cairo_array_t	*array,
  * @num_elements, then copying @num_elements * element_size bytes from
  * @elements into the array.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
  * operation.
  **/
@@ -282,7 +282,7 @@ _cairo_array_append_multiple (cairo_array_t	*array,
  * @elements. This memory will be unitialized, but will be accounted
  * for in the return value of _cairo_array_num_elements().
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
  * operation.
  **/
diff --git a/src/cairo-bentley-ottmann.c b/src/cairo-bentley-ottmann.c
index 3ef7858..c2e11bd 100644
--- a/src/cairo-bentley-ottmann.c
+++ b/src/cairo-bentley-ottmann.c
@@ -507,7 +507,7 @@ det64_128 (cairo_int64_t a,
 /* Compute the intersection of two lines as defined by two edges. The
  * result is provided as a coordinate pair of 128-bit integers.
  *
- * Returns CAIRO_BO_STATUS_INTERSECTION if there is an intersection or
+ * Returns %CAIRO_BO_STATUS_INTERSECTION if there is an intersection or
  * CAIRO_BO_STATUS_PARALLEL if the two lines are exactly parallel.
  */
 static cairo_bo_status_t
@@ -638,10 +638,10 @@ _cairo_bo_edge_contains_intersect_point (cairo_bo_edge_t		*edge,
 /* Compute the intersection of two edges. The result is provided as a
  * coordinate pair of 128-bit integers.
  *
- * Returns CAIRO_BO_STATUS_INTERSECTION if there is an intersection
- * that is within both edges, CAIRO_BO_STATUS_NO_INTERSECTION if the
+ * Returns %CAIRO_BO_STATUS_INTERSECTION if there is an intersection
+ * that is within both edges, %CAIRO_BO_STATUS_NO_INTERSECTION if the
  * intersection of the lines defined by the edges occurs outside of
- * one or both edges, and CAIRO_BO_STATUS_PARALLEL if the two edges
+ * one or both edges, and %CAIRO_BO_STATUS_PARALLEL if the two edges
  * are exactly parallel.
  *
  * Note that when determining if a candidate intersection is "inside"
diff --git a/src/cairo-cache.c b/src/cairo-cache.c
index 9bb4de5..fa23da8 100644
--- a/src/cairo-cache.c
+++ b/src/cairo-cache.c
@@ -239,8 +239,8 @@ _cairo_cache_lookup (cairo_cache_t	  *cache,
  *
  * Remove a random entry from the cache.
  *
- * Return value: CAIRO_STATUS_SUCCESS if an entry was successfully
- * removed. CAIRO_INT_STATUS_CACHE_EMPTY if there are no entries that
+ * Return value: %CAIRO_STATUS_SUCCESS if an entry was successfully
+ * removed. %CAIRO_INT_STATUS_CACHE_EMPTY if there are no entries that
  * can be removed.
  **/
 static cairo_int_status_t
@@ -295,7 +295,7 @@ _cairo_cache_shrink_to_accommodate (cairo_cache_t *cache,
  * a matching key, then the old entry will be removed first, (and the
  * entry_destroy() callback will be called on it).
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if insufficient memory is available.
  **/
 cairo_status_t
diff --git a/src/cairo-deprecated.h b/src/cairo-deprecated.h
index 77523c4..35a4eb9 100644
--- a/src/cairo-deprecated.h
+++ b/src/cairo-deprecated.h
@@ -36,7 +36,7 @@
 #ifndef CAIRO_DEPRECATED_H
 #define CAIRO_DEPRECATED_H
 
-/* The CAIRO_FORMAT_RGB16_565 value was added in cairo 1.2.0 as part
+/* The %CAIRO_FORMAT_RGB16_565 value was added in cairo 1.2.0 as part
  * of fixing cairo's xlib backend to work with X servers advertising a
  * 16-bit, 565 visual. But as it turned out, adding this format to
  * #cairo_format_t was not necessary, and was a mistake, (cairo's xlib
diff --git a/src/cairo-directfb.h b/src/cairo-directfb.h
index 59653d3..21005e1 100644
--- a/src/cairo-directfb.h
+++ b/src/cairo-directfb.h
@@ -37,10 +37,10 @@
 /*
  * Environment variables affecting the backend:
  *
- *  CAIRO_DIRECTFB_NO_ACCEL (boolean)
+ *  %CAIRO_DIRECTFB_NO_ACCEL (boolean)
  *      if found, disables acceleration at all
  *
- *  CAIRO_DIRECTFB_ARGB_FONT (boolean)
+ *  %CAIRO_DIRECTFB_ARGB_FONT (boolean)
  *      if found, enables using ARGB fonts instead of A8
  */
 
diff --git a/src/cairo-fixed-type-private.h b/src/cairo-fixed-type-private.h
index 78ca672..9c99d3f 100644
--- a/src/cairo-fixed-type-private.h
+++ b/src/cairo-fixed-type-private.h
@@ -61,7 +61,7 @@ typedef cairo_int128_t	cairo_fixed_96_32_t;
  */
 #define CAIRO_FIXED_FRAC_BITS	16
 
-/* A signed type CAIRO_FIXED_BITS in size; the main fixed point type */
+/* A signed type %CAIRO_FIXED_BITS in size; the main fixed point type */
 typedef int32_t cairo_fixed_t;
 
 /* An unsigned type of the same size as cairo_fixed_t */
diff --git a/src/cairo-freelist-private.h b/src/cairo-freelist-private.h
index 0d02127..218c4c0 100644
--- a/src/cairo-freelist-private.h
+++ b/src/cairo-freelist-private.h
@@ -50,14 +50,14 @@ _cairo_freelist_fini (cairo_freelist_t *freelist);
 /* Allocate a new node from the freelist.  If the freelist contains no
  * nodes, a new one will be allocated using malloc().  The caller is
  * responsible for calling _cairo_freelist_free() or free() on the
- * returned node.  Returns NULL on memory allocation error. */
+ * returned node.  Returns %NULL on memory allocation error. */
 cairo_private void *
 _cairo_freelist_alloc (cairo_freelist_t *freelist);
 
 /* Allocate a new node from the freelist.  If the freelist contains no
  * nodes, a new one will be allocated using calloc().  The caller is
  * responsible for calling _cairo_freelist_free() or free() on the
- * returned node.  Returns NULL on memory allocation error. */
+ * returned node.  Returns %NULL on memory allocation error. */
 cairo_private void *
 _cairo_freelist_calloc (cairo_freelist_t *freelist);
 
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index 708578d..4af0f17 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -301,11 +301,11 @@ _cairo_ft_unscaled_font_init_key (cairo_ft_unscaled_font_t *key,
  * created from an FT_Face and the other created from a filename/id
  * pair. These two flavors are identified as from_face and !from_face.
  *
- * To initialize a from_face font, pass filename==NULL, id=0 and the
+ * To initialize a from_face font, pass filename==%NULL, id=0 and the
  * desired face.
  *
  * To initialize a !from_face font, pass the filename/id as desired
- * and face==NULL.
+ * and face==%NULL.
  *
  * Note that the code handles these two flavors in very distinct
  * ways. For example there is a hash_table mapping
@@ -360,7 +360,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
+ * CAUTION: The unscaled->face field must be %NULL before calling this
  * function. This is because the cairo_ft_unscaled_font_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
diff --git a/src/cairo-gstate.c b/src/cairo-gstate.c
index 4cbab95..410b237 100644
--- a/src/cairo-gstate.c
+++ b/src/cairo-gstate.c
@@ -126,7 +126,7 @@ _cairo_gstate_init (cairo_gstate_t  *gstate,
  * _cairo_gstate_init_copy:
  *
  * Initialize @gstate by performing a deep copy of state fields from
- * @other. Note that gstate->next is not copied but is set to NULL by
+ * @other. Note that gstate->next is not copied but is set to %NULL by
  * this function.
  **/
 static cairo_status_t
@@ -215,14 +215,14 @@ _cairo_gstate_destroy (cairo_gstate_t *gstate)
 
 /**
  * _cairo_gstate_clone:
- * @other: a #cairo_gstate_t to be copied, not NULL.
+ * @other: a #cairo_gstate_t to be copied, not %NULL.
  *
  * Create a new #cairo_gstate_t setting all graphics state parameters
  * to the same values as contained in @other. gstate->next will be set
- * to NULL and may be used by the caller to chain cairo_gstate_t
+ * to %NULL and may be used by the caller to chain cairo_gstate_t
  * objects together.
  *
- * Return value: a new cairo_gstate_t or NULL if there is insufficient
+ * Return value: a new cairo_gstate_t or %NULL if there is insufficient
  * memory.
  **/
 static cairo_gstate_t*
@@ -364,8 +364,8 @@ _cairo_gstate_redirect_target (cairo_gstate_t *gstate, cairo_surface_t *child)
  * _cairo_gstate_is_redirected
  * @gstate: a #cairo_gstate_t
  *
- * Return value: TRUE if the gstate is redirected to a target
- * different than the original, FALSE otherwise.
+ * Return value: %TRUE if the gstate is redirected to a target
+ * different than the original, %FALSE otherwise.
  **/
 cairo_bool_t
 _cairo_gstate_is_redirected (cairo_gstate_t *gstate)
@@ -393,7 +393,7 @@ _cairo_gstate_get_target (cairo_gstate_t *gstate)
  * @gstate: a #cairo_gstate_t
  *
  * Return the parent surface of the current drawing target surface;
- * if this particular gstate isn't a redirect gstate, this will return NULL.
+ * if this particular gstate isn't a redirect gstate, this will return %NULL.
  **/
 cairo_surface_t *
 _cairo_gstate_get_parent_target (cairo_gstate_t *gstate)
diff --git a/src/cairo-hash.c b/src/cairo-hash.c
index c419e9e..8075ac4 100644
--- a/src/cairo-hash.c
+++ b/src/cairo-hash.c
@@ -42,14 +42,14 @@
  * An entry can be in one of three states:
  *
  * FREE: Entry has never been used, terminates all searches.
- *       Appears in the table as a NULL pointer.
+ *       Appears in the table as a %NULL pointer.
  *
  * DEAD: Entry had been live in the past. A dead entry can be reused
  *       but does not terminate a search for an exact entry.
  *       Appears in the table as a pointer to DEAD_ENTRY.
  *
  * LIVE: Entry is currently being used.
- *       Appears in the table as any non-NULL, non-DEAD_ENTRY pointer.
+ *       Appears in the table as any non-%NULL, non-DEAD_ENTRY pointer.
  */
 
 static cairo_hash_entry_t dead_entry = { 0 };
@@ -129,7 +129,7 @@ struct _cairo_hash_table {
 
 /**
  * _cairo_hash_table_create:
- * @keys_equal: a function to return TRUE if two keys are equal
+ * @keys_equal: a function to return %TRUE if two keys are equal
  *
  * Creates a new hash table which will use the keys_equal() function
  * to compare hash keys. Data is provided to the hash table in the
@@ -141,7 +141,7 @@ struct _cairo_hash_table {
  *
  * See #cairo_hash_entry_t for more details.
  *
- * Return value: the new hash table or NULL if out of memory.
+ * Return value: the new hash table or %NULL if out of memory.
  **/
 cairo_hash_table_t *
 _cairo_hash_table_create (cairo_hash_keys_equal_func_t keys_equal)
@@ -212,9 +212,9 @@ _cairo_hash_table_destroy (cairo_hash_table_t *hash_table)
  * @hash_table: a #cairo_hash_table_t to search
  * @key: the key to search on
  * @hash_code: the hash_code for @key
- * @key_unique: If TRUE, then caller asserts that no key already
+ * @key_unique: If %TRUE, then caller asserts that no key already
  * exists that will compare equal to #key, so search can be
- * optimized. If unsure, set to FALSE and the code will always work.
+ * optimized. If unsure, set to %FALSE and the code will always work.
  *
  * Search the hashtable for a live entry for which
  * hash_table->keys_equal returns true. If no such entry exists then
@@ -295,7 +295,7 @@ _cairo_hash_table_lookup_internal (cairo_hash_table_t *hash_table,
  * bigger or smaller than the ideal number of entries for the current
  * size.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if out of memory.
  **/
 static cairo_status_t
@@ -361,9 +361,9 @@ _cairo_hash_table_resize  (cairo_hash_table_t *hash_table)
  * key that matches @key, (as determined by the keys_equal() function
  * passed to _cairo_hash_table_create).
  *
- * Return value: TRUE if there is an entry in the hash table that
- * matches the given key, (which will now be in *entry_return). FALSE
- * otherwise, (in which case *entry_return will be NULL).
+ * Return value: %TRUE if there is an entry in the hash table that
+ * matches the given key, (which will now be in *entry_return). %FALSE
+ * otherwise, (in which case *entry_return will be %NULL).
  **/
 cairo_bool_t
 _cairo_hash_table_lookup (cairo_hash_table_t *hash_table,
@@ -386,22 +386,22 @@ _cairo_hash_table_lookup (cairo_hash_table_t *hash_table,
 /**
  * _cairo_hash_table_random_entry:
  * @hash_table: a hash table
- * @predicate: a predicate function, or NULL for any entry.
+ * @predicate: a predicate function, or %NULL for any entry.
  *
  * Find a random entry in the hash table satisfying the given
- * @predicate. A NULL @predicate is taken as equivalent to a function
- * which always returns TRUE, (eg. any entry in the table will do).
+ * @predicate. A %NULL @predicate is taken as equivalent to a function
+ * which always returns %TRUE, (eg. any entry in the table will do).
  *
  * We use the same algorithm as the lookup algorithm to walk over the
  * entries in the hash table in a pseudo-random order. Walking
  * linearly would favor entries following gaps in the hash table. We
  * could also call rand() repeatedly, which works well for almost-full
  * tables, but degrades when the table is almost empty, or predicate
- * returns TRUE for most entries.
+ * returns %TRUE for most entries.
  *
- * Return value: a random live entry or NULL if there are no entries
+ * Return value: a random live entry or %NULL if there are no entries
  * that match the given predicate. In particular, if predicate is
- * NULL, a NULL return value indicates that the table is empty.
+ * NULL, a %NULL return value indicates that the table is empty.
  **/
 void *
 _cairo_hash_table_random_entry (cairo_hash_table_t	   *hash_table,
@@ -458,7 +458,7 @@ _cairo_hash_table_random_entry (cairo_hash_table_t	   *hash_table,
  * the entry obtained with _cairo_hash_table_lookup. Or if absolutely
  * necessary, use _cairo_hash_table_remove first.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if insufficient memory is available.
  **/
 cairo_status_t
@@ -503,7 +503,7 @@ _cairo_hash_table_insert (cairo_hash_table_t *hash_table,
  * @key, if any (as determined by the keys_equal() function passed to
  * _cairo_hash_table_create).
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful or
+ * Return value: %CAIRO_STATUS_SUCCESS if successful or
  * CAIRO_STATUS_NO_MEMORY if out of memory.
  **/
 void
diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index 32c755e..a7908f8 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -516,7 +516,7 @@ _cairo_image_surface_create_for_data_with_content (unsigned char	*data,
  * 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
+ * Return value: a pointer to the image data of this surface or %NULL
  * if @surface is not an image surface.
  *
  * Since: 1.2
@@ -1248,7 +1248,7 @@ _cairo_image_surface_reset (void *abstract_surface)
  *
  * Checks if a surface is an #cairo_image_surface_t
  *
- * Return value: TRUE if the surface is an image surface
+ * Return value: %TRUE if the surface is an image surface
  **/
 cairo_bool_t
 _cairo_surface_is_image (const cairo_surface_t *surface)
diff --git a/src/cairo-lzw.c b/src/cairo-lzw.c
index 6158eaf..fcf90be 100644
--- a/src/cairo-lzw.c
+++ b/src/cairo-lzw.c
@@ -58,7 +58,7 @@ typedef struct _lzw_buf {
  * Instead of returning failure from any functions, lzw_buf_t provides
  * a status value that the caller can query, (and should query at
  * least once when done with the object). The status value will be
- * either CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY;
+ * either %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY;
  */
 static void
 _lzw_buf_init (lzw_buf_t *buf, int size)
@@ -82,7 +82,7 @@ _lzw_buf_init (lzw_buf_t *buf, int size)
 
 /* Increase the buffer size by doubling.
  *
- * Returns CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY
+ * Returns %CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY
  */
 static cairo_status_t
 _lzw_buf_grow (lzw_buf_t *buf)
@@ -119,7 +119,7 @@ _lzw_buf_grow (lzw_buf_t *buf)
  * See also _lzw_buf_store_pending which must be called after the last
  * call to _lzw_buf_store_bits.
  *
- * Sets buf->status to either CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY.
+ * Sets buf->status to either %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY.
  */
 static void
 _lzw_buf_store_bits (lzw_buf_t *buf, uint16_t value, int num_bits)
@@ -150,7 +150,7 @@ _lzw_buf_store_bits (lzw_buf_t *buf, uint16_t value, int num_bits)
  * NOTE: This function must be called after the last call to
  * _lzw_buf_store_bits.
  *
- * Sets buf->status to either CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY.
+ * Sets buf->status to either %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY.
  */
 static void
 _lzw_buf_store_pending  (lzw_buf_t *buf)
@@ -234,11 +234,11 @@ _lzw_symbol_table_init (lzw_symbol_table_t *table)
 /* Lookup a symbol in the symbol table. The PREV and NEXT fields of
  * symbol form the key for the lookup.
  *
- * If successful, then this function returns TRUE and slot_ret will be
+ * If successful, then this function returns %TRUE and slot_ret will be
  * left pointing at the result that will have the CODE field of
  * interest.
  *
- * If the lookup fails, then this function returns FALSE and slot_ret
+ * If the lookup fails, then this function returns %FALSE and slot_ret
  * will be pointing at the location in the table to which a new CODE
  * value should be stored along with PREV and NEXT.
  */
@@ -312,7 +312,7 @@ _lzw_symbol_table_lookup (lzw_symbol_table_t	 *table,
  * to 12 bits).
  *
  * This function returns a pointer to a newly allocated buffer holding
- * the compressed data, or NULL if an out-of-memory situation
+ * the compressed data, or %NULL if an out-of-memory situation
  * occurs.
  *
  * Notice that any one of the _lzw_buf functions called here could
diff --git a/src/cairo-meta-surface.c b/src/cairo-meta-surface.c
index 51ed382..0fa2544 100644
--- a/src/cairo-meta-surface.c
+++ b/src/cairo-meta-surface.c
@@ -485,7 +485,7 @@ _cairo_meta_surface_show_glyphs (void			*abstract_surface,
  *
  * The caller owns the return value and should call
  * cairo_surface_destroy when finished with it. This function will not
- * return NULL, but will return a nil surface instead.
+ * return %NULL, but will return a nil surface instead.
  *
  * Return value: The snapshot surface.
  **/
@@ -583,7 +583,7 @@ _cairo_meta_surface_get_extents (void			 *abstract_surface,
  *
  * Checks if a surface is a #cairo_meta_surface_t
  *
- * Return value: TRUE if the surface is a meta surface
+ * Return value: %TRUE if the surface is a meta surface
  **/
 cairo_bool_t
 _cairo_surface_is_meta (const cairo_surface_t *surface)
@@ -868,7 +868,7 @@ _cairo_meta_surface_replay (cairo_surface_t *surface,
 }
 
 /* Replay meta to surface. When the return status of each operation is
- * one of CAIRO_STATUS_SUCCESS, CAIRO_INT_STATUS_UNSUPPORTED, or
+ * one of %CAIRO_STATUS_SUCCESS, %CAIRO_INT_STATUS_UNSUPPORTED, or
  * CAIRO_INT_STATUS_FLATTEN_TRANSPARENCY the status of each operation
  * will be stored in the meta surface. Any other status will abort the
  * replay and return the status.
diff --git a/src/cairo-mutex-private.h b/src/cairo-mutex-private.h
index ac803c8..64afd64 100644
--- a/src/cairo-mutex-private.h
+++ b/src/cairo-mutex-private.h
@@ -76,7 +76,7 @@ CAIRO_BEGIN_DECLS
 
 #ifdef CAIRO_MUTEX_INIT
 
-/* If CAIRO_MUTEX_INIT is defined, we may need to initialize all
+/* If %CAIRO_MUTEX_INIT is defined, we may need to initialize all
  * static mutex'es. */
 # ifndef CAIRO_MUTEX_INITIALIZE
 #  define CAIRO_MUTEX_INITIALIZE() do {	\
@@ -108,7 +108,7 @@ CAIRO_BEGIN_DECLS
 
 #ifdef CAIRO_MUTEX_FINI
 
-/* If CAIRO_MUTEX_FINI is defined, we may need to finalize all
+/* If %CAIRO_MUTEX_FINI is defined, we may need to finalize all
  * static mutex'es. */
 # ifndef CAIRO_MUTEX_FINALIZE
 #  define CAIRO_MUTEX_FINALIZE() do {	\
diff --git a/src/cairo-mutex-type-private.h b/src/cairo-mutex-type-private.h
index b9f0fb3..cb00c77 100644
--- a/src/cairo-mutex-type-private.h
+++ b/src/cairo-mutex-type-private.h
@@ -85,21 +85,21 @@ CAIRO_BEGIN_DECLS
  *	cairo_mutex_t _cairo_some_mutex;
  *
  *      if (1)
- *          CAIRO_MUTEX_LOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_LOCK (_cairo_some_mutex);
  *      else
- *          CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
  *
- * - #define CAIRO_MUTEX_NIL_INITIALIZER to something that can
+ * - #define %CAIRO_MUTEX_NIL_INITIALIZER to something that can
  *   initialize the cairo_mutex_t type you defined.  Most of the
- *   time one of 0, NULL, or {} works.  At this point
+ *   time one of 0, %NULL, or {} works.  At this point
  *   you should be able to compile the following snippet:
  *
  *	cairo_mutex_t _cairo_some_mutex = CAIRO_MUTEX_NIL_INITIALIZER;
  *
  *      if (1)
- *          CAIRO_MUTEX_LOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_LOCK (_cairo_some_mutex);
  *      else
- *          CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
  *
  * - If the above code is not enough to initialize a mutex on
  *   your platform, #define CAIRO_MUTEX_INIT(mutex) to statement
@@ -108,17 +108,17 @@ CAIRO_BEGIN_DECLS
  *
  *	cairo_mutex_t _cairo_some_mutex = CAIRO_MUTEX_NIL_INITIALIZER;
  *
- *      CAIRO_MUTEX_INIT (_cairo_some_mutex);
+ *      %CAIRO_MUTEX_INIT (_cairo_some_mutex);
  *
  *      if (1)
- *          CAIRO_MUTEX_LOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_LOCK (_cairo_some_mutex);
  *      else
- *          CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
+ *          %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex);
  *
  * - If you define CAIRO_MUTEX_INIT(mutex), cairo will use it to
  *   initialize all static mutex'es.  If for any reason that should
- *   not happen (eg. CAIRO_MUTEX_INIT is just a faster way than
- *   what cairo does using CAIRO_MUTEX_NIL_INITIALIZER), then
+ *   not happen (eg. %CAIRO_MUTEX_INIT is just a faster way than
+ *   what cairo does using %CAIRO_MUTEX_NIL_INITIALIZER), then
  *   #define CAIRO_MUTEX_INITIALIZE() CAIRO_MUTEX_NOOP
  *
  * - If your system supports freeing a mutex object (deallocating
@@ -130,7 +130,7 @@ CAIRO_BEGIN_DECLS
  *   However, it's up to you to call CAIRO_MUTEX_FINALIZE() at
  *   proper places, eg. when the system is unloading the cairo library.
  *   So, if for any reason finalizing static mutex'es is not needed
- *   (eg. you never call CAIRO_MUTEX_FINALIZE), then
+ *   (eg. you never call %CAIRO_MUTEX_FINALIZE), then
  *   #define CAIRO_MUTEX_FINALIZE() CAIRO_MUTEX_NOOP
  *
  * - That is all.  If for any reason you think the above API is
diff --git a/src/cairo-os2.h b/src/cairo-os2.h
index 6a6c04d..bd4d034 100644
--- a/src/cairo-os2.h
+++ b/src/cairo-os2.h
@@ -125,7 +125,7 @@ cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
 /* the buffers. It is necessary, because it can be that Cairo is    */
 /* just drawing something into the surface while we want to         */
 /* destroy and recreate it.                                         */
-/* Returns CAIRO_STATUS_SUCCESS if the surface could be resized,    */
+/* Returns %CAIRO_STATUS_SUCCESS if the surface could be resized,    */
 /* or returns other error code if                                   */
 /*  - the surface is not a real OS/2 Surface                        */
 /*  - there is not enough memory to resize the surface              */
@@ -149,9 +149,9 @@ cairo_os2_surface_set_size (cairo_surface_t *surface,
 /* The returned values of WinBeginPaint () is just perfect here,    */
 /* but you can also get the HPS by using the WinGetPS () function,  */
 /* and you can assemble your own update rect by hand.               */
-/* If the hps_begin_paint parameter is NULL, the function will use  */
+/* If the hps_begin_paint parameter is %NULL, the function will use  */
 /* the HPS you passed in to cairo_os2_surface_create (). If the     */
-/* prcl_begin_paint_rect parameter is NULL, the function will query */
+/* prcl_begin_paint_rect parameter is %NULL, the function will query */
 /* the current window size and repaint the whole window.            */
 /*                                                                  */
 /* Cairo/2 assumes that if you told the HWND to the surface using   */
diff --git a/src/cairo-output-stream-private.h b/src/cairo-output-stream-private.h
index 8377eca..ac87447 100644
--- a/src/cairo-output-stream-private.h
+++ b/src/cairo-output-stream-private.h
@@ -74,7 +74,7 @@ typedef cairo_status_t (*cairo_write_func_t) (void		  *closure,
 typedef cairo_status_t (*cairo_close_func_t) (void *closure);
 
 
-/* This function never returns NULL. If an error occurs (NO_MEMORY)
+/* This function never returns %NULL. If an error occurs (NO_MEMORY)
  * while trying to create the output stream this function returns a
  * valid pointer to a nil output stream.
  *
@@ -128,7 +128,7 @@ _cairo_output_stream_get_position (cairo_output_stream_t *stream);
 cairo_private cairo_status_t
 _cairo_output_stream_get_status (cairo_output_stream_t *stream);
 
-/* This function never returns NULL. If an error occurs (NO_MEMORY or
+/* This function never returns %NULL. If an error occurs (NO_MEMORY or
  * WRITE_ERROR) while trying to create the output stream this function
  * returns a valid pointer to a nil output stream.
  *
@@ -139,7 +139,7 @@ _cairo_output_stream_get_status (cairo_output_stream_t *stream);
 cairo_private cairo_output_stream_t *
 _cairo_output_stream_create_for_filename (const char *filename);
 
-/* This function never returns NULL. If an error occurs (NO_MEMORY or
+/* This function never returns %NULL. If an error occurs (NO_MEMORY or
  * WRITE_ERROR) while trying to create the output stream this function
  * returns a valid pointer to a nil output stream.
  *
diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h
index 7b41191..48e646d 100644
--- a/src/cairo-paginated-private.h
+++ b/src/cairo-paginated-private.h
@@ -92,7 +92,7 @@ struct _cairo_paginated_surface_backend {
  * sequence of operations (using the backend functions passed to
  * cairo_paginated_surface_create):
  *
- * 1. Calls start_page (if non NULL). At this point, it is appropriate
+ * 1. Calls start_page (if non %NULL). At this point, it is appropriate
  *    for the target to emit any page-specific header information into
  *    its output.
  *
@@ -121,7 +121,7 @@ struct _cairo_paginated_surface_backend {
  * the target should not actually perform any rendering, (for example,
  * if performing output to a file, no output should be generated
  * during this stage). Instead the drawing functions simply need to
- * return CAIRO_STATUS_SUCCESS or CAIRO_INT_STATUS_UNSUPPORTED to
+ * return %CAIRO_STATUS_SUCCESS or %CAIRO_INT_STATUS_UNSUPPORTED to
  * indicate whether rendering would be supported. And it should do
  * this as quickly as possible. The FALLBACK phase allows the surface
  * to distinguish fallback images from native rendering in case they
diff --git a/src/cairo-path-fill.c b/src/cairo-path-fill.c
index f8e4ab0..8e4daca 100644
--- a/src/cairo-path-fill.c
+++ b/src/cairo-path-fill.c
@@ -208,7 +208,7 @@ BAIL:
  * the general tessellator when drawing very common rectangles.
  *
  * If the path described anything but a device-axis aligned rectangle,
- * this function will return CAIRO_INT_STATUS_UNSUPPORTED.
+ * this function will return %CAIRO_INT_STATUS_UNSUPPORTED.
  */
 static cairo_int_status_t
 _cairo_path_fixed_fill_rectangle (cairo_path_fixed_t	*path,
diff --git a/src/cairo-path.c b/src/cairo-path.c
index 96ecbb3..f480b62 100644
--- a/src/cairo-path.c
+++ b/src/cairo-path.c
@@ -391,8 +391,8 @@ cairo_path_destroy (cairo_path_t *path)
  *
  * Return value: the new copy of the path. If there is insufficient
  * memory a pointer to a special static cairo_path_nil will be
- * returned instead with status==CAIRO_STATUS_NO_MEMORY and
- * data==NULL.
+ * returned instead with status==%CAIRO_STATUS_NO_MEMORY and
+ * data==%NULL.
  **/
 cairo_path_t *
 _cairo_path_create (cairo_path_fixed_t *path,
@@ -413,8 +413,8 @@ _cairo_path_create (cairo_path_fixed_t *path,
  *
  * Return value: the flattened copy of the path. If there is insufficient
  * memory a pointer to a special static cairo_path_nil will be
- * returned instead with status==CAIRO_STATUS_NO_MEMORY and
- * data==NULL.
+ * returned instead with status==%CAIRO_STATUS_NO_MEMORY and
+ * data==%NULL.
  **/
 cairo_path_t *
 _cairo_path_create_flat (cairo_path_fixed_t *path,
@@ -430,8 +430,8 @@ _cairo_path_create_flat (cairo_path_fixed_t *path,
  *
  * Append @path to the current path within @cr.
  *
- * Return value: CAIRO_STATUS_INVALID_PATH_DATA if the data in @path
- * is invalid, and CAIRO_STATUS_SUCCESS otherwise.
+ * Return value: %CAIRO_STATUS_INVALID_PATH_DATA if the data in @path
+ * is invalid, and %CAIRO_STATUS_SUCCESS otherwise.
  **/
 cairo_status_t
 _cairo_path_append_to_context (const cairo_path_t	*path,
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index 62f75aa..bb51496 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -1059,7 +1059,7 @@ cairo_pattern_get_matrix (cairo_pattern_t *pattern, cairo_matrix_t *matrix)
  *
  * <informatlexample><programlisting>
  * cairo_set_source_surface (cr, image, x, y);
- * cairo_pattern_set_filter (cairo_get_source (cr), CAIRO_FILTER_NEAREST);
+ * cairo_pattern_set_filter (cairo_get_source (cr), %CAIRO_FILTER_NEAREST);
  * </programlisting></informatlexample>
  **/
 void
diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c
index 77fd95b..3c74328 100644
--- a/src/cairo-pdf-surface.c
+++ b/src/cairo-pdf-surface.c
@@ -401,7 +401,7 @@ _cairo_surface_is_pdf (cairo_surface_t *surface)
 
 /* If the abstract_surface is a paginated surface, and that paginated
  * surface's target is a pdf_surface, then set pdf_surface to that
- * target. Otherwise return CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
+ * target. Otherwise return %CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
  */
 static cairo_status_t
 _extract_pdf_surface (cairo_surface_t		 *surface,
diff --git a/src/cairo-png.c b/src/cairo-png.c
index a78da3f..ded83dc 100644
--- a/src/cairo-png.c
+++ b/src/cairo-png.c
@@ -260,11 +260,11 @@ stdio_write_func (png_structp png, png_bytep data, png_size_t size)
  * Writes the contents of @surface to a new file @filename as a PNG
  * image.
  *
- * Return value: CAIRO_STATUS_SUCCESS if the PNG file was written
- * successfully. Otherwise, CAIRO_STATUS_NO_MEMORY if memory could not
+ * Return value: %CAIRO_STATUS_SUCCESS if the PNG file was written
+ * successfully. Otherwise, %CAIRO_STATUS_NO_MEMORY if memory could not
  * be allocated for the operation or
  * CAIRO_STATUS_SURFACE_TYPE_MISMATCH if the surface does not have
- * pixel contents, or CAIRO_STATUS_WRITE_ERROR if an I/O error occurs
+ * pixel contents, or %CAIRO_STATUS_WRITE_ERROR if an I/O error occurs
  * while attempting to write the file.
  **/
 cairo_status_t
@@ -320,8 +320,8 @@ stream_write_func (png_structp png, png_bytep data, png_size_t size)
  *
  * Writes the image surface to the write function.
  *
- * Return value: CAIRO_STATUS_SUCCESS if the PNG file was written
- * successfully.  Otherwise, CAIRO_STATUS_NO_MEMORY is returned if
+ * Return value: %CAIRO_STATUS_SUCCESS if the PNG file was written
+ * successfully.  Otherwise, %CAIRO_STATUS_NO_MEMORY is returned if
  * memory could not be allocated for the operation,
  * CAIRO_STATUS_SURFACE_TYPE_MISMATCH if the surface does not have
  * pixel contents.
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index d54b22b..61b429b 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -289,7 +289,7 @@ _cairo_ps_surface_path_close_path (void *closure)
  * while cairo draws something only for round caps).
  *
  * When using this function to emit a path to be filled, rather than
- * stroked, simply pass CAIRO_LINE_CAP_ROUND which will guarantee that
+ * stroked, simply pass %CAIRO_LINE_CAP_ROUND which will guarantee that
  * the stroke workaround will not modify the path being emitted.
  */
 static cairo_status_t
@@ -1107,7 +1107,7 @@ _cairo_surface_is_ps (cairo_surface_t *surface)
 
 /* If the abstract_surface is a paginated surface, and that paginated
  * surface's target is a ps_surface, then set ps_surface to that
- * target. Otherwise return CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
+ * target. Otherwise return %CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
  */
 static cairo_status_t
 _extract_ps_surface (cairo_surface_t	 *surface,
@@ -1187,7 +1187,7 @@ cairo_ps_get_levels (cairo_ps_level_t const	**levels,
  * @level: a level id
  *
  * Get the string representation of the given @level id. This function
- * will return NULL if @level id isn't valid. See cairo_ps_get_levels()
+ * will return %NULL if @level id isn't valid. See cairo_ps_get_levels()
  * for a way to get the list of valid level ids.
  *
  * Return value: the string associated to given level.
@@ -1206,9 +1206,9 @@ cairo_ps_level_to_string (cairo_ps_level_t level)
 /**
  * cairo_ps_surface_set_eps:
  * @surface: a PostScript cairo_surface_t
- * @eps: TRUE to output EPS format PostScript
+ * @eps: %TRUE to output EPS format PostScript
  *
- * If @eps is TRUE, the PostScript surface will output Encapsulated
+ * If @eps is %TRUE, the PostScript surface will output Encapsulated
  * PostScript.
  *
  * This function should only be called before any drawing operations
@@ -1241,7 +1241,7 @@ cairo_ps_surface_set_eps (cairo_surface_t	*surface,
  *
  * Check whether the PostScript surface will output Encapsulated PostScript.
  *
- * Return value: TRUE if the surface will output Encapsulated PostScript.
+ * Return value: %TRUE if the surface will output Encapsulated PostScript.
  *
  * Since: 1.6
  **/
diff --git a/src/cairo-scaled-font-subsets-private.h b/src/cairo-scaled-font-subsets-private.h
index f80257b..b42e277 100644
--- a/src/cairo-scaled-font-subsets-private.h
+++ b/src/cairo-scaled-font-subsets-private.h
@@ -178,7 +178,7 @@ _cairo_scaled_font_subsets_destroy (cairo_scaled_font_subsets_t *font_subsets);
  * @x_advance: When @is_scaled is true, @x_advance contains the x_advance for the mapped glyph in device space.
  * When @is_scaled is false, @x_advance contains the x_advance for the the mapped glyph from an unhinted 1 point font.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful, or a non-zero
+ * Return value: %CAIRO_STATUS_SUCCESS if successful, or a non-zero
  * value indicating an error. Possible errors include
  * CAIRO_STATUS_NO_MEMORY.
  **/
@@ -218,7 +218,7 @@ typedef cairo_status_t
  * values of the array correspond to the scaled_font_glyph_index
  * values passed as input to the same function.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful, or a non-zero
+ * Return value: %CAIRO_STATUS_SUCCESS if successful, or a non-zero
  * value indicating an error. Possible errors include
  * CAIRO_STATUS_NO_MEMORY.
  **/
@@ -253,7 +253,7 @@ _cairo_scaled_font_subsets_foreach_scaled (cairo_scaled_font_subsets_t		    *fon
  * values of the array correspond to the scaled_font_glyph_index
  * values passed as input to the same function.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful, or a non-zero
+ * Return value: %CAIRO_STATUS_SUCCESS if successful, or a non-zero
  * value indicating an error. Possible errors include
  * CAIRO_STATUS_NO_MEMORY.
  **/
@@ -269,10 +269,10 @@ _cairo_scaled_font_subsets_foreach_unscaled (cairo_scaled_font_subsets_t
  * Create an array of strings containing the glyph name for each glyph
  * in @font_subsets. The array as store in font_subsets->glyph_names.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font backend does not support
  * mapping the glyph indices to unicode characters. Possible errors
- * include CAIRO_STATUS_NO_MEMORY.
+ * include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_int_status_t
 _cairo_scaled_font_subset_create_glyph_names (cairo_scaled_font_subset_t *subset);
@@ -297,10 +297,10 @@ typedef struct _cairo_cff_subset {
  * @cff_subset with information about the subset and the cff
  * data.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a
  * cff file, or an non-zero value indicating an error.  Possible
- * errors include CAIRO_STATUS_NO_MEMORY.
+ * errors include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_cff_subset_init (cairo_cff_subset_t          *cff_subset,
@@ -328,10 +328,10 @@ _cairo_cff_subset_fini (cairo_cff_subset_t *cff_subset);
  * file corresponding to @font_subset and initialize @cff_subset
  * with information about the subset and the cff data.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a
  * cff file, or an non-zero value indicating an error.  Possible
- * errors include CAIRO_STATUS_NO_MEMORY.
+ * errors include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_cff_fallback_init (cairo_cff_subset_t          *cff_subset,
@@ -371,10 +371,10 @@ typedef struct _cairo_truetype_subset {
  * @truetype_subset with information about the subset and the truetype
  * data.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a
  * truetype file, or an non-zero value indicating an error.  Possible
- * errors include CAIRO_STATUS_NO_MEMORY.
+ * errors include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_truetype_subset_init (cairo_truetype_subset_t    *truetype_subset,
@@ -415,10 +415,10 @@ typedef struct _cairo_type1_subset {
  * file corresponding to @font_subset and initialize @type1_subset
  * with information about the subset and the type1 data.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a type1
  * file, or an non-zero value indicating an error.  Possible errors
- * include CAIRO_STATUS_NO_MEMORY.
+ * include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_type1_subset_init (cairo_type1_subset_t		*type_subset,
@@ -441,7 +441,7 @@ _cairo_type1_subset_fini (cairo_type1_subset_t *subset);
  * _cairo_type1_scaled_font_is_type1:
  * @scaled_font: a #cairo_scaled_font_t
  *
- * Return TRUE if @scaled_font is a Type 1 font, otherwise return FALSE.
+ * Return %TRUE if @scaled_font is a Type 1 font, otherwise return %FALSE.
  **/
 cairo_private cairo_bool_t
 _cairo_type1_scaled_font_is_type1 (cairo_scaled_font_t	*scaled_font);
@@ -457,10 +457,10 @@ _cairo_type1_scaled_font_is_type1 (cairo_scaled_font_t	*scaled_font);
  * with information about the subset and the type1 data.  The encrypted
  * part of the font is binary encoded.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a type1
  * file, or an non-zero value indicating an error.  Possible errors
- * include CAIRO_STATUS_NO_MEMORY.
+ * include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_type1_fallback_init_binary (cairo_type1_subset_t	      *type_subset,
@@ -478,10 +478,10 @@ _cairo_type1_fallback_init_binary (cairo_type1_subset_t	      *type_subset,
  * with information about the subset and the type1 data. The encrypted
  * part of the font is hex encoded.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a type1
  * file, or an non-zero value indicating an error.  Possible errors
- * include CAIRO_STATUS_NO_MEMORY.
+ * include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_type1_fallback_init_hex (cairo_type1_subset_t	   *type_subset,
@@ -516,10 +516,10 @@ typedef struct _cairo_type2_charstrings {
  * charstrings to @font_subset and initialize @type2_subset
  * with information about the subset.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the font can't be subset as a type2
  * charstrings, or an non-zero value indicating an error.  Possible errors
- * include CAIRO_STATUS_NO_MEMORY.
+ * include %CAIRO_STATUS_NO_MEMORY.
  **/
 cairo_private cairo_status_t
 _cairo_type2_charstrings_init (cairo_type2_charstrings_t   *charstrings,
@@ -545,7 +545,7 @@ _cairo_type2_charstrings_fini (cairo_type2_charstrings_t *charstrings);
  * the unicode character of each glyph in font_subset to
  * fontsubset->to_unicode.
  *
- * Return value: CAIRO_STATUS_SUCCESS if successful,
+ * Return value: %CAIRO_STATUS_SUCCESS if successful,
  * CAIRO_INT_STATUS_UNSUPPORTED if the unicode encoding of
  * the glyphs is not available.  Possible  errors include
  * CAIRO_STATUS_NO_MEMORY.
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index d69d475..681edaf 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -704,7 +704,7 @@ slim_hidden_def (cairo_scaled_font_create);
 
 /**
  * cairo_scaled_font_reference:
- * @scaled_font: a #cairo_scaled_font_t, (may be NULL in which case
+ * @scaled_font: a #cairo_scaled_font_t, (may be %NULL in which case
  * this function does nothing)
  *
  * Increases the reference count on @scaled_font by one. This prevents
@@ -1455,7 +1455,7 @@ _add_unit_rectangle_to_path (cairo_path_fixed_t *path, int x, int y)
 
 /**
  * _trace_mask_to_path:
- * @bitmap: An alpha mask (either CAIRO_FORMAT_A1 or CAIRO_FORMAT_A8)
+ * @bitmap: An alpha mask (either %CAIRO_FORMAT_A1 or %CAIRO_FORMAT_A8)
  * @path: An initialized path to hold the result
  *
  * Given a mask surface, (an alpha image), fill out the provided path
diff --git a/src/cairo-surface-fallback.c b/src/cairo-surface-fallback.c
index 2eb4eae..f9f5b04 100644
--- a/src/cairo-surface-fallback.c
+++ b/src/cairo-surface-fallback.c
@@ -55,8 +55,8 @@ typedef struct {
  * Acquire destination image surface needed for an image-based
  * fallback.
  *
- * Return value: CAIRO_INT_STATUS_NOTHING_TO_DO if the extents are not
- * visible, CAIRO_STATUS_SUCCESS if some portion is visible and all
+ * Return value: %CAIRO_INT_STATUS_NOTHING_TO_DO if the extents are not
+ * visible, %CAIRO_STATUS_SUCCESS if some portion is visible and all
  * went well, or some error status otherwise.
  **/
 static cairo_int_status_t
@@ -273,7 +273,7 @@ _clip_and_composite_combine (cairo_clip_t                  *clip,
     return status;
 }
 
-/* Handles compositing for CAIRO_OPERATOR_SOURCE, which is special; it's
+/* Handles compositing for %CAIRO_OPERATOR_SOURCE, which is special; it's
  * defined as (src IN mask IN clip) ADD (dst OUT (mask IN clip))
  */
 static cairo_status_t
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 38be109..3227dbe 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -972,7 +972,7 @@ _cairo_surface_release_source_image (cairo_surface_t        *surface,
  * @surface: a #cairo_surface_t
  * @interest_rect: area of @surface for which fallback drawing is being done.
  *    A value of %NULL indicates that the entire surface is desired.
- *    XXXX I'd like to get rid of being able to pass NULL here (nothing seems to)
+ *    XXXX I'd like to get rid of being able to pass %NULL here (nothing seems to)
  * @image_out: location to store a pointer to an image surface that includes at least
  *    the intersection of @interest_rect with the visible area of @surface.
  *    This surface could be @surface itself, a surface held internal to @surface,
@@ -993,7 +993,7 @@ _cairo_surface_release_source_image (cairo_surface_t        *surface,
  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY.
  *  %CAIRO_INT_STATUS_UNSUPPORTED can be returned but this will mean that
  *  the backend can't draw with fallbacks. It's possible for the routine
- *  to store NULL in @local_out and return %CAIRO_STATUS_SUCCESS;
+ *  to store %NULL in @local_out and return %CAIRO_STATUS_SUCCESS;
  *  that indicates that no part of @interest_rect is visible, so no drawing
  *  is necessary. _cairo_surface_release_dest_image() should not be called in that
  *  case.
@@ -1131,7 +1131,7 @@ _cairo_surface_clone_similar (cairo_surface_t  *surface,
  *
  * The caller owns the return value and should call
  * cairo_surface_destroy when finished with it. This function will not
- * return NULL, but will return a nil surface instead.
+ * return %NULL, but will return a nil surface instead.
  *
  * Return value: The snapshot surface. Note that the return surface
  * may not necessarily be of the same type as @surface.
@@ -1161,7 +1161,7 @@ _cairo_surface_snapshot (cairo_surface_t *surface)
  * general, it means that the surface is equivalent to one
  * that would have been generated by a call to cairo_surface_create_similar.
  *
- * Return value: TRUE if the surfaces are similar.
+ * Return value: %TRUE if the surfaces are similar.
  **/
 cairo_bool_t
 _cairo_surface_is_similar (cairo_surface_t *surface_a,
@@ -2030,7 +2030,7 @@ _cairo_surface_get_extents (cairo_surface_t         *surface,
 }
 
 /* Note: the backends may modify the contents of the glyph array as long as
- * they do not return CAIRO_STATUS_UNSUPPORTED. This makes it possible to
+ * they do not return %CAIRO_STATUS_UNSUPPORTED. This makes it possible to
  * avoid copying the array again and again, and edit it in-place.
  * Backends are in fact free to use the array as a generic buffer as they
  * see fit.
diff --git a/src/cairo-svg-surface.c b/src/cairo-svg-surface.c
index 60d93e7..712b8ab 100644
--- a/src/cairo-svg-surface.c
+++ b/src/cairo-svg-surface.c
@@ -224,7 +224,7 @@ _cairo_surface_is_svg (cairo_surface_t *surface)
 
 /* If the abstract_surface is a paginated surface, and that paginated
  * surface's target is a svg_surface, then set svg_surface to that
- * target. Otherwise return CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
+ * target. Otherwise return %CAIRO_STATUS_SURFACE_TYPE_MISMATCH.
  */
 static cairo_status_t
 _extract_svg_surface (cairo_surface_t		 *surface,
@@ -303,7 +303,7 @@ cairo_svg_get_versions (cairo_svg_version_t const	**versions,
  * @version: a version id
  *
  * Get the string representation of the given @version id. This function
- * will return NULL if @version isn't valid. See cairo_svg_get_versions()
+ * will return %NULL if @version isn't valid. See cairo_svg_get_versions()
  * for a way to get the list of valid version ids.
  *
  * Return value: the string associated to given version.
diff --git a/src/cairo-types-private.h b/src/cairo-types-private.h
index ac7d837..af6d42a 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -79,9 +79,9 @@ typedef cairo_array_t cairo_user_data_array_t;
  * IMPORTANT: The caller is reponsible for initializing
  * my_entry->base.hash with a hash code derived from the key. The
  * essential property of the hash code is that keys_equal must never
- * return TRUE for two keys that have different hashes. The best hash
+ * return %TRUE for two keys that have different hashes. The best hash
  * code will reduce the frequency of two keys with the same code for
- * which keys_equal returns FALSE.
+ * which keys_equal returns %FALSE.
  *
  * 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
diff --git a/src/cairo-win32-font.c b/src/cairo-win32-font.c
index f7ae1f0..2039264 100644
--- a/src/cairo-win32-font.c
+++ b/src/cairo-win32-font.c
@@ -240,7 +240,7 @@ _get_system_quality (void)
     }
 }
 
-/* If face_hfont is non-NULL then font_matrix must be a simple scale by some
+/* If face_hfont is non-%NULL then font_matrix must be a simple scale by some
  * factor S, ctm must be the identity, logfont->lfHeight must be -S,
  * logfont->lfWidth, logfont->lfEscapement, logfont->lfOrientation must
  * all be 0, and face_hfont is the result of calling CreateFontIndirectW on
@@ -1767,7 +1767,7 @@ const cairo_scaled_font_backend_t cairo_win32_scaled_font_backend = {
 
 typedef struct _cairo_win32_font_face cairo_win32_font_face_t;
 
-/* If hfont is non-NULL then logfont->lfHeight must be -S for some S,
+/* If hfont is non-%NULL then logfont->lfHeight must be -S for some S,
  * logfont->lfWidth, logfont->lfEscapement, logfont->lfOrientation must
  * all be 0, and hfont is the result of calling CreateFontIndirectW on
  * logfont.
diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c
index 4017e2f..452775b 100644
--- a/src/cairo-win32-surface.c
+++ b/src/cairo-win32-surface.c
@@ -1861,10 +1861,10 @@ _cairo_surface_is_win32 (cairo_surface_t *surface)
  * cairo_win32_surface_get_dc
  * @surface: a #cairo_surface_t
  *
- * Returns the HDC associated with this surface, or NULL if none.
- * Also returns NULL if the surface is not a win32 surface.
+ * Returns the HDC associated with this surface, or %NULL if none.
+ * Also returns %NULL if the surface is not a win32 surface.
  *
- * Return value: HDC or NULL if no HDC available.
+ * Return value: HDC or %NULL if no HDC available.
  *
  * Since: 1.2
  **/
@@ -1888,10 +1888,10 @@ cairo_win32_surface_get_dc (cairo_surface_t *surface)
  *
  * Returns a #cairo_surface_t image surface that refers to the same bits
  * as the DIB of the Win32 surface.  If the passed-in win32 surface
- * is not a DIB surface, NULL is returned.
+ * is not a DIB surface, %NULL is returned.
  *
  * Return value: a #cairo_surface_t (owned by the win32 cairo_surface_t),
- * or NULL if the win32 surface is not a DIB.
+ * or %NULL if the win32 surface is not a DIB.
  *
  * Since: 1.4
  */
diff --git a/src/cairo-xcb-surface.c b/src/cairo-xcb-surface.c
index 6187db2..39ca0de 100644
--- a/src/cairo-xcb-surface.c
+++ b/src/cairo-xcb-surface.c
@@ -1886,7 +1886,7 @@ cairo_xcb_surface_create (xcb_connection_t *c,
  * @height: the current height of @bitmap
  *
  * Creates an XCB surface that draws to the given bitmap.
- * This will be drawn to as a CAIRO_FORMAT_A1 object.
+ * This will be drawn to as a %CAIRO_FORMAT_A1 object.
  *
  * Return value: the newly created surface
  **/
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index c777810..f5bd5e5 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -2108,7 +2108,7 @@ cairo_xlib_surface_create (Display     *dpy,
  * @height: the current height of @bitmap.
  *
  * Creates an Xlib surface that draws to the given bitmap.
- * This will be drawn to as a CAIRO_FORMAT_A1 object.
+ * This will be drawn to as a %CAIRO_FORMAT_A1 object.
  *
  * Return value: the newly created surface
  **/
@@ -2167,7 +2167,7 @@ slim_hidden_def (cairo_xlib_surface_create_with_xrender_format);
  * cairo_xlib_surface_create_with_render_format
  *
  * Return value: the XRenderPictFormat* with which the surface was
- * originally created, (or NULL if the surface is not an xlib surface
+ * originally created, (or %NULL if the surface is not an xlib surface
  * or if the X Render extension is not available).
  */
 XRenderPictFormat *
diff --git a/src/cairo.c b/src/cairo.c
index 5bbc53a..2597efc 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -125,7 +125,7 @@ _cairo_set_error (cairo_t *cr, cairo_status_t status)
  * cairo_version:
  *
  * Returns the version of the cairo library encoded in a single
- * integer as per CAIRO_VERSION_ENCODE. The encoding ensures that
+ * integer as per %CAIRO_VERSION_ENCODE. The encoding ensures that
  * later versions compare greater than earlier versions.
  *
  * A run-time comparison to check that cairo's version is greater than
@@ -1021,7 +1021,7 @@ cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
  *
  * 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
+ * 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
@@ -1036,7 +1036,7 @@ cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
  *
  * 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
- * #CAIRO_STATUS_INVALID_DASH.
+ * #%CAIRO_STATUS_INVALID_DASH.
  **/
 void
 cairo_set_dash (cairo_t	     *cr,
@@ -1887,7 +1887,7 @@ slim_hidden_def(cairo_close_path);
  * the corresponding drawing operations.
  *
  * The result of cairo_path_extents() is defined as equivalent to the
- * limit of cairo_stroke_extents() with CAIRO_LINE_CAP_ROUND as the
+ * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
  * line width approaches 0.0, (but never reaching the empty-rectangle
  * returned by cairo_stroke_extents() for a line width of 0.0).
  *
@@ -2059,20 +2059,20 @@ cairo_mask_surface (cairo_t         *cr,
  * situations:
  *
  * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
- * style is CAIRO_LINE_CAP_ROUND or CAIRO_LINE_CAP_SQUARE then these
+ * 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
+ * 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 cairo_move_to() followed by either a
  * cairo_close_path() or one or more calls to cairo_line_to() to the
  * same coordinate as the cairo_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
+ * 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
+ * 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
@@ -2497,7 +2497,7 @@ _cairo_rectangle_list_create_in_error (cairo_status_t status)
  * Gets the current clip region as a list of rectangles in user coordinates.
  * Never returns %NULL.
  *
- * The status in the list may be CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
+ * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
  * indicate that the clip region cannot be represented as a list of
  * user-space rectangles. The status may have other values to indicate
  * other errors.
@@ -3229,9 +3229,9 @@ cairo_get_antialias (cairo_t *cr)
  * Some functions unset the current path and as a result, current point:
  * cairo_fill(), cairo_stroke().
  *
- * Returns: CAIRO_STATUS_SUCCESS if current point was successfully
+ * Returns: %CAIRO_STATUS_SUCCESS if current point was successfully
  * retrieved.  Otherwise, if @cr has been in an error status, that status
- * is returned, otherwise CAIRO_STATUS_NO_CURRENT_POINT is returned if
+ * is returned, otherwise %CAIRO_STATUS_NO_CURRENT_POINT is returned if
  * no current point exists.  In all error cases, both @x and @y will be
  * set to 0.0.
  **/
@@ -3439,7 +3439,7 @@ cairo_get_group_target (cairo_t *cr)
  * over the returned data structure.
  *
  * This function will always return a valid pointer, but the result
- * will have no data (<literal>data==NULL</literal> and
+ * will have no data (<literal>data==%NULL</literal> and
  * <literal>num_data==0</literal>), if either of the following
  * conditions hold:
  *
@@ -3485,7 +3485,7 @@ cairo_copy_path (cairo_t *cr)
  * series of %CAIRO_PATH_LINE_TO elements.
  *
  * This function will always return a valid pointer, but the result
- * will have no data (<literal>data==NULL</literal> and
+ * will have no data (<literal>data==%NULL</literal> and
  * <literal>num_data==0</literal>), if either of the following
  * conditions hold:
  *
diff --git a/src/cairo.h b/src/cairo.h
index a6a34d6..0d08497 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -185,7 +185,7 @@ typedef struct _cairo_user_data_key {
  * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined
  * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible)
  * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input cairo_status_t
- * @CAIRO_STATUS_NULL_POINTER: NULL pointer
+ * @CAIRO_STATUS_NULL_POINTER: %NULL pointer
  * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8
  * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid
  * @CAIRO_STATUS_READ_ERROR: error while reading from input stream
@@ -1354,18 +1354,18 @@ typedef enum _cairo_path_data_type {
  *      for (i=0; i < path->num_data; i += path->data[i].header.length) {
  *          data = &amp;path->data[i];
  *          switch (data->header.type) {
- *          case CAIRO_PATH_MOVE_TO:
+ *          case %CAIRO_PATH_MOVE_TO:
  *              do_move_to_things (data[1].point.x, data[1].point.y);
  *              break;
- *          case CAIRO_PATH_LINE_TO:
+ *          case %CAIRO_PATH_LINE_TO:
  *              do_line_to_things (data[1].point.x, data[1].point.y);
  *              break;
- *          case CAIRO_PATH_CURVE_TO:
+ *          case %CAIRO_PATH_CURVE_TO:
  *              do_curve_to_things (data[1].point.x, data[1].point.y,
  *                                  data[2].point.x, data[2].point.y,
  *                                  data[3].point.x, data[3].point.y);
  *              break;
- *          case CAIRO_PATH_CLOSE_PATH:
+ *          case %CAIRO_PATH_CLOSE_PATH:
  *              do_close_path_things ();
  *              break;
  *          }
diff --git a/src/cairoint.h b/src/cairoint.h
index ee2d331..de87ab6 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -1756,7 +1756,7 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
 
 /* cairo_image_surface.c */
 
-/* XXX: In cairo 1.2.0 we added a new CAIRO_FORMAT_RGB16_565 but
+/* XXX: In cairo 1.2.0 we added a new %CAIRO_FORMAT_RGB16_565 but
  * 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
@@ -1773,7 +1773,7 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
  * visuals. This time we invented cairo_internal_format_t instead,
  * (see it for more discussion).
  *
- * The punchline is that CAIRO_FORMAT_VALID must not conside any
+ * The punchline is that %CAIRO_FORMAT_VALID must not conside any
  * internal format to be valid. Also we need to decide if the
  * RGB16_565 should be moved to instead be an internal format. If so,
  * this macro need not change for it. (We probably will need to leave
@@ -1781,7 +1781,7 @@ _cairo_surface_has_device_transform (cairo_surface_t *surface);
  * might have that value in it.)
  *
  * If we do decide to start fully supporting RGB16_565 as an external
- * format, then CAIRO_FORMAT_VALID needs to be adjusted to include
+ * 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
  * in cairo-xlib-surface.c--again see -Wswitch-enum).
diff --git a/src/test-fallback-surface.c b/src/test-fallback-surface.c
index 0bac87e..e720e88 100644
--- a/src/test-fallback-surface.c
+++ b/src/test-fallback-surface.c
@@ -37,8 +37,8 @@
  * test suite to test a mythical backend that uses nothing but
  * fallbacks.
  *
- * The defining feature of this backend is that it has as many NULL
- * backend function entries as possible. The ones that aren't NULL are
+ * The defining feature of this backend is that it has as many %NULL
+ * backend function entries as possible. The ones that aren't %NULL are
  * simply those that must be implemented to have working fallbacks.
  * (Except for create_similar---fallbacks would work fine without
  * that---I implemented it here in order to create as many surfaces as
commit 099c3c2602b59fbf9424044caa1fec7eb92f71df
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Mon Jan 28 20:32:35 2008 -0500

    [doc] Another enum nick expansion

diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index a2271f3..d69d475 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -1455,7 +1455,7 @@ _add_unit_rectangle_to_path (cairo_path_fixed_t *path, int x, int y)
 
 /**
  * _trace_mask_to_path:
- * @bitmap: An alpha mask (either CAIRO_FORMAT_A1 or _A8)
+ * @bitmap: An alpha mask (either CAIRO_FORMAT_A1 or CAIRO_FORMAT_A8)
  * @path: An initialized path to hold the result
  *
  * Given a mask surface, (an alpha image), fill out the provided path


More information about the cairo-commit mailing list