[cairo] [PATCH] Fix warnings from check-doc-syntax.sh

[Uli Schlachter]

$ ./check-doc-syntax.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 (857): WARNING: cairo_region_overlap_t: not found
./cairo-raster-source-pattern.c (62): WARNING: SECTION:cairo-raster-source 'Since' field in non-public element

The warnings about missing 'Since' fields are fixed by changing the
documentation comment so that the script can see that these are private types.

The documentation for cairo_region_overlap_t gets moved to cairo.h, just like
e.g. the documentation for cairo_status_t.

The 'Since' field from the SECTION:cairo-raster-source is removed, because this
kind of field is needed on the individual functions and structs, not on the
section.

Thanks to Bryce Harrington for bringing this up!

Signed-off-by: Uli Schlachter <psychon at znc.in>
---
 src/cairo-cache-private.h         |  2 +-
 src/cairo-raster-source-pattern.c |  2 --
 src/cairo-region.c                | 12 ------------
 src/cairo-types-private.h         |  4 ++--
 src/cairo.h                       | 11 +++++++++++
 5 files changed, 14 insertions(+), 17 deletions(-)

Hi Bryce,

I'd like to replace your patch 5/7 with this one. I hope that you agree that
this is better than introducing unneeded 'Since' fields.

However, I didn't do any tests with gtk-doc...

diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h
index 76b5561..24b6d0b 100644
--- a/src/cairo-cache-private.h
+++ b/src/cairo-cache-private.h
@@ -43,7 +43,7 @@
 #include "cairo-types-private.h"
 
 /**
- * cairo_cache_entry_t:
+ * _cairo_cache_entry:
  *
  * 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
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..ccfb220 100644
--- a/src/cairo-region.c
+++ b/src/cairo-region.c
@@ -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..3d15d96 100644
--- a/src/cairo-types-private.h
+++ b/src/cairo-types-private.h
@@ -113,7 +113,7 @@ struct _cairo_observer {
 };
 
 /**
- * cairo_hash_entry_t:
+ * _cairo_hash_entry:
  *
  * 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
@@ -158,7 +158,7 @@ struct _cairo_array {
 };
 
 /**
- * cairo_lcd_filter_t:
+ * _cairo_lcd_filter:
  * @CAIRO_LCD_FILTER_DEFAULT: Use the default LCD filter for
  *   font backend and target device
  * @CAIRO_LCD_FILTER_NONE: Do not perform LCD filtering
diff --git a/src/cairo.h b/src/cairo.h
index 2e69793..6a092d3 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -3039,6 +3039,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.8.5.3