From 7ebb1e7157ab5d3efbeb37d7879d851adc7da40e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 9 Feb 2010 14:41:37 +0000 Subject: [PATCH] docs: Fixes for Cogl API reference 98% symbol docs coverage. 335 symbols documented. 0 symbols incomplete. 8 not documented. Not bad, if I may say so. --- clutter/cogl/cogl/cogl-buffer.h | 12 ++++++--- clutter/cogl/cogl/cogl-color.h | 41 +++++++++++++++++++++++++++++++ clutter/cogl/cogl/cogl-fixed.h | 2 +- clutter/cogl/cogl/cogl-material-private.h | 2 +- clutter/cogl/cogl/cogl-matrix.h | 3 ++- clutter/cogl/cogl/cogl-types.h | 23 ++++++++++++++++- doc/reference/cogl/cogl-sections.txt | 16 +++--------- 7 files changed, 80 insertions(+), 19 deletions(-) diff --git a/clutter/cogl/cogl/cogl-buffer.h b/clutter/cogl/cogl/cogl-buffer.h index ddad4bc..3d90d1e 100644 --- a/clutter/cogl/cogl/cogl-buffer.h +++ b/clutter/cogl/cogl/cogl-buffer.h @@ -93,7 +93,7 @@ typedef enum { /*< prefix=COGL_BUFFER_USAGE_HINT >*/ * @handle: a buffer handle * @hint: the new hint * - * Set the usage hint on a buffer. See #CoglBufferUsageHint for a description + * Sets the usage hint on a buffer. See #CoglBufferUsageHint for a description * of the available hints. * * Since: 1.2 @@ -107,6 +107,8 @@ cogl_buffer_set_usage_hint (CoglHandle handle, * cogl_buffer_get_usage_hint: * @handle: a buffer handle * + * Retrieves the usage hint set using cogl_buffer_set_usage_hint() + * * Return value: the #CoglBufferUsageHint currently used by the buffer * * Since: 1.2 @@ -122,7 +124,7 @@ cogl_buffer_get_usage_hint (CoglHandle handle); * @COGL_BUFFER_UPDATE_HINT_STREAM: the buffer will be used once or a couple of * times * - * The update hint on a buffer allows the user to give some clue on how often + * The update hint on a buffer allows the user to give some detail on how often * the buffer data is going to be updated. * * Since: 1.2 @@ -139,7 +141,7 @@ typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/ * @handle: a buffer handle * @hint: the new hint * - * Set the update hint on a buffer. See #CoglBufferUpdateHint for a description + * Sets the update hint on a buffer. See #CoglBufferUpdateHint for a description * of the available hints. * * Since: 1.2 @@ -153,6 +155,8 @@ cogl_buffer_set_update_hint (CoglHandle handle, * cogl_buffer_get_update_hint: * @handle: a buffer handle * + * Retrieves the update hints set using cogl_buffer_set_update_hint() + * * Return value: the #CoglBufferUpdateHint currently used by the buffer * * Since: 1.2 @@ -168,6 +172,8 @@ cogl_buffer_get_update_hint (CoglHandle handle); * @COGL_BUFFER_ACCESS_READ_WRITE: the buffer will be used for both reading and * writing * + * The access hints for cogl_buffer_set_update_hint() + * * Since: 1.2 * Stability: Unstable */ diff --git a/clutter/cogl/cogl/cogl-color.h b/clutter/cogl/cogl/cogl-color.h index cb7d533..abc0e64 100644 --- a/clutter/cogl/cogl/cogl-color.h +++ b/clutter/cogl/cogl/cogl-color.h @@ -21,6 +21,16 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:cogl-color + * @short_description: A generic color definition + * + * #CoglColor is a simple structure holding the definition of a color such + * that it can be efficiently used by GL + * + * Since: 1.0 + */ + #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION) #error "Only can be included directly." #endif @@ -32,8 +42,39 @@ G_BEGIN_DECLS +/** + * cogl_color_new: + * + * Creates a new (empty) color + * + * Return value: a newly-allocated #CoglColor. Use cogl_color_free() + * to free the allocated resources + * + * Since: 1.0 + */ CoglColor *cogl_color_new (void); + +/** + * cogl_color_copy: + * @color: the color to copy + * + * Creates a copy of @color + * + * Return value: a newly-allocated #CoglColor. Use cogl_color_free() + * to free the allocate resources + * + * Since: 1.0 + */ CoglColor *cogl_color_copy (const CoglColor *color); + +/** + * cogl_color_free: + * @color: the color to free + * + * Frees the resources allocated by cogl_color_new() and cogl_color_copy() + * + * Since: 1.0 + */ void cogl_color_free (CoglColor *color); /** diff --git a/clutter/cogl/cogl/cogl-fixed.h b/clutter/cogl/cogl/cogl-fixed.h index 904913e..8684351 100644 --- a/clutter/cogl/cogl/cogl-fixed.h +++ b/clutter/cogl/cogl/cogl-fixed.h @@ -304,7 +304,7 @@ G_BEGIN_DECLS #define COGL_FIXED_FROM_DOUBLE(x) (cogl_double_to_fixed (x)) /** - * COGL_FIXED_TO_FLOAT: + * COGL_FIXED_TO_DOUBLE: * @x: a #CoglFixed number * * Converts @x from a fixed point to a floating point notation, in diff --git a/clutter/cogl/cogl/cogl-material-private.h b/clutter/cogl/cogl/cogl-material-private.h index a9cf77a..a5a846f 100644 --- a/clutter/cogl/cogl/cogl-material-private.h +++ b/clutter/cogl/cogl/cogl-material-private.h @@ -148,7 +148,7 @@ struct _CoglMaterial /* * SECTION:cogl-material-internals * @short_description: Functions for creating custom primitives that make use - * of Cogl materials for filling. + * of Cogl materials for filling. * * Normally you shouldn't need to use this API directly, but if you need to * developing a custom/specialised primitive - probably using raw OpenGL - then diff --git a/clutter/cogl/cogl/cogl-matrix.h b/clutter/cogl/cogl/cogl-matrix.h index 451233d..eb5215a 100644 --- a/clutter/cogl/cogl/cogl-matrix.h +++ b/clutter/cogl/cogl/cogl-matrix.h @@ -151,7 +151,8 @@ void cogl_matrix_rotate (CoglMatrix *matrix, float y, float z); -/* cogl_matrix_translate: +/** + * cogl_matrix_translate: * @matrix: A 4x4 transformation matrix * @x: The X translation you want to apply * @y: The Y translation you want to apply diff --git a/clutter/cogl/cogl/cogl-types.h b/clutter/cogl/cogl/cogl-types.h index 816d240..2bc6865 100644 --- a/clutter/cogl/cogl/cogl-types.h +++ b/clutter/cogl/cogl/cogl-types.h @@ -283,8 +283,10 @@ struct _CoglTextureVertex * the mipmap pyramid from the base level image whenever it is * updated. The mipmaps are only generated when the texture is * rendered with a mipmap filter so it should be free to leave out - * this flag when using other filtering modes. + * this flag when using other filtering modes * @COGL_TEXTURE_NO_SLICING: Disables the slicing of the texture + * @COGL_TEXTURE_NO_ATLAS: Disables the insertion of the texture inside + * the texture atlas used by Cogl * * Flags to pass to the cogl_texture_new_* family of functions. * @@ -331,8 +333,27 @@ typedef enum { COGL_FOG_MODE_EXPONENTIAL_SQUARED } CoglFogMode; +/** + * COGL_BLEND_STRING_ERROR: + * + * #GError domain for blend string parser errors + * + * Since: 1.0 + */ #define COGL_BLEND_STRING_ERROR (cogl_blend_string_error_quark ()) +/** + * CoglBlendStringError: + * @COGL_BLEND_STRING_ERROR_PARSE_ERROR: Generic parse error + * @COGL_BLEND_STRING_ERROR_ARGUMENT_PARSE_ERROR: Argument parse error + * @COGL_BLEND_STRING_ERROR_INVALID_ERROR: Internal parser error + * @COGL_BLEND_STRING_ERROR_GPU_UNSUPPORTED_ERROR: Blend string not + * supported by the GPU + * + * Error enumeration for the blend strings parser + * + * Since: 1.0 + */ typedef enum { /*< prefix=COGL_BLEND_STRING_ERROR >*/ COGL_BLEND_STRING_ERROR_PARSE_ERROR, COGL_BLEND_STRING_ERROR_ARGUMENT_PARSE_ERROR, diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index c2678dc..7c9fab8 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/doc/reference/cogl/cogl-sections.txt @@ -184,7 +184,6 @@ cogl_is_bitmap
cogl-texture Textures -COGL_TEXTURE_MAX_WASTE CoglTextureVertex CoglTextureFlags cogl_texture_new_with_size @@ -207,6 +206,9 @@ cogl_texture_is_sliced cogl_texture_get_gl_texture cogl_texture_get_data cogl_texture_set_region + + +COGL_TEXTURE_MAX_WASTE
@@ -247,7 +249,7 @@ cogl_offscreen_ref cogl_offscreen_unref cogl_is_offscreen cogl_set_framebuffer -cogl_push_frameffer +cogl_push_framebuffer cogl_pop_framebuffer cogl_set_draw_buffer cogl_pop_draw_buffer @@ -443,7 +445,6 @@ cogl_material_get_shininess CoglMaterialAlphaFunc cogl_material_set_alpha_test_function CoglBlendStringError -COGL_BLEND_STRING_ERROR cogl_material_set_blend cogl_material_set_blend_constant cogl_material_set_layer @@ -465,15 +466,6 @@ cogl_blend_string_error_quark
-cogl-material-internals -Material Internals -cogl_material_get_layers -CoglMaterialLayerType -cogl_material_layer_get_type -cogl_material_layer_get_texture -
- -
cogl-buffer Buffers cogl_is_buffer -- 2.7.4