From 5f633580189fa48f5b650d3c63c585521bb833a9 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Fri, 9 May 2008 09:53:40 -0400 Subject: [PATCH] [src/check-doc-syntax.sh] Fix some bugs in the check and fix errors found --- src/cairo-lzw.c | 2 +- src/cairo-mutex-type-private.h | 32 ++++++++++++++++++--------- src/cairo-output-stream.c | 6 +++-- src/cairo-paginated-private.h | 12 +++++----- src/cairo-surface.c | 4 ++-- src/cairo.h | 12 +++++----- src/check-doc-syntax.sh | 40 ++++++++++++---------------------- 7 files changed, 55 insertions(+), 53 deletions(-) diff --git a/src/cairo-lzw.c b/src/cairo-lzw.c index d95da8c9a..1241225d4 100644 --- a/src/cairo-lzw.c +++ b/src/cairo-lzw.c @@ -82,7 +82,7 @@ _lzw_buf_init (lzw_buf_t *buf, int size) /* Increase the buffer size by doubling. * - * Returns %CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY + * Returns %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY */ static cairo_status_t _lzw_buf_grow (lzw_buf_t *buf) diff --git a/src/cairo-mutex-type-private.h b/src/cairo-mutex-type-private.h index 1a29dcbf3..f68afb77f 100644 --- a/src/cairo-mutex-type-private.h +++ b/src/cairo-mutex-type-private.h @@ -72,7 +72,9 @@ CAIRO_BEGIN_DECLS * You should be able to compile the following snippet (don't try * running it): * + * * cairo_mutex_t _cairo_some_mutex; + * * * - #define CAIRO_MUTEX_LOCK(mutex) and CAIRO_MUTEX_UNLOCK(mutex) to * proper statement to lock/unlock the mutex object passed in. @@ -82,44 +84,52 @@ CAIRO_BEGIN_DECLS * No trailing semicolons are needed (in any macro you define here). * You should be able to compile the following snippet: * + * * cairo_mutex_t _cairo_some_mutex; * * if (1) - * %CAIRO_MUTEX_LOCK (_cairo_some_mutex); + * CAIRO_MUTEX_LOCK (_cairo_some_mutex); * else - * %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * * * - #define %CAIRO_MUTEX_NIL_INITIALIZER to something that can * initialize the #cairo_mutex_t type you defined. Most of the * time one of 0, %NULL, or {} works. At this point * you should be able to compile the following snippet: * + * * cairo_mutex_t _cairo_some_mutex = CAIRO_MUTEX_NIL_INITIALIZER; * * if (1) - * %CAIRO_MUTEX_LOCK (_cairo_some_mutex); + * CAIRO_MUTEX_LOCK (_cairo_some_mutex); * else - * %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * * * - If the above code is not enough to initialize a mutex on * your platform, #define CAIRO_MUTEX_INIT(mutex) to statement * to initialize the mutex (allocate resources, etc). Such that * you should be able to compile AND RUN the following snippet: * + * * cairo_mutex_t _cairo_some_mutex = CAIRO_MUTEX_NIL_INITIALIZER; * - * %CAIRO_MUTEX_INIT (_cairo_some_mutex); + * CAIRO_MUTEX_INIT (_cairo_some_mutex); * * if (1) - * %CAIRO_MUTEX_LOCK (_cairo_some_mutex); + * CAIRO_MUTEX_LOCK (_cairo_some_mutex); * else - * %CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * CAIRO_MUTEX_UNLOCK (_cairo_some_mutex); + * * * - If you define CAIRO_MUTEX_INIT(mutex), cairo will use it to * initialize all static mutex'es. If for any reason that should * not happen (eg. %CAIRO_MUTEX_INIT is just a faster way than * what cairo does using %CAIRO_MUTEX_NIL_INITIALIZER), then - * #define CAIRO_MUTEX_INITIALIZE() CAIRO_MUTEX_NOOP + * + * #define CAIRO_MUTEX_INITIALIZE() CAIRO_MUTEX_NOOP + * * * - If your system supports freeing a mutex object (deallocating * resources, etc), then #define CAIRO_MUTEX_FINI(mutex) to do @@ -130,8 +140,10 @@ CAIRO_BEGIN_DECLS * However, it's up to you to call CAIRO_MUTEX_FINALIZE() at * proper places, eg. when the system is unloading the cairo library. * So, if for any reason finalizing static mutex'es is not needed - * (eg. you never call %CAIRO_MUTEX_FINALIZE), then - * #define CAIRO_MUTEX_FINALIZE() CAIRO_MUTEX_NOOP + * (eg. you never call CAIRO_MUTEX_FINALIZE()), then + * + * #define CAIRO_MUTEX_FINALIZE() CAIRO_MUTEX_NOOP + * * * - That is all. If for any reason you think the above API is * not enough to implement #cairo_mutex_t on your system, please diff --git a/src/cairo-output-stream.c b/src/cairo-output-stream.c index 351585e75..e2fffb28e 100644 --- a/src/cairo-output-stream.c +++ b/src/cairo-output-stream.c @@ -49,7 +49,7 @@ */ #define SIGNIFICANT_DIGITS_AFTER_DECIMAL 6 -/* Numbers printed with %g are assumed to only have CAIRO_FIXED_FRAC_BITS +/* Numbers printed with %g are assumed to only have %CAIRO_FIXED_FRAC_BITS * bits of precision available after the decimal point. * * FIXED_POINT_DECIMAL_DIGITS specifies the minimum number of decimal @@ -58,10 +58,12 @@ * * The conversion is: * + * * FIXED_POINT_DECIMAL_DIGITS = ceil( CAIRO_FIXED_FRAC_BITS * ln(2)/ln(10) ) + * * * We can replace ceil(x) with (int)(x+1) since x will never be an - * integer for any likely value of CAIRO_FIXED_FRAC_BITS. + * integer for any likely value of %CAIRO_FIXED_FRAC_BITS. */ #define FIXED_POINT_DECIMAL_DIGITS ((int)(CAIRO_FIXED_FRAC_BITS*0.301029996 + 1)) diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h index 35384c9f4..bb31487aa 100644 --- a/src/cairo-paginated-private.h +++ b/src/cairo-paginated-private.h @@ -90,27 +90,27 @@ struct _cairo_paginated_surface_backend { * operations for a page into a meta-surface. Then when the user calls * cairo_show_page, the paginated surface performs the following * sequence of operations (using the backend functions passed to - * cairo_paginated_surface_create): + * cairo_paginated_surface_create()): * - * 1. Calls start_page (if non %NULL). At this point, it is appropriate + * 1. Calls start_page() (if not %NULL). At this point, it is appropriate * for the target to emit any page-specific header information into * its output. * - * 2. Calls set_paginated_mode with an argument of CAIRO_PAGINATED_MODE_ANALYZE + * 2. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_ANALYZE * * 3. Replays the meta-surface to the target surface, (with an * analysis surface inserted between which watches the return value * from each operation). This analysis stage is used to decide which * operations will require fallbacks. * - * 4. Calls set_bounding_box to provide the target surface with the + * 4. Calls set_bounding_box() to provide the target surface with the * tight bounding box of the page. * - * 5. Calls set_paginated_mode with an argument of CAIRO_PAGINATED_MODE_RENDER + * 5. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_RENDER * * 6. Replays a subset of the meta-surface operations to the target surface * - * 7. Calls set_paginated_mode with an argument of CAIRO_PAGINATED_MODE_FALLBACK + * 7. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_FALLBACK * * 8. Replays the remaining operations to an image surface, sets an * appropriate clip on the target, then paints the resulting image diff --git a/src/cairo-surface.c b/src/cairo-surface.c index 0d5a3f826..023070385 100644 --- a/src/cairo-surface.c +++ b/src/cairo-surface.c @@ -476,7 +476,7 @@ cairo_surface_get_reference_count (cairo_surface_t *surface) * After calling cairo_surface_finish() the only valid operations on a * surface are getting and setting user data and referencing and * destroying it. Further drawing to the surface will not affect the - * surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED + * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED * error. * * When the last call to cairo_surface_destroy() decreases the @@ -2081,7 +2081,7 @@ _cairo_surface_get_extents (cairo_surface_t *surface, } /* Note: the backends may modify the contents of the glyph array as long as - * they do not return %CAIRO_STATUS_UNSUPPORTED. This makes it possible to + * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to * avoid copying the array again and again, and edit it in-place. * Backends are in fact free to use the array as a generic buffer as they * see fit. diff --git a/src/cairo.h b/src/cairo.h index 4a3a773df..42eb02727 100644 --- a/src/cairo.h +++ b/src/cairo.h @@ -1369,26 +1369,26 @@ typedef enum _cairo_path_data_type { * * * int i; - * #cairo_path_t *path; - * #cairo_path_data_t *data; + * cairo_path_t *path; + * cairo_path_data_t *data; *   * path = cairo_copy_path (cr); *   * for (i=0; i < path->num_data; i += path->data[i].header.length) { * data = &path->data[i]; * switch (data->header.type) { - * case %CAIRO_PATH_MOVE_TO: + * case CAIRO_PATH_MOVE_TO: * do_move_to_things (data[1].point.x, data[1].point.y); * break; - * case %CAIRO_PATH_LINE_TO: + * case CAIRO_PATH_LINE_TO: * do_line_to_things (data[1].point.x, data[1].point.y); * break; - * case %CAIRO_PATH_CURVE_TO: + * case CAIRO_PATH_CURVE_TO: * do_curve_to_things (data[1].point.x, data[1].point.y, * data[2].point.x, data[2].point.y, * data[3].point.x, data[3].point.y); * break; - * case %CAIRO_PATH_CLOSE_PATH: + * case CAIRO_PATH_CLOSE_PATH: * do_close_path_things (); * break; * } diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh index 1ed24b515..1e5e76a20 100755 --- a/src/check-doc-syntax.sh +++ b/src/check-doc-syntax.sh @@ -21,36 +21,25 @@ if test "x$SGML_DOCS" = x; then fi fi -# Note: This test reports false positives on non-gtk-doc comments and -# non-public enum values, (such as CAIRO_FIXED_FRAC_BITS in the comment -# for _cairo_output_stream_init). I'm opposed to uglifying those comments -# with % just to shut this warning up. So instead, I'm turning this check -# off. (cworth 2008-03-02) -# -# Meanwhile, I'd love to see a system that would just link things like -# enums up without any decoration. -# -#enum_regexp='\([^%@]\|^\)\<\(FALSE\|TRUE\|NULL\|CAIRO_[0-9A-Z_]*[^(0-9A-Z_]\)' -#if test "x$SGML_DOCS" = x; then -# enum_regexp='^[/ ][*] .*'$enum_regexp -#fi -#if grep "$enum_regexp" $FILES | grep -v '#####'; then -# status=1 -# echo Error: some macros in the docs are not prefixed by percent sign. -# echo Fix this by searching for the following regexp in the above files: -# echo " '$enum_regexp'" -#fi +enum_regexp='\([^%@]\|^\)\<\(FALSE\|TRUE\|NULL\|CAIRO_[0-9A-Z_]*\)\($\|[^(A-Za-z0-9_]\)' +if test "x$SGML_DOCS" = x; then + enum_regexp='^[^:]*:[/ ][*] .*'$enum_regexp +fi +if grep . /dev/null $FILES | sed -e '//,/<\/programlisting>/d' | grep "$enum_regexp" | grep -v '#####'; then + status=1 + echo Error: some macros in the docs are not prefixed by percent sign. + echo Fix this by searching for the following regexp in the above files: + echo " '$enum_regexp'" +fi type_regexp='\( .*[^#]\| \|^\)\\($\|[^:]$\|[^:].\)' if test "x$SGML_DOCS" = x; then - type_regexp='^[/ ][*]'$type_regexp + type_regexp='^[^:]*:[/ ][*]'$type_regexp else type_regexp='\(.'$type_regexp'\)\|\('$type_regexp'.\)' fi -# We need to filter out gtk-doc markup errors for program listings. -files=`grep "$type_regexp" $FILES | grep -v '#####' | cut -d: -f1 | sort | uniq` -if test -n "$files" && sed -e '//,/<\/programlisting>/d' $files | grep "$type_regexp" | grep -v '#####'; then +if grep . /dev/null $FILES | sed -e '//,/<\/programlisting>/d' | grep "$type_regexp" | grep -v '#####'; then status=1 echo Error: some type names in the docs are not prefixed by hash sign, echo neither are the only token in the doc line followed by colon. @@ -60,12 +49,11 @@ fi func_regexp='\([^#]\|^\)\<\(cairo_[][<>/0-9a-z_]*\> \?[^][ <>(]\)' if test "x$SGML_DOCS" = x; then - func_regexp='^[/ ][*] .*'$func_regexp + func_regexp='^[^:]*:[/ ][*] .*'$func_regexp fi # We need to filter out gtk-doc markup errors for program listings. -files=`grep "$func_regexp" $FILES | grep -v '#####' | cut -d: -f1 | sort | uniq` -if test -n "$files" && sed -e '//,/<\/programlisting>/d' $files | grep "$func_regexp" | grep -v '#####'; then +if grep . /dev/null $FILES | sed -e '//,/<\/programlisting>/d' | grep "$func_regexp" | grep -v '#####'; then status=1 echo Error: some function names in the docs are not followed by parentheses. echo Fix this by searching for the following regexp in the above files: