docs: Annotation fixes

The introspection scanner has become slightly more annoying, in the hope that people start fixing their annotations. As it turns out, it was the right move.
2012-04-30 17:12:12 +01:00 · 2012-04-30 17:12:12 +01:00 · 0dd74ca3fb
commit 0dd74ca3fb
parent 64f897c7f0
17 changed files with 53 additions and 43 deletions
--- a/clutter/Makefile.am
+++ b/clutter/Makefile.am
@ -967,6 +967,7 @@ Cally_@CLUTTER_API_VERSION_AM@_gir_LIBS = libclutter-@CLUTTER_API_VERSION@.la
 Cally_@CLUTTER_API_VERSION_AM@_gir_FILES = $(cally_sources_h) $(cally_sources_c)
 Cally_@CLUTTER_API_VERSION_AM@_gir_CFLAGS = $(INCLUDES) $(CLUTTER_CFLAGS) $(AM_CPPFLAGS)
 Cally_@CLUTTER_API_VERSION_AM@_gir_SCANNERFLAGS = \
+	--warn-all \
 	--identifier-prefix=Cally \
 	--symbol-prefix=cally \
 	--c-include='cally/cally.h' \
@ -979,6 +980,7 @@ if SUPPORT_X11
 ClutterX11-@CLUTTER_API_VERSION@.gir: Makefile Clutter-@CLUTTER_API_VERSION@.gir

 ClutterX11_@CLUTTER_API_VERSION_AM@_gir_SCANNERFLAGS = \
