[cairo] [PATCH] Fix warnings from check-doc-syntax.sh
Bryce W. Harrington
b.harrington at samsung.com
Thu Mar 13 17:14:53 PDT 2014
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 <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
More information about the cairo
mailing list