[doc] Miscellaneous documentation fixes

Remove private symbols, and add missing public ones.

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,
  * <channel-mask>=ADD(SRC_COLOR*(<factor>), DST_COLOR*(<factor>))
  * </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)"
+ *   RGBA = MODULATE (PREVIOUS, TEXTURE)
- * </programlisting>
+ * ]|
  * 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>
+ * </refsect2>
- * <b>Note: you can't give a multiplication factor for arguments as you can
- * with blending.</b>
  *
- * Returns: TRUE if the blend string was successfully parsed, and the described
+ * <note>You can't give a multiplication factor for arguments as you can
- *          texture combining is supported by the underlying driver/hardware.
+ * with blending.</note>
- *          If there was an error, it returns FALSE.
+ *
+ * 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
+ * <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.
+ * 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.
  *

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);
 
 /**

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
+ * and cogl_set_source_color() will premultiply colors, so unless you
- *       explicitly load your textures requesting an unmultiplied
+ * explicitly load your textures requesting an unmultiplied internal format
- *       internal_format and use cogl_material_set_color you can only use
+ * and use cogl_material_set_color() you can only use fogging with fully
- *       fogging with fully opaque primitives.
+ * opaque primitives. This might improve in the future when we can depend
- *
+ * on fragment shaders.</note>
- *       We can look to improve this in the future when we can depend on
- *       fragment shaders.
  */
 void            cogl_set_fog                  (const CoglColor *fog_color,
                                                CoglFogMode      mode,
@@ -694,10 +692,13 @@ 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
-  COGL_READ_PIXELS_COLOR_BUFFER = 1L<<0
 } CoglReadPixelsFlags;
 
 /**

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

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