+	--warn-all \
 	--identifier-prefix=ClutterX11 \
 	--symbol-prefix=clutter_x11 \
 	--c-include='clutter/x11/clutter-x11.h' \
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@ -6863,7 +6863,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
                  CLUTTER_TYPE_ACTOR);

  /**
-   * ClutterActor::queue-relayout
+   * ClutterActor::queue-relayout:
   * @actor: the actor being queued for relayout
   *
   * The ::queue_layout signal is emitted when clutter_actor_queue_relayout()
--- a/clutter/clutter-actor.h
+++ b/clutter/clutter-actor.h
@ -85,7 +85,7 @@ typedef void (*ClutterCallback) (ClutterActor *actor,
                                 gpointer      data);

 /**
- * CLUTTER_CALLBACK
+ * CLUTTER_CALLBACK:
 * @f: a function
 *
 * Convenience macro to cast a function to #ClutterCallback
--- a/clutter/clutter-drag-action.c
+++ b/clutter/clutter-drag-action.c
@ -707,7 +707,7 @@ clutter_drag_action_class_init (ClutterDragActionClass *klass)
                  CLUTTER_TYPE_MODIFIER_TYPE);

  /**
-   * ClutterDragAction::drag-motion
+   * ClutterDragAction::drag-motion:
   * @action: the #ClutterDragAction that emitted the signal
   * @actor: the #ClutterActor attached to the action
   * @delta_x: the X component of the distance between the press event
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@ -552,7 +552,7 @@ clutter_event_get_related (const ClutterEvent *event)
 }

 /**
- * clutter_event_set_related
+ * clutter_event_set_related:
 * @event: a #ClutterEvent of type %CLUTTER_ENTER or %CLUTTER_LEAVE
 * @actor: (allow-none): a #ClutterActor or %NULL
 *
--- a/clutter/clutter-layout-meta.h
+++ b/clutter/clutter-layout-meta.h
@ -47,7 +47,7 @@ G_BEGIN_DECLS
 typedef struct _ClutterLayoutMetaClass          ClutterLayoutMetaClass;

 /**
- * ClutterLayoutMeta
+ * ClutterLayoutMeta:
 * @manager: the layout manager handling this data
 *
 * Sub-class of #ClutterChildMeta specific for layout managers
--- a/clutter/clutter-macros.h
+++ b/clutter/clutter-macros.h
@ -44,7 +44,7 @@
 #define CLUTTER_FLAVOUR         "deprecated"

 /**
- * CLUTTER_COGL
+ * CLUTTER_COGL:
 *
 * Cogl (internal GL abstraction utility library) backend. Can be "gl" or
 * "gles" currently
@ -75,7 +75,7 @@
 *
 * Set to 1 if Clutter was built without FPU (i.e fixed math), 0 otherwise
 *
- * @Deprecated: 0.6: This macro is no longer defined (identical code is used
+ * Deprecated: 0.6: This macro is no longer defined (identical code is used
 *  regardless the presence of FPU).
 */
 #define CLUTTER_NO_FPU          (0)
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@ -2354,7 +2354,7 @@ is_off_stage (ClutterActor *stage,
 }

 /**
- * clutter_do_event
+ * clutter_do_event:
 * @event: a #ClutterEvent.
 *
 * Processes an event.
--- a/clutter/clutter-paint-nodes.c
+++ b/clutter/clutter-paint-nodes.c
@ -339,6 +339,14 @@ struct _ClutterPipelineNode
  CoglPipeline *pipeline;
 };

+/**
+ * ClutterPipelineNodeClass:
+ *
+ * The <structname>ClutterPipelineNodeClass</structname> structure is an opaque
+ * type whose members cannot be directly accessed.
+ *
+ * Since: 1.10
+ */
 struct _ClutterPipelineNodeClass
 {
  ClutterPaintNodeClass parent_class;
@ -520,21 +528,13 @@ clutter_pipeline_node_new (CoglPipeline *pipeline)
 * Color node
 */

-/**
- * ClutterColorNode:
- *
- * The <structname>ClutterColorNode</structname> structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 struct _ClutterColorNode
 {
  ClutterPipelineNode parent_instance;
 };

 /**
- * ClutterColorNode:
+ * ClutterColorNodeClass:
 *
 * The <structname>ClutterColorNodeClass</structname> structure is an
 * opaque type whose members cannot be directly accessed.
@ -603,21 +603,13 @@ clutter_color_node_new (const ClutterColor *color)
 * Texture node
 */

-/**
- * ClutterTextureNode:
- *
- * The <structname>ClutterTextureNode</structname> structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 struct _ClutterTextureNode
 {
  ClutterPipelineNode parent_instance;
 };

 /**
- * ClutterTextureNode:
+ * ClutterTextureNodeClass:
 *
 * The <structname>ClutterTextureNodeClass</structname> structure is an
 * opaque type whose members cannot be directly accessed.
@ -723,6 +715,14 @@ struct _ClutterTextNode
  CoglColor color;
 };

+/**
+ * ClutterTextNodeClass:
+ *
+ * The <structname>ClutterTextNodeClass</structure> structure is an opaque
+ * type whose contents cannot be directly accessed.
+ *
+ * Since: 1.10
+ */
 struct _ClutterTextNodeClass
 {
  ClutterPaintNodeClass parent_class;
@ -915,6 +915,14 @@ struct _ClutterClipNode
  ClutterPaintNode parent_instance;
 };

+/**
+ * ClutterClipNodeClass:
+ *
+ * The <structname>ClutterClipNodeClass</structname> structure is an opaque
+ * type whose members cannot be directly accessed.
+ *
+ * Since: 1.10
+ */
 struct _ClutterClipNodeClass
 {
  ClutterPaintNodeClass parent_class;
--- a/clutter/clutter-stage.c
+++ b/clutter/clutter-stage.c
@ -2088,7 +2088,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
  g_object_class_install_property (gobject_class, PROP_ACCEPT_FOCUS, pspec);

  /**
-   * ClutterStage::fullscreen
+   * ClutterStage::fullscreen:
   * @stage: the stage which was fullscreened
   *
   * The ::fullscreen signal is emitted when the stage is made fullscreen.
@ -2104,7 +2104,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
 		  _clutter_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
  /**
-   * ClutterStage::unfullscreen
+   * ClutterStage::unfullscreen:
   * @stage: the stage which has left a fullscreen state.
   *
   * The ::unfullscreen signal is emitted when the stage leaves a fullscreen
@ -2121,7 +2121,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
 		  _clutter_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
  /**
-   * ClutterStage::activate
+   * ClutterStage::activate:
   * @stage: the stage which was activated
   *
   * The ::activate signal is emitted when the stage receives key focus
@ -2138,7 +2138,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
 		  _clutter_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
  /**
-   * ClutterStage::deactivate
+   * ClutterStage::deactivate:
   * @stage: the stage which was deactivated
   *
   * The ::activate signal is emitted when the stage loses key focus
@ -2960,7 +2960,7 @@ clutter_stage_event (ClutterStage *stage,
 }

 /**
- * clutter_stage_set_title
+ * clutter_stage_set_title:
 * @stage: A #ClutterStage
 * @title: A utf8 string for the stage windows title.
 *
@ -2990,7 +2990,7 @@ clutter_stage_set_title (ClutterStage       *stage,
 }

 /**
- * clutter_stage_get_title
+ * clutter_stage_get_title:
 * @stage: A #ClutterStage
 *
 * Gets the stage title.
--- a/clutter/clutter-text.c
+++ b/clutter/clutter-text.c
@ -3509,7 +3509,7 @@ clutter_text_class_init (ClutterTextClass *klass)
 		  CLUTTER_TYPE_GEOMETRY | G_SIGNAL_TYPE_STATIC_SCOPE);

  /**
-   * ClutterText::activate
+   * ClutterText::activate:
   * @self: the #ClutterText that emitted the signal
   *
   * The ::activate signal is emitted each time the actor is 'activated'
--- a/clutter/clutter-texture.c
+++ b/clutter/clutter-texture.c
@ -1436,7 +1436,7 @@ clutter_texture_get_cogl_texture (ClutterTexture *texture)
 }

 /**
- * clutter_texture_set_cogl_texture
+ * clutter_texture_set_cogl_texture:
 * @texture: A #ClutterTexture
 * @cogl_tex: A CoglHandle for a texture
 *
@ -2134,7 +2134,7 @@ clutter_texture_set_filter_quality (ClutterTexture        *texture,
 }

 /**
- * clutter_texture_get_filter_quality
+ * clutter_texture_get_filter_quality:
 * @texture: A #ClutterTexture
 *
 * Gets the filter quality used when scaling a texture.
@ -2175,7 +2175,7 @@ clutter_texture_get_filter_quality (ClutterTexture *texture)
 }

 /**
- * clutter_texture_get_max_tile_waste
+ * clutter_texture_get_max_tile_waste:
 * @texture: A #ClutterTexture
 *
 * Gets the maximum waste that will be used when creating a texture or
--- a/clutter/clutter-timeline.c
+++ b/clutter/clutter-timeline.c
@ -1322,7 +1322,7 @@ clutter_timeline_is_playing (ClutterTimeline *timeline)
 * Create a new #ClutterTimeline instance which has property values
 * matching that of supplied timeline. The cloned timeline will not
 * be started and will not be positioned to the current position of
- * @timeline: you will have to start it with clutter_timeline_start().
+ * the original @timeline: you will have to start it with clutter_timeline_start().
 *
 * <note><para>The only cloned properties are:</para>
 * <itemizedlist>
--- a/clutter/clutter-version.h.in
+++ b/clutter/clutter-version.h.in
@ -27,6 +27,9 @@
 #error "Only <clutter/clutter.h> can be included directly."
 #endif

+#ifndef __CLUTTER_VERSION_H__
+#define __CLUTTER_VERSION_H__
+
 /**
 * SECTION:clutter-version
 * @short_description: Versioning utility macros
@ -70,9 +73,6 @@
 * header.
 */

-#ifndef __CLUTTER_VERSION_H__
-#define __CLUTTER_VERSION_H__
-
 #include <glib.h>

 G_BEGIN_DECLS
--- a/clutter/deprecated/clutter-behaviour-path.h
+++ b/clutter/deprecated/clutter-behaviour-path.h
@ -80,7 +80,7 @@ struct _ClutterBehaviourPath
 };

 /**
- * ClutterBehaviourPathClass
+ * ClutterBehaviourPathClass:
 * @knot_reached: signal class handler for the
 *   ClutterBehaviourPath::knot_reached signal
 *
--- a/clutter/deprecated/clutter-behaviour.h
+++ b/clutter/deprecated/clutter-behaviour.h
@ -94,7 +94,7 @@ struct _ClutterBehaviour
 };

 /**
- * ClutterBehaviourClass
+ * ClutterBehaviourClass:
 * @alpha_notify: virtual function, called each time the #ClutterAlpha
 *   computes a new alpha value; the actors to which the behaviour applies
 *   should be changed in this function. Every subclass of #ClutterBehaviour
--- a/clutter/x11/clutter-x11-texture-pixmap.c
+++ b/clutter/x11/clutter-x11-texture-pixmap.c
@ -669,7 +669,7 @@ clutter_x11_texture_pixmap_class_init (ClutterX11TexturePixmapClass *klass)
                    G_TYPE_INT);

  /**
-   * ClutterX11TexturePixmap::queue-damage-redraw
+   * ClutterX11TexturePixmap::queue-damage-redraw:
   * @texture: the object which received the signal
   * @x: The top left x position of the damage region
   * @y: The top left y position of the damage region