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

18 files changed, 45 insertions, 44 deletions

diff --git a/src/cairo-array.c b/src/cairo-array.c
index a6918b2b..b547b121 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 65a8aee8..4ae63ade 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 6a296005..397dd563 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 2fce865b..00f3b91a 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 c85a2b4b..59ea6f28 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 ab2ee1df..35384c9f 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 2473eb89..65df5a20 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 f3ac2904..720b1b76 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 8fc65677..4e2d7238 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 bccd0de1..733fe1e6 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 469b4dc8..43fe29bb 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 2c4f5ab7..5d18c643 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 0b847740..9cb9882e 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 20392643..eb4d3b1e 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 7d429f24..d3c5ba48 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 bcef13a5..37a34a66 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 61c59ff4..75b646e0 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 a7e8d5a3..7b0908ff 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_]*\> \?[^][ <>(]\)'