From 918794a256f7588e73969ea86948d61a5747e004 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.
---
 cogl-types.h       | 72 +++++++++++++++++++++++++---------------------
 common/cogl-mesh.c |  2 ++
 2 files changed, 41 insertions(+), 33 deletions(-)

diff --git a/cogl-types.h b/cogl-types.h
index 4fb69953a..3ae0d9caa 100644
--- a/cogl-types.h
+++ b/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/common/cogl-mesh.c b/common/cogl-mesh.c
index 88a0ba473..f7287f953 100644
--- a/common/cogl-mesh.c
+++ b/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)