[docs] Documentation warnings

Fix the various warnings issued by gtk-doc when enabling the API reference generation for both COGL and Clutter.
2024-11-23 00:20:42 -05:00 · 2009-01-09 14:26:35 +00:00 · 2009-01-09 14:26:35 +00:00 · 2693ea3ddc
commit 2693ea3ddc
parent 00a3c69868
5 changed files with 83 additions and 62 deletions
--- 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 >*/
--- 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
 {
--- 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)
--- 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>
--- 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>