[doc] Miscellaneous documentation fixes

Remove private symbols, and add missing public ones.
2024-11-29 19:40:43 -05:00 · 2009-07-20 12:49:35 +01:00 · 2009-07-20 12:49:35 +01:00 · d1b8cab65d
commit d1b8cab65d
parent 1da8ce3429
5 changed files with 83 additions and 72 deletions
--- a/cogl-material.h
+++ b/cogl-material.h
@ -304,7 +304,7 @@ void cogl_material_get_specular (CoglHandle  material, CoglColor  *specular);
 /**
 * cogl_material_set_shininess:
 * @material: A CoglMaterial object
- * shininess: The desired shininess; range: [0.0, 1.0]
+ * @shininess: The desired shininess; range: [0.0, 1.0]
 *
 * This function sets the materials shininess which determines how
 * specular highlights are calculated. A higher shininess will produce
@ -441,7 +441,7 @@ void cogl_material_set_alpha_test_function (CoglHandle            material,
 * &lt;channel-mask&gt;=ADD(SRC_COLOR*(&lt;factor&gt;), DST_COLOR*(&lt;factor&gt;))
 * </programlisting>
 *
- * <b>NOTE: The brackets around blend factors are currently not optional!</b>
+ * <warning>The brackets around blend factors are currently not optional!</warning>
 *
 * This is the list of source-names usable as blend factors:
 * <itemizedlist>
@ -548,7 +548,7 @@ void cogl_material_remove_layer (CoglHandle material,
 * @layer_index: Specifies the layer you want define a combine function for
 * @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
 *                describing the desired texture combine function.
- * @error: A GError that may report parse errors or lack of GPU/driver support.
+ * @error: A #GError that may report parse errors or lack of GPU/driver support.
 *         May be %NULL, in which case a warning will be printed out if an
 *         error is encountered.
 *
@ -606,25 +606,26 @@ void cogl_material_remove_layer (CoglHandle material,
 * cogl_material_set_color()
 * </listitem>
 * </itemizedlist>
- * <section>
+ * <refsect2>
 * <title>Example</title>
 * This is effectively what the default blending is:
- * <programlisting>
- * "RGBA = MODULATE (PREVIOUS, TEXTURE)"
- * </programlisting>
+ * |[
+ *   RGBA = MODULATE (PREVIOUS, TEXTURE)
+ * ]|
 * This could be used to cross-fade between two images, using the alpha
 * component of a constant as the interpolator. The constant color
 * is given by calling cogl_material_set_layer_constant.
- * <programlisting>
+ * |[
 *   RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
- * </programlisting>
- * </section>
- * <b>Note: you can't give a multiplication factor for arguments as you can
- * with blending.</b>
+ * ]|
+ * </refsect2>
 *
- * Returns: TRUE if the blend string was successfully parsed, and the described
- *          texture combining is supported by the underlying driver/hardware.
- *          If there was an error, it returns FALSE.
+ * <note>You can't give a multiplication factor for arguments as you can
+ * with blending.</note>
+ *
+ * Returns: %TRUE if the blend string was successfully parsed, and the
+ *   described texture combining is supported by the underlying driver and
+ *   or hardware. If there was an error, it returns FALSE.
 *
 * Since: 1.0
 */
