fdo-mirrors/cairo
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/cairo/cairo.git synced 2026-05-08 21:58:04 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

[src/check-doc-syntax.sh] Fix some bugs in the check and fix errors found

Browse source
This commit is contained in:
Behdad Esfahbod 2008-05-09 09:53:40 -04:00
parent 7dce536042
commit 5f63358018
7 changed files with 55 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/cairo-lzw.c
View file

@ -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)

32
src/cairo-mutex-type-private.h
View file

@ -72,7 +72,9 @@ CAIRO_BEGIN_DECLS
* You should be able to compile the following snippet (don't try
* running it):
*
* <programlisting>
* cairo_mutex_t _cairo_some_mutex;
* </programlisting>
*
* - #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:
*
* <programlisting>
* 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);
* </programlisting>
*
* - #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:
*
* <programlisting>
* 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);
* </programlisting>
*
* - 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:
*
* <programlisting>
* 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);
* </programlisting>
*
* - 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
* <programlisting>
* #define CAIRO_MUTEX_INITIALIZE() CAIRO_MUTEX_NOOP
* </programlisting>
*
* - 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
* <programlisting>
* #define CAIRO_MUTEX_FINALIZE() CAIRO_MUTEX_NOOP
* </programlisting>
*
* - That is all. If for any reason you think the above API is
* not enough to implement #cairo_mutex_t on your system, please

6
src/cairo-output-stream.c
View file

@ -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:
*
* <programlisting>
* FIXED_POINT_DECIMAL_DIGITS = ceil( CAIRO_FIXED_FRAC_BITS * ln(2)/ln(10) )
* </programlisting>
*
* 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))

12
src/cairo-paginated-private.h
View file

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

4
src/cairo-surface.c
View file

@ -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.

12
src/cairo.h
View file

@ -1369,26 +1369,26 @@ typedef enum _cairo_path_data_type {
*
* <informalexample><programlisting>
* int i;
* #cairo_path_t *path;
* #cairo_path_data_t *data;
* cairo_path_t *path;
* cairo_path_data_t *data;
* &nbsp;
* path = cairo_copy_path (cr);
* &nbsp;
* for (i=0; i < path->num_data; i += path->data[i].header.length) {
* data = &amp;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;
* }

40
src/check-doc-syntax.sh
View file

@ -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>/,/<\/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='\( .*[^#]\| \|^\)\<cairo[0-9a-z_]*_t\>\($\|[^:]$\|[^:].\)'
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>/,/<\/programlisting>/d' $files | grep "$type_regexp" | grep -v '#####'; then
if grep . /dev/null $FILES | sed -e '/<programlisting>/,/<\/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>/,/<\/programlisting>/d' $files | grep "$func_regexp" | grep -v '#####'; then
if grep . /dev/null $FILES | sed -e '/<programlisting>/,/<\/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: