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

[Bryce W. Harrington]

On Thu, Feb 27, 2014 at 10:56:20AM +0100, Uli Schlachter wrote:
> $ ./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.

Yes!  I spent hours tinkering with the script to try to convince it to
ignore private stuff but it proved to be a twisty maze of regexp's, all
the same.
 
> However, I didn't do any tests with gtk-doc...

I'll check them tomorrow.  The gtk-doc stuff is complicated and without
actually running the tests it's hard to be certain that the format is
going to be acceptable.

Tomorrow I'll run your patch on my system and see if it passes.

> 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:

Yeah, I tried this approach too, but the cairo_cache_entry_t,
cairo_lcd_filter_t, etc. stuff still gets flagged by distcheck.
Your approach is probably better, but the trick is getting the tools to
accept it.  :-)

>   *
>   * 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