From 2693ea3ddc4f7a70109a56c425280b6836ca9924 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Fri, 9 Jan 2009 14:26:35 +0000
Subject: [PATCH] [docs] Documentation warnings
Fix the various warnings issued by gtk-doc when enabling the API
reference generation for both COGL and Clutter.
---
clutter/clutter-cairo-texture.h | 14 +++++
clutter/cogl/cogl-types.h | 72 ++++++++++++----------
clutter/cogl/common/cogl-mesh.c | 2 +
doc/reference/clutter/clutter-docs.xml | 2 +-
doc/reference/clutter/clutter-sections.txt | 55 ++++++++---------
5 files changed, 83 insertions(+), 62 deletions(-)
diff --git a/clutter/clutter-cairo-texture.h b/clutter/clutter-cairo-texture.h
index a5cca866c..b7816fef6 100644
--- a/clutter/clutter-cairo-texture.h
+++ b/clutter/clutter-cairo-texture.h
@@ -49,6 +49,13 @@ typedef struct _ClutterCairoTexture ClutterCairoTexture;
typedef struct _ClutterCairoTextureClass ClutterCairoTextureClass;
typedef struct _ClutterCairoTexturePrivate ClutterCairoTexturePrivate;
+/**
+ * ClutterCairoTexture:
+ *
+ * The #ClutterCairoTexture struct contains only private data.
+ *
+ * Since: 1.0
+ */
struct _ClutterCairoTexture
{
/*< private >*/
@@ -57,6 +64,13 @@ struct _ClutterCairoTexture
ClutterCairoTexturePrivate *priv;
};
+/**
+ * ClutterCairoTextureClass:
+ *
+ * The #ClutterCairoTextureClass struct contains only private data.
+ *
+ * Since: 1.0
+ */
struct _ClutterCairoTextureClass
{
/*< private >*/
diff --git a/clutter/cogl/cogl-types.h b/clutter/cogl/cogl-types.h
index 4fb69953a..3ae0d9caa 100644
--- a/clutter/cogl/cogl-types.h
+++ b/clutter/cogl/cogl-types.h
@@ -86,27 +86,29 @@ typedef struct _CoglTextureVertex CoglTextureVertex;
/**
* CoglPixelFormat:
- * @COGL_PIXEL_FORMAT_ANY:
- * @COGL_PIXEL_FORMAT_A_8:
- * @COGL_PIXEL_FORMAT_RGB_888:
- * @COGL_PIXEL_FORMAT_BGR_888:
- * @COGL_PIXEL_FORMAT_RGBA_8888:
- * @COGL_PIXEL_FORMAT_BGRA_8888:
- * @COGL_PIXEL_FORMAT_ARGB_8888:
- * @COGL_PIXEL_FORMAT_ABGR_8888:
- * @COGL_PIXEL_FORMAT_RGBA_8888_PRE:
- * @COGL_PIXEL_FORMAT_BGRA_8888_PRE:
- * @COGL_PIXEL_FORMAT_ARGB_8888_PRE:
- * @COGL_PIXEL_FORMAT_ABGR_8888_PRE:
- * @COGL_PIXEL_FORMAT_RGB_565:
- * @COGL_PIXEL_FORMAT_RGBA_4444:
- * @COGL_PIXEL_FORMAT_RGBA_5551:
- * @COGL_PIXEL_FORMAT_RGBA_4444_PRE:
- * @COGL_PIXEL_FORMAT_RGBA_5551_PRE:
- * @COGL_PIXEL_FORMAT_YUV:
- * @COGL_PIXEL_FORMAT_G_8:
+ * @COGL_PIXEL_FORMAT_ANY: Any format
+ * @COGL_PIXEL_FORMAT_A_8: 8 bits alpha mask
+ * @COGL_PIXEL_FORMAT_RGB_565: RGB, 16 bits
+ * @COGL_PIXEL_FORMAT_RGBA_4444: RGBA, 16 bits
+ * @COGL_PIXEL_FORMAT_RGBA_5551: RGBA, 16 bits
+ * @COGL_PIXEL_FORMAT_YUV: FIXME
+ * @COGL_PIXEL_FORMAT_G_8: FIXME
+ * @COGL_PIXEL_FORMAT_RGB_888: RGB, 24 bits
+ * @COGL_PIXEL_FORMAT_BGR_888: BGR, 24 bits
+ * @COGL_PIXEL_FORMAT_RGBA_8888: RGBA, 32 bits
+ * @COGL_PIXEL_FORMAT_BGRA_8888: BGRA, 32 bits
+ * @COGL_PIXEL_FORMAT_ARGB_8888: ARGB, 32 bits
+ * @COGL_PIXEL_FORMAT_ABGR_8888: ABGR, 32 bits
+ * @COGL_PIXEL_FORMAT_RGBA_8888_PRE: Premultiplied RGBA, 32 bits
+ * @COGL_PIXEL_FORMAT_BGRA_8888_PRE: Premultiplied BGRA, 32 bits
+ * @COGL_PIXEL_FORMAT_ARGB_8888_PRE: Premultiplied ARGB, 32 bits
+ * @COGL_PIXEL_FORMAT_ABGR_8888_PRE: Premultiplied ABGR, 32 bits
+ * @COGL_PIXEL_FORMAT_RGBA_4444_PRE: Premultiplied RGBA, 16 bits
+ * @COGL_PIXEL_FORMAT_RGBA_5551_PRE: Premultiplied RGBA, 16 bits
*
* Pixel formats used by COGL.
+ *
+ * Since: 0.8
*/
typedef enum
{
@@ -173,19 +175,21 @@ typedef enum
/**
* CoglFeatureFlags:
- * @COGL_FEATURE_TEXTURE_RECTANGLE:
- * @COGL_FEATURE_TEXTURE_NPOT:
- * @COGL_FEATURE_TEXTURE_YUV:
- * @COGL_FEATURE_TEXTURE_READ_PIXELS:
- * @COGL_FEATURE_SHADERS_GLSL:
- * @COGL_FEATURE_OFFSCREEN:
- * @COGL_FEATURE_OFFSCREEN_MULTISAMPLE:
- * @COGL_FEATURE_OFFSCREEN_BLIT:
- * @COGL_FEATURE_FOUR_CLIP_PLANES:
- * @COGL_FEATURE_STENCIL_BUFFER:
- * @COGL_FEATURE_VBOS:
+ * @COGL_FEATURE_TEXTURE_RECTANGLE: ARB_texture_rectangle support
+ * @COGL_FEATURE_TEXTURE_NPOT: ARB_texture_non_power_of_two support
+ * @COGL_FEATURE_TEXTURE_YUV: ycbcr conversion support
+ * @COGL_FEATURE_TEXTURE_READ_PIXELS: glReadPixels() support
+ * @COGL_FEATURE_SHADERS_GLSL: GLSL support
+ * @COGL_FEATURE_OFFSCREEN: FBO support
+ * @COGL_FEATURE_OFFSCREEN_MULTISAMPLE: Multisample support on FBOs
+ * @COGL_FEATURE_OFFSCREEN_BLIT: Blit support on FBOs
+ * @COGL_FEATURE_FOUR_CLIP_PLANES: At least 4 clip planes available
+ * @COGL_FEATURE_STENCIL_BUFFER: Stencil buffer support
+ * @COGL_FEATURE_VBOS: VBO support
*
* Flags for the supported features.
+ *
+ * Since: 0.8
*/
typedef enum
{
@@ -204,11 +208,13 @@ typedef enum
/**
* CoglBufferTarget:
- * @COGL_WINDOW_BUFFER:
- * @COGL_MASK_BUFFER:
- * @COGL_OFFSCREEN_BUFFER:
+ * @COGL_WINDOW_BUFFER: FIXME
+ * @COGL_MASK_BUFFER: FIXME
+ * @COGL_OFFSCREEN_BUFFER: FIXME
*
+ * Target flags for FBOs.
*
+ * Since: 0.8
*/
typedef enum
{
diff --git a/clutter/cogl/common/cogl-mesh.c b/clutter/cogl/common/cogl-mesh.c
index 88a0ba473..f7287f953 100644
--- a/clutter/cogl/common/cogl-mesh.c
+++ b/clutter/cogl/common/cogl-mesh.c
@@ -209,6 +209,8 @@ COGL_HANDLE_DEFINE (Mesh, mesh, mesh_handles);
*
* This creates a Cogl handle for a new mesh that you can then start to add
* attributes too.
+ *
+ * Return value: a new #CoglHandle
*/
CoglHandle
cogl_mesh_new (guint n_vertices)
diff --git a/doc/reference/clutter/clutter-docs.xml b/doc/reference/clutter/clutter-docs.xml
index e29317036..baeb0b5bf 100644
--- a/doc/reference/clutter/clutter-docs.xml
+++ b/doc/reference/clutter/clutter-docs.xml
@@ -57,8 +57,8 @@
<xi:include href="xml/clutter-rectangle.xml"/>
<xi:include href="xml/clutter-texture.xml"/>
<xi:include href="xml/clutter-clone-texture.xml"/>
- <xi:include href="xml/clutter-cairo-texture.xml"/>
<xi:include href="xml/clutter-text.xml"/>
+ <xi:include href="xml/clutter-cairo-texture.xml"/>
</chapter>
<chapter>
diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt
index 7c9ed607b..3f0a8429f 100644
--- a/doc/reference/clutter/clutter-sections.txt
+++ b/doc/reference/clutter/clutter-sections.txt
@@ -28,6 +28,7 @@ clutter_media_get_type
<FILE>clutter-units</FILE>
<TITLE>Unit conversion</TITLE>
ClutterUnit
+CLUTTER_UNITS_FORMAT
CLUTTER_UNITS_FROM_DEVICE
CLUTTER_UNITS_TO_DEVICE
CLUTTER_UNITS_FROM_FIXED
@@ -1497,9 +1498,6 @@ clutter_shader_float_get_type
clutter_shader_int_get_type
clutter_shader_matrix_get_type
clutter_shader_error_quark
-clutter_shader_float_get_type
-clutter_shader_int_get_type
-clutter_shader_matrix_get_type
</SECTION>
<SECTION>
@@ -1582,31 +1580,6 @@ ClutterIntervalPrivate
clutter_interval_get_type
</SECTION>
-<SECTION>
-<TITLE>Key Bindings</TITLE>
-<FILE>clutter-binding-pool</FILE>
-ClutterBindingPool
-ClutterBindingActionFunc
-
-<SUBSECTION>
-clutter_binding_pool_new
-clutter_binding_pool_get_for_class
-clutter_binding_pool_find
-
-<SUBSECTION>
-clutter_binding_pool_install_action
-clutter_binding_pool_install_closure
-clutter_binding_pool_override_action
-clutter_binding_pool_override_closure
-clutter_binding_pool_find_action
-clutter_binding_pool_remove_action
-clutter_binding_pool_block_action
-clutter_binding_pool_unblock_action
-
-<SUBSECTION>
-clutter_binding_pool_activate
-</SECTION>
-
<SECTION>
<FILE>clutter-cairo-texture</FILE>
<TITLE>ClutterCairoTexture</TITLE>
@@ -1634,6 +1607,7 @@ CLUTTER_CAIRO_TEXTURE_GET_CLASS
<SUBSECTION Private>
ClutterCairoTexturePrivate
clutter_cairo_texture_get_type
+</SECTION>
<SECTION>
<TITLE>ClutterText</TITLE>
@@ -1713,3 +1687,28 @@ CLUTTER_TYPE_TEXT
ClutterTextPrivate
clutter_text_get_type
</SECTION>
+
+<SECTION>
+<TITLE>Key Bindings</TITLE>
+<FILE>clutter-binding-pool</FILE>
+ClutterBindingPool
+ClutterBindingActionFunc
+
+<SUBSECTION>
+clutter_binding_pool_new
+clutter_binding_pool_get_for_class
+clutter_binding_pool_find
+
+<SUBSECTION>
+clutter_binding_pool_install_action
+clutter_binding_pool_install_closure
+clutter_binding_pool_override_action
+clutter_binding_pool_override_closure
+clutter_binding_pool_find_action
+clutter_binding_pool_remove_action
+clutter_binding_pool_block_action
+clutter_binding_pool_unblock_action
+
+<SUBSECTION>
+clutter_binding_pool_activate
+</SECTION>