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

Thanks, after testing and verifying your patch I took the liberty of
pushing it to master.  Hope that's cool.

Bryce

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 <[email protected]>
> ---
>  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
-- 
cairo mailing list
[email protected]
http://lists.cairographics.org/mailman/listinfo/cairo