[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

@@ -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 >*/

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
 {

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)

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>

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>