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.

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' \

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()

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

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

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
  *

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

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)

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.

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;

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.

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'

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

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>

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

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
  *

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

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