@ -653,6 +654,8 @@ void cogl_material_set_layer_combine_constant (CoglHandle  material,
 /**
 * cogl_material_set_layer_matrix:
 * @material: A CoglMaterial object
+ * @layer_index: the index for the layer inside @material
+ * @matrix: the transformation matrix for the layer
 *
 * This function lets you set a matrix that can be used to e.g. translate
 * and rotate a single layer of a material used to fill your geometry.
@ -663,21 +666,24 @@ void cogl_material_set_layer_matrix (CoglHandle  material,

 /**
 * cogl_material_get_layers:
- * @material: A CoglMaterial object
+ * @material: a #CoglHandle for a material
 *
 * This function lets you access a materials internal list of layers
 * for iteration.
 *
 * Returns: A list of #CoglHandle<!-- -->'s that can be passed to the
- *          cogl_material_layer_* functions.
+ *   cogl_material_layer_* functions. The list is owned by COGL and it
+ *   should not be modified or freed
 */
-const GList *cogl_material_get_layers (CoglHandle material);
+G_CONST_RETURN GList *cogl_material_get_layers (CoglHandle material);

 /**
 * cogl_material_get_n_layers:
- * @material: A CoglMaterial object
+ * @material: a #CoglHandle for a material
 *
- * Returns: The number of layers defined for the given material
+ * Retrieves the number of layers defined for the given @material
+ *
+ * Returns: the number of layers
 *
 * Since: 1.0
 */
@ -693,14 +699,13 @@ int cogl_material_get_n_layers (CoglHandle material);
 *
 * Since: 1.0
 */
-typedef enum _CoglMaterialLayerType
-{
+typedef enum { /*< prefix=COGL_MATERIAL_LAYER_TYPE >*/
  COGL_MATERIAL_LAYER_TYPE_TEXTURE
 } CoglMaterialLayerType;

 /**
 * cogl_material_layer_get_type:
- * @layer_handle: A Cogl material layer handle
+ * @layer_handle: A #CoglHandle for a material layer
 *
 * Retrieves the type of the layer
 *
@ -709,26 +714,28 @@ typedef enum _CoglMaterialLayerType
 * based layers in the future, you should write code that checks the type
 * first.
 *
- * Return value: the type of the layer
+ * Returns: the type of the layer
 */
 CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);

 /**
 * cogl_material_layer_get_texture:
- * @layer_handle: A CoglMaterialLayer handle
+ * @layer_handle: A #CoglHandle for a material layer
 *
 * This lets you extract a CoglTexture handle for a specific layer.
 *
- * Note: In the future, we may support purely GLSL based layers which will
- *       likely return COGL_INVALID_HANDLE if you try to get the texture.
+ * <note>In the future, we may support purely GLSL based layers which will
+ * likely return %COGL_INVALID_HANDLE if you try to get the texture.
 * Considering this, you can call cogl_material_layer_get_type first,
- *       to check it is of type COGL_MATERIAL_LAYER_TYPE_TEXTURE.
+ * to check it is of type %COGL_MATERIAL_LAYER_TYPE_TEXTURE.</note>
+ *
+ * Returns: a #CoglHandle for the texture inside @layer_handle
 */
 CoglHandle cogl_material_layer_get_texture (CoglHandle layer_handle);

 /**
 * cogl_material_layer_get_min_filter:
- * @layer_handle: a #CoglHandle for a material layer.
+ * @layer_handle: a #CoglHandle for a material layer
 *
 * Query the currently set downscaling filter for a cogl material layer.
 *
@ -738,7 +745,7 @@ CoglMaterialFilter cogl_material_layer_get_min_filter (CoglHandle layer_handle);

 /**
 * cogl_material_layer_get_mag_filter:
- * @layer_handle: a #CoglHandle for a material layer.
+ * @layer_handle: a #CoglHandle for a material layer
 *
 * Query the currently set downscaling filter for a cogl material layer.
 *
--- a/cogl-types.h
+++ b/cogl-types.h
@ -51,7 +51,23 @@ typedef gpointer CoglHandle;
 #define COGL_TYPE_HANDLE        (cogl_handle_get_type ())
 GType cogl_handle_get_type (void) G_GNUC_CONST;

+/**
+ * cogl_handle_ref:
+ * @handle: a #CoglHandle
+ *
+ * Increases the reference count of @handle by 1
+ *
+ * Returns: the handle, with its reference count increased
+ */
 CoglHandle cogl_handle_ref   (CoglHandle handle);
+
+/**
+ * cogl_handle_unref:
+ * @handle: a #CoglHandle
+ *
+ * Drecreases the reference count of @handle by 1; if the reference
+ * count reaches 0, the resources allocated by @handle will be freed
+ */
 void       cogl_handle_unref (CoglHandle Handle);

 /**
--- a/cogl.h.in
+++ b/cogl.h.in
@ -346,11 +346,11 @@ void            cogl_get_viewport             (float        v[4]);
 void            cogl_set_depth_test_enabled   (gboolean setting);

 /**
- * cogl_get_depth_test_enable:
+ * cogl_get_depth_test_enabled:
 *
 * Queries if depth testing has been enabled via cogl_set_depth_test_enable()
 *
- * Returns: TRUE if depth testing is enabled else FALSE
+ * Returns: %TRUE if depth testing is enabled, and %FALSE otherwise
 */
 gboolean        cogl_get_depth_test_enabled   (void);

@ -372,7 +372,7 @@ void            cogl_set_backface_culling_enabled (gboolean setting);
 * Queries if backface culling has been enabled via
 * cogl_set_backface_culling_enabled()
 *
- * Returns: TRUE if backface culling is enabled else FALSE
+ * Returns: %TRUE if backface culling is enabled, and %FALSE otherwise
 */
 gboolean        cogl_get_backface_culling_enabled (void);

@ -393,15 +393,13 @@ gboolean        cogl_get_backface_culling_enabled (void);
 * vertices at @z_far are drawn fully with @fog_color. Fogging will remain
 * enabled until you call cogl_disable_fog().
 *
- * Note: The fogging functions only work correctly when primitives use
+ * <note>The fogging functions only work correctly when primitives use
 * unmultiplied alpha colors. By default Cogl will premultiply textures
- *       and cogl_set_source_color will premultiply colors, so unless you
- *       explicitly load your textures requesting an unmultiplied
- *       internal_format and use cogl_material_set_color you can only use
- *       fogging with fully opaque primitives.
- *
- *       We can look to improve this in the future when we can depend on
- *       fragment shaders.
+ * and cogl_set_source_color() will premultiply colors, so unless you
+ * explicitly load your textures requesting an unmultiplied internal format
+ * and use cogl_material_set_color() you can only use fogging with fully
+ * opaque primitives. This might improve in the future when we can depend
+ * on fragment shaders.</note>
 */
 void            cogl_set_fog                  (const CoglColor *fog_color,
                                               CoglFogMode      mode,
@ -694,9 +692,12 @@ void            cogl_pop_draw_buffer          (void);
 /**
 * CoglReadPixelsFlags:
 * @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer
+ *
+ * Flags for cogl_read_pixels()
+ *
+ * Since: 1.0
 */
-typedef enum _CoglReadPixelsFlags
-{
+typedef enum { /*< prefix=COGL_READ_PIXELS >*/
  COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
 } CoglReadPixelsFlags;

--- a/doc/reference/cogl/Makefile.am
+++ b/doc/reference/cogl/Makefile.am
@ -56,6 +56,13 @@ CFILE_GLOB=\
 IGNORE_HFILES=\
 	cogl-defines-gl.h \
        cogl-defines-gles.h \
+	cogl-internal.h \
+	cogl-material-private.h \
+	cogl-current-matrix.h \
+	cogl-bitmap-private.h \
+	cogl-blend-string.h \
+	cogl-vertex-buffer-private.h \
+	cogl-util.h \
 	cogl-handle.h \
 	gl \
 	gles
--- a/doc/reference/cogl/cogl-sections.txt
+++ b/doc/reference/cogl/cogl-sections.txt
@ -28,7 +28,6 @@ cogl_features_available
 cogl_check_extension
 cogl_get_proc_address
 cogl_get_option_group
-cogl_gl_error_to_string

 <SUBSECTION>
 cogl_push_matrix
@ -90,14 +89,12 @@ COGL_TYPE_INDICES_TYPE
 COGL_TYPE_MATERIAL_ALPHA_FUNC
 COGL_TYPE_MATERIAL_FILTER
 COGL_TYPE_MATERIAL_LAYER_TYPE
-COGL_TYPE_MATRIX_MODE
 COGL_TYPE_PIXEL_FORMAT
 COGL_TYPE_SHADER_TYPE
 COGL_TYPE_TEXTURE_FLAGS
 COGL_TYPE_VERTICES_MODE

 <SUBSECTION Private>
-cogl_util_next_p2
 cogl_attribute_type_get_type
 cogl_buffer_bit_get_type
 cogl_buffer_target_get_type
@ -110,12 +107,10 @@ cogl_indices_type_get_type
 cogl_material_alpha_func_get_type
 cogl_material_filter_get_type
 cogl_material_layer_type_get_type
-cogl_matrix_mode_get_type
 cogl_pixel_format_get_type
 cogl_shader_type_get_type
 cogl_texture_flags_get_type
 cogl_vertices_mode_get_type
-GE
 COGL_NOTE
 CoglDebugFlags
 cogl_debug_flags
@ -380,18 +375,12 @@ CoglIndicesType
 cogl_vertex_buffer_indices_new
 cogl_vertex_buffer_draw_elements
 cogl_vertex_buffer_indices_get_for_quads
-<SUBSECTION Private>
-CoglVertexBufferAttribFlags
-COGL_VERTEX_BUFFER_ATTRIB_FLAG_GL_TYPE_MASK
-COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
 </SECTION>

 <SECTION>
 <FILE>cogl-matrix</FILE>
 <TITLE>Matrices</TITLE>
 CoglMatrix
-CoglMatrixMode
-CoglMatrixStack
 cogl_matrix_init_identity
 cogl_matrix_frustum
 cogl_matrix_ortho
@ -429,11 +418,7 @@ cogl_material_set_shininess
 cogl_material_get_shininess
 CoglMaterialAlphaFunc
 cogl_material_set_alpha_test_function
-CoglBlendStringChannelMask
-CoglBlendStringColorSourceType
-CoglBlendStringContext
 CoglBlendStringError
-CoglBlendStringFunctionType
 COGL_BLEND_STRING_ERROR
 cogl_material_set_blend
 cogl_material_set_blend_constant
@ -443,23 +428,18 @@ cogl_material_set_layer_combine
 cogl_material_set_layer_combine_constant
 cogl_material_set_layer_matrix
 cogl_material_get_layers
+cogl_material_get_n_layers
 CoglMaterialFilter
 cogl_material_set_layer_filters
 cogl_material_layer_get_type
 cogl_material_layer_get_texture
 cogl_material_layer_get_min_filter
 cogl_material_layer_get_mag_filter
-<SUBSECTION Private>
-CoglMaterial
-CoglMaterialFlags
-CoglMaterialLayerFlags
-CoglMaterialLayerPrivFlags
 </SECTION>

 <SECTION>
 <FILE>cogl-material-internals</FILE>
 <TITLE>Material Internals</TITLE>
-CoglMaterialLayer
 cogl_material_get_layers
 CoglMaterialLayerType
 cogl_material_layer_get_type