[PATCH 5/7] check-def: Fix code document errors

This updates docs to resolve the following distcheck errors from the
check-def.sh script:

FAIL: check-def.sh
Checking documentation for incorrect syntax
./cairo-types-private.h (148): WARNING: cairo_hash_entry_t: missing 'Since' field (is it a private type?)
./cairo-types-private.h (161): WARNING: cairo_hash_entry_t: not found
./cairo-types-private.h (175): WARNING: cairo_lcd_filter_t: missing 'Since' field (is it a private type?)
./cairo-cache-private.h (85): WARNING: cairo_cache_entry_t: missing 'Since' field (is it a private type?)
./cairo-region.c (856): WARNING: cairo_region_overlap_t: not found
./cairo-raster-source-pattern.c (62): WARNING: SECTION:cairo-raster-source 'Since' field in non-public element

For the 'not_found' errors, move the documentation closer to the type
definition.  For the Since fields, either add [my guess as to...] when
the type became available, or mark it private (in the case of
cairo_lcd_filter_t).

Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=74894

Signed-off-by: Bryce Harrington <[email protected]>
---
 src/cairo-cache-private.h         |    2 +
 src/cairo-raster-source-pattern.c |    2 -
 src/cairo-region.c                |   16 +-------
 src/cairo-types-private.h         |   74 ++++++++++++++++++++-----------------
 src/cairo.h                       |   11 ++++++
 5 files changed, 55 insertions(+), 50 deletions(-)

diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h
index 76b5561..114e071 100644
--- a/src/cairo-cache-private.h
+++ b/src/cairo-cache-private.h
@@ -82,6 +82,8 @@
  * 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.
+ *
+ * Since: 1.6
  **/
 typedef struct _cairo_cache_entry {
     unsigned long hash;
diff --git a/src/cairo-raster-source-pattern.c b/src/cairo-raster-source-pattern.c
index 601fe60..64520fe 100644
--- a/src/cairo-raster-source-pattern.c
+++ b/src/cairo-raster-source-pattern.c
@@ -57,8 +57,6 @@
  * Other callbacks are provided for when the pattern is copied temporarily
  * during rasterisation, or more permanently as a snapshot in order to keep
  * the pixel data available for printing.
- *
- * Since: 1.12
  **/
 
 cairo_surface_t *
diff --git a/src/cairo-region.c b/src/cairo-region.c
index ceaf4c0..d12cb47 100644
--- a/src/cairo-region.c
+++ b/src/cairo-region.c
@@ -49,8 +49,8 @@
  * @Title: Regions
  * @Short_Description: Representing a pixel-aligned area
  *
- * Regions are a simple graphical data type representing an area of 
- * integer-aligned rectangles. They are often used on raster surfaces 
+ * Regions are a simple graphical data type representing an area of
+ * integer-aligned rectangles. They are often used on raster surfaces
  * to track areas of interest, such as change or clip areas.
  **/
 
@@ -842,18 +842,6 @@ cairo_region_translate (cairo_region_t *region,
 slim_hidden_def (cairo_region_translate);
 
 /**
- * cairo_region_overlap_t:
- * @CAIRO_REGION_OVERLAP_IN: The contents are entirely inside the region. (Since 1.10)
- * @CAIRO_REGION_OVERLAP_OUT: The contents are entirely outside the region. (Since 1.10)
- * @CAIRO_REGION_OVERLAP_PART: The contents are partially inside and
- *     partially outside the region. (Since 1.10)
- *
- * Used as the return value for cairo_region_contains_rectangle().
- *
- * Since: 1.10
- **/
-
-/**
  * cairo_region_contains_rectangle:
  * @region: a #cairo_region_t
  * @rectangle: a #cairo_rectangle_int_t
diff --git a/src/cairo-types-private.h b/src/cairo-types-private.h
index 3c2d21a..5d564f6 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -72,7 +72,45 @@ typedef struct _cairo_font_face_backend     cairo_font_face_backend_t;
 typedef struct _cairo_gstate cairo_gstate_t;
 typedef struct _cairo_gstate_backend cairo_gstate_backend_t;
 typedef struct _cairo_glyph_text_info cairo_glyph_text_info_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
+ * 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:
+ *
+ * 	typedef _my_entry {
+ *	    cairo_hash_entry_t base;
+ *	    ... Remainder of key and value fields here ..
+ *	} my_entry_t;
+ *
+ * which then allows a pointer to my_entry_t to be passed to any of
+ * the #cairo_hash_table_t functions as follows without requiring a cast:
+ *
+ *	_cairo_hash_table_insert (hash_table, &my_entry->base);
+ *
+ * IMPORTANT: The caller is responsible 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
+ * code will reduce the frequency of two keys with the same code for
+ * 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
+ * computation going into base.hash as well as the keys_equal
+ * 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.
+ *
+ * Since: 1.6
+ **/
 typedef struct _cairo_hash_entry cairo_hash_entry_t;
+
 typedef struct _cairo_hash_table cairo_hash_table_t;
 typedef struct _cairo_image_surface cairo_image_surface_t;
 typedef struct _cairo_mime_data cairo_mime_data_t;
@@ -112,40 +150,6 @@ struct _cairo_observer {
     void (*callback) (cairo_observer_t *self, void *arg);
 };
 
-/**
- * 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
- * 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:
- *
- * 	typedef _my_entry {
- *	    cairo_hash_entry_t base;
- *	    ... Remainder of key and value fields here ..
- *	} my_entry_t;
- *
- * which then allows a pointer to my_entry_t to be passed to any of
- * the #cairo_hash_table_t functions as follows without requiring a cast:
- *
- *	_cairo_hash_table_insert (hash_table, &my_entry->base);
- *
- * IMPORTANT: The caller is responsible 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
- * code will reduce the frequency of two keys with the same code for
- * 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
- * computation going into base.hash as well as the keys_equal
- * 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.
- **/
 struct _cairo_hash_entry {
     unsigned long hash;
 };
@@ -172,6 +176,8 @@ struct _cairo_array {
  * Note: This API was temporarily made available in the public
  * interface during the 1.7.x development series, but was made private
  * before 1.8.
+ *
+ * Since: TBD
  **/
 typedef enum _cairo_lcd_filter {
     CAIRO_LCD_FILTER_DEFAULT,
diff --git a/src/cairo.h b/src/cairo.h
index aa2070e..3104d47 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -3048,6 +3048,17 @@ cairo_matrix_transform_point (const cairo_matrix_t *matrix,
  **/
 typedef struct _cairo_region cairo_region_t;
 
+/**
+ * cairo_region_overlap_t:
+ * @CAIRO_REGION_OVERLAP_IN: The contents are entirely inside the region. (Since 1.10)
+ * @CAIRO_REGION_OVERLAP_OUT: The contents are entirely outside the region. (Since 1.10)
+ * @CAIRO_REGION_OVERLAP_PART: The contents are partially inside and
+ *     partially outside the region. (Since 1.10)
+ *
+ * Used as the return value for cairo_region_contains_rectangle().
+ *
+ * Since: 1.10
+ **/
 typedef enum _cairo_region_overlap {
     CAIRO_REGION_OVERLAP_IN,		/* completely inside region */
     CAIRO_REGION_OVERLAP_OUT,		/* completely outside region */
-- 
1.7.9.5
-- 
cairo mailing list
[email protected]
http://lists.cairographics.org/mailman/listinfo/cairo