[mutter/bilelmoussaoui/clutter-docs: 1/3] clutter: Migrate to gi-docgen




commit c8e63866f058d7e6db706ded70837e539619df8f
Author: Bilal Elmoussaoui <belmouss redhat com>
Date:   Wed May 25 18:41:48 2022 +0200

    clutter: Migrate to gi-docgen
    
    - Drop all the private structs documentations
    - Make use of gi-docgen items linking as much as possible
    - Use markdown formatting for code snippets
    
    Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2441>

 clutter/clutter/clutter-action.c                   |  15 +-
 clutter/clutter/clutter-actor-box.c                |  22 +--
 clutter/clutter/clutter-actor-meta.c               |  19 +-
 clutter/clutter/clutter-actor.c                    | 216 +++++++++++----------
 clutter/clutter/clutter-actor.h                    |   7 +-
 clutter/clutter/clutter-align-constraint.c         |  14 +-
 clutter/clutter/clutter-align-constraint.h         |   8 -
 clutter/clutter/clutter-animatable.c               |  15 +-
 clutter/clutter/clutter-backend.c                  |  13 +-
 clutter/clutter/clutter-backend.h                  |   8 -
 clutter/clutter/clutter-bin-layout.c               |   7 +-
 clutter/clutter/clutter-bin-layout.h               |   8 -
 clutter/clutter/clutter-bind-constraint.c          |  22 +--
 clutter/clutter/clutter-bind-constraint.h          |   8 -
 clutter/clutter/clutter-binding-pool.c             |  35 ++--
 clutter/clutter/clutter-binding-pool.h             |   8 -
 clutter/clutter/clutter-blur-effect.c              |   8 +-
 clutter/clutter/clutter-blur-effect.h              |   8 -
 clutter/clutter/clutter-box-layout.c               |   7 +-
 clutter/clutter/clutter-box-layout.h               |   8 -
 .../clutter/clutter-brightness-contrast-effect.c   |   8 +-
 .../clutter/clutter-brightness-contrast-effect.h   |   8 -
 clutter/clutter/clutter-cairo.c                    |   4 +-
 clutter/clutter/clutter-canvas.c                   |  13 +-
 clutter/clutter/clutter-canvas.h                   |   9 -
 clutter/clutter/clutter-child-meta.c               |  41 +++-
 clutter/clutter/clutter-child-meta.h               |  40 ----
 clutter/clutter/clutter-click-action.c             |  77 ++++----
 clutter/clutter/clutter-clone.c                    |   7 +-
 clutter/clutter/clutter-clone.h                    |   8 -
 clutter/clutter/clutter-color.c                    |  24 +--
 clutter/clutter/clutter-color.h                    |   9 +-
 clutter/clutter/clutter-colorize-effect.c          |   8 +-
 clutter/clutter/clutter-colorize-effect.h          |   8 -
 clutter/clutter/clutter-constraint.c               |  11 +-
 clutter/clutter/clutter-constraint.h               |   8 -
 clutter/clutter/clutter-container.c                |  32 ++-
 clutter/clutter/clutter-container.h                |   9 -
 clutter/clutter/clutter-content.c                  |  10 +-
 clutter/clutter/clutter-deform-effect.c            |  13 +-
 clutter/clutter/clutter-deform-effect.h            |   8 -
 clutter/clutter/clutter-desaturate-effect.c        |   8 +-
 clutter/clutter/clutter-desaturate-effect.h        |   8 -
 clutter/clutter/clutter-effect.c                   |  15 +-
 clutter/clutter/clutter-effect.h                   |   8 -
 clutter/clutter/clutter-enums.h                    |  37 ++--
 clutter/clutter/clutter-event.c                    |  10 -
 clutter/clutter/clutter-event.h                    |  20 +-
 clutter/clutter/clutter-fixed-layout.c             |   7 +-
 clutter/clutter/clutter-fixed-layout.h             |   8 -
 clutter/clutter/clutter-flow-layout.c              |   7 +-
 clutter/clutter/clutter-flow-layout.h              |   8 -
 clutter/clutter/clutter-gesture-action.c           |  66 +++----
 clutter/clutter/clutter-grid-layout.c              |   7 +-
 clutter/clutter/clutter-grid-layout.h              |   8 -
 clutter/clutter/clutter-image.c                    |  14 +-
 clutter/clutter/clutter-input-device.c             |   5 +-
 clutter/clutter/clutter-input-device.h             |   6 -
 clutter/clutter/clutter-interval.c                 |  19 +-
 clutter/clutter/clutter-interval.h                 |   8 -
 clutter/clutter/clutter-keyframe-transition.c      |  12 +-
 clutter/clutter/clutter-keyframe-transition.h      |   8 -
 clutter/clutter/clutter-layout-manager.c           |  30 +--
 clutter/clutter/clutter-layout-manager.h           |   8 -
 clutter/clutter/clutter-layout-meta.c              |  15 +-
 clutter/clutter/clutter-layout-meta.h              |  12 --
 clutter/clutter/clutter-main.c                     |  10 +-
 clutter/clutter/clutter-offscreen-effect.c         |  43 ++--
 clutter/clutter/clutter-offscreen-effect.h         |   8 -
 clutter/clutter/clutter-page-turn-effect.c         |  14 +-
 clutter/clutter/clutter-page-turn-effect.h         |   8 -
 clutter/clutter/clutter-paint-node.c               |  17 +-
 clutter/clutter/clutter-paint-nodes.c              |  61 +++---
 clutter/clutter/clutter-paint-nodes.h              |  80 --------
 clutter/clutter/clutter-paint-volume.c             |  20 +-
 clutter/clutter/clutter-pan-action.c               |  34 ++--
 clutter/clutter/clutter-pan-action.h               |   8 -
 clutter/clutter/clutter-path-constraint.c          |  18 +-
 clutter/clutter/clutter-path-constraint.h          |   8 -
 clutter/clutter/clutter-path.c                     |  41 ++--
 clutter/clutter/clutter-path.h                     |  10 +-
 clutter/clutter/clutter-pick-context.c             |   8 +-
 clutter/clutter/clutter-property-transition.c      |  18 +-
 clutter/clutter/clutter-property-transition.h      |   8 -
 clutter/clutter/clutter-rotate-action.c            |  10 +-
 clutter/clutter/clutter-rotate-action.h            |   8 -
 clutter/clutter/clutter-script.c                   |  57 +++---
 clutter/clutter/clutter-script.h                   |   8 -
 clutter/clutter/clutter-scriptable.c               |  17 +-
 clutter/clutter/clutter-scriptable.h               |   9 -
 clutter/clutter/clutter-scroll-actor.c             |  16 +-
 clutter/clutter/clutter-scroll-actor.h             |   8 -
 clutter/clutter/clutter-seat.c                     |  47 +++--
 clutter/clutter/clutter-settings.c                 |  24 +--
 clutter/clutter/clutter-shader-effect.c            |  55 +++---
 clutter/clutter/clutter-shader-effect.h            |   8 -
 clutter/clutter/clutter-shader-types.c             |  12 +-
 clutter/clutter/clutter-snap-constraint.c          |  32 +--
 clutter/clutter/clutter-snap-constraint.h          |   8 -
 clutter/clutter/clutter-stage-manager.c            |  17 +-
 clutter/clutter/clutter-stage-manager.h            |   8 -
 clutter/clutter/clutter-stage-window.c             |   7 +-
 clutter/clutter/clutter-stage.c                    |  31 +--
 clutter/clutter/clutter-stage.h                    |   8 -
 clutter/clutter/clutter-swipe-action.c             |  14 +-
 clutter/clutter/clutter-swipe-action.h             |   8 -
 clutter/clutter/clutter-tap-action.c               |  18 +-
 clutter/clutter/clutter-tap-action.h               |   8 -
 clutter/clutter/clutter-text-buffer.c              |  29 +--
 clutter/clutter/clutter-text-buffer.h              |   8 -
 clutter/clutter/clutter-text.c                     | 173 +++++++++--------
 clutter/clutter/clutter-text.h                     |   7 -
 clutter/clutter/clutter-texture-content.c          |  16 +-
 clutter/clutter/clutter-timeline.c                 | 199 +++++++++----------
 clutter/clutter/clutter-timeline.h                 |   8 -
 clutter/clutter/clutter-transition-group.c         |  18 +-
 clutter/clutter/clutter-transition-group.h         |   8 -
 clutter/clutter/clutter-transition.c               |  84 ++++----
 clutter/clutter/clutter-transition.h               |   8 -
 clutter/clutter/clutter-types.h                    |  29 ++-
 clutter/clutter/clutter-units.c                    |  57 +++---
 clutter/clutter/clutter-units.h                    |   8 -
 clutter/clutter/clutter-util.c                     |  16 +-
 clutter/clutter/clutter-zoom-action.c              |  20 +-
 clutter/clutter/clutter-zoom-action.h              |   8 -
 125 files changed, 1120 insertions(+), 1593 deletions(-)
---
diff --git a/clutter/clutter/clutter-action.c b/clutter/clutter/clutter-action.c
index 50eda35f25..1966ced743 100644
--- a/clutter/clutter/clutter-action.c
+++ b/clutter/clutter/clutter-action.c
@@ -23,22 +23,21 @@
  */
 
 /**
- * SECTION:clutter-action
- * @Title: ClutterAction
- * @Short_Description: Abstract class for event-related logic
- * @See_Also: #ClutterConstraint
+ * ClutterAction:
+ * 
+ * Abstract class for event-related logic
  *
  * #ClutterAction is an abstract base class for event-related actions that
- * modify the user interaction of a #ClutterActor, just like
- * #ClutterConstraint is an abstract class for modifiers of an actor's
+ * modify the user interaction of a [class@Actor], just like
+ * [class@Constraint] is an abstract class for modifiers of an actor's
  * position or size.
  *
  * Implementations of #ClutterAction are associated to an actor and can
  * provide behavioral changes when dealing with user input - for instance
  * drag and drop capabilities, or scrolling, or panning - by using the
- * various event-related signals provided by #ClutterActor itself.
+ * various event-related signals provided by [class@Actor] itself.
  *
- * #ClutterAction is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-actor-box.c b/clutter/clutter/clutter-actor-box.c
index 73f6443d06..01e9da0f39 100644
--- a/clutter/clutter/clutter-actor-box.c
+++ b/clutter/clutter/clutter-actor-box.c
@@ -14,19 +14,19 @@
  * @x_2: X coordinate of the bottom right point
  * @y_2: Y coordinate of the bottom right point
  *
- * Allocates a new #ClutterActorBox using the passed coordinates
+ * Allocates a new [struct@ActorBox] using the passed coordinates
  * for the top left and bottom right points.
  *
  * This function is the logical equivalent of:
  *
- * |[
+ * ```c
  *   clutter_actor_box_init (clutter_actor_box_alloc (),
  *                           x_1, y_1,
  *                           x_2, y_2);
- * ]|
+ * ```
  *
  * Return value: (transfer full): the newly allocated #ClutterActorBox.
- *   Use clutter_actor_box_free() to free the resources
+ *   Use [method ActorBox free] to free the resources
  *
  * Since: 1.0
  */
@@ -44,10 +44,10 @@ clutter_actor_box_new (gfloat x_1,
 /**
  * clutter_actor_box_alloc:
  *
- * Allocates a new #ClutterActorBox.
+ * Allocates a new [struct@ActorBox].
  *
  * Return value: (transfer full): the newly allocated #ClutterActorBox.
- *   Use clutter_actor_box_free() to free its resources
+ *   Use [method ActorBox free] to free its resources
  *
  * Since: 1.12
  */
@@ -122,7 +122,7 @@ clutter_actor_box_init_rect (ClutterActorBox *box,
  * Copies @box
  *
  * Return value: a newly allocated copy of #ClutterActorBox. Use
- *   clutter_actor_box_free() to free the allocated resources
+ *   [method ActorBox free] to free the allocated resources
  *
  * Since: 1.0
  */
@@ -139,8 +139,8 @@ clutter_actor_box_copy (const ClutterActorBox *box)
  * clutter_actor_box_free:
  * @box: a #ClutterActorBox
  *
- * Frees a #ClutterActorBox allocated using clutter_actor_box_new()
- * or clutter_actor_box_copy()
+ * Frees a #ClutterActorBox allocated using [ctor ActorBox new]
+ * or [method ActorBox copy].
  *
  * Since: 1.0
  */
@@ -343,7 +343,7 @@ clutter_actor_box_contains (const ClutterActorBox *box,
  * @verts: (array fixed-size=4): array of four #graphene_point3d_t
  *
  * Calculates the bounding box represented by the four vertices; for details
- * of the vertex array see clutter_actor_get_abs_allocation_vertices().
+ * of the vertex array see [method@Actor.get_abs_allocation_vertices].
  *
  * Since: 1.0
  */
@@ -412,7 +412,7 @@ clutter_actor_box_from_vertices (ClutterActorBox          *box,
  * @progress: the interpolation progress
  * @result: (out): return location for the interpolation
  *
- * Interpolates between @initial and @final #ClutterActorBox<!-- -->es
+ * Interpolates between @initial and @final `ClutterActorBox`es
  * using @progress
  *
  * Since: 1.2
diff --git a/clutter/clutter/clutter-actor-meta.c b/clutter/clutter/clutter-actor-meta.c
index 8b564eadef..42666ddb80 100644
--- a/clutter/clutter/clutter-actor-meta.c
+++ b/clutter/clutter/clutter-actor-meta.c
@@ -23,22 +23,21 @@
  */
 
 /**
- * SECTION:clutter-actor-meta
- * @Title: ClutterActorMeta
- * @Short_Description: Base class of actor modifiers
- * @See_Also: #ClutterAction, #ClutterConstraint
+ * ClutterActorMeta:
+ * 
+ * Base class of actor modifiers
  *
  * #ClutterActorMeta is an abstract class providing a common API for
- * modifiers of #ClutterActor behaviour, appearance or layout.
+ * modifiers of [class@Actor] behaviour, appearance or layout.
  *
- * A #ClutterActorMeta can only be owned by a single #ClutterActor at
+ * A #ClutterActorMeta can only be owned by a single [class@Actor] at
  * any time.
  *
  * Every sub-class of #ClutterActorMeta should check if the
- * #ClutterActorMeta:enabled property is set to %TRUE before applying
+ * [property@ActorMeta:enabled] property is set to %TRUE before applying
  * any kind of modification.
  *
- * #ClutterActorMeta is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -298,7 +297,7 @@ clutter_actor_meta_set_name (ClutterActorMeta *meta,
  * clutter_actor_meta_get_name:
  * @meta: a #ClutterActorMeta
  *
- * Retrieves the name set using clutter_actor_meta_set_name()
+ * Retrieves the name set using [method@ActorMeta.set_name]
  *
  * Return value: (transfer none): the name of the #ClutterActorMeta
  *   instance, or %NULL if none was set. The returned string is owned
@@ -391,7 +390,7 @@ _clutter_actor_meta_set_actor (ClutterActorMeta *meta,
  * clutter_actor_meta_get_actor:
  * @meta: a #ClutterActorMeta
  *
- * Retrieves a pointer to the #ClutterActor that owns @meta
+ * Retrieves a pointer to the [class@Actor] that owns @meta
  *
  * Return value: (transfer none): a pointer to a #ClutterActor or %NULL
  *
diff --git a/clutter/clutter/clutter-actor.c b/clutter/clutter/clutter-actor.c
index 502e0a7f36..0a7f19647c 100644
--- a/clutter/clutter/clutter-actor.c
+++ b/clutter/clutter/clutter-actor.c
@@ -23,46 +23,47 @@
  */
 
 /**
- * SECTION:clutter-actor
- * @short_description: The basic element of the scene graph 
+ * ClutterActor:
+ * 
+ * The basic element of the scene graph 
  *
  * The ClutterActor class is the basic element of the scene graph in Clutter,
  * and it encapsulates the position, size, and transformations of a node in
  * the graph.
  *
- * ## Actor transformations ## {#clutter-actor-transformations}
+ * ## Actor transformations
  *
- * Each actor can be transformed using methods like clutter_actor_set_scale()
- * or clutter_actor_set_rotation(). The order in which the transformations are
+ * Each actor can be transformed using methods like [method@Actor.set_scale]
+ * or [method@Actor.set_rotation_angle]. The order in which the transformations are
  * applied is decided by Clutter and it is the following:
  *
- *  1. translation by the origin of the #ClutterActor:allocation property
- *  2. translation by the actor's #ClutterActor:z-position property
- *  3. translation by the actor's #ClutterActor:pivot-point property
- *  4. scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y factors
- *  5. rotation around the #ClutterActor:rotation-angle-x and #ClutterActor:rotation-center-x
- *  6. rotation around the #ClutterActor:rotation-angle-y and #ClutterActor:rotation-center-y
- *  7. rotation around the #ClutterActor:rotation-angle-z and #ClutterActor:rotation-center-z
- *  8. negative translation by the actor's #ClutterActor:pivot-point
+ *  1. translation by the origin of the [property@Actor:allocation] property
+ *  2. translation by the actor's [property@Actor:z-position] property
+ *  3. translation by the actor's [property@Actor:pivot-point] property
+ *  4. scaling by the [property@Actor:scale-x] and [property@Actor:scale-y] factors
+ *  5. rotation around the [property@Actor:rotation-angle-x]
+ *  6. rotation around the [property@Actor:rotation-angle-y]
+ *  7. rotation around the [property@Actor:rotation-angle-z]
+ *  8. negative translation by the actor's [property@Actor:pivot-point]
  *
- * ## Modifying an actor's geometry ## {#clutter-actor-geometry}
+ * ## Modifying an actor's geometry
  *
- * Each actor has a bounding box, called #ClutterActor:allocation
+ * Each actor has a bounding box, called [property@Actor:allocation]
  * which is either set by its parent or explicitly through the
- * clutter_actor_set_position() and clutter_actor_set_size() methods.
+ * [method@Actor.set_position] and [method@Actor.set_size] methods.
  * Each actor also has an implicit preferred size.
  *
  * An actor’s preferred size can be defined by any subclass by
- * overriding the #ClutterActorClass.get_preferred_width() and the
- * #ClutterActorClass.get_preferred_height() virtual functions, or it can
- * be explicitly set by using clutter_actor_set_width() and
- * clutter_actor_set_height().
+ * overriding the [vfunc@Actor.get_preferred_width] and the
+ * [vfunc@Actor.get_preferred_height] virtual functions, or it can
+ * be explicitly set by using [method@Actor.set_width] and
+ * [method@Actor.set_height].
  *
  * An actor’s position can be set explicitly by using
- * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are
+ * [method@Actor.set_x] and [method@Actor.set_y]; the coordinates are
  * relative to the origin of the actor’s parent.
  *
- * ## Managing actor children ## {#clutter-actor-children}
+ * ## Managing actor children
  *
  * Each actor can have multiple children, by calling
  * clutter_actor_add_child() to add a new child actor, and
@@ -71,7 +72,7 @@
  * the child is removed from its parent, or destroyed using
  * clutter_actor_destroy().
  *
- * |[<!-- language="C" -->
+ * ```c
  *  ClutterActor *actor = clutter_actor_new ();
  *
  *  // set the bounding box of the actor
@@ -91,7 +92,7 @@
  *
  *  // add the child to the actor
  *  clutter_actor_add_child (actor, child);
- * ]|
+ * ```
  *
  * Children can be inserted at a given index, or above and below
  * another child actor. The order of insertion determines the order of the
@@ -109,7 +110,7 @@
  *
  * See [basic-actor.c](https://git.gnome.org/browse/clutter/tree/examples/basic-actor.c?h=clutter-1.18).
  *
- * ## Painting an actor ## {#clutter-actor-painting}
+ * ## Painting an actor
  *
  * There are three ways to paint an actor:
  *
@@ -123,7 +124,7 @@
  * and before calling the actor's own implementation of the
  * #ClutterActorClass.paint_node() virtual function.
  *
- * |[<!-- language="C" -->
+ * ```c
  * ClutterActor *actor = clutter_actor_new ();
  *
  * // set the bounding box
@@ -132,7 +133,7 @@
  *
  * // set the content; the image_content variable is set elsewhere
  * clutter_actor_set_content (actor, image_content);
- * ]|
+ * ```
  *
  * The #ClutterActorClass.paint_node() virtual function is invoked whenever
  * an actor needs to be painted. The implementation of the virtual function
@@ -143,7 +144,7 @@
  * the render tree; any node added to it will be rendered at the correct
  * position, as defined by the actor's #ClutterActor:allocation.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
  * my_actor_paint_node (ClutterActor     *actor,
  *                      ClutterPaintNode *root)
@@ -166,6 +167,7 @@
  *   clutter_paint_node_add_child (root, node);
  *   clutter_paint_node_unref (node);
  * }
+ * ```
  *
  * The #ClutterActorClass.paint() virtual function function gives total
  * control to the paint sequence of the actor itself, including the
@@ -173,7 +175,7 @@
  * the #ClutterActorClass.paint() virtual function and it will be removed
  * when the Clutter API changes.
  *
- * ## Handling events on an actor ## {#clutter-actor-event-handling}
+ * ## Handling events on an actor
  *
  * A #ClutterActor can receive and handle input device events, for
  * instance pointer events and key events, as long as its
@@ -193,7 +195,7 @@
  * through the scene graph by returning %CLUTTER_EVENT_STOP; otherwise, they can
  * continue the propagation by returning %CLUTTER_EVENT_PROPAGATE.
  *
- * ## Animation ## {#clutter-actor-animation}
+ * ## Animation
  *
  * Animation is a core concept of modern user interfaces; Clutter provides a
  * complete and powerful animation framework that automatically tweens the
@@ -217,7 +219,7 @@
  * the default easing state for an actor you should call the
  * clutter_actor_save_easing_state() function:
  *
- * |[<!-- language="C" -->
+ * ```c
  * // assume that the actor is currently positioned at (100, 100)
  *
  * // store the current easing state and reset the new easing state to
@@ -229,7 +231,7 @@
  *
  * // restore the previously saved easing state
  * clutter_actor_restore_easing_state (actor);
- * ]|
+ * ```
  *
  * The example above will trigger an implicit animation of the
  * actor between its current position to a new position.
@@ -243,7 +245,7 @@
  * at the same time, and you can animate multiple actors at the same
  * time as well, for instance:
  *
- * |[<!-- language="C" -->
+ * ```c
  * clutter_actor_save_easing_state (actor);
  *
  * // animate the actor's opacity and depth
@@ -259,7 +261,7 @@
  * clutter_actor_set_z_position (another_actor, 100);
  *
  * clutter_actor_restore_easing_state (another_actor);
- * ]|
+ * ```
  *
  * Changing the easing state will affect all the following property
  * transitions, but will not affect existing transitions.
@@ -270,7 +272,7 @@
  * mode by using the current easing state; for instance, in the following
  * example:
  *
- * |[<!-- language="C" -->
+ * ```c
  * clutter_actor_save_easing_state (actor);
  * clutter_actor_set_easing_duration (actor, 1000);
  * clutter_actor_set_x (actor, 200);
@@ -280,7 +282,7 @@
  * clutter_actor_set_easing_duration (actor, 500);
  * clutter_actor_set_x (actor, 100);
  * clutter_actor_restore_easing_state (actor);
- * ]|
+ * ```
  *
  * the first call to clutter_actor_set_x() will begin a transition
  * of the #ClutterActor:x property from the current value to the value of
@@ -303,7 +305,7 @@
  * and final values. The transition will not start unless you add it to the
  * #ClutterActor.
  *
- * |[<!-- language="C" -->
+ * ```c
  * ClutterTransition *transition;
  *
  * transition = clutter_property_transition_new_for_actor (actor, "opacity");
@@ -314,7 +316,7 @@
  * clutter_transition_set_to (transition, G_TYPE_UINT, 0);
  *
  * clutter_actor_add_transition (actor, "animate-opacity", transition);
- * ]|
+ * ```
  *
  * The example above will animate the #ClutterActor:opacity property
  * of an actor between fully opaque and fully transparent, and back, over
@@ -334,7 +336,7 @@
  * Finally, explicit animations are useful for creating animations
  * that run continuously, for instance:
  *
- * |[<!-- language="C" -->
+ * ```c
  * // this animation will pulse the actor's opacity continuously
  * ClutterTransition *transition;
  * ClutterInterval *interval;
@@ -358,9 +360,9 @@
  *
  * // add the transition to the desired actor to start it
  * clutter_actor_add_transition (actor, "opacityAnimation", transition);
- * ]|
+ * ```
  *
- * ## Implementing an actor ## {#clutter-actor-implementing}
+ * ## Implementing an actor
  *
  * Careful consideration should be given when deciding to implement
  * a #ClutterActor sub-class. It is generally recommended to implement a
@@ -378,16 +380,16 @@
  * In general, it is strongly encouraged to use delegation and composition
  * instead of direct subclassing.
  *
- * ## ClutterActor custom properties for ClutterScript ## {#clutter-actor-custom-script}
+ * ## ClutterActor custom properties for ClutterScript
  *
  * #ClutterActor defines a custom "rotation" property which allows a short-hand
  * description of the rotations to be applied to an actor.
  *
  * The syntax of the "rotation" property is the following:
  *
- * |[
+ * ```
  * "rotation" : [ { "<axis>" : [ <angle>, [ <center-point> ] ] } ]
- * ]|
+ * ```
  *
  * where:
  *
@@ -400,7 +402,7 @@
  *
  * #ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand.
  *
- * |[
+ * ```
  *   // 4 values
  *   "margin" : [ top, right, bottom, left ]
  *   // 3 values
@@ -409,7 +411,7 @@
  *   "margin" : [ top/bottom, left/right ]
  *   // 1 value
  *   "margin" : [ top/right/bottom/left ]
- * ]|
+ * ```
  *
  * #ClutterActor will also parse every positional and dimensional
  * property defined as a string through clutter_units_from_string(); you
@@ -428,9 +430,9 @@
  *
  * The property can be accessed using the following syntax:
  *
- * |[
+ * ```
  *   @<section>.<meta-name>.<property-name>
- * ]|
+ * ```
  *
  *  - the initial `@` is mandatory
  *  - the `section` fragment can be one between "actions", "constraints", "content",
@@ -448,11 +450,11 @@
  * As the actor has only one #ClutterLayoutManager, the syntax for accessing its
  * properties is simpler:
  *
- * |[
+ * ```
  *   @layout.<property-name>
- * ]|
+ * ```
  *
- * |[<!-- language="C" -->
+ * ```c
  * constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
  * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
  * clutter_actor_add_constraint (rect, constraint);
@@ -466,13 +468,13 @@
  * g_signal_connect (origin, "button-press-event",
  *                   G_CALLBACK (on_button_press),
  *                   rect);
- * ]|
+ * ```
  *
  * On button press, the rectangle "slides" from behind the actor to
  * which is bound to, using the #ClutterBindConstraint:offset property to
  * achieve the effect:
  *
- * |[<!-- language="C" -->
+ * ```c
  * gboolean
  * on_button_press (ClutterActor *origin,
  *                  ClutterEvent *event,
@@ -512,7 +514,7 @@
  *   // we handled the event
  *   return CLUTTER_EVENT_STOP;
  * }
- * ]|
+ * ```
  */
 
 /**
@@ -6324,7 +6326,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    *
    * For instance:
    *
-   * |[<!-- language="C" -->
+   * ```c
    *   ClutterRequestMode mode;
    *   gfloat natural_width, min_width;
    *   gfloat natural_height, min_height;
@@ -6358,7 +6360,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    *       if (content != NULL)
    *         clutter_content_get_preferred_size (content, &natural_width, &natural_height);
    *     }
-   * ]|
+   * ```
    *
    * will retrieve the minimum and natural width and height depending on the
    * preferred request mode of the #ClutterActor "child".
@@ -7348,10 +7350,10 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::destroy:
    * @actor: the #ClutterActor which emitted the signal
    *
-   * The ::destroy signal notifies that all references held on the
+   * The signal notifies that all references held on the
    * actor which emitted it should be released.
    *
-   * The ::destroy signal should be used by all holders of a reference
+   * The signal should be used by all holders of a reference
    * on @actor.
    *
    * This signal might result in the finalization of the #ClutterActor
@@ -7376,7 +7378,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::show:
    * @actor: the object which received the signal
    *
-   * The ::show signal is emitted when an actor is visible and
+   * The signal is emitted when an actor is visible and
    * rendered on the stage.
    *
    * Since: 0.2
@@ -7392,7 +7394,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::hide:
    * @actor: the object which received the signal
    *
-   * The ::hide signal is emitted when an actor is no longer rendered
+   * The signal is emitted when an actor is no longer rendered
    * on the stage.
    *
    * Since: 0.2
@@ -7426,7 +7428,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::queue-relayout:
    * @actor: the actor being queued for relayout
    *
-   * The ::queue_layout signal is emitted when clutter_actor_queue_relayout()
+   * The signal is emitted when clutter_actor_queue_relayout()
    * is called on an actor.
    *
    * The default implementation for #ClutterActor chains up to the
@@ -7453,7 +7455,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: a #ClutterEvent
    *
-   * The ::event signal is emitted each time an event is received
+   * The signal is emitted each time an event is received
    * by the @actor. This signal will be emitted on every actor,
    * following the hierarchy chain, until it reaches the top-level
    * container (the #ClutterStage).
@@ -7480,7 +7482,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterButtonEvent): a #ClutterButtonEvent
    *
-   * The ::button-press-event signal is emitted each time a mouse button
+   * The signal is emitted each time a mouse button
    * is pressed on @actor.
    *
    * Return value: %TRUE if the event has been handled by the actor,
@@ -7505,7 +7507,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterButtonEvent): a #ClutterButtonEvent
    *
-   * The ::button-release-event signal is emitted each time a mouse button
+   * The signal is emitted each time a mouse button
    * is released on @actor.
    *
    * Return value: %TRUE if the event has been handled by the actor,
@@ -7530,7 +7532,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterScrollEvent): a #ClutterScrollEvent
    *
-   * The ::scroll-event signal is emitted each time the mouse is
+   * The signal is emitted each time the mouse is
    * scrolled on @actor
    *
    * Return value: %TRUE if the event has been handled by the actor,
@@ -7555,7 +7557,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterKeyEvent): a #ClutterKeyEvent
    *
-   * The ::key-press-event signal is emitted each time a keyboard button
+   * The signal is emitted each time a keyboard button
    * is pressed while @actor has key focus (see clutter_stage_set_key_focus()).
    *
    * Return value: %TRUE if the event has been handled by the actor,
@@ -7580,7 +7582,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterKeyEvent): a #ClutterKeyEvent
    *
-   * The ::key-release-event signal is emitted each time a keyboard button
+   * The signal is emitted each time a keyboard button
    * is released while @actor has key focus (see
    * clutter_stage_set_key_focus()).
    *
@@ -7606,7 +7608,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the event
    * @event: (type ClutterMotionEvent): a #ClutterMotionEvent
    *
-   * The ::motion-event signal is emitted each time the mouse pointer is
+   * The signal is emitted each time the mouse pointer is
    * moved over @actor.
    *
    * Return value: %TRUE if the event has been handled by the actor,
@@ -7631,7 +7633,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::key-focus-in:
    * @actor: the actor which now has key focus
    *
-   * The ::key-focus-in signal is emitted when @actor receives key focus.
+   * The signal is emitted when @actor receives key focus.
    *
    * Since: 0.6
    */
@@ -7647,7 +7649,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::key-focus-out:
    * @actor: the actor which now has key focus
    *
-   * The ::key-focus-out signal is emitted when @actor loses key focus.
+   * The signal is emitted when @actor loses key focus.
    *
    * Since: 0.6
    */
@@ -7664,7 +7666,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which the pointer has entered.
    * @event: (type ClutterCrossingEvent): a #ClutterCrossingEvent
    *
-   * The ::enter-event signal is emitted when the pointer enters the @actor
+   * The signal is emitted when the pointer enters the @actor
    *
    * Return value: %TRUE if the event has been handled by the actor,
    *   or %FALSE to continue the emission.
@@ -7689,7 +7691,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which the pointer has left
    * @event: (type ClutterCrossingEvent): a #ClutterCrossingEvent
    *
-   * The ::leave-event signal is emitted when the pointer leaves the @actor.
+   * The signal is emitted when the pointer leaves the @actor.
    *
    * Return value: %TRUE if the event has been handled by the actor,
    *   or %FALSE to continue the emission.
@@ -7714,7 +7716,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the actor which received the signal
    * @event: a #ClutterEvent
    *
-   * The ::captured-event signal is emitted when an event is captured
+   * The signal is emitted when an event is captured
    * by Clutter. This signal will be emitted starting from the top-level
    * container (the #ClutterStage) to the actor which received the event
    * going down the hierarchy. This signal can be used to intercept every
@@ -7744,7 +7746,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::realize:
    * @actor: the #ClutterActor that received the signal
    *
-   * The ::realize signal is emitted each time an actor is being
+   * The signal is emitted each time an actor is being
    * realized.
    *
    * Since: 0.8
@@ -7763,7 +7765,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::unrealize:
    * @actor: the #ClutterActor that received the signal
    *
-   * The ::unrealize signal is emitted each time an actor is being
+   * The signal is emitted each time an actor is being
    * unrealized.
    *
    * Since: 0.8
@@ -7784,14 +7786,14 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: the #ClutterActor that received the signal
    * @pick_context: a #ClutterPickContext
    *
-   * The ::pick signal is emitted each time an actor is being painted
+   * The signal is emitted each time an actor is being painted
    * in "pick mode". The pick mode is used to identify the actor during
    * the event handling phase, or by clutter_stage_get_actor_at_pos().
    *
    * Subclasses of #ClutterActor should override the class signal handler
    * and paint themselves in that function.
    *
-   * It is possible to connect a handler to the ::pick signal in order
+   * It is possible to connect a handler to the signal in order
    * to set up some custom aspect of a paint in pick mode.
    *
    * Since: 1.0
@@ -7811,7 +7813,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::transitions-completed:
    * @actor: a #ClutterActor
    *
-   * The ::transitions-completed signal is emitted once all transitions
+   * The signal is emitted once all transitions
    * involving @actor are complete.
    *
    * Since: 1.10
@@ -7830,7 +7832,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @name: the name of the transition
    * @is_finished: whether the transition was finished, or stopped
    *
-   * The ::transition-stopped signal is emitted once a transition
+   * The signal is emitted once a transition
    * is stopped; a transition is stopped once it reached its total
    * duration (including eventual repeats), it has been stopped
    * using clutter_timeline_stop(), or it has been removed from the
@@ -7858,7 +7860,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * @actor: a #ClutterActor
    * @event: a #ClutterEvent
    *
-   * The ::touch-event signal is emitted each time a touch
+   * The signal is emitted each time a touch
    * begin/end/update/cancel event.
    *
    * Return value: %CLUTTER_EVENT_STOP if the event has been handled by
@@ -7883,7 +7885,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::stage-views-changed:
    * @actor: a #ClutterActor
    *
-   * The ::stage-views-changed signal is emitted when the position or
+   * The signal is emitted when the position or
    * size an actor is being painted at have changed so that it's visible
    * on different stage views.
    *
@@ -7903,7 +7905,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * ClutterActor::resource-scale-changed:
    * @actor: a #ClutterActor
    *
-   * The ::resource-scale-changed signal is emitted when the resource scale
+   * The signal is emitted when the resource scale
    * value returned by clutter_actor_get_resource_scale() changes.
    *
    * This signal can be used to get notified about the correct resource scale
@@ -11260,7 +11262,7 @@ clutter_actor_get_clip (ClutterActor *self,
  * Retrieves the list of children of @self.
  *
  * Return value: (transfer container) (element-type ClutterActor): A newly
- *   allocated #GList of #ClutterActor<!-- -->s. Use g_list_free() when
+ *   allocated #GList of `ClutterActor`s. Use g_list_free() when
  *   done.
  *
  * Since: 1.10
@@ -13723,7 +13725,7 @@ clutter_actor_get_stage (ClutterActor *actor)
  *
  * The implementation of this function is equivalent to:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
  *     {
  *       clutter_actor_get_preferred_width (self, available_height,
@@ -13760,7 +13762,7 @@ clutter_actor_get_stage (ClutterActor *actor)
  *   box.x2 = box.x1 + available_width;
  *   box.y2 = box.y1 + available_height;
  *   clutter_actor_allocate (self, &box);
- * ]|
+ * ```
  *
  * This function can be used by fluid layout managers to allocate
  * an actor's preferred size without making it bigger than the area
@@ -14895,10 +14897,10 @@ clutter_actor_add_action (ClutterActor  *self,
  *
  * This function is the logical equivalent of:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
  *   clutter_actor_add_action (self, action);
- * ]|
+ * ```
  *
  * Since: 1.4
  */
@@ -15005,7 +15007,7 @@ clutter_actor_remove_action_by_name (ClutterActor *self,
  * Retrieves the list of actions applied to @self
  *
  * Return value: (transfer container) (element-type Clutter.Action): a copy
- *   of the list of #ClutterAction<!-- -->s. The contents of the list are
+ *   of the list of `ClutterAction`s. The contents of the list are
  *   owned by the #ClutterActor. Use g_list_free() to free the resources
  *   allocated by the returned #GList
  *
@@ -15073,7 +15075,7 @@ clutter_actor_clear_actions (ClutterActor *self)
  * @self: a #ClutterActor
  * @constraint: a #ClutterConstraint
  *
- * Adds @constraint to the list of #ClutterConstraint<!-- -->s applied
+ * Adds @constraint to the list`of `ClutterConstraint`s applied
  * to @self
  *
  * The #ClutterActor will hold a reference on the @constraint until
@@ -15117,10 +15119,10 @@ clutter_actor_add_constraint (ClutterActor      *self,
  *
  * This function is the logical equivalent of:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
  *   clutter_actor_add_constraint (self, constraint);
- * ]|
+ * ```
  *
  * Since: 1.4
  */
@@ -15213,7 +15215,7 @@ clutter_actor_remove_constraint_by_name (ClutterActor *self,
  * Retrieves the list of constraints applied to @self
  *
  * Return value: (transfer container) (element-type Clutter.Constraint): a copy
- *   of the list of #ClutterConstraint<!-- -->s. The contents of the list are
+ *   of the list of `ClutterConstraint`s. The contents of the list are
  *   owned by the #ClutterActor. Use g_list_free() to free the resources
  *   allocated by the returned #GList
  *
@@ -15335,7 +15337,7 @@ clutter_actor_get_clip_to_allocation (ClutterActor *self)
  * @self: a #ClutterActor
  * @effect: a #ClutterEffect
  *
- * Adds @effect to the list of #ClutterEffect<!-- -->s applied to @self
+ * Adds @effect to the list of `ClutterEffect`s applied to @self
  *
  * The #ClutterActor will hold a reference on the @effect until either
  * clutter_actor_remove_effect() or clutter_actor_clear_effects() is
@@ -15368,10 +15370,10 @@ clutter_actor_add_effect (ClutterActor  *self,
  *
  * This function is the logical equivalent of:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
  *   clutter_actor_add_effect (self, effect);
- * ]|
+ * ```
  *
  * Since: 1.4
  */
@@ -15449,10 +15451,10 @@ clutter_actor_remove_effect_by_name (ClutterActor *self,
  * clutter_actor_get_effects:
  * @self: a #ClutterActor
  *
- * Retrieves the #ClutterEffect<!-- -->s applied on @self, if any
+ * Retrieves the `ClutterEffect`s applied on @self, if any
  *
  * Return value: (transfer container) (element-type Clutter.Effect): a list
- *   of #ClutterEffect<!-- -->s, or %NULL. The elements of the returned
+ *   of `ClutterEffect`s, or %NULL. The elements of the returned
  *   list are owned by Clutter and they should not be freed. You should
  *   free the returned list using g_list_free() when done
  *
@@ -16089,7 +16091,7 @@ clutter_actor_finish_layout (ClutterActor *self,
  * clutter_actor_peek_stage_views:
  * @self: A #ClutterActor
  *
- * Retrieves the list of #ClutterStageView<!-- -->s the actor is being
+ * Retrieves the list of `ClutterStageView`s the actor is being
  * painted on.
  *
  * If this function is called during the paint cycle, the list is guaranteed
@@ -16105,7 +16107,7 @@ clutter_actor_finish_layout (ClutterActor *self,
  * always return an empty list.
  *
  * Returns: (transfer none) (element-type Clutter.StageView): The list of
- *   #ClutterStageView<!-- -->s the actor is being painted on. The list and
+ *   `ClutterStageView`s the actor is being painted on. The list and
  *   its contents are owned by the #ClutterActor and the list may not be
  *   freed or modified.
  */
@@ -17284,7 +17286,7 @@ typedef struct _RealActorIter
  * Modifying the scene graph section that contains @root will invalidate
  * the iterator.
  *
- * |[<!-- language="C" -->
+ * ```c
  *   ClutterActorIter iter;
  *   ClutterActor *child;
  *
@@ -17293,7 +17295,7 @@ typedef struct _RealActorIter
  *     {
  *       // do something with child
  *     }
- * ]|
+ * ```
  *
  * Since: 1.10
  */
@@ -18217,7 +18219,7 @@ clutter_actor_get_easing_delay (ClutterActor *self)
  * Transitions created for animatable properties use the name of the
  * property itself, for instance the code below:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_actor_set_easing_duration (actor, 1000);
  *   clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 360.0);
  *
@@ -18225,7 +18227,7 @@ clutter_actor_get_easing_delay (ClutterActor *self)
  *   g_signal_connect (transition, "stopped",
  *                     G_CALLBACK (on_transition_stopped),
  *                     actor);
- * ]|
+ * ```
  *
  * will call the `on_transition_stopped` callback when the transition
  * is finished.
@@ -19627,7 +19629,7 @@ bind_child_with_properties (gpointer item,
  * items inside the @model to the corresponding properties on the child,
  * for instance:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_actor_bind_model_with_properties (actor, model,
  *                                             MY_TYPE_CHILD_VIEW,
  *                                             "label", "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE,
@@ -19635,12 +19637,12 @@ bind_child_with_properties (gpointer item,
  *                                             "selected", "selected", G_BINDING_BIDIRECTIONAL,
  *                                             "active", "active", G_BINDING_BIDIRECTIONAL,
  *                                             NULL);
- * ]|
+ * ```
  *
  * is the equivalent of calling clutter_actor_bind_model() with a
  * #ClutterActorCreateChildFunc of:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   ClutterActor *res = g_object_new (MY_TYPE_CHILD_VIEW, NULL);
  *
  *   g_object_bind_property (item, "label", res, "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE);
@@ -19649,7 +19651,7 @@ bind_child_with_properties (gpointer item,
  *   g_object_bind_property (item, "active", res, "active", G_BINDING_BIDIRECTIONAL);
  *
  *   return res;
- * ]|
+ * ```
  *
  * If the #ClutterActor was already bound to a #GListModel, the previous
  * binding is destroyed.
diff --git a/clutter/clutter/clutter-actor.h b/clutter/clutter/clutter-actor.h
index 5707aa672b..5f2016425f 100644
--- a/clutter/clutter/clutter-actor.h
+++ b/clutter/clutter/clutter-actor.h
@@ -118,12 +118,7 @@ typedef void (*ClutterCallback) (ClutterActor *actor,
  */
 #define CLUTTER_CALLBACK(f)        ((ClutterCallback) (f))
 
-/**
- * ClutterActor:
- * @flags: #ClutterActorFlags
- *
- * Base class for actors.
- */
+
 struct _ClutterActor
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-align-constraint.c b/clutter/clutter/clutter-align-constraint.c
index 46cf44073b..645997e07a 100644
--- a/clutter/clutter/clutter-align-constraint.c
+++ b/clutter/clutter/clutter-align-constraint.c
@@ -23,15 +23,15 @@
  */
 
 /**
- * SECTION:clutter-align-constraint
- * @Title: ClutterAlignConstraint
- * @Short_Description: A constraint aligning the position of an actor
+ * ClutterAlignConstraint:
+ * 
+ * A constraint aligning the position of an actor
  *
- * #ClutterAlignConstraint is a #ClutterConstraint that aligns the position
- * of the #ClutterActor to which it is applied to the size of another
- * #ClutterActor using an alignment factor
+ * #ClutterAlignConstraint is a [class@Constraint] that aligns the position
+ * of the [class@Actor] to which it is applied to the size of another
+ * [class@Actor] using an alignment factor
  *
- * #ClutterAlignConstraint is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-align-constraint.h b/clutter/clutter/clutter-align-constraint.h
index 7e316ce45e..8bf26c3b99 100644
--- a/clutter/clutter/clutter-align-constraint.h
+++ b/clutter/clutter/clutter-align-constraint.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_ALIGN_CONSTRAINT(obj)           (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_ALIGN_CONSTRAINT, ClutterAlignConstraint))
 #define CLUTTER_IS_ALIGN_CONSTRAINT(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_ALIGN_CONSTRAINT))
 
-/**
- * ClutterAlignConstraint:
- *
- * #ClutterAlignConstraint is an opaque structure
- * whose members cannot be directly accesses
- *
- * Since: 1.4
- */
 typedef struct _ClutterAlignConstraint          ClutterAlignConstraint;
 typedef struct _ClutterAlignConstraintClass     ClutterAlignConstraintClass;
 
diff --git a/clutter/clutter/clutter-animatable.c b/clutter/clutter/clutter-animatable.c
index 8ea28de771..b1a12f546d 100644
--- a/clutter/clutter/clutter-animatable.c
+++ b/clutter/clutter/clutter-animatable.c
@@ -23,18 +23,19 @@
  */
 
 /**
- * SECTION:clutter-animatable
- * @short_description: Interface for animatable classes
+ * ClutterAnimatable:
+ * 
+ * Interface for animatable classes
  *
- * #ClutterAnimatable is an interface that allows a #GObject class
+ * #ClutterAnimatable is an interface that allows a [class@GObject.Object] class
  * to control how an actor will animate a property.
  *
  * Each #ClutterAnimatable should implement the
- * #ClutterAnimatableInterface.interpolate_property() virtual function of the
+ * [vfunc@Animatable.interpolate_value] virtual function of the
  * interface to compute the animation state between two values of an interval
  * depending on a progress factor, expressed as a floating point value.
  *
- * #ClutterAnimatable is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -56,7 +57,7 @@ clutter_animatable_default_init (ClutterAnimatableInterface *iface)
  * @animatable: a #ClutterAnimatable
  * @property_name: the name of the animatable property to find
  *
- * Finds the #GParamSpec for @property_name
+ * Finds the [class@GObject.ParamSpec] for @property_name
  *
  * Return value: (transfer none): The #GParamSpec for the given property
  *   or %NULL
@@ -156,7 +157,7 @@ clutter_animatable_set_final_state (ClutterAnimatable *animatable,
  * value, and store the result inside @value.
  *
  * This function should be used for every property animation
- * involving #ClutterAnimatable<!-- -->s.
+ * involving `ClutterAnimatable`s.
  *
  * This function replaces clutter_animatable_animate_property().
  *
diff --git a/clutter/clutter/clutter-backend.c b/clutter/clutter/clutter-backend.c
index 4191942e18..1d3794c1d1 100644
--- a/clutter/clutter/clutter-backend.c
+++ b/clutter/clutter/clutter-backend.c
@@ -25,8 +25,9 @@
  */
 
 /**
- * SECTION:clutter-backend
- * @short_description: Backend abstraction
+ * ClutterBackend:
+ * 
+ * Backend abstraction
  *
  * Clutter can be compiled against different backends. Each backend
  * has to implement a set of functions, in order to be used by Clutter.
@@ -35,7 +36,7 @@
  * it provides a basic API to query the backend for generic information
  * and settings.
  *
- * #ClutterBackend is available since Clutter 0.4
+ * Since: 0.4
  */
 
 #include "clutter-build-config.h"
@@ -376,7 +377,7 @@ clutter_backend_class_init (ClutterBackendClass *klass)
    * ClutterBackend::resolution-changed:
    * @backend: the #ClutterBackend that emitted the signal
    *
-   * The ::resolution-changed signal is emitted each time the font
+   * The signal is emitted each time the font
    * resolutions has been changed through #ClutterSettings.
    *
    * Since: 1.0
@@ -393,7 +394,7 @@ clutter_backend_class_init (ClutterBackendClass *klass)
    * ClutterBackend::font-changed:
    * @backend: the #ClutterBackend that emitted the signal
    *
-   * The ::font-changed signal is emitted each time the font options
+   * The signal is emitted each time the font options
    * have been changed through #ClutterSettings.
    *
    * Since: 1.0
@@ -410,7 +411,7 @@ clutter_backend_class_init (ClutterBackendClass *klass)
    * ClutterBackend::settings-changed:
    * @backend: the #ClutterBackend that emitted the signal
    *
-   * The ::settings-changed signal is emitted each time the #ClutterSettings
+   * The signal is emitted each time the #ClutterSettings
    * properties have been changed.
    *
    * Since: 1.4
diff --git a/clutter/clutter/clutter-backend.h b/clutter/clutter/clutter-backend.h
index 570fd96a4e..117fdc0fb1 100644
--- a/clutter/clutter/clutter-backend.h
+++ b/clutter/clutter/clutter-backend.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 #define CLUTTER_BACKEND(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BACKEND, 
ClutterBackend))
 #define CLUTTER_IS_BACKEND(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BACKEND))
 
-/**
- * ClutterBackend:
- *
- * #ClutterBackend is an opaque structure whose
- * members cannot be directly accessed.
- *
- * Since: 0.4
- */
 typedef struct _ClutterBackend          ClutterBackend;
 typedef struct _ClutterBackendClass     ClutterBackendClass;
 
diff --git a/clutter/clutter/clutter-bin-layout.c b/clutter/clutter/clutter-bin-layout.c
index a17393c48c..49805d5325 100644
--- a/clutter/clutter/clutter-bin-layout.c
+++ b/clutter/clutter/clutter-bin-layout.c
@@ -23,8 +23,9 @@
  */
 
 /**
- * SECTION:clutter-bin-layout
- * @short_description: A simple layout manager
+ * ClutterBinLayout:
+ * 
+ * A simple layout manager
  *
  * #ClutterBinLayout is a layout manager which implements the following
  * policy:
@@ -40,7 +41,7 @@
  * The [bin-layout example](https://git.gnome.org/browse/clutter/tree/examples/bin-layout.c?h=clutter-1.18)
  * shows how to pack actors inside a #ClutterBinLayout.
  *
- * #ClutterBinLayout is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-bin-layout.h b/clutter/clutter/clutter-bin-layout.h
index fa826d6289..fd343c5932 100644
--- a/clutter/clutter/clutter-bin-layout.h
+++ b/clutter/clutter/clutter-bin-layout.h
@@ -44,14 +44,6 @@ typedef struct _ClutterBinLayout                ClutterBinLayout;
 typedef struct _ClutterBinLayoutPrivate         ClutterBinLayoutPrivate;
 typedef struct _ClutterBinLayoutClass           ClutterBinLayoutClass;
 
-/**
- * ClutterBinLayout:
- *
- * The #ClutterBinLayout structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.2
- */
 struct _ClutterBinLayout
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-bind-constraint.c b/clutter/clutter/clutter-bind-constraint.c
index 6a5ab57d21..c86d7b7bcf 100644
--- a/clutter/clutter/clutter-bind-constraint.c
+++ b/clutter/clutter/clutter-bind-constraint.c
@@ -23,20 +23,20 @@
  */
 
 /**
- * SECTION:clutter-bind-constraint
- * @Title: ClutterBindConstraint
- * @Short_Description: A constraint binding the position or size of an actor
+ * ClutterBindConstraint:
+ * 
+ * A constraint binding the position or size of an actor
  *
- * #ClutterBindConstraint is a #ClutterConstraint that binds the
- * position or the size of the #ClutterActor to which it is applied
- * to the the position or the size of another #ClutterActor, or
+ * #ClutterBindConstraint is a [class@Constraint] that binds the
+ * position or the size of the [class@Actor] to which it is applied
+ * to the the position or the size of another [class@Actor], or
  * "source".
  *
  * An offset can be applied to the constraint, to avoid overlapping. The offset
  * can also be animated. For instance, the following code will set up three
  * actors to be bound to the same origin:
  *
- * |[<!-- language="C" -->
+ * ```c
  * // source
  * rect[0] = clutter_actor_new ();
  * clutter_actor_set_background_color (rect[0], &red_color);
@@ -64,12 +64,12 @@
  * clutter_actor_add_constraint_with_name (rect[2], "blue-x", constraint);
  * constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0);
  * clutter_actor_add_constraint_with_name (rect[2], "blue-y", constraint);
- * ]|
+ * ```
  *
  * The following code animates the second and third rectangles to "expand"
  * them horizontally from underneath the first rectangle:
  *
- * |[<!-- language="C" -->
+ * ```c
  * clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250,
  *                        "@constraints.green-x.offset", 100.0,
  *                        "opacity", 255,
@@ -78,9 +78,9 @@
  *                        "@constraints.blue-x.offset", 200.0,
  *                        "opacity", 255,
  *                        NULL);
- * ]|
+ * ```
  *
- * #ClutterBindConstraint is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-bind-constraint.h b/clutter/clutter/clutter-bind-constraint.h
index 16bf478991..319407ad76 100644
--- a/clutter/clutter/clutter-bind-constraint.h
+++ b/clutter/clutter/clutter-bind-constraint.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_BIND_CONSTRAINT(obj)    (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BIND_CONSTRAINT, 
ClutterBindConstraint))
 #define CLUTTER_IS_BIND_CONSTRAINT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BIND_CONSTRAINT))
 
-/**
- * ClutterBindConstraint:
- *
- * #ClutterBindConstraint is an opaque structure
- * whose members cannot be directly accessed
- *
- * Since: 1.4
- */
 typedef struct _ClutterBindConstraint           ClutterBindConstraint;
 typedef struct _ClutterBindConstraintClass      ClutterBindConstraintClass;
 
diff --git a/clutter/clutter/clutter-binding-pool.c b/clutter/clutter/clutter-binding-pool.c
index 347ad6d7c0..5f00b3073a 100644
--- a/clutter/clutter/clutter-binding-pool.c
+++ b/clutter/clutter/clutter-binding-pool.c
@@ -22,8 +22,9 @@
  */
 
 /**
- * SECTION:clutter-binding-pool
- * @short_description: Pool for key bindings
+ * ClutterBindingPool
+ * 
+ * Pool for key bindings
  *
  * #ClutterBindingPool is a data structure holding a set of key bindings.
  * Each key binding associates a key symbol (eventually with modifiers)
@@ -38,7 +39,7 @@
  * inside their class initialization function and then install actions
  * like this:
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
  * foo_class_init (FooClass *klass)
  * {
@@ -55,23 +56,23 @@
  *                                        G_CALLBACK (foo_action_move_up),
  *                                        NULL, NULL);
  * }
- * ]|
+ * ```
  *
  * The callback has a signature of:
  *
- * |[<!-- language="C" -->
+ * ```c
  *    gboolean (* callback) (GObject             *instance,
  *                           const gchar         *action_name,
  *                           guint                key_val,
  *                           ClutterModifierType  modifiers,
  *                           gpointer             user_data);
- * ]|
+ * ```
  *
- * The actor should then override the #ClutterActor::key-press-event and
- * use clutter_binding_pool_activate() to match a #ClutterKeyEvent structure
+ * The actor should then override the [signal@Actor::key-press-event] and
+ * use [method@BindingPool.activate] to match a [struct@KeyEvent] structure
  * to one of the actions:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   ClutterBindingPool *pool;
  *
  *   // retrieve the binding pool for the type of the actor
@@ -84,14 +85,14 @@
  *                                         key_event->keyval,
  *                                         key_event->modifier_state,
  *                                         G_OBJECT (actor));
- * ]|
+ * ```
  *
- * The clutter_binding_pool_activate() function will return %FALSE if
+ * The [method@BindingPool.activate] function will return %FALSE if
  * no action for the given key binding was found, if the action was
- * blocked (using clutter_binding_pool_block_action()) or if the
+ * blocked (using [method@BindingPool.block_action]) or if the
  * key binding handler returned %FALSE.
  *
- * #ClutterBindingPool is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -382,9 +383,9 @@ clutter_binding_pool_new (const gchar *name)
  * A binding pool for a class can also be retrieved using
  * clutter_binding_pool_find() with the class type name:
  *
- * |[
+ * ```
  *   pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));
- * ]|
+ * ```
  *
  * Return value: (transfer none): the binding pool for the given class.
  *   The returned #ClutterBindingPool is owned by Clutter and should not
@@ -832,13 +833,13 @@ clutter_binding_entry_invoke (ClutterBindingEntry *entry,
  *
  * The callback has the following signature:
  *
- * |[
+ * ```
  *   void (* callback) (GObject             *gobject,
  *                      const gchar         *action_name,
  *                      guint                key_val,
  *                      ClutterModifierType  modifiers,
  *                      gpointer             user_data);
- * ]|
+ * ```
  *
  * Where the #GObject instance is @gobject and the user data
  * is the one passed when installing the action with
diff --git a/clutter/clutter/clutter-binding-pool.h b/clutter/clutter/clutter-binding-pool.h
index dcf771d243..ae19727f4c 100644
--- a/clutter/clutter/clutter-binding-pool.h
+++ b/clutter/clutter/clutter-binding-pool.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_BINDING_POOL(obj)       (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BINDING_POOL, 
ClutterBindingPool))
 #define CLUTTER_IS_BINDING_POOL(obj)    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BINDING_POOL))
 
-/**
- * ClutterBindingPool:
- *
- * Container of key bindings. The #ClutterBindingPool struct is
- * private.
- *
- * Since: 1.0
- */
 typedef struct _ClutterBindingPool      ClutterBindingPool;
 typedef struct _ClutterBindingPoolClass ClutterBindingPoolClass;
 
diff --git a/clutter/clutter/clutter-blur-effect.c b/clutter/clutter/clutter-blur-effect.c
index 33aa201bc7..b2974c869c 100644
--- a/clutter/clutter/clutter-blur-effect.c
+++ b/clutter/clutter/clutter-blur-effect.c
@@ -23,14 +23,14 @@
  */
 
 /**
- * SECTION:clutter-blur-effect
- * @short_description: A blur effect
- * @see_also: #ClutterEffect, #ClutterOffscreenEffect
+ * ClutterBlurEffect:
+ * 
+ * A blur effect
  *
  * #ClutterBlurEffect is a sub-class of #ClutterEffect that allows blurring a
  * actor and its contents.
  *
- * #ClutterBlurEffect is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #define CLUTTER_BLUR_EFFECT_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), CLUTTER_TYPE_BLUR_EFFECT, 
ClutterBlurEffectClass))
diff --git a/clutter/clutter/clutter-blur-effect.h b/clutter/clutter/clutter-blur-effect.h
index 0739a75bd0..7096a0ac3c 100644
--- a/clutter/clutter/clutter-blur-effect.h
+++ b/clutter/clutter/clutter-blur-effect.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_BLUR_EFFECT(obj)        (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BLUR_EFFECT, 
ClutterBlurEffect))
 #define CLUTTER_IS_BLUR_EFFECT(obj)     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BLUR_EFFECT))
 
-/**
- * ClutterBlurEffect:
- *
- * #ClutterBlurEffect is an opaque structure
- * whose members cannot be accessed directly
- *
- * Since: 1.4
- */
 typedef struct _ClutterBlurEffect       ClutterBlurEffect;
 typedef struct _ClutterBlurEffectClass  ClutterBlurEffectClass;
 
diff --git a/clutter/clutter/clutter-box-layout.c b/clutter/clutter/clutter-box-layout.c
index f263eb4d5c..901126198f 100644
--- a/clutter/clutter/clutter-box-layout.c
+++ b/clutter/clutter/clutter-box-layout.c
@@ -26,8 +26,9 @@
  */
 
 /**
- * SECTION:clutter-box-layout
- * @short_description: A layout manager arranging children on a single line
+ * ClutterBoxLayout:
+ * 
+ * A layout manager arranging children on a single line
  *
  * The #ClutterBoxLayout is a #ClutterLayoutManager implementing the
  * following layout policy:
@@ -44,7 +45,7 @@
  * It is possible to control the spacing between children of a
  * #ClutterBoxLayout by using clutter_box_layout_set_spacing().
  *
- * #ClutterBoxLayout is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-box-layout.h b/clutter/clutter/clutter-box-layout.h
index 35d61b6d12..98c08be2cd 100644
--- a/clutter/clutter/clutter-box-layout.h
+++ b/clutter/clutter/clutter-box-layout.h
@@ -47,14 +47,6 @@ typedef struct _ClutterBoxLayout                ClutterBoxLayout;
 typedef struct _ClutterBoxLayoutPrivate         ClutterBoxLayoutPrivate;
 typedef struct _ClutterBoxLayoutClass           ClutterBoxLayoutClass;
 
-/**
- * ClutterBoxLayout:
- *
- * The #ClutterBoxLayout structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.2
- */
 struct _ClutterBoxLayout
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-brightness-contrast-effect.c 
b/clutter/clutter/clutter-brightness-contrast-effect.c
index 7b7fdd183c..b9acccec55 100644
--- a/clutter/clutter/clutter-brightness-contrast-effect.c
+++ b/clutter/clutter/clutter-brightness-contrast-effect.c
@@ -23,14 +23,14 @@
  */
 
 /**
- * SECTION:clutter-brightness-contrast-effect
- * @short_description: Increase/decrease brightness and/or contrast of actor.
- * @see_also: #ClutterEffect, #ClutterOffscreenEffect
+ * ClutterBrightnessContrastEffect:
+ * 
+ * Increase/decrease brightness and/or contrast of actor.
  *
  * #ClutterBrightnessContrastEffect is a sub-class of #ClutterEffect that
  * changes the overall brightness of a #ClutterActor.
  *
- * #ClutterBrightnessContrastEffect is available since Clutter 1.10
+ * Since: 1.10
  */
 
 #define CLUTTER_BRIGHTNESS_CONTRAST_EFFECT_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), 
CLUTTER_TYPE_BRIGHTNESS_CONTRAST_EFFECT, ClutterBrightnessContrastEffectClass))
diff --git a/clutter/clutter/clutter-brightness-contrast-effect.h 
b/clutter/clutter/clutter-brightness-contrast-effect.h
index d474ed5b86..3e69e26150 100644
--- a/clutter/clutter/clutter-brightness-contrast-effect.h
+++ b/clutter/clutter/clutter-brightness-contrast-effect.h
@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define CLUTTER_BRIGHTNESS_CONTRAST_EFFECT(obj)     (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_BRIGHTNESS_CONTRAST_EFFECT, ClutterBrightnessContrastEffect))
 #define CLUTTER_IS_BRIGHTNESS_CONTRAST_EFFECT(obj)  (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_BRIGHTNESS_CONTRAST_EFFECT))
 
-/**
- * ClutterBrightnessContrastEffect:
- *
- * #ClutterBrightnessContrastEffect is an opaque structure
- * whose members cannot be directly accessed
- *
- * Since: 1.10
- */
 typedef struct _ClutterBrightnessContrastEffect         ClutterBrightnessContrastEffect;
 typedef struct _ClutterBrightnessContrastEffectClass    ClutterBrightnessContrastEffectClass;
 
diff --git a/clutter/clutter/clutter-cairo.c b/clutter/clutter/clutter-cairo.c
index 164eac310d..f030796230 100644
--- a/clutter/clutter/clutter-cairo.c
+++ b/clutter/clutter/clutter-cairo.c
@@ -40,13 +40,13 @@
  * Utility function for setting the source color of @cr using
  * a #ClutterColor. This function is the equivalent of:
  *
- * |[
+ * ```c
  *   cairo_set_source_rgba (cr,
  *                          color->red / 255.0,
  *                          color->green / 255.0,
  *                          color->blue / 255.0,
  *                          color->alpha / 255.0);
- * ]|
+ * ```
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter/clutter-canvas.c b/clutter/clutter/clutter-canvas.c
index a0c753d9fe..3c93384152 100644
--- a/clutter/clutter/clutter-canvas.c
+++ b/clutter/clutter/clutter-canvas.c
@@ -23,10 +23,9 @@
  */
 
 /**
- * SECTION:clutter-canvas
- * @Title: ClutterCanvas
- * @Short_Description: Content for 2D painting
- * @See_Also: #ClutterContent
+ * ClutterCanvas:
+ * 
+ * Content for 2D painting
  *
  * The #ClutterCanvas class is a #ClutterContent implementation that allows
  * drawing using the Cairo API on a 2D surface.
@@ -39,7 +38,7 @@
  * See [canvas.c](https://git.gnome.org/browse/clutter/tree/examples/canvas.c?h=clutter-1.18)
  * for an example of how to use #ClutterCanvas.
  *
- * #ClutterCanvas is available since Clutter 1.10.
+ * Since: 1.10.
  */
 
 #include "clutter-build-config.h"
@@ -575,10 +574,10 @@ clutter_canvas_invalidate_internal (ClutterCanvas *canvas,
  * the size, you can use the return value of the function to conditionally
  * call clutter_content_invalidate():
  *
- * |[
+ * ```c
  *   if (!clutter_canvas_set_size (canvas, width, height))
  *     clutter_content_invalidate (CLUTTER_CONTENT (canvas));
- * ]|
+ * ```
  *
  * Return value: this function returns %TRUE if the size change
  *   caused a content invalidation, and %FALSE otherwise
diff --git a/clutter/clutter/clutter-canvas.h b/clutter/clutter/clutter-canvas.h
index ed13f49e3b..f7d88f2707 100644
--- a/clutter/clutter/clutter-canvas.h
+++ b/clutter/clutter/clutter-canvas.h
@@ -44,15 +44,6 @@ typedef struct _ClutterCanvas           ClutterCanvas;
 typedef struct _ClutterCanvasPrivate    ClutterCanvasPrivate;
 typedef struct _ClutterCanvasClass      ClutterCanvasClass;
 
-/**
- * ClutterCanvas:
- *
- * The #ClutterCanvas structure contains
- * private data and should only be accessed using the provided
- * API.
- *
- * Since: 1.10
- */
 struct _ClutterCanvas
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-child-meta.c b/clutter/clutter/clutter-child-meta.c
index b0fe5611fd..03d61dc9b4 100644
--- a/clutter/clutter/clutter-child-meta.c
+++ b/clutter/clutter/clutter-child-meta.c
@@ -25,16 +25,45 @@
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
+
 /**
- * SECTION:clutter-child-meta
- * @short_description: Wrapper for actors inside a container
+ * ClutterChildMeta:
+ * 
+ * Base interface for container specific state for child actors.
+ * 
+ * A child data is meant to be used when you need to keep track 
+ * of information about each individual child added to a container.
+ *
+ * In order to use it you should create your own subclass of
+ * #ClutterChildMeta and set the #ClutterContainerIface child_meta_type
+ * interface member to your subclass type, like:
+ *
+ * ```c
+ * static void
+ * my_container_iface_init (ClutterContainerIface *iface)
+ * {
+ *   // set the rest of the #ClutterContainer vtable
  *
- * #ClutterChildMeta is a wrapper object created by #ClutterContainer
- * implementations in order to store child-specific data and properties.
+ *   container_iface->child_meta_type  = MY_TYPE_CHILD_META;
+ * }
+ * ```
  *
- * A #ClutterChildMeta wraps a #ClutterActor inside a #ClutterContainer.
+ * This will automatically create a #ClutterChildMeta of type
+ * `MY_TYPE_CHILD_META` for every actor that is added to the container.
  *
- * #ClutterChildMeta is available since Clutter 0.8
+ * The child data for an actor can be retrieved using the
+ * clutter_container_get_child_meta() function.
+ * 
+ * The properties of the data and your subclass can be manipulated with
+ * clutter_container_child_set() and clutter_container_child_get() which
+ * act like g_object_set() and g_object_get().
+ *
+ * You can provide hooks for your own storage as well as control the
+ * instantiation by overriding the #ClutterContainerIface virtual functions
+ * #ClutterContainerIface.create_child_meta(), #ClutterContainerIface.destroy_child_meta(),
+ * and #ClutterContainerIface.get_child_meta().
+ *
+ * Since: 0.8
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-child-meta.h b/clutter/clutter/clutter-child-meta.h
index 1c473bd32f..b67e9a14d9 100644
--- a/clutter/clutter/clutter-child-meta.h
+++ b/clutter/clutter/clutter-child-meta.h
@@ -46,46 +46,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterChildMetaClass           ClutterChildMetaClass;
 
-/**
- * ClutterChildMeta:
- * @container: the container handling this data
- * @actor: the actor wrapped by this data
- * 
- * Base interface for container specific state for child actors. A child
- * data is meant to be used when you need to keep track of information
- * about each individual child added to a container.
- *
- * In order to use it you should create your own subclass of
- * #ClutterChildMeta and set the #ClutterContainerIface child_meta_type
- * interface member to your subclass type, like:
- *
- * |[
- * static void
- * my_container_iface_init (ClutterContainerIface *iface)
- * {
- *   // set the rest of the #ClutterContainer vtable
- *
- *   container_iface->child_meta_type  = MY_TYPE_CHILD_META;
- * }
- * ]|
- *
- * This will automatically create a #ClutterChildMeta of type
- * `MY_TYPE_CHILD_META` for every actor that is added to the container.
- *
- * The child data for an actor can be retrieved using the
- * clutter_container_get_child_meta() function.
- * 
- * The properties of the data and your subclass can be manipulated with
- * clutter_container_child_set() and clutter_container_child_get() which
- * act like g_object_set() and g_object_get().
- *
- * You can provide hooks for your own storage as well as control the
- * instantiation by overriding the #ClutterContainerIface virtual functions
- * #ClutterContainerIface.create_child_meta(), #ClutterContainerIface.destroy_child_meta(),
- * and #ClutterContainerIface.get_child_meta().
- *
- * Since: 0.8
- */
 struct _ClutterChildMeta
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-click-action.c b/clutter/clutter/clutter-click-action.c
index a4e33cc4a6..0b2c912fd3 100644
--- a/clutter/clutter/clutter-click-action.c
+++ b/clutter/clutter/clutter-click-action.c
@@ -23,39 +23,39 @@
  */
 
 /**
- * SECTION:clutter-click-action
- * @Title: ClutterClickAction
- * @Short_Description: Action for clickable actors
+ * ClutterClickAction:
+ * 
+ * Action for clickable actors
  *
- * #ClutterClickAction is a sub-class of #ClutterAction that implements
+ * #ClutterClickAction is a sub-class of [class@Action] that implements
  * the logic for clickable actors, by using the low level events of
- * #ClutterActor, such as #ClutterActor::button-press-event and
- * #ClutterActor::button-release-event, to synthesize the high level
- * #ClutterClickAction::clicked signal.
+ * [class@Actor], such as [signal@Actor::button-press-event] and
+ * [signal@Actor::button-release-event], to synthesize the high level
+ * [signal@ClickAction::clicked] signal.
  *
- * To use #ClutterClickAction you just need to apply it to a #ClutterActor
- * using clutter_actor_add_action() and connect to the
- * #ClutterClickAction::clicked signal:
+ * To use #ClutterClickAction you just need to apply it to a [class@Actor]
+ * using [method@Actor.add_action] and connect to the
+ * [signal@ClickAction::clicked] signal:
  *
- * |[
+ * ```c
  *   ClutterAction *action = clutter_click_action_new ();
  *
  *   clutter_actor_add_action (actor, action);
  *
  *   g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), NULL);
- * ]|
+ * ```
  *
  * #ClutterClickAction also supports long press gestures: a long press is
  * activated if the pointer remains pressed within a certain threshold (as
- * defined by the #ClutterClickAction:long-press-threshold property) for a
+ * defined by the [property@ClickAction:long-press-threshold] property) for a
  * minimum amount of time (as the defined by the
- * #ClutterClickAction:long-press-duration property).
- * The #ClutterClickAction::long-press signal is emitted multiple times,
- * using different #ClutterLongPressState values; to handle long presses
- * you should connect to the #ClutterClickAction::long-press signal and
+ * [property@ClickAction:long-press-duration] property).
+ * The [signal@ClickAction::long-press] signal is emitted multiple times,
+ * using different [enum@LongPressState] values; to handle long presses
+ * you should connect to the [signal@ClickAction::long-press] signal and
  * handle the different states:
  *
- * |[
+ * ```c
  *   static gboolean
  *   on_long_press (ClutterClickAction    *action,
  *                  ClutterActor          *actor,
@@ -64,32 +64,29 @@
  *     switch (state)
  *       {
  *       case CLUTTER_LONG_PRESS_QUERY:
- *         /&ast; return TRUE if the actor should support long press
- *          &ast; gestures, and FALSE otherwise; this state will be
- *          &ast; emitted on button presses
- *          &ast;/
+ *         // return TRUE if the actor should support long press
+ *         // gestures, and FALSE otherwise; this state will be
+ *         // emitted on button presses
  *         return TRUE;
  *
  *       case CLUTTER_LONG_PRESS_ACTIVATE:
- *         /&ast; this state is emitted if the minimum duration has
- *          &ast; been reached without the gesture being cancelled.
- *          &ast; the return value is not used
- *          &ast;/
+ *         // this state is emitted if the minimum duration has
+ *         // been reached without the gesture being cancelled.
+ *         // the return value is not used
  *         return TRUE;
  *
  *       case CLUTTER_LONG_PRESS_CANCEL:
- *         /&ast; this state is emitted if the long press was cancelled;
- *          &ast; for instance, the pointer went outside the actor or the
- *          &ast; allowed threshold, or the button was released before
- *          &ast; the minimum duration was reached. the return value is
- *          &ast; not used
- *          &ast;/
+ *         // this state is emitted if the long press was cancelled;
+ *         // for instance, the pointer went outside the actor or the
+ *         // allowed threshold, or the button was released before
+ *         // the minimum duration was reached. the return value is
+ *         // not used
  *         return FALSE;
  *       }
  *   }
- * ]|
+ * ```
  *
- * #ClutterClickAction is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -578,7 +575,7 @@ clutter_click_action_class_init (ClutterClickActionClass *klass)
    * press gesture, in milliseconds.
    *
    * A value of -1 will make the #ClutterClickAction use the value of
-   * the #ClutterSettings:long-press-duration property.
+   * the [property@Settings:long-press-duration] property.
    *
    * Since: 1.8
    */
@@ -597,7 +594,7 @@ clutter_click_action_class_init (ClutterClickActionClass *klass)
    * a long press gesture is cancelled, in pixels.
    *
    * A value of -1 will make the #ClutterClickAction use the value of
-   * the #ClutterSettings:dnd-drag-threshold property.
+   * the [property@Settings:dnd-drag-threshold] property.
    *
    * Since: 1.8
    */
@@ -618,7 +615,7 @@ clutter_click_action_class_init (ClutterClickActionClass *klass)
    * @action: the #ClutterClickAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::clicked signal is emitted when the #ClutterActor to which
+   * The signal is emitted when the [class@Actor] to which
    * a #ClutterClickAction has been applied should respond to a
    * pointer button press and release events
    *
@@ -639,7 +636,7 @@ clutter_click_action_class_init (ClutterClickActionClass *klass)
    * @actor: the #ClutterActor attached to the @action
    * @state: the long press state
    *
-   * The ::long-press signal is emitted during the long press gesture
+   * The signal is emitted during the long press gesture
    * handling.
    *
    * This signal can be emitted multiple times with different states.
@@ -653,7 +650,7 @@ clutter_click_action_class_init (ClutterClickActionClass *klass)
    * %CLUTTER_LONG_PRESS_CANCEL state if the long press was cancelled.
    *
    * It is possible to forcibly cancel a long press detection using
-   * clutter_click_action_release().
+   * [method@ClickAction.release].
    *
    * Return value: Only the %CLUTTER_LONG_PRESS_QUERY state uses the
    *   returned value of the handler; other states will ignore it
@@ -702,7 +699,7 @@ clutter_click_action_new (void)
  * @action: a #ClutterClickAction
  *
  * Emulates a release of the pointer button, which ungrabs the pointer
- * and unsets the #ClutterClickAction:pressed state.
+ * and unsets the [property@ClickAction:pressed] state.
  *
  * This function will also cancel the long press gesture if one was
  * initiated.
diff --git a/clutter/clutter/clutter-clone.c b/clutter/clutter/clutter-clone.c
index 42e3e07cdb..3e1d99602f 100644
--- a/clutter/clutter/clutter-clone.c
+++ b/clutter/clutter/clutter-clone.c
@@ -22,8 +22,9 @@
  */
 
 /**
- * SECTION:clutter-clone
- * @short_description: An actor that displays a clone of a source actor
+ * ClutterClone:
+ * 
+ * An actor that displays a clone of a source actor
  *
  * #ClutterClone is a #ClutterActor which draws with the paint
  * function of another actor, scaled to fit its own allocation.
@@ -34,7 +35,7 @@
  * the presence of support for FBOs in the underlying GL or GLES
  * implementation.
  *
- * #ClutterClone is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-clone.h b/clutter/clutter/clutter-clone.h
index ce4e6f43f9..d7faf4eeb8 100644
--- a/clutter/clutter/clutter-clone.h
+++ b/clutter/clutter/clutter-clone.h
@@ -43,14 +43,6 @@ typedef struct _ClutterClone            ClutterClone;
 typedef struct _ClutterCloneClass       ClutterCloneClass;
 typedef struct _ClutterClonePrivate     ClutterClonePrivate;
 
-/**
- * ClutterClone:
- *
- * The #ClutterClone structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.0
- */
 struct _ClutterClone
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-color.c b/clutter/clutter/clutter-color.c
index ddd41a253f..c72a089244 100644
--- a/clutter/clutter/clutter-color.c
+++ b/clutter/clutter/clutter-color.c
@@ -21,18 +21,6 @@
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * SECTION:clutter-color
- * @short_description: Color management and manipulation.
- *
- * #ClutterColor is a simple type for representing colors in Clutter.
- *
- * A #ClutterColor is expressed as a 4-tuple of values ranging from
- * zero to 255, one for each color channel plus one for the alpha.
- *
- * The alpha channel is fully opaque at 255 and fully transparent at 0.
- */
-
 #include "clutter-build-config.h"
 
 #include <math.h>
@@ -803,10 +791,10 @@ clutter_color_to_string (const ClutterColor *color)
  * @v1: (type Clutter.Color): a #ClutterColor
  * @v2: (type Clutter.Color): a #ClutterColor
  *
- * Compares two #ClutterColor<!-- -->s and checks if they are the same.
+ * Compares two `ClutterColor`s and checks if they are the same.
  *
  * This function can be passed to g_hash_table_new() as the @key_equal_func
- * parameter, when using #ClutterColor<!-- -->s as keys in a #GHashTable.
+ * parameter, when using `ClutterColor`s as keys in a #GHashTable.
  *
  * Return value: %TRUE if the two colors are the same.
  *
@@ -840,7 +828,7 @@ clutter_color_equal (gconstpointer v1,
  * Converts a #ClutterColor to a hash value.
  *
  * This function can be passed to g_hash_table_new() as the @hash_func
- * parameter, when using #ClutterColor<!-- -->s as keys in a #GHashTable.
+ * parameter, when using `ClutterColor`s as keys in a #GHashTable.
  *
  * Return value: a hash value corresponding to the color
  *
@@ -859,7 +847,7 @@ clutter_color_hash (gconstpointer v)
  * @progress: the interpolation progress
  * @result: (out): return location for the interpolation
  *
- * Interpolates between @initial and @final #ClutterColor<!-- -->s
+ * Interpolates between @initial and @final `ClutterColor`s
  * using @progress
  *
  * Since: 1.6
@@ -942,9 +930,9 @@ clutter_color_free (ClutterColor *color)
  *
  * This function is the equivalent of:
  *
- * |[
+ * ```c
  *   clutter_color_init (clutter_color_alloc (), red, green, blue, alpha);
- * ]|
+ * ```
  *
  * Return value: (transfer full): the newly allocated color.
  *   Use clutter_color_free() when done
diff --git a/clutter/clutter/clutter-color.h b/clutter/clutter/clutter-color.h
index cff4937899..232afcce09 100644
--- a/clutter/clutter/clutter-color.h
+++ b/clutter/clutter/clutter-color.h
@@ -43,7 +43,12 @@ G_BEGIN_DECLS
  * @blue: blue component, between 0 and 255
  * @alpha: alpha component, between 0 and 255
  *
- * Color representation.
+ * A simple type for representing colors.
+ *
+ * A #ClutterColor is expressed as a 4-tuple of values ranging from
+ * zero to 255, one for each color channel plus one for the alpha.
+ *
+ * The alpha channel is fully opaque at 255 and fully transparent at 0.
  */
 struct _ClutterColor
 {
@@ -151,7 +156,7 @@ void          clutter_color_interpolate (const ClutterColor *initial,
  * CLUTTER_VALUE_HOLDS_COLOR:
  * @x: a #GValue
  *
- * Evaluates to %TRUE if @x holds a #ClutterColor<!-- -->.
+ * Evaluates to %TRUE if @x holds a `ClutterColor`.
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter/clutter-colorize-effect.c b/clutter/clutter/clutter-colorize-effect.c
index 50ac90a677..84c7f4831c 100644
--- a/clutter/clutter/clutter-colorize-effect.c
+++ b/clutter/clutter/clutter-colorize-effect.c
@@ -23,14 +23,14 @@
  */
 
 /**
- * SECTION:clutter-colorize-effect
- * @short_description: A colorization effect
- * @see_also: #ClutterEffect, #ClutterOffscreenEffect
+ * ClutterColorizeEffect:
+ * 
+ * A colorization effect
  *
  * #ClutterColorizeEffect is a sub-class of #ClutterEffect that
  * colorizes an actor with the given tint.
  *
- * #ClutterColorizeEffect is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #define CLUTTER_COLORIZE_EFFECT_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), 
CLUTTER_TYPE_COLORIZE_EFFECT, ClutterColorizeEffectClass))
diff --git a/clutter/clutter/clutter-colorize-effect.h b/clutter/clutter/clutter-colorize-effect.h
index 92e878735e..817d58a77e 100644
--- a/clutter/clutter/clutter-colorize-effect.h
+++ b/clutter/clutter/clutter-colorize-effect.h
@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define CLUTTER_COLORIZE_EFFECT(obj)    (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_COLORIZE_EFFECT, 
ClutterColorizeEffect))
 #define CLUTTER_IS_COLORIZE_EFFECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_COLORIZE_EFFECT))
 
-/**
- * ClutterColorizeEffect:
- *
- * #ClutterColorizeEffect is an opaque structure
- * whose members cannot be directly accessed
- *
- * Since: 1.4
- */
 typedef struct _ClutterColorizeEffect           ClutterColorizeEffect;
 typedef struct _ClutterColorizeEffectClass      ClutterColorizeEffectClass;
 
diff --git a/clutter/clutter/clutter-constraint.c b/clutter/clutter/clutter-constraint.c
index fc05907447..114935cc1a 100644
--- a/clutter/clutter/clutter-constraint.c
+++ b/clutter/clutter/clutter-constraint.c
@@ -23,10 +23,9 @@
  */
 
 /**
- * SECTION:clutter-constraint
- * @Title: ClutterConstraint
- * @Short_Description: Abstract class for constraints on position or size
- * @See_Also: #ClutterAction
+ * ClutterConstraint:
+ * 
+ * Abstract class for constraints on position or size
  *
  * #ClutterConstraint is a base abstract class for modifiers of a #ClutterActor
  * position or size.
@@ -37,8 +36,6 @@
  * allocation of the actor to which they are applied by overriding the
  * #ClutterConstraintClass.update_allocation() virtual function.
  *
- * #ClutterConstraint is available since Clutter 1.4
- *
  * ## Using Constraints
  *
  * Constraints can be used with fixed layout managers, like
@@ -126,6 +123,8 @@
  * call clutter_actor_queue_relayout() on the actor to which it is attached
  * to whenever any parameter is changed. The actor to which it is attached
  * can be recovered at any point using clutter_actor_meta_get_actor().
+ * 
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-constraint.h b/clutter/clutter/clutter-constraint.h
index 420e7de75b..a58768ab51 100644
--- a/clutter/clutter/clutter-constraint.h
+++ b/clutter/clutter/clutter-constraint.h
@@ -42,14 +42,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterConstraintClass          ClutterConstraintClass;
 
-/**
- * ClutterConstraint:
- *
- * The #ClutterConstraint structure contains only
- * private data and should be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _ClutterConstraint
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-container.c b/clutter/clutter/clutter-container.c
index 7d129fcfbe..7ae9d0243b 100644
--- a/clutter/clutter/clutter-container.c
+++ b/clutter/clutter/clutter-container.c
@@ -63,20 +63,16 @@
         } G_STMT_END
 
 /**
- * SECTION:clutter-container
- * @short_description: An interface for container actors
+ * ClutterContainer:
+ * 
+ * An interface for container actors
  *
- * #ClutterContainer is an interface implemented by #ClutterActor, and
+ * #ClutterContainer is an interface implemented by [class@Actor], and
  * it provides some common API for notifying when a child actor is added
  * or removed, as well as the infrastructure for accessing child properties
- * through #ClutterChildMeta.
- *
- * Until Clutter 1.10, the #ClutterContainer interface was also the public
- * API for implementing container actors; this part of the interface has
- * been deprecated: #ClutterContainer has a default implementation which
- * defers to #ClutterActor the child addition and removal, as well as the
- * iteration. See the documentation of #ClutterContainerIface for the list
- * of virtual functions that should be overridden.
+ * through [class@ChildMeta].
+ * 
+ * Since: 0.4
  */
 
 enum
@@ -132,7 +128,7 @@ clutter_container_default_init (ClutterContainerInterface *iface)
    * @container: the actor which received the signal
    * @actor: the new child that has been added to @container
    *
-   * The ::actor-added signal is emitted each time an actor
+   * The signal is emitted each time an actor
    * has been added to @container.
    *
    * Since: 0.4
@@ -150,7 +146,7 @@ clutter_container_default_init (ClutterContainerInterface *iface)
    * @container: the actor which received the signal
    * @actor: the child that has been removed from @container
    *
-   * The ::actor-removed signal is emitted each time an actor
+   * The signal is emitted each time an actor
    * is removed from @container.
    *
    * Since: 0.4
@@ -170,7 +166,7 @@ clutter_container_default_init (ClutterContainerInterface *iface)
    * @actor: the child that has had a property set
    * @pspec: (type GParamSpec): the #GParamSpec of the property set
    *
-   * The ::child-notify signal is emitted each time a property is
+   * The signal is emitted each time a property is
    * being set through the clutter_container_child_set() and
    * clutter_container_child_set_property() calls.
    *
@@ -301,7 +297,7 @@ container_remove_valist (ClutterContainer *container,
  * @first_actor: the first #ClutterActor to add
  * @...: %NULL terminated list of actors to add
  *
- * Adds a list of #ClutterActor<!-- -->s to @container. Each time and
+ * Adds a list of `ClutterActor`s to @container. Each time and
  * actor is added, the "actor-added" signal is emitted. Each actor should
  * be parented to @container, which takes a reference on the actor. You
  * cannot add a #ClutterActor to more than one #ClutterContainer.
@@ -363,7 +359,7 @@ clutter_container_add_actor (ClutterContainer *container,
  * @first_actor: first #ClutterActor to remove
  * @...: a %NULL-terminated list of actors to remove
  *
- * Removes a %NULL terminated list of #ClutterActor<!-- -->s from
+ * Removes a %NULL terminated list of `ClutterActor`s from
  * @container. Each actor should be unparented, so if you want to keep it
  * around you must hold a reference to it yourself, using g_object_ref().
  * Each time an actor is removed, the "actor-removed" signal is
@@ -541,7 +537,7 @@ destroy_child_meta (ClutterContainer *container,
  *
  * Return value: (transfer none): the #ClutterChildMeta for the @actor child
  *   of @container or %NULL if the specifiec actor does not exist or the
- *   container is not configured to provide #ClutterChildMeta<!-- -->s
+ *   container is not configured to provide `ClutterChildMeta`s
  *
  * Since: 0.8
  */
@@ -678,7 +674,7 @@ clutter_container_class_find_child_property (GObjectClass *klass,
  * Returns an array of #GParamSpec for all child properties.
  *
  * Return value: (array length=n_properties) (transfer full): an array
- *   of #GParamSpec<!-- -->s which should be freed after use.
+ *   of `GParamSpec`s which should be freed after use.
  *
  * Since: 0.8
  */
diff --git a/clutter/clutter/clutter-container.h b/clutter/clutter/clutter-container.h
index cf263fe5e9..6ecce0e7d4 100644
--- a/clutter/clutter/clutter-container.h
+++ b/clutter/clutter/clutter-container.h
@@ -44,15 +44,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterContainerIface   ClutterContainerIface;
 
-/**
- * ClutterContainer:
- *
- * #ClutterContainer is an opaque structure whose members cannot be directly
- * accessed
- *
- * Since: 0.4
- */
-
 /**
  * ClutterContainerIface:
  * @add: virtual function for adding an actor to the container. This virtual
diff --git a/clutter/clutter/clutter-content.c b/clutter/clutter/clutter-content.c
index 92f485d74c..3160e034ec 100644
--- a/clutter/clutter/clutter-content.c
+++ b/clutter/clutter/clutter-content.c
@@ -23,17 +23,17 @@
  */
 
 /**
- * SECTION:clutter-content
- * @Title: ClutterContent
- * @Short_Description: Delegate for painting the content of an actor
+ * ClutterContent:
+ * 
+ * Delegate for painting the content of an actor
  *
  * #ClutterContent is an interface to implement types responsible for
- * painting the content of a #ClutterActor.
+ * painting the content of a [class@Actor].
  *
  * Multiple actors can use the same #ClutterContent instance, in order
  * to share the resources associated with painting the same content.
  *
- * #ClutterContent is available since Clutter 1.10.
+ * Since: 1.10.
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-deform-effect.c b/clutter/clutter/clutter-deform-effect.c
index 039ce014bb..9f86d386ed 100644
--- a/clutter/clutter/clutter-deform-effect.c
+++ b/clutter/clutter/clutter-deform-effect.c
@@ -26,10 +26,9 @@
  */
 
 /**
- * SECTION:clutter-deform-effect
- * @Title: ClutterDeformEffect
- * @Short_Description: A base class for effects deforming the geometry
- *   of an actor
+ * ClutterDeformEffect:
+ * 
+ * A base class for effects deforming the geometry of an actor
  *
  * #ClutterDeformEffect is an abstract class providing all the plumbing
  * for creating effects that result in the deformation of an actor's
@@ -39,8 +38,6 @@
  * a #ClutterActor and then the Cogl vertex buffers API to submit the
  * geometry to the GPU.
  *
- * #ClutterDeformEffect is available since Clutter 1.4
- *
  * ## Implementing ClutterDeformEffect
  *
  * Sub-classes of #ClutterDeformEffect should override the
@@ -49,6 +46,8 @@
  * Each passed vertex is an in-out parameter that initially contains the
  * position of the vertex and should be modified according to a specific
  * deformation algorithm.
+ * 
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -803,7 +802,7 @@ clutter_deform_effect_get_n_tiles (ClutterDeformEffect *effect,
  * clutter_deform_effect_invalidate:
  * @effect: a #ClutterDeformEffect
  *
- * Invalidates the @effect<!-- -->'s vertices and, if it is associated
+ * Invalidates the `effect`'s vertices and, if it is associated
  * to an actor, it will queue a redraw
  *
  * Since: 1.4
diff --git a/clutter/clutter/clutter-deform-effect.h b/clutter/clutter/clutter-deform-effect.h
index bc0fa210da..d439618247 100644
--- a/clutter/clutter/clutter-deform-effect.h
+++ b/clutter/clutter/clutter-deform-effect.h
@@ -45,14 +45,6 @@ typedef struct _ClutterDeformEffect             ClutterDeformEffect;
 typedef struct _ClutterDeformEffectPrivate      ClutterDeformEffectPrivate;
 typedef struct _ClutterDeformEffectClass        ClutterDeformEffectClass;
 
-/**
- * ClutterDeformEffect:
- *
- * The #ClutterDeformEffect structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _ClutterDeformEffect
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-desaturate-effect.c b/clutter/clutter/clutter-desaturate-effect.c
index 16824782fa..fbc394e8c5 100644
--- a/clutter/clutter/clutter-desaturate-effect.c
+++ b/clutter/clutter/clutter-desaturate-effect.c
@@ -23,16 +23,16 @@
  */
 
 /**
- * SECTION:clutter-desaturate-effect
- * @short_description: A desaturation effect
- * @see_also: #ClutterEffect, #ClutterOffscreenEffect
+ * ClutterDesaturateEffect:
+ * 
+ * A desaturation effect
  *
  * #ClutterDesaturateEffect is a sub-class of #ClutterEffect that
  * desaturates the color of an actor and its contents. The strength
  * of the desaturation effect is controllable and animatable through
  * the #ClutterDesaturateEffect:factor property.
  *
- * #ClutterDesaturateEffect is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #define CLUTTER_DESATURATE_EFFECT_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), 
CLUTTER_TYPE_DESATURATE_EFFECT, ClutterDesaturateEffectClass))
diff --git a/clutter/clutter/clutter-desaturate-effect.h b/clutter/clutter/clutter-desaturate-effect.h
index b832dbaca9..f4c17b1dc5 100644
--- a/clutter/clutter/clutter-desaturate-effect.h
+++ b/clutter/clutter/clutter-desaturate-effect.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_DESATURATE_EFFECT(obj)          (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_DESATURATE_EFFECT, ClutterDesaturateEffect))
 #define CLUTTER_IS_DESATURATE_EFFECT(obj)       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_DESATURATE_EFFECT))
 
-/**
- * ClutterDesaturateEffect:
- *
- * #ClutterDesaturateEffect is an opaque structure
- * whose members cannot be directly accessed
- *
- * Since: 1.4
- */
 typedef struct _ClutterDesaturateEffect         ClutterDesaturateEffect;
 typedef struct _ClutterDesaturateEffectClass    ClutterDesaturateEffectClass;
 
diff --git a/clutter/clutter/clutter-effect.c b/clutter/clutter/clutter-effect.c
index 012037f614..9558a82ef1 100644
--- a/clutter/clutter/clutter-effect.c
+++ b/clutter/clutter/clutter-effect.c
@@ -23,8 +23,9 @@
  */
 
 /**
- * SECTION:clutter-effect
- * @short_description: Base class for actor effects
+ * ClutterEffect:
+ * 
+ * Base class for actor effects
  *
  * The #ClutterEffect class provides a default type and API for creating
  * effects for generic actors.
@@ -42,7 +43,7 @@
  * #ClutterEffectClass.paint() method. The implementation of the function should look
  * something like this:
  *
- * |[
+ * ```c
  * void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags)
  * {
  *   // Set up initialisation of the paint such as binding a
@@ -58,7 +59,7 @@
  *
  *   // perform any cleanup of state, such as popping the CoglOffscreen
  * }
- * ]|
+ * ```
  *
  * The effect can optionally avoid calling clutter_actor_continue_paint() to skip any
  * further stages of the paint sequence. This is useful for example if the effect
@@ -79,7 +80,7 @@
  * will paint the first material using cogl_rectangle(), before continuing and then it
  * will paint paint the second material after.
  *
- *  |[
+ * ```c
  *  typedef struct {
  *    ClutterEffect parent_instance;
  *
@@ -155,9 +156,9 @@
  *
  *    klass->paint = my_effect_paint;
  *  }
- * ]|
+ * ```
  *
- * #ClutterEffect is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-effect.h b/clutter/clutter/clutter-effect.h
index 8969fcd784..82ab7f2c16 100644
--- a/clutter/clutter/clutter-effect.h
+++ b/clutter/clutter/clutter-effect.h
@@ -44,14 +44,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterEffectClass      ClutterEffectClass;
 
-/**
- * ClutterEffect:
- *
- * The #ClutterEffect structure contains only private data and should
- * be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _ClutterEffect
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-enums.h b/clutter/clutter/clutter-enums.h
index 6a4734d885..157c2a2496 100644
--- a/clutter/clutter/clutter-enums.h
+++ b/clutter/clutter/clutter-enums.h
@@ -43,9 +43,11 @@ G_BEGIN_DECLS
  * @CLUTTER_GRAVITY_NORTH_WEST: Scale from the top left corner
  * @CLUTTER_GRAVITY_CENTER: Scale from the center.
  *
- * Gravity of the scaling operations. When a gravity different than
- * %CLUTTER_GRAVITY_NONE is used, an actor is scaled keeping the position
- * of the specified portion at the same coordinates.
+ * Gravity of the scaling operations.
+ * 
+ * When a gravity different than %CLUTTER_GRAVITY_NONE is used, 
+ * an actor is scaled keeping the position of the specified portion 
+ * at the same coordinates.
  *
  * Since: 0.2
  *
@@ -190,8 +192,9 @@ typedef enum /*< prefix=CLUTTER_REQUEST >*/
  * @CLUTTER_ANIMATION_LAST: last animation mode, used as a guard for
  *   registered global alpha functions
  *
- * The animation modes used by #ClutterAnimatable. This
- * enumeration can be expanded in later versions of Clutter.
+ * The animation modes used by [iface@Animatable]. 
+ * 
+ * This enumeration can be expanded in later versions of Clutter.
  *
  * <figure id="easing-modes">
  *   <title>Easing modes provided by Clutter</title>
@@ -284,7 +287,7 @@ typedef enum
  * @CLUTTER_TEXT_DIRECTION_LTR: Use left-to-right text direction
  * @CLUTTER_TEXT_DIRECTION_RTL: Use right-to-left text direction
  *
- * The text direction to be used by #ClutterActor<!-- -->s
+ * The text direction to be used by [class@Actor]s
  *
  * Since: 1.2
  */
@@ -1338,8 +1341,8 @@ typedef enum
  *   mipmap generation; this filter linearly interpolates on every axis,
  *   as well as between mipmap levels.
  *
- * The scaling filters to be used with the #ClutterActor:minification-filter
- * and #ClutterActor:magnification-filter properties.
+ * The scaling filters to be used with the [property@Actor:minification-filter]
+ * and [property@Actor:magnification-filter] properties.
  *
  * Since: 1.10
  */
@@ -1472,7 +1475,7 @@ typedef enum
  * the gesture must begin immediately and that it must be cancelled
  * once the drag exceed the configured threshold.
  *
- * Enum passed to the clutter_gesture_action_set_threshold_trigger_edge()
+ * Enum passed to the [method@GestureAction.set_threshold_trigger_edge]
  * function.
  *
  * Since: 1.18
@@ -1493,9 +1496,11 @@ typedef enum
  * @CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL: The gesture was cancelled, all
  *   changes should be undone.
  *
- * The phase of a touchpad gesture event. All gestures are guaranteed to
- * begin with an event of type %CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN,
- * followed by a number of %CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE (possibly 0).
+ * The phase of a touchpad gesture event. 
+ * 
+ * All gestures are guaranteed to begin with an event of type 
+ * %CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by a number
+ * of %CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE (possibly 0).
  *
  * A finished gesture may have 2 possible outcomes, an event with phase
  * %CLUTTER_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is
@@ -1531,9 +1536,10 @@ typedef enum
  * @CLUTTER_SCROLL_SOURCE_CONTINUOUS: The scroll event is originated by the
  *   motion of some device (eg. a scroll button is set).
  *
- * The scroll source determines the source of the scroll event. Keep in mind
- * that the source device #ClutterInputDeviceType is not enough to infer
- * the scroll source.
+ * The scroll source determines the source of the scroll event. 
+ * 
+ * Keep in mind that the source device #ClutterInputDeviceType is not enough
+ * to infer the scroll source.
  *
  * Since: 1.26
  */
@@ -1552,6 +1558,7 @@ typedef enum
  * @CLUTTER_SCROLL_FINISHED_VERTICAL: The vertical axis stopped.
  *
  * Flags used to notify the axes that were stopped in a #ClutterScrollEvent.
+ * 
  * These can be used to trigger post-scroll effects like kinetic scrolling.
  *
  * Since: 1.26
diff --git a/clutter/clutter/clutter-event.c b/clutter/clutter/clutter-event.c
index 0433a1ec98..1092929bf8 100644
--- a/clutter/clutter/clutter-event.c
+++ b/clutter/clutter/clutter-event.c
@@ -33,16 +33,6 @@
 
 #include <math.h>
 
-/**
- * SECTION:clutter-event
- * @short_description: User and window system events
- *
- * Windowing events handled by Clutter.
- *
- * The events usually come from the windowing backend, but can also
- * be synthesized by Clutter itself or by the application code.
- */
-
 typedef struct _ClutterEventPrivate {
   ClutterEvent base;
 
diff --git a/clutter/clutter/clutter-event.h b/clutter/clutter/clutter-event.h
index b9a7d27e8c..df9925e60c 100644
--- a/clutter/clutter/clutter-event.h
+++ b/clutter/clutter/clutter-event.h
@@ -412,8 +412,9 @@ struct _ClutterTouchEvent
  *   represented by positive deltas
  * @scale: the current scale
  *
- * Used for touchpad pinch gesture events. The current state of the
- * gesture will be determined by the @phase field.
+ * Used for touchpad pinch gesture events.
+ * 
+ * The current state of the gesture will be determined by the @phase field.
  *
  * Each event with phase %CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN
  * will report a @scale of 1.0, all later phases in the gesture
@@ -459,8 +460,9 @@ struct _ClutterTouchpadPinchEvent
  * @dy_unaccel: unaccelerated movement delta of the swipe center
  *   point in the Y axis
  *
- * Used for touchpad swipe gesture events. The current state of the
- * gesture will be determined by the @phase field.
+ * Used for touchpad swipe gesture events.
+ * 
+ * The current state of the gesture will be determined by the @phase field.
  *
  * Since: 1.24
  */
@@ -493,8 +495,9 @@ struct _ClutterTouchpadSwipeEvent
  * @x: the X coordinate of the pointer, relative to the stage
  * @y: the Y coordinate of the pointer, relative to the stage
  *
- * Used for touchpad hold gesture events. The current state of the
- * gesture will be determined by the @phase field.
+ * Used for touchpad hold gesture events.
+ * 
+ * The current state of the gesture will be determined by the @phase field.
  *
  * A hold gesture starts when the user places one or many fingers on the
  * touchpad and ends when all fingers are lifted. It is cancelled when the
@@ -586,8 +589,11 @@ struct _ClutterIMEvent
 /**
  * ClutterEvent:
  *
- * Generic event wrapper.
+ * User and window system events
  *
+ * The events usually come from the windowing backend, but can also
+ * be synthesized by Clutter itself or by the application code.
+ * 
  * Since: 0.2
  */
 union _ClutterEvent
diff --git a/clutter/clutter/clutter-fixed-layout.c b/clutter/clutter/clutter-fixed-layout.c
index 9f68bb1757..17113c5446 100644
--- a/clutter/clutter/clutter-fixed-layout.c
+++ b/clutter/clutter/clutter-fixed-layout.c
@@ -25,13 +25,14 @@
  */
 
 /**
- * SECTION:clutter-fixed-layout
- * @short_description: A fixed layout manager
+ * ClutterFixedLayout:
+ * 
+ * A fixed layout manager
  *
  * #ClutterFixedLayout is a layout manager implementing the same
  * layout policies as #ClutterGroup.
  *
- * #ClutterFixedLayout is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-fixed-layout.h b/clutter/clutter/clutter-fixed-layout.h
index d67e4a8d7b..c7584dfeb5 100644
--- a/clutter/clutter/clutter-fixed-layout.h
+++ b/clutter/clutter/clutter-fixed-layout.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterFixedLayout              ClutterFixedLayout;
 typedef struct _ClutterFixedLayoutClass         ClutterFixedLayoutClass;
 
-/**
- * ClutterFixedLayout:
- *
- * The #ClutterFixedLayout structure contains only private data and
- * it should be accessed using the provided API
- *
- * Since: 1.2
- */
 struct _ClutterFixedLayout
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-flow-layout.c b/clutter/clutter/clutter-flow-layout.c
index 29919ad335..2d33e3ebea 100644
--- a/clutter/clutter/clutter-flow-layout.c
+++ b/clutter/clutter/clutter-flow-layout.c
@@ -23,8 +23,9 @@
  */
 
 /**
- * SECTION:clutter-flow-layout
- * @short_description: A reflowing layout manager
+ * ClutterFlowLayout:
+ * 
+ * A reflowing layout manager
  *
  * #ClutterFlowLayout is a layout manager which implements the following
  * policy:
@@ -49,7 +50,7 @@
  * The [flow-layout example](https://git.gnome.org/browse/clutter/tree/examples/flow-layout.c?h=clutter-1.18)
  * shows how to use the #ClutterFlowLayout.
  *
- * #ClutterFlowLayout is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-flow-layout.h b/clutter/clutter/clutter-flow-layout.h
index 0980bc3cb9..3efd766708 100644
--- a/clutter/clutter/clutter-flow-layout.h
+++ b/clutter/clutter/clutter-flow-layout.h
@@ -44,14 +44,6 @@ typedef struct _ClutterFlowLayout               ClutterFlowLayout;
 typedef struct _ClutterFlowLayoutPrivate        ClutterFlowLayoutPrivate;
 typedef struct _ClutterFlowLayoutClass          ClutterFlowLayoutClass;
 
-/**
- * ClutterFlowLayout:
- *
- * The #ClutterFlowLayout structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.2
- */
 struct _ClutterFlowLayout
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-gesture-action.c b/clutter/clutter/clutter-gesture-action.c
index bcca5a08d6..cc400cfd4a 100644
--- a/clutter/clutter/clutter-gesture-action.c
+++ b/clutter/clutter/clutter-gesture-action.c
@@ -25,20 +25,20 @@
  */
 
 /**
- * SECTION:clutter-gesture-action
- * @Title: ClutterGestureAction
- * @Short_Description: Action for gesture gestures
+ * ClutterGestureAction:
+ * 
+ * Action for gesture gestures
  *
- * #ClutterGestureAction is a sub-class of #ClutterAction that implements
+ * #ClutterGestureAction is a sub-class of [class@Action] that implements
  * the logic for recognizing gesture gestures. It listens for low level events
- * such as #ClutterButtonEvent and #ClutterMotionEvent on the stage to raise
- * the #ClutterGestureAction::gesture-begin, #ClutterGestureAction::gesture-progress,
- * and #ClutterGestureAction::gesture-end signals.
+ * such as [struct@ButtonEvent] and [struct@MotionEvent] on the stage to raise
+ * the [signal@GestureAction::gesture-begin], [signal@GestureAction::gesture-progress],
+ * and [signal@GestureAction::gesture-end] signals.
  *
- * To use #ClutterGestureAction you just need to apply it to a #ClutterActor
- * using clutter_actor_add_action() and connect to the signals:
+ * To use #ClutterGestureAction you just need to apply it to a [class@Actor]
+ * using [method@Actor.add_action] and connect to the signals:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   ClutterAction *action = clutter_gesture_action_new ();
  *
  *   clutter_actor_add_action (actor, action);
@@ -46,7 +46,7 @@
  *   g_signal_connect (action, "gesture-begin", G_CALLBACK (on_gesture_begin), NULL);
  *   g_signal_connect (action, "gesture-progress", G_CALLBACK (on_gesture_progress), NULL);
  *   g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);
- * ]|
+ * ```
  *
  * ## Creating Gesture actions
  *
@@ -60,13 +60,13 @@
  *  - Prepare -> Begin -> Progress -> End
  *
  * Each #ClutterGestureAction starts in the "prepare" state, and calls
- * the #ClutterGestureActionClass.gesture_prepare() virtual function; this
+ * the [vfunc@GestureAction.gesture_prepare] virtual function; this
  * state can be used to reset the internal state of a #ClutterGestureAction
  * subclass, but it can also immediately cancel a gesture without going
  * through the rest of the states.
  *
  * The "begin" state follows the "prepare" state, and calls the
- * #ClutterGestureActionClass.gesture_begin() virtual function. This state
+ * [vfunc@GestureAction.gesture_begin] virtual function. This state
  * signals the start of a gesture recognizing process. From the "begin" state
  * the gesture recognition process can successfully end, by going to the
  * "end" state; it can continue in the "progress" state, in case of a
@@ -74,7 +74,7 @@
  * state.
  *
  * In case of continuous gestures, the #ClutterGestureAction will use
- * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress()
+ * the "progress" state, calling the [vfunc@GestureAction.gesture_progress]
  * virtual function; the "progress" state will continue until the end of the
  * gesture, in which case the "end" state will be reached, or until the
  * gesture is cancelled, in which case the "cancel" gesture will be used
@@ -665,8 +665,8 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * ClutterGestureAction:threshold-trigger-edge:
    *
    * The trigger edge to be used by the action to either emit the
-   * #ClutterGestureAction::gesture-begin signal or to emit the
-   * #ClutterGestureAction::gesture-cancel signal.
+   * [signal@GestureAction::gesture-begin] signal or to emit the
+   * [signal@GestureAction::gesture-cancel] signal.
    *
    * Since: 1.18
    */
@@ -683,8 +683,8 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * ClutterGestureAction:threshold-trigger-distance-x:
    *
    * The horizontal trigger distance to be used by the action to either
-   * emit the #ClutterGestureAction::gesture-begin signal or to emit
-   * the #ClutterGestureAction::gesture-cancel signal.
+   * emit the [signal@GestureAction::gesture-begin] signal or to emit
+   * the [signal@GestureAction::gesture-cancel] signal.
    *
    * A negative value will be interpreted as the default drag threshold.
    *
@@ -702,8 +702,8 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * ClutterGestureAction:threshold-trigger-distance-y:
    *
    * The vertical trigger distance to be used by the action to either
-   * emit the #ClutterGestureAction::gesture-begin signal or to emit
-   * the #ClutterGestureAction::gesture-cancel signal.
+   * emit the [signal@GestureAction::gesture-begin] signal or to emit
+   * the [signal@GestureAction::gesture-cancel] signal.
    *
    * A negative value will be interpreted as the default drag threshold.
    *
@@ -726,7 +726,7 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * @action: the #ClutterGestureAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::gesture_begin signal is emitted when the #ClutterActor to which
+   * The signal is emitted when the [class@Actor] to which
    * a #ClutterGestureAction has been applied starts receiving a gesture.
    *
    * Return value: %TRUE if the gesture should start, and %FALSE if
@@ -749,8 +749,8 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * @action: the #ClutterGestureAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::gesture-progress signal is emitted for each motion event after
-   * the #ClutterGestureAction::gesture-begin signal has been emitted.
+   * The signal is emitted for each motion event after
+   * the [signal@GestureAction::gesture-begin] signal has been emitted.
    *
    * Return value: %TRUE if the gesture should continue, and %FALSE if
    *   the gesture should be cancelled.
@@ -772,10 +772,10 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * @action: the #ClutterGestureAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::gesture-end signal is emitted at the end of the gesture gesture,
+   * The signal is emitted at the end of the gesture gesture,
    * when the pointer's button is released
    *
-   * This signal is emitted if and only if the #ClutterGestureAction::gesture-begin
+   * This signal is emitted if and only if the [signal@GestureAction::gesture-begin]
    * signal has been emitted first.
    *
    * Since: 1.8
@@ -794,10 +794,10 @@ clutter_gesture_action_class_init (ClutterGestureActionClass *klass)
    * @action: the #ClutterGestureAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::gesture-cancel signal is emitted when the ongoing gesture gets
-   * cancelled from the #ClutterGestureAction::gesture-progress signal handler.
+   * The signal is emitted when the ongoing gesture gets
+   * cancelled from the [signal@GestureAction::gesture-progress] signal handler.
    *
-   * This signal is emitted if and only if the #ClutterGestureAction::gesture-begin
+   * This signal is emitted if and only if the [signal@GestureAction::gesture-begin]
    * signal has been emitted first.
    *
    * Since: 1.8
@@ -1218,7 +1218,7 @@ clutter_gesture_action_get_device (ClutterGestureAction *action,
  * @point: index of a point currently active
  *
  * Retrieves a reference to the last #ClutterEvent for a touch point. Call
- * clutter_event_copy() if you need to store the reference somewhere.
+ * [method Event copy] if you need to store the reference somewhere.
  *
  * Return value: (transfer none): the last #ClutterEvent for a touch point.
  *
@@ -1293,7 +1293,7 @@ clutter_gesture_action_set_threshold_trigger_edge (ClutterGestureAction      *ac
  * @action: a #ClutterGestureAction
  *
  * Retrieves the edge trigger of the gesture @action, as set using
- * clutter_gesture_action_set_threshold_trigger_edge().
+ * [method@GestureAction.set_threshold_trigger_edge].
  *
  * Return value: the edge trigger
  *
@@ -1317,13 +1317,13 @@ clutter_gesture_action_get_threshold_trigger_edge (ClutterGestureAction *action)
  * @action: a #ClutterGestureAction
  *
  * Retrieves the edge trigger of the gesture @action, as set using
- * clutter_gesture_action_set_threshold_trigger_edge().
+ * [method@GestureAction.set_threshold_trigger_edge].
  *
  * Return value: the edge trigger
  *
  * Since: 1.18
  *
- * Deprecated: 1.20: Use clutter_gesture_action_get_threshold_trigger_edge() instead.
+ * Deprecated: 1.20: Use [method@GestureAction.get_threshold_trigger_edge] instead.
  */
 ClutterGestureTriggerEdge
 clutter_gesture_action_get_threshold_trigger_egde (ClutterGestureAction *action)
@@ -1375,7 +1375,7 @@ clutter_gesture_action_set_threshold_trigger_distance (ClutterGestureAction
  * @y: (out) (allow-none): The return location for the vertical distance, or %NULL
  *
  * Retrieves the threshold trigger distance of the gesture @action,
- * as set using clutter_gesture_action_set_threshold_trigger_distance().
+ * as set using [method@GestureAction.set_threshold_trigger_distance].
  *
  * Since: 1.18
  */
diff --git a/clutter/clutter/clutter-grid-layout.c b/clutter/clutter/clutter-grid-layout.c
index ebc022eb75..7ff2c8d5d5 100644
--- a/clutter/clutter/clutter-grid-layout.c
+++ b/clutter/clutter/clutter-grid-layout.c
@@ -41,10 +41,9 @@
 #include "clutter-private.h"
 
 /**
- * SECTION:clutter-grid-layout
- * @Short_description: A layout manager for a grid of actors
- * @Title: ClutterGridLayout
- * @See_also: #ClutterBoxLayout
+ * ClutterGridLayout:
+ * 
+ * A layout manager for a grid of actors
  *
  * #ClutterGridLayout is a layout manager which arranges its child widgets in
  * rows and columns. It is a very similar to #ClutterBoxLayout, but it
diff --git a/clutter/clutter/clutter-grid-layout.h b/clutter/clutter/clutter-grid-layout.h
index 88603265d1..6cd04ad5f1 100644
--- a/clutter/clutter/clutter-grid-layout.h
+++ b/clutter/clutter/clutter-grid-layout.h
@@ -48,14 +48,6 @@ typedef struct _ClutterGridLayout                ClutterGridLayout;
 typedef struct _ClutterGridLayoutPrivate         ClutterGridLayoutPrivate;
 typedef struct _ClutterGridLayoutClass           ClutterGridLayoutClass;
 
-/**
- * ClutterGridLayout:
- *
- * The #ClutterGridLayout structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.12
- */
 struct _ClutterGridLayout
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-image.c b/clutter/clutter/clutter-image.c
index 9ebf7c96ad..038d0743a8 100644
--- a/clutter/clutter/clutter-image.c
+++ b/clutter/clutter/clutter-image.c
@@ -23,17 +23,17 @@
  */
 
 /**
- * SECTION:clutter-image
- * @Title: ClutterImage
- * @Short_Description: Image data content
+ * ClutterImage:
+ * 
+ * Image data content
  *
  * #ClutterImage is a #ClutterContent implementation that displays
- * image data inside a #ClutterActor.
+ * image data inside a [class@Actor].
  *
  * See [image.c](https://git.gnome.org/browse/clutter/tree/examples/image-content.c?h=clutter-1.18)
  * for an example of how to use #ClutterImage.
  *
- * #ClutterImage is available since Clutter 1.10.
+ * Since: 1.10.
  */
 
 #include "clutter-build-config.h"
@@ -218,7 +218,7 @@ clutter_image_new (void)
  * how to retrieve that data is left to platform specific image loaders. For
  * instance, if you use the GdkPixbuf library:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   ClutterContent *image = clutter_image_new ();
  *
  *   GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file (filename, NULL);
@@ -234,7 +234,7 @@ clutter_image_new (void)
  *                           &error);
  *
  *   g_object_unref (pixbuf);
- * ]|
+ * ```
  *
  * Return value: %TRUE if the image data was successfully loaded,
  *   and %FALSE otherwise.
diff --git a/clutter/clutter/clutter-input-device.c b/clutter/clutter/clutter-input-device.c
index 8b99846ec0..3c90f6bdd9 100644
--- a/clutter/clutter/clutter-input-device.c
+++ b/clutter/clutter/clutter-input-device.c
@@ -22,8 +22,9 @@
  */
 
 /**
- * SECTION:clutter-input-device
- * @short_description: An input device managed by Clutter
+ * ClutterInputDevice:
+ * 
+ * An input device managed by Clutter
  *
  * #ClutterInputDevice represents an input device known to Clutter.
  *
diff --git a/clutter/clutter/clutter-input-device.h b/clutter/clutter/clutter-input-device.h
index d6fd62a038..dcfc624d7a 100644
--- a/clutter/clutter/clutter-input-device.h
+++ b/clutter/clutter/clutter-input-device.h
@@ -59,12 +59,6 @@ struct _ClutterInputDeviceClass
 #define CLUTTER_IS_INPUT_DEVICE_CLASS(klass)    (G_TYPE_CHECK_CLASS_TYPE ((klass), 
CLUTTER_TYPE_INPUT_DEVICE))
 #define CLUTTER_INPUT_DEVICE_GET_CLASS(obj)     (G_TYPE_INSTANCE_GET_CLASS ((obj), 
CLUTTER_TYPE_INPUT_DEVICE, ClutterInputDeviceClass))
 
-/**
- * ClutterInputDevice:
- *
- * Generic representation of an input device. The actual contents of this
- * structure depend on the backend used.
- */
 typedef struct _ClutterInputDeviceClass ClutterInputDeviceClass;
 
 CLUTTER_EXPORT
diff --git a/clutter/clutter/clutter-interval.c b/clutter/clutter/clutter-interval.c
index b7d75a4bd4..75cdca43cf 100644
--- a/clutter/clutter/clutter-interval.c
+++ b/clutter/clutter/clutter-interval.c
@@ -23,8 +23,9 @@
  */
 
 /**
- * SECTION:clutter-interval
- * @short_description: An object holding an interval of two values
+ * ClutterInterval:
+ * 
+ * An object holding an interval of two values
  *
  * #ClutterInterval is a simple object that can hold two values
  * defining an interval. #ClutterInterval can hold any value that
@@ -40,7 +41,7 @@
  * #ClutterInterval can be subclassed to override the validation
  * and value computation.
  *
- * #ClutterInterval is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -744,11 +745,11 @@ clutter_interval_get_interval_valist (ClutterInterval *interval,
  * This function avoids using a #GValue for the initial and final values
  * of the interval:
  *
- * |[
+ * ```c
  *   interval = clutter_interval_new (G_TYPE_FLOAT, 0.0, 1.0);
  *   interval = clutter_interval_new (G_TYPE_BOOLEAN, FALSE, TRUE);
  *   interval = clutter_interval_new (G_TYPE_INT, 0, 360);
- * ]|
+ * ```
  *
  * Return value: the newly created #ClutterInterval
  *
@@ -1047,11 +1048,11 @@ clutter_interval_peek_final_value (ClutterInterval *interval)
  * and clutter_interval_set_final_value() that avoids using the
  * #GValue arguments:
  *
- * |[
+ * ```c
  *   clutter_interval_set_interval (interval, 0, 50);
  *   clutter_interval_set_interval (interval, 1.0, 0.0);
  *   clutter_interval_set_interval (interval, FALSE, TRUE);
- * ]|
+ * ```
  *
  * This function is meant for the convenience of the C API; bindings
  * should reimplement this function using the #GValue-based API.
@@ -1088,10 +1089,10 @@ out:
  * and clutter_interval_get_final_value() that avoids using the
  * #GValue arguments:
  *
- * |[
+ * ```c
  *   gint a = 0, b = 0;
  *   clutter_interval_get_interval (interval, &a, &b);
- * ]|
+ * ```
  *
  * This function is meant for the convenience of the C API; bindings
  * should reimplement this function using the #GValue-based API.
diff --git a/clutter/clutter/clutter-interval.h b/clutter/clutter/clutter-interval.h
index 99b0cc0990..fb9a47199e 100644
--- a/clutter/clutter/clutter-interval.h
+++ b/clutter/clutter/clutter-interval.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterIntervalPrivate          ClutterIntervalPrivate;
 typedef struct _ClutterIntervalClass            ClutterIntervalClass;
 
-/**
- * ClutterInterval:
- *
- * The #ClutterInterval structure contains only private data and should
- * be accessed using the provided functions.
- *
- * Since: 1.0
- */
 struct _ClutterInterval
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-keyframe-transition.c b/clutter/clutter/clutter-keyframe-transition.c
index d278109cb2..7a546c1240 100644
--- a/clutter/clutter/clutter-keyframe-transition.c
+++ b/clutter/clutter/clutter-keyframe-transition.c
@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:clutter-keyframe-transition
- * @Title: ClutterKeyframeTransition
- * @Short_Description: Keyframe property transition
+ * ClutterKeyframeTransition:
+ * 
+ * Keyframe property transition
  *
  * #ClutterKeyframeTransition allows animating a property by defining
  * "key frames": values at a normalized position on the transition
@@ -36,7 +36,7 @@
  * Setting up a #ClutterKeyframeTransition means providing the times,
  * values, and easing modes between these key frames, for instance:
  *
- * |[
+ * ```c
  *   ClutterTransition *keyframe;
  *
  *   keyframe = clutter_keyframe_transition_new ("opacity");
@@ -46,7 +46,7 @@
  *                                    G_TYPE_UINT,
  *                                    1, /&ast; number of key frames &ast;/
  *                                    0.5, 128, CLUTTER_EASE_IN_OUT_CUBIC);
- * ]|
+ * ```
  *
  * The example above sets up a keyframe transition for the #ClutterActor:opacity
  * property of a #ClutterActor; the transition starts and sets the value of the
@@ -59,7 +59,7 @@
  * and the 1.0 value, to interpolate to the final value of the transition's
  * interval.
  *
- * #ClutterKeyframeTransition is available since Clutter 1.12.
+ * Since: 1.12.
  */
 
 #include "clutter-build-config.h"
diff --git a/clutter/clutter/clutter-keyframe-transition.h b/clutter/clutter/clutter-keyframe-transition.h
index 2b3746f710..0f908bd255 100644
--- a/clutter/clutter/clutter-keyframe-transition.h
+++ b/clutter/clutter/clutter-keyframe-transition.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterKeyframeTransitionPrivate        ClutterKeyframeTransitionPrivate;
 typedef struct _ClutterKeyframeTransitionClass          ClutterKeyframeTransitionClass;
 
-/**
- * ClutterKeyframeTransition:
- *
- * The `ClutterKeyframeTransition` structure contains only private
- * data and should be accessed using the provided API.
- *
- * Since: 1.12
- */
 struct _ClutterKeyframeTransition
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-layout-manager.c b/clutter/clutter/clutter-layout-manager.c
index 3fe02a196a..4f5e19b234 100644
--- a/clutter/clutter/clutter-layout-manager.c
+++ b/clutter/clutter/clutter-layout-manager.c
@@ -23,8 +23,9 @@
  */
 
 /**
- * SECTION:clutter-layout-manager
- * @short_description: Layout managers base class
+ * ClutterLayoutManager:
+ * 
+ * Layout managers base class
  *
  * #ClutterLayoutManager is a base abstract class for layout managers. A
  * layout manager implements the layouting policy for a composite or a
@@ -66,7 +67,7 @@
  * to control how the #ClutterLayoutMeta instance is created, otherwise the
  * default implementation will be equivalent to:
  *
- * |[
+ * ```c
  *  ClutterLayoutManagerClass *klass;
  *  GType meta_type;
  *
@@ -78,7 +79,7 @@
  *                       "container", container,
  *                       "actor", actor,
  *                       NULL);
- * ]|
+ * ```
  *
  * Where `manager` is the  #ClutterLayoutManager, `container` is the
  * #ClutterContainer using the #ClutterLayoutManager, and `actor` is
@@ -94,7 +95,7 @@
  * a #ClutterLayoutManager using the `layout::` modifier on the property
  * name, for instance:
  *
- * |[
+ * ```json
  * {
  *   "type" : "ClutterActor",
  *   "layout-manager" : { "type" : "ClutterGridLayout" },
@@ -123,9 +124,9 @@
  *     }
  *   ]
  * }
- * ]|
+ * ```
  *
- * #ClutterLayoutManager is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
@@ -316,12 +317,13 @@ clutter_layout_manager_class_init (ClutterLayoutManagerClass *klass)
    * ClutterLayoutManager::layout-changed:
    * @manager: the #ClutterLayoutManager that emitted the signal
    *
-   * The ::layout-changed signal is emitted each time a layout manager
+   * The signal is emitted each time a layout manager
    * has been changed. Every #ClutterActor using the @manager instance
-   * as a layout manager should connect a handler to the ::layout-changed
+   * as a layout manager should connect a handler to the
+   * [signal@LayoutManager::layout-changed]
    * signal and queue a relayout on themselves:
    *
-   * |[
+   * ```c
    *   static void layout_changed (ClutterLayoutManager *manager,
    *                               ClutterActor         *self)
    *   {
@@ -332,7 +334,7 @@ clutter_layout_manager_class_init (ClutterLayoutManagerClass *klass)
    *     g_signal_connect (self->manager, "layout-changed",
    *                       G_CALLBACK (layout_changed),
    *                       self);
-   * ]|
+   * ```
    *
    * Sub-classes of #ClutterLayoutManager that implement a layout that
    * can be controlled or changed using parameters should emit the
@@ -975,13 +977,13 @@ clutter_layout_manager_find_child_property (ClutterLayoutManager *manager,
  * clutter_layout_manager_list_child_properties:
  * @manager: a #ClutterLayoutManager
  * @n_pspecs: (out): return location for the number of returned
- *   #GParamSpec<!-- -->s
+ *   `GParamSpec`s
  *
- * Retrieves all the #GParamSpec<!-- -->s for the layout properties
+ * Retrieves all the `GParamSpec`s for the layout properties
  * stored inside the #ClutterLayoutMeta sub-class used by @manager
  *
  * Return value: (transfer full) (array length=n_pspecs): the newly-allocated,
- *   %NULL-terminated array of #GParamSpec<!-- -->s. Use g_free() to free the
+ *   %NULL-terminated array of `GParamSpec`s. Use g_free() to free the
  *   resources allocated for the array
  *
  * Since: 1.2
diff --git a/clutter/clutter/clutter-layout-manager.h b/clutter/clutter/clutter-layout-manager.h
index 4817f7c88c..77717a5c0b 100644
--- a/clutter/clutter/clutter-layout-manager.h
+++ b/clutter/clutter/clutter-layout-manager.h
@@ -42,14 +42,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterLayoutManagerClass       ClutterLayoutManagerClass;
 
-/**
- * ClutterLayoutManager:
- *
- * The #ClutterLayoutManager structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.2
- */
 struct _ClutterLayoutManager
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-layout-meta.c b/clutter/clutter/clutter-layout-meta.c
index 7360725ce8..bf3c643029 100644
--- a/clutter/clutter/clutter-layout-meta.c
+++ b/clutter/clutter/clutter-layout-meta.c
@@ -23,16 +23,17 @@
  */
 
 /**
- * SECTION:clutter-layout-meta
- * @short_description: Wrapper for actors inside a layout manager
+ * ClutterLayoutMeta:
+ * 
+ * Wrapper for actors inside a layout manager
  *
- * #ClutterLayoutMeta is a wrapper object created by #ClutterLayoutManager
+ * #ClutterLayoutMeta is a wrapper object created by [class@LayoutManager]
  * implementations in order to store child-specific data and properties.
  *
- * A #ClutterLayoutMeta wraps a #ClutterActor inside a #ClutterContainer
- * using a #ClutterLayoutManager.
+ * A #ClutterLayoutMeta wraps a [class@Actor] inside a [iface@Container]
+ * using a [class@LayoutManager].
  *
- * #ClutterLayoutMeta is available since Clutter 1.2
+ * Since: 1.2
  */
 
 #include "clutter-build-config.h"
@@ -108,7 +109,7 @@ clutter_layout_meta_class_init (ClutterLayoutMetaClass *klass)
   /**
    * ClutterLayoutMeta:manager:
    *
-   * The #ClutterLayoutManager that created this #ClutterLayoutMeta.
+   * The [class@LayoutManager] that created this #ClutterLayoutMeta.
    *
    * Since: 1.2
    */
diff --git a/clutter/clutter/clutter-layout-meta.h b/clutter/clutter/clutter-layout-meta.h
index a4f6abe929..ff86e9ca6e 100644
--- a/clutter/clutter/clutter-layout-meta.h
+++ b/clutter/clutter/clutter-layout-meta.h
@@ -46,18 +46,6 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterLayoutMetaClass          ClutterLayoutMetaClass;
 
-/**
- * ClutterLayoutMeta:
- * @manager: the layout manager handling this data
- *
- * Sub-class of #ClutterChildMeta specific for layout managers
- *
- * A #ClutterLayoutManager sub-class should create a #ClutterLayoutMeta
- * instance by overriding the #ClutterLayoutManager::create_child_meta()
- * virtual function
- *
- * Since: 1.2
- */
 struct _ClutterLayoutMeta
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-main.c b/clutter/clutter/clutter-main.c
index d1aec04e5f..78902cd743 100644
--- a/clutter/clutter/clutter-main.c
+++ b/clutter/clutter/clutter-main.c
@@ -286,7 +286,7 @@ _clutter_threads_dispatch_free (gpointer data)
  * it will call @function while holding the Clutter lock. It is logically
  * equivalent to the following implementation:
  *
- * |[
+ * ```c
  * static gboolean
  * idle_safe_callback (gpointer data)
  * {
@@ -314,7 +314,7 @@ _clutter_threads_dispatch_free (gpointer data)
  *                           closure,
  *                           g_free)
  * }
- *]|
+ * ```
  *
  * This function should be used by threaded applications to make sure
  * that @func is emitted under the Clutter threads lock and invoked
@@ -322,7 +322,7 @@ _clutter_threads_dispatch_free (gpointer data)
  * it can be used to update the UI using the results from a worker
  * thread:
  *
- * |[
+ * ```c
  * static gboolean
  * update_ui (gpointer data)
  * {
@@ -351,7 +351,7 @@ _clutter_threads_dispatch_free (gpointer data)
  *                                  update_ui,
  *                                  closure,
  *                                  NULL);
- * ]|
+ * ```
  *
  * Return value: the ID (greater than 0) of the event source.
  *
@@ -1239,7 +1239,7 @@ _clutter_run_repaint_functions (ClutterRepaintFlags flags)
  * environment variable.
  *
  * The default text direction can be overridden on a per-actor basis by using
- * clutter_actor_set_text_direction().
+ * [method@Actor.set_text_direction].
  *
  * Return value: the default text direction
  *
diff --git a/clutter/clutter/clutter-offscreen-effect.c b/clutter/clutter/clutter-offscreen-effect.c
index bdb3288515..e27c23db90 100644
--- a/clutter/clutter/clutter-offscreen-effect.c
+++ b/clutter/clutter/clutter-offscreen-effect.c
@@ -24,12 +24,12 @@
  */
 
 /**
- * SECTION:clutter-offscreen-effect
- * @short_description: Base class for effects using offscreen buffers
- * @see_also: #ClutterBlurEffect, #ClutterEffect
+ * ClutterOffscreenEffect:
+ * 
+ * Base class for effects using offscreen buffers
  *
  * #ClutterOffscreenEffect is an abstract class that can be used by
- * #ClutterEffect sub-classes requiring access to an offscreen buffer.
+ * [class@Effect] sub-classes requiring access to an offscreen buffer.
  *
  * Some effects, like the fragment shader based effects, can only use GL
  * textures, and in order to apply those effects to any kind of actor they
@@ -40,24 +40,23 @@
  * offscreen framebuffer, the redirection and the final paint of the texture on
  * the desired stage.
  *
- * #ClutterOffscreenEffect is available since Clutter 1.4
  *
  * ## Implementing a ClutterOffscreenEffect
  *
  * Creating a sub-class of #ClutterOffscreenEffect requires, in case
- * of overriding the #ClutterEffect virtual functions, to chain up to the
+ * of overriding the [class@Effect] virtual functions, to chain up to the
  * #ClutterOffscreenEffect's implementation.
  *
- * On top of the #ClutterEffect's virtual functions,
- * #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target()
+ * On top of the [class@Effect]'s virtual functions,
+ * #ClutterOffscreenEffect also provides a [vfunc@OffscreenEffect.paint_target]
  * function, which encapsulates the effective painting of the texture that
  * contains the result of the offscreen redirection.
  *
  * The size of the target material is defined to be as big as the
- * transformed size of the #ClutterActor using the offscreen effect.
+ * transformed size of the [class@Actor] using the offscreen effect.
  * Sub-classes of #ClutterOffscreenEffect can change the texture creation
  * code to provide bigger textures by overriding the
- * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up
+ * [vfunc@OffscreenEffect.create_texture] virtual function; no chain up
  * to the #ClutterOffscreenEffect implementation is required in this
  * case.
  *
@@ -65,25 +64,27 @@
  *
  * #ClutterOffscreenEffect generates the following paint node tree:
  *
- * |[<!-- language="plain" -->
+ * ```
  * Effect
  *  ├─────────┐
  * Layer   Pipeline
  *  │
  * Actor
- * ]|
+ * ```
  *
  * When the actor contents are cached, the generated paint node tree
  * looks like this:
  *
- * |[<!-- language="plain" -->
+ * ```
  * Effect
  *  │
  * Pipeline
- * ]|
+ * ```
  *
  * In both cases, the "Pipeline" node is created with the return value
- * of #ClutterOffscreenEffectClass.create_pipeline().
+ * of [vfunc@OffscreenEffect.create_pipeline].
+ * 
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -619,10 +620,10 @@ clutter_offscreen_effect_init (ClutterOffscreenEffect *self)
  * buffer created by @effect
  *
  * You should only use the returned texture when painting. The texture
- * may change after ClutterEffect::pre_paint is called so the effect
+ * may change after [vfunc@Effect.pre_paint] is called so the effect
  * implementation should update any references to the texture after
  * chaining-up to the parent's pre_paint implementation. This can be
- * used instead of clutter_offscreen_effect_get_target() when the
+ * used instead of [method@OffscreenEffect.get_texture] when the
  * effect subclass wants to paint using its own material.
  *
  * Return value: (transfer none): a #CoglHandle or %NULL. The
@@ -647,7 +648,7 @@ clutter_offscreen_effect_get_texture (ClutterOffscreenEffect *effect)
  * Retrieves the pipeline used as a render target for the offscreen
  * buffer created by @effect
  *
- * You should only use the returned #CoglPipeline when painting. The
+ * You should only use the returned [class@Cogl.Pipeline] when painting. The
  * returned pipeline might change between different frames.
  *
  * Return value: (transfer none)(nullable): a #CoglPipeline. The
@@ -671,7 +672,7 @@ clutter_offscreen_effect_get_pipeline (ClutterOffscreenEffect *effect)
  * @node: a #ClutterPaintNode
  * @paint_context: a #ClutterPaintContext
  *
- * Calls the paint_target() virtual function of the @effect
+ * Calls the [vfunc@OffscreenEffect.paint_target] virtual function of the @effect
  *
  * Since: 1.4
  */
@@ -693,7 +694,7 @@ clutter_offscreen_effect_paint_target (ClutterOffscreenEffect *effect,
  * @width: the minimum width of the target texture
  * @height: the minimum height of the target texture
  *
- * Calls the create_texture() virtual function of the @effect
+ * Calls the [vfunc@OffscreenEffect.create_texture] virtual function of the @effect
  *
  * Return value: (transfer full): a handle to a Cogl texture, or
  *   %NULL. The returned handle has its reference
@@ -724,7 +725,7 @@ clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
  * paint the actor to which it has been applied.
  *
  * This function should only be called by #ClutterOffscreenEffect
- * implementations, from within the #ClutterOffscreenEffectClass.paint_target()
+ * implementations, from within the [vfunc@OffscreenEffect.paint_target]
  * virtual function.
  *
  * Return value: %TRUE if the offscreen buffer has a valid size,
diff --git a/clutter/clutter/clutter-offscreen-effect.h b/clutter/clutter/clutter-offscreen-effect.h
index b06bc34ed4..0e9582d364 100644
--- a/clutter/clutter/clutter-offscreen-effect.h
+++ b/clutter/clutter/clutter-offscreen-effect.h
@@ -45,14 +45,6 @@ typedef struct _ClutterOffscreenEffect          ClutterOffscreenEffect;
 typedef struct _ClutterOffscreenEffectPrivate   ClutterOffscreenEffectPrivate;
 typedef struct _ClutterOffscreenEffectClass     ClutterOffscreenEffectClass;
 
-/**
- * ClutterOffscreenEffect:
- *
- * The #ClutterOffscreenEffect structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _ClutterOffscreenEffect
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-page-turn-effect.c b/clutter/clutter/clutter-page-turn-effect.c
index 2c0bc0ac69..a70e53d95c 100644
--- a/clutter/clutter/clutter-page-turn-effect.c
+++ b/clutter/clutter/clutter-page-turn-effect.c
@@ -26,13 +26,13 @@
  */
 
 /**
- * SECTION:clutter-page-turn-effect
- * @Title: ClutterPageTurnEffect
- * @Short_Description: A page turning effect
+ * ClutterPageTurnEffect:
+ * 
+ * A page turning effect
  *
  * A simple page turning effect
  *
- * #ClutterPageTurnEffect is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -326,7 +326,7 @@ clutter_page_turn_effect_set_period (ClutterPageTurnEffect *effect,
  * clutter_page_turn_effect_get_period:
  * @effect: a #ClutterPageTurnEffect
  *
- * Retrieves the value set using clutter_page_turn_effect_get_period()
+ * Retrieves the value set using [method@PageTurnEffect.get_period]
  *
  * Return value: the period of the page curling
  *
@@ -367,7 +367,7 @@ clutter_page_turn_effect_set_angle (ClutterPageTurnEffect *effect,
  * clutter_page_turn_effect_get_angle:
  * @effect: a #ClutterPageTurnEffect:
  *
- * Retrieves the value set using clutter_page_turn_effect_get_angle()
+ * Retrieves the value set using [method@PageTurnEffect.get_angle]
  *
  * Return value: the angle of the page curling
  *
@@ -407,7 +407,7 @@ clutter_page_turn_effect_set_radius (ClutterPageTurnEffect *effect,
  * clutter_page_turn_effect_get_radius:
  * @effect: a #ClutterPageTurnEffect
  *
- * Retrieves the value set using clutter_page_turn_effect_set_radius()
+ * Retrieves the value set using [method@PageTurnEffect.set_radius]
  *
  * Return value: the radius of the page curling
  *
diff --git a/clutter/clutter/clutter-page-turn-effect.h b/clutter/clutter/clutter-page-turn-effect.h
index dd036bac8c..46f45b6004 100644
--- a/clutter/clutter/clutter-page-turn-effect.h
+++ b/clutter/clutter/clutter-page-turn-effect.h
@@ -40,14 +40,6 @@ G_BEGIN_DECLS
 #define CLUTTER_PAGE_TURN_EFFECT(obj)           (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_PAGE_TURN_EFFECT, ClutterPageTurnEffect))
 #define CLUTTER_IS_PAGE_TURN_EFFECT(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_PAGE_TURN_EFFECT))
 
-/**
- * ClutterPageTurnEffect:
- *
- * #ClutterPageTurnEffect is an opaque structure
- * whose members can only be accessed using the provided API
- *
- * Since: 1.4
- */
 typedef struct _ClutterPageTurnEffect           ClutterPageTurnEffect;
 typedef struct _ClutterPageTurnEffectClass      ClutterPageTurnEffectClass;
 
diff --git a/clutter/clutter/clutter-paint-node.c b/clutter/clutter/clutter-paint-node.c
index 57b6b65896..10025bcd00 100644
--- a/clutter/clutter/clutter-paint-node.c
+++ b/clutter/clutter/clutter-paint-node.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:clutter-paint-node
- * @Title: ClutterPaintNode
- * @Short_Description: Paint objects
+ * ClutterPaintNode:(ref-func clutter_paint_node_ref) (unref-func clutter_paint_node_unref) (set-value-func 
clutter_value_set_paint_node) (get-value-func clutter_value_get_paint_node)
+ * 
+ * Paint objects
  *
  * #ClutterPaintNode is an element in the render graph.
  *
@@ -37,16 +37,9 @@
  * elements also respond to events. The render graph, instead, is only
  * composed by nodes that will be painted.
  *
- * Each #ClutterActor can submit multiple #ClutterPaintNode<!-- -->s to
+ * Each #ClutterActor can submit multiple `ClutterPaintNode`s to
  * the render graph.
- */
-
-/**
- * ClutterPaintNode: (ref-func clutter_paint_node_ref) (unref-func clutter_paint_node_unref) (set-value-func 
clutter_value_set_paint_node) (get-value-func clutter_value_get_paint_node)
- *
- * The `ClutterPaintNode` structure contains only private data
- * and it should be accessed using the provided API.
- *
+ * 
  * Since: 1.10
  */
 
diff --git a/clutter/clutter/clutter-paint-nodes.c b/clutter/clutter/clutter-paint-nodes.c
index abf06450d6..2664af879c 100644
--- a/clutter/clutter/clutter-paint-nodes.c
+++ b/clutter/clutter/clutter-paint-nodes.c
@@ -22,14 +22,6 @@
  *   Emmanuele Bassi <ebassi linux intel com>
  */
 
-/**
- * SECTION:clutter-paint-nodes
- * @Title: Paint Nodes
- * @Short_Description: ClutterPaintNode implementations
- *
- * Clutter provides a set of predefined #ClutterPaintNode implementations
- * that cover all the state changes available.
- */
 
 #include "clutter-build-config.h"
 
@@ -82,9 +74,9 @@ clutter_paint_node_init_types (ClutterBackend *clutter_backend)
 }
 
 /*
- * Root node
+ * ClutterRootNode:
  *
- * any frame can only have a since RootNode instance for each
+ * Any frame can only have a since RootNode instance for each
  * top-level actor.
  */
 
@@ -183,7 +175,9 @@ clutter_root_node_new (CoglFramebuffer    *framebuffer,
 }
 
 /*
- * ClutterTransformNode
+ * ClutterTransformNode:
+ *
+ * Since: 1.10
  */
 
 struct _ClutterTransformNode
@@ -362,8 +356,10 @@ _clutter_dummy_node_new (ClutterActor    *actor,
   return res;
 }
 
-/*
- * Pipeline node
+/**
+ * ClutterPipelineNode:
+ * 
+ * Since: 1.10
  */
 
 struct _ClutterPipelineNode
@@ -586,8 +582,10 @@ clutter_pipeline_node_new (CoglPipeline *pipeline)
   return (ClutterPaintNode *) res;
 }
 
-/*
- * Color node
+/**
+ * ClutterColorNode:
+ *
+ * Since: 1.10
  */
 
 struct _ClutterColorNode
@@ -661,8 +659,11 @@ clutter_color_node_new (const ClutterColor *color)
   return (ClutterPaintNode *) cnode;
 }
 
-/*
- * Texture node
+/**
+ * ClutterTextureNode:
+ *
+ *
+ * Since: 1.10
  */
 
 struct _ClutterTextureNode
@@ -775,10 +776,12 @@ clutter_texture_node_new (CoglTexture          *texture,
   return (ClutterPaintNode *) tnode;
 }
 
-/*
- * Text node
- */
 
+/**
+ * ClutterTextNode:
+ *
+ * Since: 1.10
+ */
 struct _ClutterTextNode
 {
   ClutterPaintNode parent_instance;
@@ -986,8 +989,10 @@ clutter_text_node_new (PangoLayout        *layout,
   return (ClutterPaintNode *) res;
 }
 
-/*
- * Clip node
+/**
+ * ClutterClipNode:
+ * 
+ * Since: 1.10
  */
 struct _ClutterClipNode
 {
@@ -1115,8 +1120,8 @@ clutter_clip_node_new (void)
   return _clutter_paint_node_create (CLUTTER_TYPE_CLIP_NODE);
 }
 
-/*
- * ClutterActorNode
+/**
+ * ClutterActorNode:
  */
 
 struct _ClutterActorNode
@@ -1769,7 +1774,7 @@ clutter_blit_node_init (ClutterBlitNode *self)
  * Creates a new #ClutterBlitNode that blits @src into the current
  * draw framebuffer.
  *
- * You must only add rectangles using clutter_blit_node_add_blit_rectangle().
+ * You must only add rectangles using [method@BlitNode.add_blit_rectangle].
  *
  * Return value: (transfer full): the newly created #ClutterBlitNode.
  *   Use clutter_paint_node_unref() when done.
@@ -1798,7 +1803,7 @@ clutter_blit_node_new (CoglFramebuffer *src)
  * @height: Height of region to copy
  *
  * Adds a new blit rectangle to the stack of rectangles. All the
- * constraints of cogl_blit_framebuffer() apply here.
+ * constraints of [func@Cogl.blit_framebuffer] apply here.
  */
 void
 clutter_blit_node_add_blit_rectangle (ClutterBlitNode *blit_node,
@@ -1824,8 +1829,8 @@ clutter_blit_node_add_blit_rectangle (ClutterBlitNode *blit_node,
                                             dst_y + height);
 }
 
-/*
- * ClutterBlurNode
+/**
+ * ClutterBlurNode:
  */
 
 struct _ClutterBlurNode
diff --git a/clutter/clutter/clutter-paint-nodes.h b/clutter/clutter/clutter-paint-nodes.h
index 7f0d12857a..d98809ffe6 100644
--- a/clutter/clutter/clutter-paint-nodes.h
+++ b/clutter/clutter/clutter-paint-nodes.h
@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define CLUTTER_COLOR_NODE(obj)         (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_COLOR_NODE, 
ClutterColorNode))
 #define CLUTTER_IS_COLOR_NODE(obj)      (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_COLOR_NODE))
 
-/**
- * ClutterColorNode:
- *
- * The #ClutterTextNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterColorNode                ClutterColorNode;
 typedef struct _ClutterColorNodeClass           ClutterColorNodeClass;
 
@@ -59,14 +51,6 @@ ClutterPaintNode *      clutter_color_node_new          (const ClutterColor    *
 #define CLUTTER_TEXTURE_NODE(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_TEXTURE_NODE, ClutterTextureNode))
 #define CLUTTER_IS_TEXTURE_NODE(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_TEXTURE_NODE))
 
-/**
- * ClutterTextureNode:
- *
- * The #ClutterTextNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterTextureNode              ClutterTextureNode;
 typedef struct _ClutterTextureNodeClass         ClutterTextureNodeClass;
 
@@ -83,14 +67,6 @@ ClutterPaintNode *      clutter_texture_node_new        (CoglTexture           *
 #define CLUTTER_CLIP_NODE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_CLIP_NODE, 
ClutterClipNode))
 #define CLUTTER_IS_CLIP_NODE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_CLIP_NODE))
 
-/**
- * ClutterClipNode:
- *
- * The #ClutterTextNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterClipNode                 ClutterClipNode;
 typedef struct _ClutterClipNodeClass            ClutterClipNodeClass;
 
@@ -104,14 +80,6 @@ ClutterPaintNode *      clutter_clip_node_new           (void);
 #define CLUTTER_PIPELINE_NODE(obj)              (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_PIPELINE_NODE, ClutterPipelineNode))
 #define CLUTTER_IS_PIPELINE_NODE(obj)           (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_PIPELINE_NODE))
 
-/**
- * ClutterPipelineNode:
- *
- * The #ClutterTextNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterPipelineNode             ClutterPipelineNode;
 typedef struct _ClutterPipelineNodeClass        ClutterPipelineNodeClass;
 
@@ -125,14 +93,6 @@ ClutterPaintNode *      clutter_pipeline_node_new       (CoglPipeline          *
 #define CLUTTER_TEXT_NODE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_TEXT_NODE, 
ClutterTextNode))
 #define CLUTTER_IS_TEXT_NODE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_TEXT_NODE))
 
-/**
- * ClutterTextNode:
- *
- * The #ClutterTextNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterTextNode                 ClutterTextNode;
 typedef struct _ClutterTextNodeClass            ClutterTextNodeClass;
 
@@ -147,12 +107,6 @@ ClutterPaintNode *      clutter_text_node_new           (PangoLayout           *
 #define CLUTTER_ACTOR_NODE(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_ACTOR_NODE, 
ClutterActorNode))
 #define CLUTTER_IS_ACTOR_NODE(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_ACTOR_NODE))
 
-/**
- * ClutterActorNode:
- *
- * The #ClutterActorNode structure is an opaque
- * type whose members cannot be directly accessed.
- */
 typedef struct _ClutterActorNode ClutterActorNode;
 typedef struct _ClutterActorNode ClutterActorNodeClass;
 
@@ -167,12 +121,6 @@ ClutterPaintNode * clutter_actor_node_new (ClutterActor *actor,
 #define CLUTTER_ROOT_NODE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_ROOT_NODE, 
ClutterRootNode))
 #define CLUTTER_IS_ROOT_NODE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_ROOT_NODE))
 
-/**
- * ClutterRootNode:
- *
- * The #ClutterRootNode structure is an opaque
- * type whose members cannot be directly accessed.
- */
 typedef struct _ClutterRootNode                 ClutterRootNode;
 typedef struct _ClutterPaintNodeClass           ClutterRootNodeClass;
 
@@ -188,14 +136,6 @@ ClutterPaintNode *      clutter_root_node_new           (CoglFramebuffer       *
 #define CLUTTER_LAYER_NODE(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_LAYER_NODE, 
ClutterLayerNode))
 #define CLUTTER_IS_LAYER_NODE(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_LAYER_NODE))
 
-/*
- * ClutterLayerNode:
- *
- * The #ClutterLayerNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterLayerNode                ClutterLayerNode;
 typedef struct _ClutterLayerNodeClass           ClutterLayerNodeClass;
 
@@ -218,14 +158,6 @@ ClutterPaintNode * clutter_layer_node_new_to_framebuffer (CoglFramebuffer *frame
 #define CLUTTER_TRANSFORM_NODE(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
CLUTTER_TYPE_TRANSFORM_NODE, ClutterTransformNode))
 #define CLUTTER_IS_TRANSFORM_NODE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
CLUTTER_TYPE_TRANSFORM_NODE))
 
-/*
- * ClutterTransformNode:
- *
- * The #ClutterLayerNode structure is an opaque
- * type whose members cannot be directly accessed.
- *
- * Since: 1.10
- */
 typedef struct _ClutterTransformNode            ClutterTransformNode;
 typedef struct _ClutterPaintNodeClass           ClutterTransformNodeClass;
 
@@ -239,12 +171,6 @@ ClutterPaintNode *      clutter_transform_node_new          (const graphene_matr
 #define CLUTTER_BLIT_NODE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BLIT_NODE, 
ClutterBlitNode))
 #define CLUTTER_IS_BLIT_NODE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BLIT_NODE))
 
-/*
- * ClutterBlitNode:
- *
- * The #ClutterBlitNode structure is an opaque
- * type whose members cannot be directly accessed.
- */
 typedef struct _ClutterBlitNode                 ClutterBlitNode;
 typedef struct _ClutterPaintNodeClass           ClutterBlitNodeClass;
 
@@ -267,12 +193,6 @@ void clutter_blit_node_add_blit_rectangle (ClutterBlitNode *blit_node,
 #define CLUTTER_BLUR_NODE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_BLUR_NODE, 
ClutterBlurNode))
 #define CLUTTER_IS_BLUR_NODE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_BLUR_NODE))
 
-/**
- * ClutterBlurNode:
- *
- * The #ClutterBurNode structure is an opaque
- * type whose members cannot be directly accessed.
- */
 typedef struct _ClutterBlurNode                 ClutterBlurNode;
 typedef struct _ClutterLayerNodeClass           ClutterBlurNodeClass;
 
diff --git a/clutter/clutter/clutter-paint-volume.c b/clutter/clutter/clutter-paint-volume.c
index e30d804c07..e8e8e53644 100644
--- a/clutter/clutter/clutter-paint-volume.c
+++ b/clutter/clutter/clutter-paint-volume.c
@@ -289,13 +289,13 @@ clutter_paint_volume_set_width (ClutterPaintVolume *pv,
  * around the volume. It returns the size of that bounding box as
  * measured along the x-axis.
  *
- * If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, [method@Actor.get_transformed_paint_volume]
  * is used to transform a 2D child actor that is 100px wide, 100px
  * high and 0px deep into container coordinates then the width might
  * not simply be 100px if the child actor has a 3D rotation applied to
  * it.
  * 
- * Remember: if clutter_actor_get_transformed_paint_volume() is
+ * Remember: if [method@Actor.get_transformed_paint_volume] is
  * used then a transformed child volume will be defined relative to the
  * ancestor container actor and so a 2D child actor can have a 3D
  * bounding volume.
@@ -381,13 +381,13 @@ clutter_paint_volume_set_height (ClutterPaintVolume *pv,
  * around the volume. It returns the size of that bounding box as
  * measured along the y-axis.
  *
- * If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, [method@Actor.get_transformed_paint_volume]
  * is used to transform a 2D child actor that is 100px wide, 100px
  * high and 0px deep into container coordinates then the height might
  * not simply be 100px if the child actor has a 3D rotation applied to
  * it.
  *
- * Remember: if clutter_actor_get_transformed_paint_volume() is
+ * Remember: if [method@Actor.get_transformed_paint_volume] is
  * used then a transformed child volume will be defined relative to the
  * ancestor container actor and so a 2D child actor
  * can have a 3D bounding volume.
@@ -474,13 +474,13 @@ clutter_paint_volume_set_depth (ClutterPaintVolume *pv,
  * around the volume. It returns the size of that bounding box as
  * measured along the z-axis.
  *
- * If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, [method@Actor.get_transformed_paint_volume]
  * is used to transform a 2D child actor that is 100px wide, 100px
  * high and 0px deep into container coordinates then the depth might
  * not simply be 0px if the child actor has a 3D rotation applied to
  * it.
  *
- * Remember: if clutter_actor_get_transformed_paint_volume() is
+ * Remember: if [method@Actor.get_transformed_paint_volume] is
  * used then the transformed volume will be defined relative to the
  * container actor and in container coordinates a 2D child actor
  * can have a 3D bounding volume.
@@ -607,7 +607,7 @@ done:
  *
  * Unions the 2D region represented by @box to a #ClutterPaintVolume.
  *
- * This function is similar to clutter_paint_volume_union(), but it is
+ * This function is similar to [method@PaintVolume.union], but it is
  * specific for 2D regions.
  *
  * Since: 1.10
@@ -985,19 +985,19 @@ _clutter_actor_set_default_paint_volume (ClutterActor       *self,
  * Sets the #ClutterPaintVolume from the allocation of @actor.
  *
  * This function should be used when overriding the
- * #ClutterActorClass.get_paint_volume() by #ClutterActor sub-classes
+ * [vfunc@Actor.get_paint_volume] by [class@Actor] sub-classes
  * that do not paint outside their allocation.
  *
  * A typical example is:
  *
- * |[
+ * ```c
  * static gboolean
  * my_actor_get_paint_volume (ClutterActor       *self,
  *                            ClutterPaintVolume *volume)
  * {
  *   return clutter_paint_volume_set_from_allocation (volume, self);
  * }
- * ]|
+ * ```
  *
  * Return value: %TRUE if the paint volume was successfully set, and %FALSE
  *   otherwise
diff --git a/clutter/clutter/clutter-pan-action.c b/clutter/clutter/clutter-pan-action.c
index 5521121ce0..e1e2d792e5 100644
--- a/clutter/clutter/clutter-pan-action.c
+++ b/clutter/clutter/clutter-pan-action.c
@@ -31,21 +31,21 @@
  */
 
 /**
- * SECTION:clutter-pan-action
- * @Title: ClutterPanAction
- * @Short_Description: Action for pan gestures
+ * ClutterPanAction:
+ * 
+ * Action for pan gestures
  *
- * #ClutterPanAction is a sub-class of #ClutterGestureAction that implements
+ * #ClutterPanAction is a sub-class of [class@GestureAction] that implements
  * the logic for recognizing pan gestures.
  *
  * The simplest usage of #ClutterPanAction consists in adding it to
- * a #ClutterActor with a child and setting it as reactive; for instance,
+ * a [class@Actor] with a child and setting it as reactive; for instance,
  * the following code:
  *
- * |[
+ * ```c
  *   clutter_actor_add_action (actor, clutter_pan_action_new ());
  *   clutter_actor_set_reactive (actor, TRUE);
- * ]|
+ * ```
  *
  * will automatically result in the actor children to be moved
  * when dragging.
@@ -551,7 +551,7 @@ clutter_pan_action_class_init (ClutterPanActionClass *klass)
    * @is_interpolated: if the event is the result of interpolating
    *                   the motion velocity at the end of the drag
    *
-   * The ::pan signal is emitted to keep track of the motion during
+   * The signal is emitted to keep track of the motion during
    * a pan gesture. @is_interpolated is set to %TRUE during the
    * interpolation phase of the pan, after the drag has ended and
    * the :interpolate property was set to %TRUE.
@@ -576,7 +576,7 @@ clutter_pan_action_class_init (ClutterPanActionClass *klass)
    * @action: the #ClutterPanAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::pan-stopped signal is emitted at the end of the interpolation
+   * The signal is emitted at the end of the interpolation
    * phase of the pan action, only when :interpolate is set to %TRUE.
    *
    * Since: 1.12
@@ -648,7 +648,7 @@ clutter_pan_action_set_pan_axis (ClutterPanAction *self,
  * clutter_pan_action_get_pan_axis:
  * @self: a #ClutterPanAction
  *
- * Retrieves the axis constraint set by clutter_pan_action_set_pan_axis()
+ * Retrieves the axis constraint set by [method@PanAction.set_pan_axis]
  *
  * Return value: the axis constraint
  *
@@ -801,7 +801,7 @@ clutter_pan_action_get_acceleration_factor (ClutterPanAction *self)
  *   interpolated event's Y coordinate
  *
  * Retrieves the coordinates, in stage space, of the latest interpolated
- * event, analogous to clutter_gesture_action_get_motion_coords().
+ * event, analogous to [method@GestureAction.get_motion_coords].
  *
  * Since: 1.12
  */
@@ -832,7 +832,7 @@ clutter_pan_action_get_interpolated_coords (ClutterPanAction *self,
  *   the latest interpolated event
  *
  * Retrieves the delta, in stage space, since the latest interpolated
- * event, analogous to clutter_gesture_action_get_motion_delta().
+ * event, analogous to [method@GestureAction.get_motion_delta].
  *
  * Return value: the distance since the latest interpolated event
  *
@@ -868,7 +868,7 @@ clutter_pan_action_get_interpolated_delta (ClutterPanAction *self,
  *
  * Retrieves the delta, in stage space, dependent on the current state
  * of the #ClutterPanAction, and respecting the constraint specified by the
- * #ClutterPanAction:pan-axis property.
+ * [property@PanAction:pan-axis] property.
  *
  * Return value: the distance since last motion event
  *
@@ -932,10 +932,10 @@ clutter_pan_action_get_constrained_motion_delta (ClutterPanAction *self,
  * Retrieves the delta, in stage space, dependent on the current state
  * of the #ClutterPanAction. If it is inactive, both fields will be
  * set to 0. If it is panning by user action, the values will be equivalent
- * to those returned by clutter_gesture_action_get_motion_delta().
+ * to those returned by [method@GestureAction.get_motion_delta].
  * If it is interpolating with some form of kinetic scrolling, the values
  * will be equivalent to those returned by
- * clutter_pan_action_get_interpolated_delta(). This is a convenience
+ * [method@PanAction.get_interpolated_delta]. This is a convenience
  * method designed to be used in replacement "pan" signal handlers.
  *
  * Since: 1.14
@@ -984,10 +984,10 @@ clutter_pan_action_get_motion_delta (ClutterPanAction *self,
  * Retrieves the coordinates, in stage space, dependent on the current state
  * of the #ClutterPanAction. If it is inactive, both fields will be
  * set to 0. If it is panning by user action, the values will be equivalent
- * to those returned by clutter_gesture_action_get_motion_coords().
+ * to those returned by [method@GestureAction.get_motion_coords].
  * If it is interpolating with some form of kinetic scrolling, the values
  * will be equivalent to those returned by
- * clutter_pan_action_get_interpolated_coords(). This is a convenience
+ * [method@PanAction.get_interpolated_coords]. This is a convenience
  * method designed to be used in replacement "pan" signal handlers.
  *
  * Since: 1.14
diff --git a/clutter/clutter/clutter-pan-action.h b/clutter/clutter/clutter-pan-action.h
index c740147922..d96a65c142 100644
--- a/clutter/clutter/clutter-pan-action.h
+++ b/clutter/clutter/clutter-pan-action.h
@@ -52,14 +52,6 @@ typedef struct _ClutterPanAction              ClutterPanAction;
 typedef struct _ClutterPanActionPrivate       ClutterPanActionPrivate;
 typedef struct _ClutterPanActionClass         ClutterPanActionClass;
 
-/**
- * ClutterPanAction:
- *
- * The #ClutterPanAction structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.12
- */
 struct _ClutterPanAction
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-path-constraint.c b/clutter/clutter/clutter-path-constraint.c
index b2eb918db0..ab6a537f7b 100644
--- a/clutter/clutter/clutter-path-constraint.c
+++ b/clutter/clutter/clutter-path-constraint.c
@@ -23,17 +23,17 @@
  */
 
 /**
- * SECTION:clutter-path-constraint
- * @Title: ClutterPathConstraint
- * @Short_Description: A constraint that follows a path
+ * ClutterPathConstraint:
+ * 
+ * A constraint that follows a path
  *
  * #ClutterPathConstraint is a simple constraint that modifies the allocation
- * of the #ClutterActor to which it has been applied using a #ClutterPath.
+ * of the [class@Actor] to which it has been applied using a [class@Path].
  *
- * By setting the #ClutterPathConstraint:offset property it is possible to
- * control how far along the path the #ClutterActor should be.
+ * By setting the [property@PathConstraint:offset] property it is possible to
+ * control how far along the path the [class@Actor] should be.
  *
- * ClutterPathConstraint is available since Clutter 1.6.
+ * Since: 1.6.
  */
 
 #include "clutter-build-config.h"
@@ -244,7 +244,7 @@ clutter_path_constraint_class_init (ClutterPathConstraintClass *klass)
    * @actor: the #ClutterActor using the @constraint
    * @index: the index of the node that has been reached
    *
-   * The ::node-reached signal is emitted each time a
+   * The signal is emitted each time a
    * #ClutterPathConstraint:offset value results in the actor
    * passing a #ClutterPathNode
    *
@@ -379,7 +379,7 @@ clutter_path_constraint_set_offset (ClutterPathConstraint *constraint,
  * clutter_path_constraint_get_offset:
  * @constraint: a #ClutterPathConstraint
  *
- * Retrieves the offset along the #ClutterPath used by @constraint.
+ * Retrieves the offset along the [class@Path] used by @constraint.
  *
  * Return value: the offset
  *
diff --git a/clutter/clutter/clutter-path-constraint.h b/clutter/clutter/clutter-path-constraint.h
index cd66a0350d..9a7bddb54b 100644
--- a/clutter/clutter/clutter-path-constraint.h
+++ b/clutter/clutter/clutter-path-constraint.h
@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define CLUTTER_PATH_CONSTRAINT(obj)    (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_PATH_CONSTRAINT, 
ClutterPathConstraint))
 #define CLUTTER_IS_PATH_CONSTRAINT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_PATH_CONSTRAINT))
 
-/**
- * ClutterPathConstraint:
- *
- * #ClutterPathConstraint is an opaque structure
- * whose members cannot be directly accessed
- *
- * Since: 1.6
- */
 typedef struct _ClutterPathConstraint           ClutterPathConstraint;
 typedef struct _ClutterPathConstraintClass      ClutterPathConstraintClass;
 
diff --git a/clutter/clutter/clutter-path.c b/clutter/clutter/clutter-path.c
index fba788df2a..d5c6d2ac03 100644
--- a/clutter/clutter/clutter-path.c
+++ b/clutter/clutter/clutter-path.c
@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:clutter-path
- * @short_description: An object describing a path with straight lines
- * and bezier curves.
+ * ClutterPath:
+ * 
+ * An object describing a path with straight lines and bezier curves.
  *
  * A #ClutterPath contains a description of a path consisting of
  * straight lines and bezier curves.
@@ -42,7 +42,7 @@
  *  - %CLUTTER_PATH_CURVE_TO, creates a bezier curve. The end of the
  *  last node is used as the first control point and the three
  *  subsequent coordinates given in the node as used as the other three.
- *  -%CLUTTER_PATH_CLOSE, creates a straight line from the last node to
+ *  - %CLUTTER_PATH_CLOSE, creates a straight line from the last node to
  *  the last %CLUTTER_PATH_MOVE_TO node. This can be used to close a
  *  path so that it will appear as a loop when animated.
  *
@@ -53,11 +53,11 @@
  * direct screen positions.
  *
  * You can build a path using the node adding functions such as
- * clutter_path_add_line_to(). Alternatively the path can be described
+ * [method@Path.add_line_to]. Alternatively the path can be described
  * in a string using a subset of the SVG path syntax. See
- * clutter_path_add_string() for details.
+ * [method@Path.add_string] for details.
  *
- * #ClutterPath is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -260,7 +260,7 @@ clutter_path_new (void)
  * @desc: a string describing the path
  *
  * Creates a new #ClutterPath instance with the nodes described in
- * @desc. See clutter_path_add_string() for details of the format of
+ * @desc. See [method@Path.add_string] for details of the format of
  * the string.
  *
  * Return value: the newly created #ClutterPath
@@ -370,7 +370,7 @@ clutter_path_add_move_to (ClutterPath *path,
  * @x: the x coordinate
  * @y: the y coordinate
  *
- * Same as clutter_path_add_move_to() except the coordinates are
+ * Same as [method@Path.add_move_to] except the coordinates are
  * relative to the previous node.
  *
  * Since: 1.0
@@ -412,7 +412,7 @@ clutter_path_add_line_to (ClutterPath *path,
  * @x: the x coordinate
  * @y: the y coordinate
  *
- * Same as clutter_path_add_line_to() except the coordinates are
+ * Same as [method@Path.add_line_to] except the coordinates are
  * relative to the previous node.
  *
  * Since: 1.0
@@ -470,7 +470,7 @@ clutter_path_add_curve_to (ClutterPath *path,
  * @x_3: the x coordinate of the third control point
  * @y_3: the y coordinate of the third control point
  *
- * Same as clutter_path_add_curve_to() except the coordinates are
+ * Same as [method@Path.add_curve_to] except the coordinates are
  * relative to the previous node.
  *
  * Since: 1.0
@@ -698,9 +698,9 @@ clutter_path_add_nodes (ClutterPath *path,
  * For example, to move an actor in a 100 by 100 pixel square centered
  * on the point 300,300 you could use the following path:
  *
- * |[
+ * ```
  *   M 250,350 l 0 -100 L 350,250 l 0 100 z
- * ]|
+ * ```
  *
  * If the path description isn't valid %FALSE will be returned and no
  * nodes will be added.
@@ -924,11 +924,12 @@ clutter_path_get_node (ClutterPath     *path,
  * clutter_path_get_nodes:
  * @path: a #ClutterPath
  *
- * Returns a #GSList of #ClutterPathNode<!-- -->s. The list should be
- * freed with g_slist_free(). The nodes are owned by the path and
- * should not be freed. Altering the path may cause the nodes in the
- * list to become invalid so you should copy them if you want to keep
- * the list.
+ * Returns a #GSList of [struct@PathNode]s.
+ * 
+ * The list should be freed with g_slist_free(). The nodes are owned 
+ * by the path and should not be freed. Altering the path may cause
+ * the nodes in the list to become invalid so you should copy them
+ * if you want to keep the list.
  *
  * Return value: (transfer container) (element-type Clutter.PathNode): a
  *   list of nodes in the path.
@@ -1088,7 +1089,7 @@ clutter_path_replace_node (ClutterPath           *path,
  * @str: a string describing the path
  *
  * Replaces all of the nodes in the path with nodes described by
- * @str. See clutter_path_add_string() for details of the format.
+ * @str. See [method@Path.add_string] for details of the format.
  *
  * If the string is invalid then %FALSE is returned and the path is
  * unaltered.
@@ -1122,7 +1123,7 @@ clutter_path_set_description (ClutterPath *path,
  * @path: a #ClutterPath
  *
  * Returns a newly allocated string describing the path in the same
- * format as used by clutter_path_add_string().
+ * format as used by [method@Path.add_string].
  *
  * Return value: a string description of the path. Free with g_free().
  *
diff --git a/clutter/clutter/clutter-path.h b/clutter/clutter/clutter-path.h
index 8ec4d93f50..00ec367107 100644
--- a/clutter/clutter/clutter-path.h
+++ b/clutter/clutter/clutter-path.h
@@ -49,7 +49,7 @@ typedef struct _ClutterPathPrivate ClutterPathPrivate;
  * @node: the node
  * @data: (closure): optional data passed to the function
  *
- * This function is passed to clutter_path_foreach() and will be
+ * This function is passed to [method@Path.foreach] and will be
  * called for each node contained in the path.
  *
  * Since: 1.0
@@ -57,14 +57,6 @@ typedef struct _ClutterPathPrivate ClutterPathPrivate;
 typedef void (* ClutterPathCallback) (const ClutterPathNode *node,
                                       gpointer               data);
 
-/**
- * ClutterPath:
- *
- * The #ClutterPath struct contains only private data and should
- * be accessed with the functions below.
- *
- * Since: 1.0
- */
 struct _ClutterPath
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-pick-context.c b/clutter/clutter/clutter-pick-context.c
index 28e095bfa6..97cc88cbfc 100644
--- a/clutter/clutter/clutter-pick-context.c
+++ b/clutter/clutter/clutter-pick-context.c
@@ -138,7 +138,7 @@ clutter_pick_context_log_overlap (ClutterPickContext *pick_context,
  * @box: a #ClutterActorBox
  *
  * Pushes a clip rectangle defined by @box into the pick stack. Pop with
- * clutter_pick_context_pop_clip() when done.
+ * [method@PickContext.pop_clip] when done.
  */
 void
 clutter_pick_context_push_clip (ClutterPickContext    *pick_context,
@@ -152,7 +152,7 @@ clutter_pick_context_push_clip (ClutterPickContext    *pick_context,
  * @pick_context: a #ClutterPickContext
  *
  * Pops the current clip rectangle from the clip stack. It is a programming
- * error to call this without a corresponding clutter_pick_context_push_clip()
+ * error to call this without a corresponding [method@PickContext.push_clip]
  * call first.
  */
 void
@@ -167,7 +167,7 @@ clutter_pick_context_pop_clip (ClutterPickContext *pick_context)
  * @transform: a #graphene_matrix_t
  *
  * Pushes @transform into the pick stack. Pop with
- * clutter_pick_context_pop_transform() when done.
+ * [method@PickContext.pop_transform] when done.
  */
 void
 clutter_pick_context_push_transform (ClutterPickContext      *pick_context,
@@ -195,7 +195,7 @@ clutter_pick_context_get_transform (ClutterPickContext *pick_context,
  * @pick_context: a #ClutterPickContext
  *
  * Pops the current transform from the clip stack. It is a programming error
- * to call this without a corresponding clutter_pick_context_push_transform()
+ * to call this without a corresponding [method@PickContext.push_transform]
  * call first.
  */
 void
diff --git a/clutter/clutter/clutter-property-transition.c b/clutter/clutter/clutter-property-transition.c
index f8c96761d8..2c716250f5 100644
--- a/clutter/clutter/clutter-property-transition.c
+++ b/clutter/clutter/clutter-property-transition.c
@@ -20,14 +20,14 @@
  */
 
 /**
- * SECTION:clutter-property-transition
- * @Title: ClutterPropertyTransition
- * @Short_Description: Property transitions
+ * ClutterPropertyTransition:
+ * 
+ * Property transitions
  *
- * #ClutterPropertyTransition is a specialized #ClutterTransition that
- * can be used to tween a property of a #ClutterAnimatable instance.
+ * #ClutterPropertyTransition is a specialized [class@Transition] that
+ * can be used to tween a property of a [iface@Animatable] instance.
  *
- * #ClutterPropertyTransition is available since Clutter 1.10
+ * Since: 1.10
  */
 
 #include "clutter-build-config.h"
@@ -258,7 +258,7 @@ clutter_property_transition_class_init (ClutterPropertyTransitionClass *klass)
   /**
    * ClutterPropertyTransition:property-name:
    *
-   * The name of the property of a #ClutterAnimatable to animate.
+   * The name of the property of a [iface@Animatable] to animate.
    *
    * Since: 1.10
    */
@@ -322,7 +322,7 @@ clutter_property_transition_new (const char *property_name)
  * @transition: a #ClutterPropertyTransition
  * @property_name: (allow-none): a property name
  *
- * Sets the #ClutterPropertyTransition:property-name property of @transition.
+ * Sets the [property@PropertyTransition:property-name] property of @transition.
  *
  * Since: 1.10
  */
@@ -360,7 +360,7 @@ clutter_property_transition_set_property_name (ClutterPropertyTransition *transi
  * clutter_property_transition_get_property_name:
  * @transition: a #ClutterPropertyTransition
  *
- * Retrieves the value of the #ClutterPropertyTransition:property-name
+ * Retrieves the value of the [property@PropertyTransition:property-name]
  * property.
  *
  * Return value: the name of the property being animated, or %NULL if
diff --git a/clutter/clutter/clutter-property-transition.h b/clutter/clutter/clutter-property-transition.h
index 5670746fac..a88d38c75f 100644
--- a/clutter/clutter/clutter-property-transition.h
+++ b/clutter/clutter/clutter-property-transition.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterPropertyTransitionPrivate        ClutterPropertyTransitionPrivate;
 typedef struct _ClutterPropertyTransitionClass          ClutterPropertyTransitionClass;
 
-/**
- * ClutterPropertyTransition:
- *
- * The #ClutterPropertyTransition structure contains
- * private data and should only be accessed using the provided API.
- *
- * Since: 1.10
- */
 struct _ClutterPropertyTransition
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-rotate-action.c b/clutter/clutter/clutter-rotate-action.c
index 21b1981e28..96dd3980a3 100644
--- a/clutter/clutter/clutter-rotate-action.c
+++ b/clutter/clutter/clutter-rotate-action.c
@@ -23,11 +23,11 @@
  */
 
 /**
- * SECTION:clutter-rotate-action
- * @Title: ClutterRotateAction
- * @Short_Description: Action to rotate an actor
+ * ClutterRotateAction:
+ * 
+ * Action to rotate an actor
  *
- * #ClutterRotateAction is a sub-class of #ClutterGestureAction that implements
+ * #ClutterRotateAction is a sub-class of [class@GestureAction] that implements
  * the logic for recognizing rotate gestures using two touch points.
  *
  * Since: 1.12
@@ -188,7 +188,7 @@ clutter_rotate_action_class_init (ClutterRotateActionClass *klass)
    * @angle: the difference of angle of rotation between the initial
    * rotation and the current rotation
    *
-   * The ::rotate signal is emitted when a rotate gesture is
+   * The signal is emitted when a rotate gesture is
    * recognized on the attached actor and when the gesture is
    * cancelled (in this case with an angle value of 0).
    *
diff --git a/clutter/clutter/clutter-rotate-action.h b/clutter/clutter/clutter-rotate-action.h
index f393a21c0a..4d10ec4391 100644
--- a/clutter/clutter/clutter-rotate-action.h
+++ b/clutter/clutter/clutter-rotate-action.h
@@ -44,14 +44,6 @@ typedef struct _ClutterRotateAction              ClutterRotateAction;
 typedef struct _ClutterRotateActionPrivate       ClutterRotateActionPrivate;
 typedef struct _ClutterRotateActionClass         ClutterRotateActionClass;
 
-/**
- * ClutterRotateAction:
- *
- * The #ClutterRotateAction structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.12
- */
 struct _ClutterRotateAction
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-script.c b/clutter/clutter/clutter-script.c
index e9d4d545e6..a056f59f06 100644
--- a/clutter/clutter/clutter-script.c
+++ b/clutter/clutter/clutter-script.c
@@ -24,8 +24,9 @@
  */
 
 /**
- * SECTION:clutter-script
- * @short_description: Loads a scene from UI definition data
+ * ClutterScript:
+ * 
+ * Loads a scene from UI definition data
  *
  * #ClutterScript is an object used for loading and building parts or a
  * complete scenegraph from external definition data in forms of string
@@ -47,7 +48,7 @@
  *
  * A simple object might be defined as:
  *
- * <informalexample><programlisting><![CDATA[
+ * ```json
  * {
  *   "id"     : "red-button",
  *   "type"   : "ClutterActor",
@@ -55,20 +56,20 @@
  *   "height" : 100,
  *   "background-color" : "&num;ff0000ff"
  * }
- * ]]></programlisting></informalexample>
+ * ```
  *
- * This will produce a red #ClutterActor, 100x100 pixels wide, and
+ * This will produce a red [class@Actor], 100x100 pixels wide, and
  * with a ClutterScript id of "red-button"; it can be retrieved by calling:
  *
- * |[
+ * ```c
  * ClutterActor *red_button;
  *
  * red_button = CLUTTER_ACTOR (clutter_script_get_object (script, "red-button"));
- * ]|
+ * ```
  *
  * and then manipulated with the Clutter API. For every object created
  * using ClutterScript it is possible to check the id by calling
- * clutter_get_script_id().
+ * [method@Scriptable.get_id].
  *
  * Packing can be represented using the "children" member, and passing an
  * array of objects or ids of objects already defined (but not packed: the
@@ -77,9 +78,9 @@
  *
  * Signal handlers can be defined inside a Clutter UI definition file and
  * then autoconnected to their respective signals using the
- * clutter_script_connect_signals() function:
+ * [method@Script.connect_signals] function:
  *
- * <informalexample><programlisting><![CDATA[
+ * ```json
  *   ...
  *   "signals" : [
  *     { "name" : "button-press-event", "handler" : "on_button_press" },
@@ -90,7 +91,7 @@
  *     },
  *   ],
  *   ...
- * ]]></programlisting></informalexample>
+ * ```
  *
  * Signal handler definitions must have a "name" and a "handler" members;
  * they can also have the "after" and "swapped" boolean members (for the
@@ -102,7 +103,7 @@
  * through the usual GObject registration process should avoid using these
  * names to avoid collisions:
  *
- * <programlisting><![CDATA[
+ * ```
  *   "id"         := the unique name of a ClutterScript object
  *   "type"       := the class literal name, also used to infer the type
  *                   function
@@ -112,9 +113,9 @@
  *   "is-default" := a boolean flag used when defining the #ClutterStage;
  *                   if set to "true" the default stage will be used instead
  *                   of creating a new #ClutterStage instance
- * ]]></programlisting>
+ * ```
  *
- * #ClutterScript is available since Clutter 0.6
+ * Since: 0.6
  */
 
 #include "clutter-build-config.h"
@@ -334,9 +335,9 @@ clutter_script_class_init (ClutterScriptClass *klass)
   /**
    * ClutterScript:filename-set:
    *
-   * Whether the #ClutterScript:filename property is set. If this property
+   * Whether the [property@Script:filename] property is set. If this property
    * is %TRUE then the currently parsed data comes from a file, and the
-   * file name is stored inside the #ClutterScript:filename property.
+   * file name is stored inside the [property@Script:filename] property.
    *
    * Since: 0.6
    */
@@ -350,7 +351,7 @@ clutter_script_class_init (ClutterScriptClass *klass)
   /**
    * ClutterScript:filename:
    *
-   * The path of the currently parsed file. If #ClutterScript:filename-set
+   * The path of the currently parsed file. If [property@Script:filename-set]
    * is %FALSE then the value of this property is undefined.
    *
    * Since: 0.6
@@ -368,7 +369,7 @@ clutter_script_class_init (ClutterScriptClass *klass)
    * The translation domain, used to localize strings marked as translatable
    * inside a UI definition.
    *
-   * If #ClutterScript:translation-domain is set to %NULL, #ClutterScript
+   * If [property@Script:translation-domain] is set to %NULL, #ClutterScript
    * will use gettext(), otherwise g_dgettext() will be used.
    *
    * Since: 1.10
@@ -437,7 +438,7 @@ clutter_script_new (void)
  *
  * Return value: on error, zero is returned and @error is set
  *   accordingly. On success, the merge id for the UI definitions is
- *   returned. You can use the merge id with clutter_script_unmerge_objects().
+ *   returned. You can use the merge id with [method@Script.unmerge_objects].
  *
  * Since: 0.6
  */
@@ -486,7 +487,7 @@ clutter_script_load_from_file (ClutterScript  *script,
  *
  * Return value: on error, zero is returned and @error is set
  *   accordingly. On success, the merge id for the UI definitions is
- *   returned. You can use the merge id with clutter_script_unmerge_objects().
+ *   returned. You can use the merge id with [method@Script.unmerge_objects].
  *
  * Since: 0.6
  */
@@ -537,7 +538,7 @@ clutter_script_load_from_data (ClutterScript  *script,
  *
  * Return value: on error, zero is returned and @error is set
  *   accordingly. On success, the merge id for the UI definitions is
- *   returned. You can use the merge id with clutter_script_unmerge_objects().
+ *   returned. You can use the merge id with [method@Script.unmerge_objects].
  *
  * Since: 1.10
  */
@@ -633,7 +634,7 @@ clutter_script_get_objects_valist (ClutterScript *script,
  * names/return location pairs should be listed, with a %NULL pointer
  * ending the list, like:
  *
- * |[
+ * ```c
  *   GObject *my_label, *a_button, *main_timeline;
  *
  *   clutter_script_get_objects (script,
@@ -641,7 +642,7 @@ clutter_script_get_objects_valist (ClutterScript *script,
  *                               "a-button", &a_button,
  *                               "main-timeline", &main_timeline,
  *                               NULL);
- * ]|
+ * ```
  *
  * Note: This function does not increment the reference count of the
  * returned objects.
@@ -883,7 +884,7 @@ clutter_script_default_connect (ClutterScript *script,
  * Connects all the signals defined into a UI definition file to their
  * handlers.
  *
- * This method invokes clutter_script_connect_signals_full() internally
+ * This method invokes [method@Script.connect_signals_full] internally
  * and uses  #GModule's introspective features (by opening the current
  * module's scope) to look at the application's symbol table.
  * 
@@ -994,7 +995,7 @@ connect_each_object (gpointer key,
  * names using the native API, but it can also be used on platforms
  * that do not support GModule.
  *
- * Applications should use clutter_script_connect_signals().
+ * Applications should use [method@Script.connect_signals].
  *
  * Since: 0.6
  */
@@ -1030,7 +1031,7 @@ clutter_script_error_quark (void)
  *
  * Adds @paths to the list of search paths held by @script.
  *
- * The search paths are used by clutter_script_lookup_filename(), which
+ * The search paths are used by [method@Script.lookup_filename], which
  * can be used to define search paths for the textures source file name
  * or other custom, file-based properties.
  *
@@ -1157,7 +1158,7 @@ clutter_script_lookup_filename (ClutterScript *script,
  * objects it returns.
  *
  * Return value: (transfer container) (element-type GObject.Object): a list
- *   of #GObject<!-- -->s, or %NULL. The objects are owned by the
+ *   of `GObject`s, or %NULL. The objects are owned by the
  *   #ClutterScript instance. Use g_list_free() on the returned list when
  *   done.
  *
@@ -1219,7 +1220,7 @@ clutter_script_set_translation_domain (ClutterScript *script,
  * @script: a #ClutterScript
  *
  * Retrieves the translation domain set using
- * clutter_script_set_translation_domain().
+ * [method@Script.set_translation_domain].
  *
  * Return value: (transfer none): the translation domain, if any is set,
  *   or %NULL
diff --git a/clutter/clutter/clutter-script.h b/clutter/clutter/clutter-script.h
index ca07a68103..2fcf4140e2 100644
--- a/clutter/clutter/clutter-script.h
+++ b/clutter/clutter/clutter-script.h
@@ -97,14 +97,6 @@ typedef enum
 CLUTTER_EXPORT
 GQuark clutter_script_error_quark (void);
 
-/**
- * ClutterScript:
- *
- * The #ClutterScript structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 0.6
- */
 struct _ClutterScript
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-scriptable.c b/clutter/clutter/clutter-scriptable.c
index 25b983c167..4ffcef0edf 100644
--- a/clutter/clutter/clutter-scriptable.c
+++ b/clutter/clutter/clutter-scriptable.c
@@ -25,15 +25,16 @@
  */
 
 /**
- * SECTION:clutter-scriptable
- * @short_description: Override the UI definition parsing
+ * ClutterScriptable:
+ * 
+ * Override the UI definition parsing
  *
- * The #ClutterScriptableIface interface exposes the UI definition parsing
+ * The #ClutterScriptable interface exposes the UI definition parsing
  * process to external classes. By implementing this interface, a class can
  * override the UI definition parsing and transform complex data types into
- * GObject properties, or allow custom properties.
+ * [class@GObject.Object] properties, or allow custom properties.
  *
- * #ClutterScriptable is available since Clutter 0.6
+ * Since: 0.6
  */
 
 #include "clutter-build-config.h"
@@ -68,7 +69,7 @@ clutter_scriptable_default_init (ClutterScriptableInterface *iface)
  *
  * This name can be used by user interface designer applications to
  * define a unique name for an object constructable using the UI
- * definition language parsed by #ClutterScript.
+ * definition language parsed by [class@Script].
  *
  * Since: 0.6
  */
@@ -95,7 +96,7 @@ clutter_scriptable_set_id (ClutterScriptable *scriptable,
  * clutter_scriptable_get_id:
  * @scriptable: a #ClutterScriptable
  *
- * Retrieves the id of @scriptable set using clutter_scriptable_set_id().
+ * Retrieves the id of @scriptable set using [method@Clutter.Scriptable.set_id].
  *
  * Return value: the id of the object. The returned string is owned by
  *   the scriptable object and should never be modified of freed
@@ -125,7 +126,7 @@ clutter_scriptable_get_id (ClutterScriptable *scriptable)
  * @node: the JSON node to be parsed
  *
  * Parses the passed JSON node. The implementation must set the type
- * of the passed #GValue pointer using g_value_init().
+ * of the passed [struct@GObject.Value] pointer using g_value_init().
  *
  * Return value: %TRUE if the node was successfully parsed, %FALSE otherwise.
  *
diff --git a/clutter/clutter/clutter-scriptable.h b/clutter/clutter/clutter-scriptable.h
index 82d187b362..445fcb6f31 100644
--- a/clutter/clutter/clutter-scriptable.h
+++ b/clutter/clutter/clutter-scriptable.h
@@ -43,15 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterScriptable               ClutterScriptable;
 typedef struct _ClutterScriptableIface          ClutterScriptableIface;
 
-/**
- * ClutterScriptable:
- *
- * #ClutterScriptable is an opaque structure whose members cannot be directly
- * accessed
- *
- * Since: 0.6
- */
-
 /**
  * ClutterScriptableIface:
  * @set_id: virtual function for setting the id of a scriptable object
diff --git a/clutter/clutter/clutter-scroll-actor.c b/clutter/clutter/clutter-scroll-actor.c
index 9ef63b23a2..d7d939ddf5 100644
--- a/clutter/clutter/clutter-scroll-actor.c
+++ b/clutter/clutter/clutter-scroll-actor.c
@@ -20,17 +20,17 @@
  */
 
 /**
- * SECTION:clutter-scroll-actor
- * @Title: ClutterScrollActor
- * @Short_Description: An actor for displaying a portion of its children
+ * ClutterScrollActor:
+ * 
+ * An actor for displaying a portion of its children
  *
  * #ClutterScrollActor is an actor that can be used to display a portion
  * of the contents of its children.
  *
  * The extent of the area of a #ClutterScrollActor is defined by the size
  * of its children; the visible region of the children of a #ClutterScrollActor
- * is set by using clutter_scroll_actor_scroll_to_point() or by using
- * clutter_scroll_actor_scroll_to_rect() to define a point or a rectangle
+ * is set by using [method@ScrollActor.scroll_to_point] or by using
+ * [method@ScrollActor.scroll_to_rect] to define a point or a rectangle
  * acting as the origin, respectively.
  *
  * #ClutterScrollActor does not provide pointer or keyboard event handling,
@@ -39,7 +39,7 @@
  * See [scroll-actor.c](https://git.gnome.org/browse/clutter/tree/examples/scroll-actor.c?h=clutter-1.18)
  * for an example of how to use #ClutterScrollActor.
  *
- * #ClutterScrollActor is available since Clutter 1.12.
+ * Since: 1.12.
  */
 
 #include "clutter-build-config.h"
@@ -280,7 +280,7 @@ clutter_scroll_actor_new (void)
  * @actor: a #ClutterScrollActor
  * @mode: a #ClutterScrollMode
  *
- * Sets the #ClutterScrollActor:scroll-mode property.
+ * Sets the [property@ScrollActor:scroll-mode] property.
  *
  * Since: 1.12
  */
@@ -306,7 +306,7 @@ clutter_scroll_actor_set_scroll_mode (ClutterScrollActor *actor,
  * clutter_scroll_actor_get_scroll_mode:
  * @actor: a #ClutterScrollActor
  *
- * Retrieves the #ClutterScrollActor:scroll-mode property
+ * Retrieves the [property@ScrollActor:scroll-mode] property
  *
  * Return value: the scrolling mode
  *
diff --git a/clutter/clutter/clutter-scroll-actor.h b/clutter/clutter/clutter-scroll-actor.h
index e6a1765213..ab4a61a272 100644
--- a/clutter/clutter/clutter-scroll-actor.h
+++ b/clutter/clutter/clutter-scroll-actor.h
@@ -41,14 +41,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterScrollActorPrivate       ClutterScrollActorPrivate;
 typedef struct _ClutterScrollActorClass         ClutterScrollActorClass;
 
-/**
- * ClutterScrollActor:
- *
- * The #ClutterScrollActor structure contains only
- * private data, and should be accessed using the provided API.
- *
- * Since: 1.12
- */
 struct _ClutterScrollActor
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-seat.c b/clutter/clutter/clutter-seat.c
index 1213042971..956907b424 100644
--- a/clutter/clutter/clutter-seat.c
+++ b/clutter/clutter/clutter-seat.c
@@ -140,7 +140,7 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * @latched_mask: the latched modifier mask from stickykeys
    * @locked_mask:  the locked modifier mask from stickykeys
    *
-   * The ::kbd-a11y-mods-state-changed signal is emitted each time either the
+   * The signal is emitted each time either the
    * latched modifiers mask or locked modifiers mask are changed as the
    * result of keyboard accessibilty's sticky keys operations.
    */
@@ -163,9 +163,8 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * @settings_flags: the new ClutterKeyboardA11yFlags configuration
    * @changed_mask: the ClutterKeyboardA11yFlags changed
    *
-   * The ::kbd-a11y-flags-changed signal is emitted each time the
-   * ClutterKeyboardA11yFlags configuration is changed as the result of
-   * keyboard accessibility operations.
+   * The signal is emitted each time the ClutterKeyboardA11yFlags
+   * configuration is changed as the result of keyboard accessibility operations.
    */
   signals[KBD_A11Y_FLAGS_CHANGED] =
     g_signal_new (I_("kbd-a11y-flags-changed"),
@@ -185,9 +184,8 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * @seat: the #ClutterSeat that emitted the signal
    * @click_type: the new #ClutterPointerA11yDwellClickType mode
    *
-   * The ::ptr-a11y-dwell-click-type-changed signal is emitted each time
-   * the ClutterPointerA11yDwellClickType mode is changed as the result
-   * of pointer accessibility operations.
+   * The signal is emitted each time the ClutterPointerA11yDwellClickType
+   * mode is changed as the result of pointer accessibility operations.
    */
   signals[PTR_A11Y_DWELL_CLICK_TYPE_CHANGED] =
     g_signal_new (I_("ptr-a11y-dwell-click-type-changed"),
@@ -204,9 +202,8 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * @timeout_type: the type of timeout #ClutterPointerA11yTimeoutType
    * @delay: the delay in ms before secondary-click is triggered.
    *
-   * The ::ptr-a11y-timeout-started signal is emitted when a
-   * pointer accessibility timeout delay is started, so that upper
-   * layers can notify the user with some visual feedback.
+   * The signal is emitted when a pointer accessibility timeout delay is started,
+   * so that upper layers can notify the user with some visual feedback.
    */
   signals[PTR_A11Y_TIMEOUT_STARTED] =
     g_signal_new (I_("ptr-a11y-timeout-started"),
@@ -229,10 +226,10 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * @timeout_type: the type of timeout #ClutterPointerA11yTimeoutType
    * @clicked: %TRUE if the timeout finished and triggered a click
    *
-   * The ::ptr-a11y-timeout-stopped signal is emitted when a running
-   * pointer accessibility timeout delay is stopped, either because
-   * it's triggered at the end of the delay or cancelled, so that
-   * upper layers can notify the user with some visual feedback.
+   * The signal is emitted when a running pointer accessibility timeout
+   * delay is stopped, either because it's triggered at the end of
+   * the delay or cancelled, so that upper layers can notify the user
+   * with some visual feedback.
    */
   signals[PTR_A11Y_TIMEOUT_STOPPED] =
     g_signal_new (I_("ptr-a11y-timeout-stopped"),
@@ -252,10 +249,10 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * ClutterSeat::is-unfocus-inhibited-changed:
    * @seat: the #ClutterSeat that emitted the signal
    *
-   * The ::is-unfocus-inhibited-changed signal is emitted when the
-   * property to inhibit the unsetting of the focus-surface of the
-   * #ClutterSeat changed. To get the current state of this property,
-   * use clutter_seat_is_unfocus_inhibited().
+   * The signal is emitted when the property to inhibit the unsetting
+   * of the focus-surface of the #ClutterSeat changed.
+   *  
+   * To get the current state of this property, use [method@Seat.is_unfocus_inhibited].
    */
   signals[IS_UNFOCUS_INHIBITED_CHANGED] =
     g_signal_new (I_("is-unfocus-inhibited-changed"),
@@ -268,7 +265,7 @@ clutter_seat_class_init (ClutterSeatClass *klass)
    * ClutterSeat:touch-mode:
    *
    * The current touch-mode of the #ClutterSeat, it is set to %TRUE if the
-   * requirements documented in clutter_seat_get_touch_mode() are fulfilled.
+   * requirements documented in [method@Seat.get_touch_mode] are fulfilled.
    **/
   props[PROP_TOUCH_MODE] =
     g_param_spec_boolean ("touch-mode",
@@ -477,8 +474,8 @@ clutter_seat_set_pointer_a11y_dwell_click_type (ClutterSeat
  * Inhibits unsetting of the pointer focus-surface for the #ClutterSeat @seat,
  * this allows to keep using the pointer even when it's hidden.
  *
- * This property is refcounted, so clutter_seat_uninhibit_unfocus() must be
- * called the exact same number of times as clutter_seat_inhibit_unfocus()
+ * This property is refcounted, so [method@Seat.uninhibit_unfocus] must be
+ * called the exact same number of times as [method@Seat.inhibit_unfocus]
  * was called before.
  **/
 void
@@ -501,10 +498,10 @@ clutter_seat_inhibit_unfocus (ClutterSeat *seat)
  * @seat: a #ClutterSeat
  *
  * Disables the inhibiting of unsetting of the pointer focus-surface
- * previously enabled by calling clutter_seat_inhibit_unfocus().
+ * previously enabled by calling [method@Seat.inhibit_unfocus].
  *
- * This property is refcounted, so clutter_seat_uninhibit_unfocus() must be
- * called the exact same number of times as clutter_seat_inhibit_unfocus()
+ * This property is refcounted, so [method@Seat.uninhibit_unfocus] must be
+ * called the exact same number of times as [method@Seat.inhibit_unfocus]
  * was called before.
  **/
 void
@@ -634,7 +631,7 @@ clutter_seat_warp_pointer (ClutterSeat *seat,
  * @seat: a #ClutterSeat
  *
  * Gets the current touch-mode state of the #ClutterSeat @seat.
- * The #ClutterSeat:touch-mode property is set to %TRUE if the following
+ * The [property@Seat:touch-mode] property is set to %TRUE if the following
  * requirements are fulfilled:
  *
  *  - A touchscreen is available
diff --git a/clutter/clutter/clutter-settings.c b/clutter/clutter/clutter-settings.c
index f3dffdbbba..9ec0b46deb 100644
--- a/clutter/clutter/clutter-settings.c
+++ b/clutter/clutter/clutter-settings.c
@@ -1,7 +1,7 @@
 /**
- * SECTION:clutter-settings
- * @Title: ClutterSettings
- * @Short_Description: Settings configuration
+ * ClutterSettings:
+ * 
+ * Settings configuration
  *
  * Clutter depends on some settings to perform operations like detecting
  * multiple button press events, or font options to render text.
@@ -14,7 +14,7 @@
  * the #ClutterSettings properties when implementing new UI elements,
  * for instance the default font name.
  *
- * #ClutterSettings is available since Clutter 1.4
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -53,14 +53,6 @@ typedef struct
   const char *clutter_font_subpixel_order;
 } FontSettings;
 
-/**
- * ClutterSettings:
- *
- * `ClutterSettings` is an opaque structure whose
- * members cannot be directly accessed.
- *
- * Since: 1.4
- */
 struct _ClutterSettings
 {
   GObject parent_instance;
@@ -787,7 +779,7 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
   /**
    * ClutterSettings:backend:
    *
-   * A back pointer to the #ClutterBackend
+   * A back pointer to the [class@Backend]
    *
    * Since: 1.4
    *
@@ -854,7 +846,7 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
    * ClutterSettings:font-name:
    *
    * The default font name that should be used by text actors, as
-   * a string that can be passed to pango_font_description_from_string().
+   * a string that can be passed to [func@Pango.FontDescription.from_string].
    *
    * Since: 1.4
    */
@@ -971,7 +963,7 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
    * Sets the minimum duration for a press to be recognized as a long press
    * gesture. The duration is expressed in milliseconds.
    *
-   * See also #ClutterClickAction:long-press-duration.
+   * See also [property@ClickAction:long-press-duration].
    *
    * Since: 1.8
    */
@@ -995,7 +987,7 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
    * ClutterText:password-hint-time:
    *
    * How long should Clutter show the last input character in editable
-   * ClutterText actors. The value is in milliseconds. A value of 0
+   * [class@Text] actors. The value is in milliseconds. A value of 0
    * disables showing the password hint. 600 is a good value for
    * enabling the hint.
    *
diff --git a/clutter/clutter/clutter-shader-effect.c b/clutter/clutter/clutter-shader-effect.c
index b2e577b635..cac1d3d8e9 100644
--- a/clutter/clutter/clutter-shader-effect.c
+++ b/clutter/clutter/clutter-shader-effect.c
@@ -23,29 +23,28 @@
  */
 
 /**
- * SECTION:clutter-shader-effect
- * @short_description: Base class for shader effects
- * @See_Also: #ClutterEffect, #ClutterOffscreenEffect
- *
+ * ClutterShaderEffect:
+ * 
+ * Base class for shader effects
+ * 
  * #ClutterShaderEffect is a class that implements all the plumbing for
- * creating #ClutterEffect<!-- -->s using GLSL shaders.
+ * creating [class@Effect]s using GLSL shaders.
  *
  * #ClutterShaderEffect creates an offscreen buffer and then applies the
  * GLSL shader (after checking whether the compilation and linking were
  * successful) to the buffer before painting it on screen.
  *
- * #ClutterShaderEffect is available since Clutter 1.4
  *
  * ## Implementing a ClutterShaderEffect
  *
  * Creating a sub-class of #ClutterShaderEffect requires the
- * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual
- * function from the #ClutterOffscreenEffect class. It is also convenient
- * to implement the #ClutterShaderEffectClass.get_static_shader_source()
+ * overriding of the [vfunc@OffscreenEffect.paint_target] virtual
+ * function from the [class@OffscreenEffect] class. It is also convenient
+ * to implement the [vfunc@ShaderEffect.get_static_shader_source]
  * virtual function in case you are planning to create more than one
  * instance of the effect.
  *
- * The #ClutterShaderEffectClass.get_static_shader_source()
+ * The [vfunc@ShaderEffect.get_static_shader_source]
  * function should return a copy of the shader source to use. This
  * function is only called once per subclass of #ClutterShaderEffect
  * regardless of how many instances of the effect are created. The
@@ -53,20 +52,20 @@
  * string which is returned from this function via
  * g_strdup().
  *
- * The #ClutterOffscreenEffectClass.paint_target() should set the
+ * The [vfunc@OffscreenEffect.paint_target] should set the
  * shader's uniforms if any. This is done by calling
- * clutter_shader_effect_set_uniform_value() or
- * clutter_shader_effect_set_uniform(). The sub-class should then
+ * [method@ShaderEffect.set_uniform_value] or
+ * [method@ShaderEffect.set_uniform]. The sub-class should then
  * chain up to the #ClutterShaderEffect implementation.
  *
  * ## Setting uniforms on a ClutterShaderEffect
  *
  * The example below shows a typical implementation of the
- * #ClutterShaderEffectClass.get_static_shader_source() and
- * #ClutterOffscreenEffectClass.paint_target() virtual functions
+ * [vfunc@ShaderEffect.get_static_shader_source] and
+ * [vfunc@OffscreenEffect.paint_target] virtual functions
  * for a #ClutterShaderEffect subclass.
  *
- * |[<!-- language="C" -->
+ * ```c
  *  static gchar *
  *  my_effect_get_static_shader_source (ClutterShaderEffect *effect)
  *  {
@@ -108,7 +107,9 @@
  *    parent_class = CLUTTER_OFFSCREEN_EFFECT_CLASS (my_effect_parent_class);
  *    return parent_class->paint_target (effect);
  *  }
- * ]|
+ * ```
+ * 
+ * Since: 1.4
  */
 
 #include "clutter-build-config.h"
@@ -486,9 +487,9 @@ clutter_shader_effect_init (ClutterShaderEffect *effect)
  *   or %CLUTTER_VERTEX_SHADER
  *
  * Creates a new #ClutterShaderEffect, to be applied to an actor using
- * clutter_actor_add_effect().
+ * [method@Actor.add_effect].
  *
- * The effect will be empty until clutter_shader_effect_set_shader_source()
+ * The effect will be empty until [method@ShaderEffect.set_shader_source]
  * is called.
  *
  * Return value: the newly created #ClutterShaderEffect.
@@ -780,16 +781,16 @@ add_uniform:
  * argument, and by the @gtype argument. For instance, a uniform named
  * "sampler0" and containing a single integer value is set using:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   clutter_shader_effect_set_uniform (effect, "sampler0",
  *                                      G_TYPE_INT, 1,
  *                                      0);
- * ]|
+ * ```
  *
  * While a uniform named "components" and containing a 3-elements vector
  * of floating point values (a "vec3") can be set using:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   gfloat component_r, component_g, component_b;
  *
  *   clutter_shader_effect_set_uniform (effect, "components",
@@ -797,28 +798,28 @@ add_uniform:
  *                                      component_r,
  *                                      component_g,
  *                                      component_b);
- * ]|
+ * ```
  *
  * or can be set using:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   gfloat component_vec[3];
  *
  *   clutter_shader_effect_set_uniform (effect, "components",
  *                                      CLUTTER_TYPE_SHADER_FLOAT, 3,
  *                                      component_vec);
- * ]|
+ * ```
  *
  * Finally, a uniform named "map" and containing a matrix can be set using:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   float v[16];
  *
  *   cogl_matrix_to_float (&matrix, v);
  *   clutter_shader_effect_set_uniform (effect, "map",
  *                                      CLUTTER_TYPE_SHADER_MATRIX,
  *                                      1, v);
- * ]|
+ * ```
  *
  * Since: 1.4
  */
diff --git a/clutter/clutter/clutter-shader-effect.h b/clutter/clutter/clutter-shader-effect.h
index 7df050ee72..4f5640548c 100644
--- a/clutter/clutter/clutter-shader-effect.h
+++ b/clutter/clutter/clutter-shader-effect.h
@@ -44,14 +44,6 @@ typedef struct _ClutterShaderEffect             ClutterShaderEffect;
 typedef struct _ClutterShaderEffectPrivate      ClutterShaderEffectPrivate;
 typedef struct _ClutterShaderEffectClass        ClutterShaderEffectClass;
 
-/**
- * ClutterShaderEffect:
- *
- * The #ClutterShaderEffect structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _ClutterShaderEffect
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-shader-types.c b/clutter/clutter/clutter-shader-types.c
index cdd78003de..6d0cc62147 100644
--- a/clutter/clutter/clutter-shader-types.c
+++ b/clutter/clutter/clutter-shader-types.c
@@ -386,7 +386,7 @@ clutter_shader_matrix_get_type (void)
  * @size: number of floating point values in @floats
  * @floats: (array length=size): an array of floating point values
  *
- * Sets @floats as the contents of @value. The passed #GValue
+ * Sets @floats as the contents of @value. The passed [struct@GObject.Value]
  * must have been initialized using %CLUTTER_TYPE_SHADER_FLOAT.
  *
  * Since: 0.8
@@ -416,7 +416,7 @@ clutter_value_set_shader_float (GValue         *value,
  * @size: number of integer values in @ints
  * @ints: (array length=size): an array of integer values
  *
- * Sets @ints as the contents of @value. The passed #GValue
+ * Sets @ints as the contents of @value. The passed [struct@GObject.Value]
  * must have been initialized using %CLUTTER_TYPE_SHADER_INT.
  *
  * Since: 0.8
@@ -446,7 +446,7 @@ clutter_value_set_shader_int (GValue     *value,
  * @size: number of floating point values in @floats
  * @matrix: (array length=size): a matrix of floating point values
  *
- * Sets @matrix as the contents of @value. The passed #GValue
+ * Sets @matrix as the contents of @value. The passed [struct@GObject.Value]
  * must have been initialized using %CLUTTER_TYPE_SHADER_MATRIX.
  *
  * Since: 0.8
@@ -477,7 +477,7 @@ clutter_value_set_shader_matrix (GValue       *value,
  *   point values, or %NULL
  *
  * Retrieves the list of floating point values stored inside
- * the passed #GValue. @value must have been initialized with
+ * the passed [struct@GObject.Value]. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_FLOAT.
  *
  * Return value: (array length=length): the pointer to a list of
@@ -509,7 +509,7 @@ clutter_value_get_shader_float (const GValue *value,
  *   values, or %NULL
  *
  * Retrieves the list of integer values stored inside the passed
- * #GValue. @value must have been initialized with
+ * [struct@GObject.Value]. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_INT.
  *
  * Return value: (array length=length): the pointer to a list of
@@ -541,7 +541,7 @@ clutter_value_get_shader_int (const GValue *value,
  *   point values, or %NULL
  *
  * Retrieves a matrix of floating point values stored inside
- * the passed #GValue. @value must have been initialized with
+ * the passed [struct@GObject.Value]. @value must have been initialized with
  * %CLUTTER_TYPE_SHADER_MATRIX.
  *
  * Return value: (array length=length) (transfer none): the pointer to a matrix
diff --git a/clutter/clutter/clutter-snap-constraint.c b/clutter/clutter/clutter-snap-constraint.c
index 5d526aab32..ed6930cfc7 100644
--- a/clutter/clutter/clutter-snap-constraint.c
+++ b/clutter/clutter/clutter-snap-constraint.c
@@ -23,16 +23,16 @@
  */
 
 /**
- * SECTION:clutter-snap-constraint
- * @Title: ClutterSnapConstraint
- * @Short_Description: A constraint snapping two actors together
+ * ClutterSnapConstraint:
+ * 
+ * A constraint snapping two actors together
  *
  * #ClutterSnapConstraint is a constraint the snaps the edges of two
  * actors together, expanding the actor's allocation if necessary.
  *
  * An offset can be applied to the constraint, to provide spacing.
  *
- * #ClutterSnapConstraint is available since Clutter 1.6
+ * Since: 1.6
  */
 
 #include "clutter-build-config.h"
@@ -310,7 +310,7 @@ clutter_snap_constraint_class_init (ClutterSnapConstraintClass *klass)
   /**
    * ClutterSnapConstraint:source:
    *
-   * The #ClutterActor used as the source for the constraint
+   * The [class@Actor] used as the source for the constraint
    *
    * Since: 1.6
    */
@@ -324,7 +324,7 @@ clutter_snap_constraint_class_init (ClutterSnapConstraintClass *klass)
   /**
    * ClutterSnapConstraint:from-edge:
    *
-   * The edge of the #ClutterActor that should be snapped
+   * The edge of the [class@Actor] that should be snapped
    *
    * Since: 1.6
    */
@@ -339,7 +339,7 @@ clutter_snap_constraint_class_init (ClutterSnapConstraintClass *klass)
   /**
    * ClutterSnapConstraint:to-edge:
    *
-   * The edge of the #ClutterSnapConstraint:source that should be snapped
+   * The edge of the [property@SnapConstraint:source] that should be snapped
    *
    * Since: 1.6
    */
@@ -354,8 +354,8 @@ clutter_snap_constraint_class_init (ClutterSnapConstraintClass *klass)
   /**
    * ClutterSnapConstraint:offset:
    *
-   * The offset, in pixels, between #ClutterSnapConstraint:from-edge
-   * and #ClutterSnapConstraint:to-edge
+   * The offset, in pixels, between [property@SnapConstraint:from-edge]
+   * and [property@SnapConstraint:to-edge]
    *
    * Since: 1.6
    */
@@ -393,7 +393,7 @@ clutter_snap_constraint_init (ClutterSnapConstraint *self)
  * @to_edge: the edge of @source to use in the constraint
  * @offset: the offset to apply to the constraint, in pixels
  *
- * Creates a new #ClutterSnapConstraint that will snap a #ClutterActor
+ * Creates a new #ClutterSnapConstraint that will snap a [class@Actor]
  * to the @edge of @source, with the given @offset.
  *
  * Return value: the newly created #ClutterSnapConstraint
@@ -421,7 +421,7 @@ clutter_snap_constraint_new (ClutterActor    *source,
  * @constraint: a #ClutterSnapConstraint
  * @source: (allow-none): a #ClutterActor, or %NULL to unset the source
  *
- * Sets the source #ClutterActor for the constraint
+ * Sets the source [class@Actor] for the constraint
  *
  * Since: 1.6
  */
@@ -469,7 +469,7 @@ clutter_snap_constraint_set_source (ClutterSnapConstraint *constraint,
  * clutter_snap_constraint_get_source:
  * @constraint: a #ClutterSnapConstraint
  *
- * Retrieves the #ClutterActor set using clutter_snap_constraint_set_source()
+ * Retrieves the [class@Actor] set using [method@SnapConstraint.set_source]
  *
  * Return value: (transfer none): a pointer to the source actor
  *
@@ -491,9 +491,9 @@ clutter_snap_constraint_get_source (ClutterSnapConstraint *constraint)
  *
  * Sets the edges to be used by the @constraint
  *
- * The @from_edge is the edge on the #ClutterActor to which @constraint
- * has been added. The @to_edge is the edge of the #ClutterActor inside
- * the #ClutterSnapConstraint:source property.
+ * The @from_edge is the edge on the [class@Actor] to which @constraint
+ * has been added. The @to_edge is the edge of the [class@Actor] inside
+ * the [property@SnapConstraint:source] property.
  *
  * Since: 1.6
  */
@@ -587,7 +587,7 @@ clutter_snap_constraint_set_offset (ClutterSnapConstraint *constraint,
  * clutter_snap_constraint_get_offset:
  * @constraint: a #ClutterSnapConstraint
  *
- * Retrieves the offset set using clutter_snap_constraint_set_offset()
+ * Retrieves the offset set using [method@SnapConstraint.set_offset]
  *
  * Return value: the offset, in pixels
  *
diff --git a/clutter/clutter/clutter-snap-constraint.h b/clutter/clutter/clutter-snap-constraint.h
index 4ee46d03d7..8ee5343ce7 100644
--- a/clutter/clutter/clutter-snap-constraint.h
+++ b/clutter/clutter/clutter-snap-constraint.h
@@ -37,14 +37,6 @@ G_BEGIN_DECLS
 #define CLUTTER_SNAP_CONSTRAINT(obj)    (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_SNAP_CONSTRAINT, 
ClutterSnapConstraint))
 #define CLUTTER_IS_SNAP_CONSTRAINT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_SNAP_CONSTRAINT))
 
-/**
- * ClutterSnapConstraint:
- *
- * #ClutterSnapConstraint is an opaque structure
- * whose members cannot be directly accesses
- *
- * Since: 1.6
- */
 typedef struct _ClutterSnapConstraint           ClutterSnapConstraint;
 typedef struct _ClutterSnapConstraintClass      ClutterSnapConstraintClass;
 
diff --git a/clutter/clutter/clutter-stage-manager.c b/clutter/clutter/clutter-stage-manager.c
index 0132e1983a..84a86fb178 100644
--- a/clutter/clutter/clutter-stage-manager.c
+++ b/clutter/clutter/clutter-stage-manager.c
@@ -22,18 +22,19 @@
  */
 
 /**
- * SECTION:clutter-stage-manager
- * @short_description: Maintains the list of stages
+ * ClutterStageManager:
+ * 
+ * Maintains the list of stages
  *
  * #ClutterStageManager is a singleton object, owned by Clutter, which
  * maintains the list of currently active stages
  *
- * Every newly-created #ClutterStage will cause the emission of the
- * #ClutterStageManager::stage-added signal; once a #ClutterStage has
- * been destroyed, the #ClutterStageManager::stage-removed signal will
+ * Every newly-created [class@Stage] will cause the emission of the
+ * [signal@StageManager::stage-added] signal; once a [class@Stage] has
+ * been destroyed, the [signal@StageManager::stage-removed] signal will
  * be emitted
  *
- * #ClutterStageManager is available since Clutter 0.8
+ * Since: 0.8
  */
 
 #include "clutter-build-config.h"
@@ -122,7 +123,7 @@ clutter_stage_manager_class_init (ClutterStageManagerClass *klass)
    * @stage_manager: the object which received the signal
    * @stage: the added stage
    *
-   * The ::stage-added signal is emitted each time a new #ClutterStage
+   * The signal is emitted each time a new #ClutterStage
    * has been added to the stage manager.
    *
    * Since: 0.8
@@ -140,7 +141,7 @@ clutter_stage_manager_class_init (ClutterStageManagerClass *klass)
    * @stage_manager: the object which received the signal
    * @stage: the removed stage
    *
-   * The ::stage-removed signal is emitted each time a #ClutterStage
+   * The signal is emitted each time a #ClutterStage
    * has been removed from the stage manager.
    *
    * Since: 0.8
diff --git a/clutter/clutter/clutter-stage-manager.h b/clutter/clutter/clutter-stage-manager.h
index 27da12e2e8..dcf4e9f201 100644
--- a/clutter/clutter/clutter-stage-manager.h
+++ b/clutter/clutter/clutter-stage-manager.h
@@ -42,14 +42,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterStageManager             ClutterStageManager;
 typedef struct _ClutterStageManagerClass        ClutterStageManagerClass;
 
-/**
- * ClutterStageManager:
- *
- * The #ClutterStageManager structure is private.
- *
- * Since: 1.0
- */
-
 /**
  * ClutterStageManagerClass:
  *
diff --git a/clutter/clutter/clutter-stage-window.c b/clutter/clutter/clutter-stage-window.c
index 40c45e2fb1..8f802882ff 100644
--- a/clutter/clutter/clutter-stage-window.c
+++ b/clutter/clutter/clutter-stage-window.c
@@ -8,11 +8,12 @@
 #include "clutter-private.h"
 
 /**
- * SECTION:clutter-stage-window
- * @short_description: Handles the implementation for ClutterStage
+ * ClutterStageWindow:
+ * 
+ * Handles the implementation for [class@Stage]
  *
  * #ClutterStageWindow is an interface that provides the implementation for the
- * #ClutterStage actor, abstracting away the specifics of the windowing system.
+ * [class@Stage] actor, abstracting away the specifics of the windowing system.
  */
 
 G_DEFINE_INTERFACE (ClutterStageWindow, clutter_stage_window, G_TYPE_OBJECT);
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index 17186c229d..8f02275297 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -22,8 +22,9 @@
  */
 
 /**
- * SECTION:clutter-stage
- * @short_description: Top level visual element to which actors are placed.
+ * ClutterStage:
+ * 
+ * Top level visual element to which actors are placed.
  *
  * #ClutterStage is a top level 'window' on which child actors are placed
  * and manipulated.
@@ -32,6 +33,8 @@
  * (a #StageWindow) of the windowing system. It is possible to subclass
  * #ClutterStage, as long as every overridden virtual function chains up to the
  * parent class corresponding function.
+ * 
+ * Since: 0.2
  */
 
 #include "clutter-build-config.h"
@@ -1353,7 +1356,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
   /**
    * ClutterStage:key-focus:
    *
-   * The #ClutterActor that will receive key events from the underlying
+   * The [class@Clutter.Actor] that will receive key events from the underlying
    * windowing system.
    *
    * If %NULL, the #ClutterStage will receive the events.
@@ -1374,7 +1377,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * ClutterStage::activate:
    * @stage: the stage which was activated
    *
-   * The ::activate signal is emitted when the stage receives key focus
+   * The signal is emitted when the stage receives key focus
    * from the underlying window system.
    *
    * Since: 0.6
@@ -1390,7 +1393,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * ClutterStage::deactivate:
    * @stage: the stage which was deactivated
    *
-   * The ::deactivate signal is emitted when the stage loses key focus
+   * The signal is emitted when the stage loses key focus
    * from the underlying window system.
    *
    * Since: 0.6
@@ -1421,7 +1424,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * @stage: the stage that received the event
    * @view: a #ClutterStageView
    *
-   * The ::prepare-frame signal is emitted after the stage is updated,
+   * The signal is emitted after the stage is updated,
    * before the stage is painted, even if it will not be painted.
    */
   stage_signals[PREPARE_FRAME] =
@@ -1438,7 +1441,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * @stage: the stage that received the event
    * @view: a #ClutterStageView
    *
-   * The ::before-paint signal is emitted before the stage is painted.
+   * The signal is emitted before the stage is painted.
    */
   stage_signals[BEFORE_PAINT] =
     g_signal_new (I_("before-paint"),
@@ -1453,7 +1456,7 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * @stage: the stage that received the event
    * @view: a #ClutterStageView
    *
-   * The ::after-paint signal is emitted after the stage is painted,
+   * The signal is emitted after the stage is painted,
    * but before the results are displayed on the screen.
    *
    * Since: 1.20
@@ -1487,12 +1490,12 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * @view: a #ClutterStageView
    * @redraw_clip: a #cairo_region_t with the redraw clip
    *
-   * The ::paint-view signal is emitted before a #ClutterStageView is being
+   * The signal is emitted before a [class@Clutter.StageView] is being
    * painted.
    *
    * The view is painted in the default handler. Hence, if you want to perform
    * some action after the view is painted, like reading the contents of the
-   * framebuffer, use g_signal_connect_after() or pass %G_CONNECT_AFTER.
+   * framebuffer, use [func@GObject.signal_connect_after] or pass %G_CONNECT_AFTER.
    */
   stage_signals[PAINT_VIEW] =
     g_signal_new (I_("paint-view"),
@@ -1931,7 +1934,7 @@ clutter_stage_read_pixels (ClutterStage *stage,
  * @y: Y coordinate to check
  *
  * Checks the scene at the coordinates @x and @y and returns a pointer
- * to the #ClutterActor at those coordinates. The result is the actor which
+ * to the [class@Clutter.Actor] at those coordinates. The result is the actor which
  * would be at the specified location on the next redraw, and is not
  * necessarily that which was there on the previous redraw. This allows the
  * function to perform chronologically correctly after any queued changes to
@@ -2847,7 +2850,7 @@ clutter_stage_presented (ClutterStage     *stage,
  * @out_scale: (out) (optional): the final scale factor
  *
  * Get the size of the framebuffer one must pass to
- * clutter_stage_paint_to_buffer() or clutter_stage_paint_to_framebuffer()
+ * [method@Stage.paint_to_buffer] or [method@Stage.paint_to_framebuffer]
  * would be used with the same @rect.
  *
  * Returns: %TRUE if the size has been retrieved, %FALSE otherwise.
@@ -3320,7 +3323,7 @@ clutter_stage_remove_device_entry (ClutterStage         *self,
  * @device: a #ClutterInputDevice
  * @sequence: (allow-none): an optional #ClutterEventSequence
  *
- * Retrieves the #ClutterActor underneath the pointer or touch point
+ * Retrieves the [class@Clutter.Actor] underneath the pointer or touch point
  * of @device and @sequence.
  *
  * Return value: (transfer none): a pointer to the #ClutterActor or %NULL
@@ -3805,7 +3808,7 @@ G_DEFINE_BOXED_TYPE (ClutterGrab, clutter_grab,
  * usual inside its hierarchy.
  *
  * Returns: (transfer full): an opaque #ClutterGrab handle, drop
- *   with clutter_grab_dismiss()
+ *   with [method@Grab.dismiss]
  **/
 ClutterGrab *
 clutter_stage_grab (ClutterStage *stage,
diff --git a/clutter/clutter/clutter-stage.h b/clutter/clutter/clutter-stage.h
index 5412c4d729..ff9fe284b2 100644
--- a/clutter/clutter/clutter-stage.h
+++ b/clutter/clutter/clutter-stage.h
@@ -46,14 +46,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterStageClass   ClutterStageClass;
 typedef struct _ClutterStagePrivate ClutterStagePrivate;
 
-/**
- * ClutterStage:
- *
- * The #ClutterStage structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 0.2
- */
 struct _ClutterStage
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-swipe-action.c b/clutter/clutter/clutter-swipe-action.c
index 17cd75e5cb..b37d1e138c 100644
--- a/clutter/clutter/clutter-swipe-action.c
+++ b/clutter/clutter/clutter-swipe-action.c
@@ -27,11 +27,11 @@
  */
 
 /**
- * SECTION:clutter-swipe-action
- * @Title: ClutterSwipeAction
- * @Short_Description: Action for swipe gestures
+ * ClutterSwipeAction:
+ * 
+ * Action for swipe gestures
  *
- * #ClutterSwipeAction is a sub-class of #ClutterGestureAction that implements
+ * #ClutterSwipeAction is a sub-class of [class@GestureAction] that implements
  * the logic for recognizing swipe gestures.
  *
  * Since: 1.8
@@ -199,10 +199,10 @@ clutter_swipe_action_class_init (ClutterSwipeActionClass *klass)
    * @actor: the #ClutterActor attached to the @action
    * @direction: the main direction of the swipe gesture
    *
-   * The ::swept signal is emitted when a swipe gesture is recognized on the
+   * The signal is emitted when a swipe gesture is recognized on the
    * attached actor.
    *
-   * Deprecated: 1.14: Use the ::swipe signal instead.
+   * Deprecated: 1.14: Use the [signal@SwipeAction::swipe] signal instead.
    *
    * Since: 1.8
    */
@@ -224,7 +224,7 @@ clutter_swipe_action_class_init (ClutterSwipeActionClass *klass)
    * @actor: the #ClutterActor attached to the @action
    * @direction: the main direction of the swipe gesture
    *
-   * The ::swipe signal is emitted when a swipe gesture is recognized on the
+   * The signal is emitted when a swipe gesture is recognized on the
    * attached actor.
    *
    * Return value: %TRUE if the swipe should continue, and %FALSE if
diff --git a/clutter/clutter/clutter-swipe-action.h b/clutter/clutter/clutter-swipe-action.h
index 44d4766bef..e8043de37b 100644
--- a/clutter/clutter/clutter-swipe-action.h
+++ b/clutter/clutter/clutter-swipe-action.h
@@ -48,14 +48,6 @@ typedef struct _ClutterSwipeAction              ClutterSwipeAction;
 typedef struct _ClutterSwipeActionPrivate       ClutterSwipeActionPrivate;
 typedef struct _ClutterSwipeActionClass         ClutterSwipeActionClass;
 
-/**
- * ClutterSwipeAction:
- *
- * The #ClutterSwipeAction structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.8
- */
 struct _ClutterSwipeAction
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-tap-action.c b/clutter/clutter/clutter-tap-action.c
index e5353f0405..d31b61270c 100644
--- a/clutter/clutter/clutter-tap-action.c
+++ b/clutter/clutter/clutter-tap-action.c
@@ -32,23 +32,23 @@
  */
 
 /**
- * SECTION:clutter-tap-action
- * @Title: ClutterTapAction
- * @Short_Description: Action for tap gestures
+ * ClutterTapAction:
+ * 
+ * Action for tap gestures
  *
- * #ClutterTapAction is a sub-class of #ClutterGestureAction that implements
+ * #ClutterTapAction is a sub-class of [class@GestureAction] that implements
  * the logic for recognizing mouse clicks and touch tap gestures.
  *
  * The simplest usage of #ClutterTapAction consists in adding it to
- * a #ClutterActor, setting it as reactive and connecting a
- * callback for the #ClutterTapAction::tap signal, along the lines of the
+ * a [class@Actor], setting it as reactive and connecting a
+ * callback for the [signal@TapAction::tap] signal, along the lines of the
  * following code:
  *
- * |[
+ * ```c
  *   clutter_actor_add_action (actor, clutter_tap_action_new ());
  *   clutter_actor_set_reactive (actor, TRUE);
  *   g_signal_connect (action, "tap", G_CALLBACK (on_tap_callback), NULL);
- * ]|
+ * ```
  *
  * Since: 1.14
  */
@@ -113,7 +113,7 @@ clutter_tap_action_class_init (ClutterTapActionClass *klass)
    * @action: the #ClutterTapAction that emitted the signal
    * @actor: the #ClutterActor attached to the @action
    *
-   * The ::tap signal is emitted when the tap gesture is complete.
+   * The signal is emitted when the tap gesture is complete.
    *
    * Since: 1.14
    */
diff --git a/clutter/clutter/clutter-tap-action.h b/clutter/clutter/clutter-tap-action.h
index 97fd604f33..f3fb264cfc 100644
--- a/clutter/clutter/clutter-tap-action.h
+++ b/clutter/clutter/clutter-tap-action.h
@@ -53,14 +53,6 @@ typedef struct _ClutterTapAction              ClutterTapAction;
 typedef struct _ClutterTapActionPrivate       ClutterTapActionPrivate;
 typedef struct _ClutterTapActionClass         ClutterTapActionClass;
 
-/**
- * ClutterTapAction:
- *
- * The #ClutterTapAction structure contains
- * only private data and should be accessed using the provided API
- *
- * Since: 1.14
- */
 struct _ClutterTapAction
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-text-buffer.c b/clutter/clutter/clutter-text-buffer.c
index 1436921d10..b88b57bc31 100644
--- a/clutter/clutter/clutter-text-buffer.c
+++ b/clutter/clutter/clutter-text-buffer.c
@@ -28,14 +28,14 @@
 #include <string.h>
 
 /**
- * SECTION:clutter-text-buffer
- * @title: ClutterTextBuffer
- * @short_description: Text buffer for ClutterText
+ * ClutterTextBuffer:
+ * 
+ * Text buffer for [class@Text]
  *
  * The #ClutterTextBuffer class contains the actual text displayed in a
- * #ClutterText widget.
+ * [class@Text] widget.
  *
- * A single #ClutterTextBuffer object can be shared by multiple #ClutterText
+ * A single #ClutterTextBuffer object can be shared by multiple [class@Text]
  * widgets which will then share the same text content, but not the cursor
  * position, visibility attributes, icon etc.
  *
@@ -494,7 +494,7 @@ clutter_text_buffer_get_length (ClutterTextBuffer *buffer)
  * @buffer: a #ClutterTextBuffer
  *
  * Retrieves the length in bytes of the buffer.
- * See clutter_text_buffer_get_length().
+ * See [method@TextBuffer.get_length].
  *
  * Return value: The byte length of the buffer.
  *
@@ -552,8 +552,8 @@ clutter_text_buffer_get_text (ClutterTextBuffer *buffer)
  *
  * Sets the text in the buffer.
  *
- * This is roughly equivalent to calling clutter_text_buffer_delete_text()
- * and clutter_text_buffer_insert_text().
+ * This is roughly equivalent to calling [method@TextBuffer.delete_text]
+ * and [method@TextBuffer.insert_text].
  *
  * Note that @n_chars is in characters, not in bytes.
  *
@@ -580,9 +580,10 @@ clutter_text_buffer_set_text (ClutterTextBuffer *buffer,
  *   (other than the maximum length of entries.) The value passed in will
  *   be clamped to the range [ 0, %CLUTTER_TEXT_BUFFER_MAX_SIZE ].
  *
- * Sets the maximum allowed length of the contents of the buffer. If
- * the current contents are longer than the given length, then they
- * will be truncated to fit.
+ * Sets the maximum allowed length of the contents of the buffer. 
+ * 
+ * If the current contents are longer than the given length,
+ * then they will be truncated to fit.
  *
  * Since: 1.10
  **/
@@ -606,7 +607,7 @@ clutter_text_buffer_set_max_length (ClutterTextBuffer *buffer,
  * @buffer: a #ClutterTextBuffer
  *
  * Retrieves the maximum allowed length of the text in
- * @buffer. See clutter_text_buffer_set_max_length().
+ * @buffer. See [method@TextBuffer.set_max_length].
  *
  * Return value: the maximum allowed number of characters
  *               in #ClutterTextBuffer, or 0 if there is no maximum.
@@ -728,7 +729,7 @@ clutter_text_buffer_delete_text (ClutterTextBuffer *buffer,
  * @chars: text that was inserted
  * @n_chars: number of characters inserted
  *
- * Emits the #ClutterTextBuffer::inserted-text signal on @buffer.
+ * Emits the [signal@TextBuffer::inserted-text] signal on @buffer.
  *
  * Used when subclassing #ClutterTextBuffer
  *
@@ -750,7 +751,7 @@ clutter_text_buffer_emit_inserted_text (ClutterTextBuffer *buffer,
  * @position: position at which text was deleted
  * @n_chars: number of characters deleted
  *
- * Emits the #ClutterTextBuffer::deleted-text signal on @buffer.
+ * Emits the [signal@TextBuffer::deleted-text] signal on @buffer.
  *
  * Used when subclassing #ClutterTextBuffer
  *
diff --git a/clutter/clutter/clutter-text-buffer.h b/clutter/clutter/clutter-text-buffer.h
index b65724d721..53257fa1a0 100644
--- a/clutter/clutter/clutter-text-buffer.h
+++ b/clutter/clutter/clutter-text-buffer.h
@@ -50,14 +50,6 @@ typedef struct _ClutterTextBuffer            ClutterTextBuffer;
 typedef struct _ClutterTextBufferClass       ClutterTextBufferClass;
 typedef struct _ClutterTextBufferPrivate     ClutterTextBufferPrivate;
 
-/**
- * ClutterTextBuffer:
- *
- * The #ClutterTextBuffer structure contains private
- * data and it should only be accessed using the provided API.
- *
- * Since: 1.10
- */
 struct _ClutterTextBuffer
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-text.c b/clutter/clutter/clutter-text.c
index b3c430b36c..2e30a46cb4 100644
--- a/clutter/clutter/clutter-text.c
+++ b/clutter/clutter/clutter-text.c
@@ -23,19 +23,20 @@
  */
 
 /**
- * SECTION:clutter-text
- * @short_description: An actor for displaying and editing text
+ * ClutterText:
+ * 
+ * An actor for displaying and editing text
  *
  * #ClutterText is an actor that displays custom text using Pango
  * as the text rendering engine.
  *
  * #ClutterText also allows inline editing of the text if the
- * actor is set editable using clutter_text_set_editable().
+ * actor is set editable using [method@Text.set_editable].
  *
  * Selection using keyboard or pointers can be enabled using
- * clutter_text_set_selectable().
+ * [method@Text.set_selectable].
  *
- * #ClutterText is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -3925,7 +3926,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    * ClutterText:font-name:
    *
    * The font to be used by the #ClutterText, as a string
-   * that can be parsed by pango_font_description_from_string().
+   * that can be parsed by [func@Pango.FontDescription.from_string].
    *
    * If set to %NULL, the default system font will be used instead.
    *
@@ -3942,10 +3943,10 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:font-description:
    *
-   * The #PangoFontDescription that should be used by the #ClutterText
+   * The [struct@Pango.FontDescription] that should be used by the #ClutterText
    *
    * If you have a string describing the font then you should look at
-   * #ClutterText:font-name instead
+   * [property@Text:font-name] instead
    *
    * Since: 1.2
    */
@@ -4011,7 +4012,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    * Whether it is possible to select text, either using the pointer
    * or the keyboard.
    *
-   * This property depends on the #ClutterActor:reactive property being
+   * This property depends on the [property@Actor:reactive] property being
    * set to %TRUE.
    *
    * Since: 1.0
@@ -4045,7 +4046,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    * Whether the input cursor is visible or not.
    *
    * The cursor will only be visible if this property and either
-   * the #ClutterText:editable or the #ClutterText:selectable properties
+   * the [property@Text:editable] or the [property@Text:selectable] properties
    * are set to %TRUE.
    *
    * Since: 1.0
@@ -4077,7 +4078,7 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:cursor-color-set:
    *
-   * Will be set to %TRUE if #ClutterText:cursor-color has been set.
+   * Will be set to %TRUE if [property@Text:cursor-color] has been set.
    *
    * Since: 1.0
    */
@@ -4112,7 +4113,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    *
    * Since: 1.0
    *
-   * Deprecated: 1.12: Use ClutterText:cursor-position instead.
+   * Deprecated: 1.12: Use [property@Text:cursor-position] instead.
    */
   pspec = g_param_spec_int ("position",
                             P_("Cursor Position"),
@@ -4176,7 +4177,7 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:selection-color-set:
    *
-   * Will be set to %TRUE if #ClutterText:selection-color has been set.
+   * Will be set to %TRUE if [property@Text:selection-color] has been set.
    *
    * Since: 1.0
    */
@@ -4191,7 +4192,7 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:attributes:
    *
-   * A list of #PangoStyleAttribute<!-- -->s to be applied to the
+   * A list of `PangoStyleAttribute`s to be applied to the
    * contents of the #ClutterText actor.
    *
    * Since: 1.0
@@ -4210,11 +4211,11 @@ clutter_text_class_init (ClutterTextClass *klass)
    * Whether the text includes Pango markup.
    *
    * For more information about the Pango markup format, see
-   * pango_layout_set_markup() in the Pango documentation.
+   * [method@Pango.Layout.set_markup] in the Pango documentation.
    *
    * It is not possible to round-trip this property between
    * %TRUE and %FALSE. Once a string with markup has been set on
-   * a #ClutterText actor with :use-markup set to %TRUE, the markup
+   * a #ClutterText actor with [property@Text:use-markup] set to %TRUE, the markup
    * is stripped from the string.
    *
    * Since: 1.0
@@ -4230,9 +4231,9 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:line-wrap:
    *
-   * Whether to wrap the lines of #ClutterText:text if the contents
+   * Whether to wrap the lines of [property@Text:text] if the contents
    * exceed the available allocation. The wrapping strategy is
-   * controlled by the #ClutterText:line-wrap-mode property.
+   * controlled by the [property@Text:line-wrap-mode] property.
    *
    * Since: 1.0
    */
@@ -4247,7 +4248,7 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:line-wrap-mode:
    *
-   * If #ClutterText:line-wrap is set to %TRUE, this property will
+   * If [property@Text:line-wrap] is set to %TRUE, this property will
    * control how the text is wrapped.
    *
    * Since: 1.0
@@ -4349,11 +4350,11 @@ clutter_text_class_init (ClutterTextClass *klass)
    * single line of text, scrolling it in case its length is bigger
    * than the allocated size.
    *
-   * Setting this property will also set the #ClutterText:activatable
+   * Setting this property will also set the [property@Text:activatable]
    * property as a side-effect.
    *
-   * The #ClutterText:single-line-mode property is used only if the
-   * #ClutterText:editable property is set to %TRUE.
+   * The [property@Text:single-line-mode] property is used only if the
+   * [property@Text:editable] property is set to %TRUE.
    *
    * Since: 1.0
    */
@@ -4384,7 +4385,7 @@ clutter_text_class_init (ClutterTextClass *klass)
   /**
    * ClutterText:selected-text-color-set:
    *
-   * Will be set to %TRUE if #ClutterText:selected-text-color has been set.
+   * Will be set to %TRUE if [property@Text:selected-text-color] has been set.
    *
    * Since: 1.8
    */
@@ -4416,7 +4417,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    * ClutterText::text-changed:
    * @self: the #ClutterText that emitted the signal
    *
-   * The ::text-changed signal is emitted after @actor's text changes
+   * The signal is emitted after @actor's text changes
    *
    * Since: 1.0
    */
@@ -4483,14 +4484,14 @@ clutter_text_class_init (ClutterTextClass *klass)
    * @self: the #ClutterText that emitted the signal
    * @rect: the coordinates of the cursor
    *
-   * The ::cursor-event signal is emitted whenever the cursor position
+   * The signal is emitted whenever the cursor position
    * changes inside a #ClutterText actor. Inside @rect it is stored
    * the current position and size of the cursor, relative to the actor
    * itself.
    *
    * Since: 1.0
    *
-   * Deprecated: 1.16: Use the #ClutterText::cursor-changed signal instead
+   * Deprecated: 1.16: Use the [signal@Text::cursor-changed] signal instead
    */
   text_signals[CURSOR_EVENT] =
     g_signal_new (I_("cursor-event"),
@@ -4505,7 +4506,7 @@ clutter_text_class_init (ClutterTextClass *klass)
    * ClutterText::cursor-changed:
    * @self: the #ClutterText that emitted the signal
    *
-   * The ::cursor-changed signal is emitted whenever the cursor
+   * The signal is emitted whenever the cursor
    * position or size changes.
    *
    * Since: 1.16
@@ -4522,9 +4523,9 @@ clutter_text_class_init (ClutterTextClass *klass)
    * ClutterText::activate:
    * @self: the #ClutterText that emitted the signal
    *
-   * The ::activate signal is emitted each time the actor is 'activated'
+   * The signal is emitted each time the actor is 'activated'
    * by the user, normally by pressing the 'Enter' key. The signal is
-   * emitted only if #ClutterText:activatable is set to %TRUE.
+   * emitted only if [property@Text:activatable] is set to %TRUE.
    *
    * Since: 1.0
    */
@@ -4738,9 +4739,9 @@ clutter_text_new (void)
  * description; @text will be used to set the contents of the actor;
  * and @color will be used as the color to render @text.
  *
- * This function is equivalent to calling clutter_text_new(),
- * clutter_text_set_font_name(), clutter_text_set_text() and
- * clutter_text_set_color().
+ * This function is equivalent to calling [ctor Text new],
+ * [method@Text.set_font_name], [method@Text.set_text] and
+ * [method@Text.set_color].
  *
  * Return value: the newly created #ClutterText actor
  *
@@ -4766,8 +4767,8 @@ clutter_text_new_full (const gchar        *font_name,
  * Creates a new #ClutterText actor, using @font_name as the font
  * description; @text will be used to set the contents of the actor.
  *
- * This function is equivalent to calling clutter_text_new(),
- * clutter_text_set_font_name(), and clutter_text_set_text().
+ * This function is equivalent to calling [ctor Text new],
+ * [method@Text.set_font_name], and [method@Text.set_text].
  *
  * Return value: the newly created #ClutterText actor
  *
@@ -4966,7 +4967,7 @@ clutter_text_get_buffer (ClutterText *self)
  * @self: a #ClutterText
  * @buffer: a #ClutterTextBuffer
  *
- * Set the #ClutterTextBuffer object which holds the text for
+ * Set the [class@TextBuffer] object which holds the text for
  * this widget.
  *
  * Since: 1.10
@@ -5015,7 +5016,7 @@ clutter_text_set_buffer (ClutterText       *self,
  * Sets whether the #ClutterText actor should be editable.
  *
  * An editable #ClutterText with key focus set using
- * clutter_actor_grab_key_focus() or clutter_stage_set_key_focus()
+ * [method@Actor.grab_key_focus] or [method@Stage.set_key_focus]
  * will receive key events and will update its contents accordingly.
  *
  * Since: 1.0
@@ -5125,12 +5126,12 @@ clutter_text_get_selectable (ClutterText *self)
  *
  * Sets whether a #ClutterText actor should be activatable.
  *
- * An activatable #ClutterText actor will emit the #ClutterText::activate
+ * An activatable #ClutterText actor will emit the [signal@Text::activate]
  * signal whenever the 'Enter' (or 'Return') key is pressed; if it is not
  * activatable, a new line will be appended to the current content.
  *
  * An activatable #ClutterText must also be set as editable using
- * clutter_text_set_editable().
+ * [method@Text.set_editable].
  *
  * Since: 1.0
  */
@@ -5176,15 +5177,15 @@ clutter_text_get_activatable (ClutterText *self)
  * clutter_text_activate:
  * @self: a #ClutterText
  *
- * Emits the #ClutterText::activate signal, if @self has been set
- * as activatable using clutter_text_set_activatable().
+ * Emits the [signal@Text::activate] signal, if @self has been set
+ * as activatable using [method@Text.set_activatable].
  *
- * This function can be used to emit the ::activate signal inside
- * a #ClutterActor::captured-event or #ClutterActor::key-press-event
+ * This function can be used to emit the [signal@Text::activate] signal inside
+ * a [signal@Actor::captured-event] or [signal@Actor::key-press-event]
  * signal handlers before the default signal handler for the
  * #ClutterText is invoked.
  *
- * Return value: %TRUE if the ::activate signal has been emitted,
+ * Return value: %TRUE if the [signal@Text::activate] signal has been emitted,
  *   and %FALSE otherwise
  *
  * Since: 1.0
@@ -5216,12 +5217,12 @@ clutter_text_activate (ClutterText *self)
  * visible or not.
  *
  * The color of the cursor will be the same as the text color
- * unless clutter_text_set_cursor_color() has been called.
+ * unless [method@Text.set_cursor_color] has been called.
  *
- * The size of the cursor can be set using clutter_text_set_cursor_size().
+ * The size of the cursor can be set using [method@Text.set_cursor_size].
  *
  * The position of the cursor can be changed programmatically using
- * clutter_text_set_cursor_position().
+ * [method@Text.set_cursor_position].
  *
  * Since: 1.0
  */
@@ -5348,7 +5349,7 @@ clutter_text_set_selection (ClutterText *self,
  * Retrieves the currently selected text.
  *
  * Return value: a newly allocated string containing the currently
- *   selected text, or %NULL. Use g_free() to free the returned
+ *   selected text, or %NULL. Use [func GLib free] to free the returned
  *   string.
  *
  * Since: 1.0
@@ -5519,7 +5520,7 @@ clutter_text_set_selected_text_color (ClutterText        *self,
 /**
  * clutter_text_get_selected_text_color:
  * @self: a #ClutterText
- * @color: (out caller-allocates): return location for a #ClutterColor
+ * @color: (out caller-allocates): return location for a [struct@Color]
  *
  * Retrieves the color of selected text of a #ClutterText actor.
  *
@@ -5547,7 +5548,7 @@ clutter_text_get_selected_text_color (ClutterText  *self,
  * Sets @font_desc as the font description for a #ClutterText
  *
  * The #PangoFontDescription is copied by the #ClutterText actor
- * so you can safely call pango_font_description_free() on it after
+ * so you can safely call [method Pango FontDescription free] on it after
  * calling this function.
  *
  * Since: 1.2
@@ -5566,7 +5567,7 @@ clutter_text_set_font_description (ClutterText          *self,
  * clutter_text_get_font_description:
  * @self: a #ClutterText
  *
- * Retrieves the #PangoFontDescription used by @self
+ * Retrieves the [struct@Pango.FontDescription] used by @self
  *
  * Return value: a #PangoFontDescription. The returned value is owned
  *   by the #ClutterText actor and it should not be modified or freed
@@ -5585,7 +5586,7 @@ clutter_text_get_font_description (ClutterText *self)
  * clutter_text_get_font_name:
  * @self: a #ClutterText
  *
- * Retrieves the font name as set by clutter_text_set_font_name().
+ * Retrieves the font name as set by [method@Text.set_font_name].
  *
  * Return value: a string containing the font name. The returned
  *   string is owned by the #ClutterText actor and should not be
@@ -5608,11 +5609,11 @@ clutter_text_get_font_name (ClutterText *text)
  *
  * Sets the font used by a #ClutterText. The @font_name string
  * must either be %NULL, which means that the font name from the
- * default #ClutterBackend will be used; or be something that can
- * be parsed by the pango_font_description_from_string() function,
+ * default [class@Backend] will be used; or be something that can
+ * be parsed by the [func@Pango.FontDescription.from_string] function,
  * like:
  *
- * |[
+ * ```c
  *   // Set the font to the system's Sans, 10 points
  *   clutter_text_set_font_name (text, "Sans 10");
  *
@@ -5621,7 +5622,7 @@ clutter_text_get_font_name (ClutterText *text)
  *
  *   // Set the font to Helvetica, 10 points
  *   clutter_text_set_font_name (text, "Helvetica 10");
- * ]|
+ * ```
  *
  * Since: 1.0
  */
@@ -5690,11 +5691,11 @@ out:
  * actor.
  *
  * If you need a copy of the contents for manipulating, either
- * use g_strdup() on the returned string, or use:
+ * use [func@GLib.strdup] on the returned string, or use:
  *
- * |[
+ * ```c
  *    copy = clutter_text_get_chars (text, 0, -1);
- * ]|
+ * ```
  *
  * Which will return a newly allocated string.
  *
@@ -5752,10 +5753,10 @@ clutter_text_set_use_markup_internal (ClutterText *self,
  *
  * Sets the contents of a #ClutterText actor.
  *
- * If the #ClutterText:use-markup property was set to %TRUE it
+ * If the [property@Text:use-markup] property was set to %TRUE it
  * will be reset to %FALSE as a side effect. If you want to
- * maintain the #ClutterText:use-markup you should use the
- * clutter_text_set_markup() function instead
+ * maintain the [property@Text:use-markup] you should use the
+ * [method@Text.set_markup] function instead
  *
  * Since: 1.0
  */
@@ -5790,11 +5791,11 @@ clutter_text_set_text (ClutterText *self,
  * This is a convenience function for setting a string containing
  * Pango markup, and it is logically equivalent to:
  *
- * |[
+ * ```c
  *   /&ast; the order is important &ast;/
  *   clutter_text_set_text (CLUTTER_TEXT (actor), markup);
  *   clutter_text_set_use_markup (CLUTTER_TEXT (actor), TRUE);
- * ]|
+ * ```
  *
  * Since: 1.0
  */
@@ -5852,7 +5853,7 @@ clutter_text_get_layout (ClutterText *self)
  * The overall opacity of the #ClutterText actor will be the
  * result of the alpha value of @color and the composited
  * opacity of the actor itself on the scenegraph, as returned
- * by clutter_actor_get_paint_opacity().
+ * by [method@Actor.get_paint_opacity].
  *
  * Since: 1.0
  */
@@ -5869,9 +5870,9 @@ clutter_text_set_color (ClutterText        *self,
 /**
  * clutter_text_get_color:
  * @self: a #ClutterText
- * @color: (out caller-allocates): return location for a #ClutterColor
+ * @color: (out caller-allocates): return location for a [struct@Color]
  *
- * Retrieves the text color as set by clutter_text_set_color().
+ * Retrieves the text color as set by [method@Text.set_color].
  *
  * Since: 1.0
  */
@@ -5929,7 +5930,7 @@ clutter_text_set_ellipsize (ClutterText        *self,
  * @self: a #ClutterText
  *
  * Returns the ellipsizing position of a #ClutterText actor, as
- * set by clutter_text_set_ellipsize().
+ * set by [method@Text.set_ellipsize].
  *
  * Return value: #PangoEllipsizeMode
  *
@@ -5947,7 +5948,7 @@ clutter_text_get_ellipsize (ClutterText *self)
  * clutter_text_get_line_wrap:
  * @self: a #ClutterText
  *
- * Retrieves the value set using clutter_text_set_line_wrap().
+ * Retrieves the value set using [method@Text.set_line_wrap].
  *
  * Return value: %TRUE if the #ClutterText actor should wrap
  *   its contents
@@ -5999,7 +6000,7 @@ clutter_text_set_line_wrap (ClutterText *self,
  * @self: a #ClutterText
  * @wrap_mode: the line wrapping mode
  *
- * If line wrapping is enabled (see clutter_text_set_line_wrap()) this
+ * If line wrapping is enabled (see [method@Text.set_line_wrap]) this
  * function controls how the line wrapping is performed. The default is
  * %PANGO_WRAP_WORD which means wrap on word boundaries.
  *
@@ -6033,7 +6034,7 @@ clutter_text_set_line_wrap_mode (ClutterText   *self,
  *
  * Retrieves the line wrap mode used by the #ClutterText actor.
  *
- * See clutter_text_set_line_wrap_mode ().
+ * See [method@Text.set_line_wrap_mode].
  *
  * Return value: the wrap mode used by the #ClutterText
  *
@@ -6055,7 +6056,7 @@ clutter_text_get_line_wrap_mode (ClutterText *self)
  * Sets the attributes list that are going to be applied to the
  * #ClutterText contents.
  *
- * The #ClutterText actor will take a reference on the #PangoAttrList
+ * The #ClutterText actor will take a reference on the [struct@Pango.AttrList]
  * passed to this function.
  *
  * Since: 1.0
@@ -6099,7 +6100,7 @@ clutter_text_set_attributes (ClutterText   *self,
  * @self: a #ClutterText
  *
  * Gets the attribute list that was set on the #ClutterText actor
- * clutter_text_set_attributes(), if any.
+ * [method@Text.set_attributes], if any.
  *
  * Return value: (transfer none): the attribute list, or %NULL if none was set. The
  *  returned value is owned by the #ClutterText and should not be unreferenced.
@@ -6153,9 +6154,9 @@ clutter_text_set_line_alignment (ClutterText    *self,
  * @self: a #ClutterText
  *
  * Retrieves the alignment of a #ClutterText, as set by
- * clutter_text_set_line_alignment().
+ * [method@Text.set_line_alignment].
  *
- * Return value: a #PangoAlignment
+ * Return value: a [enum@Pango.Alignment]
  *
  * Since: 1.0
  */
@@ -6173,12 +6174,12 @@ clutter_text_get_line_alignment (ClutterText *self)
  * @setting: %TRUE if the text should be parsed for markup.
  *
  * Sets whether the contents of the #ClutterText actor contains markup
- * in <link linkend="PangoMarkupFormat">Pango's text markup language</link>.
+ * in [Pango's text markup language](https://docs.gtk.org/Pango/pango_markup.html#pango-markup).
  *
- * Setting #ClutterText:use-markup on an editable #ClutterText will
+ * Setting [property@Text:use-markup] on an editable #ClutterText will
  * not have any effect except hiding the markup.
  *
- * See also #ClutterText:use-markup.
+ * See also [property@Text:use-markup].
  *
  * Since: 1.0
  */
@@ -6338,7 +6339,7 @@ clutter_text_set_cursor_position (ClutterText *self,
  *   default value
  *
  * Sets the size of the cursor of a #ClutterText. The cursor
- * will only be visible if the #ClutterText:cursor-visible property
+ * will only be visible if the [property@Text:cursor-visible] property
  * is set to %TRUE.
  *
  * Since: 1.0
@@ -6423,7 +6424,7 @@ clutter_text_set_password_char (ClutterText *self,
  * @self: a #ClutterText
  *
  * Retrieves the character to use in place of the actual text
- * as set by clutter_text_set_password_char().
+ * as set by [method@Text.set_password_char].
  *
  * Return value: a Unicode character or 0 if the password
  *   character is not set
@@ -6464,7 +6465,7 @@ clutter_text_set_max_length (ClutterText *self,
  *
  * Gets the maximum length of text that can be set into a text actor.
  *
- * See clutter_text_set_max_length().
+ * See [method@Text.set_max_length].
  *
  * Return value: the maximum number of characters.
  *
@@ -6539,7 +6540,7 @@ clutter_text_insert_unichar (ClutterText *self,
  * @text: the text to be inserted
  * @position: the position of the insertion, or -1
  *
- * Inserts @text into a #ClutterActor at the given position.
+ * Inserts @text into a [class@Actor] at the given position.
  *
  * If @position is a negative number, the text will be appended
  * at the end of the current contents of the #ClutterText.
@@ -6647,7 +6648,7 @@ clutter_text_delete_chars (ClutterText *self,
  * The positions are specified in characters, not in bytes.
  *
  * Return value: a newly allocated string with the contents of
- *   the text actor between the specified positions. Use g_free()
+ *   the text actor between the specified positions. Use [func GLib free]
  *   to free the resources when done
  *
  * Since: 1.0
@@ -6684,7 +6685,7 @@ clutter_text_get_chars (ClutterText *self,
  * @single_line: whether to enable single line mode
  *
  * Sets whether a #ClutterText actor should be in single line mode
- * or not. Only editable #ClutterText<!-- -->s can be in single line
+ * or not. Only editable `ClutterText`s can be in single line
  * mode.
  *
  * A text actor in single line mode will not wrap text and will clip
@@ -6692,9 +6693,9 @@ clutter_text_get_chars (ClutterText *self,
  * text actor will scroll to display the end of the text if its length
  * is bigger than the allocated width.
  *
- * When setting the single line mode the #ClutterText:activatable
+ * When setting the single line mode the [property@Text:activatable]
  * property is also set as a side effect. Instead of entering a new
- * line character, the text actor will emit the #ClutterText::activate
+ * line character, the text actor will emit the [signal@Text::activate]
  * signal.
  *
  * Since: 1.0
@@ -6822,7 +6823,7 @@ clutter_text_set_preedit_string (ClutterText   *self,
  * @x: (out): location to store X offset of layout, or %NULL
  * @y: (out): location to store Y offset of layout, or %NULL
  *
- * Obtains the coordinates where the #ClutterText will draw the #PangoLayout
+ * Obtains the coordinates where the #ClutterText will draw the [class@Pango.Layout]
  * representing the text.
  *
  * Since: 1.8
diff --git a/clutter/clutter/clutter-text.h b/clutter/clutter/clutter-text.h
index 7fa8116da9..258ccf9d83 100644
--- a/clutter/clutter/clutter-text.h
+++ b/clutter/clutter/clutter-text.h
@@ -46,13 +46,6 @@ typedef struct _ClutterText        ClutterText;
 typedef struct _ClutterTextPrivate ClutterTextPrivate;
 typedef struct _ClutterTextClass   ClutterTextClass;
 
-/**
- * ClutterText:
- *
- * The #ClutterText struct contains only private data.
- *
- * Since: 1.0
- */
 struct _ClutterText
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-texture-content.c b/clutter/clutter/clutter-texture-content.c
index 53aea4dc1e..79f0c308dd 100644
--- a/clutter/clutter/clutter-texture-content.c
+++ b/clutter/clutter/clutter-texture-content.c
@@ -111,15 +111,15 @@ clutter_content_iface_init (ClutterContentInterface *iface)
  * @texture: a #CoglTexture
  * @clip: (nullable): A clipping rectangle
  *
- * Creates a new #ClutterTextureContent instance for @texture, taking an
+ * Creates a new [class@TextureContent] instance for @texture, taking an
  * internal reference to @texture.
  *
- * If you change the contents of the #CoglTexture you will need
- * to manually invalidate the @texture_content with clutter_content_invalidate()
+ * If you change the contents of the [iface@Cogl.Texture] you will need
+ * to manually invalidate the @texture_content with [method@Content.invalidate]
  * in order to update the actors using @texture_content as their content.
  *
  * Return value: (transfer full): the newly created #ClutterTextureContent instance.
- *   Use g_object_unref() when done.
+ *   Use [method@GObject.Object.unref] when done.
  */
 ClutterContent *
 clutter_texture_content_new_from_texture (CoglTexture           *texture,
@@ -155,13 +155,13 @@ clutter_texture_content_new_from_texture (CoglTexture           *texture,
  * clutter_texture_content_get_texture:
  * @texture_content: a #ClutterTextureContent
  *
- * Retrieves a pointer to the #CoglTexture used by @texture_content.
+ * Retrieves a pointer to the [iface@Cogl.Texture] used by @texture_content.
  *
- * If you change the contents of the returned #CoglTexture you will need
- * to manually invalidate the @texture_content with clutter_content_invalidate()
+ * If you change the contents of the returned [iface@Cogl.Texture] you will need
+ * to manually invalidate the @texture_content with [method@Content.invalidate]
  * in order to update the actors using @texture_content as their content.
  *
- * Return value: (transfer none): a pointer to the #CoglTexture
+ * Return value: (transfer none): a pointer to the [iface@Cogl.Texture]
  */
 CoglTexture *
 clutter_texture_content_get_texture (ClutterTextureContent *texture_content)
diff --git a/clutter/clutter/clutter-timeline.c b/clutter/clutter/clutter-timeline.c
index 0f5ddaede8..692a6f9471 100644
--- a/clutter/clutter/clutter-timeline.c
+++ b/clutter/clutter/clutter-timeline.c
@@ -22,74 +22,77 @@
  */
 
 /**
- * SECTION:clutter-timeline
- * @short_description: A class for time-based events
+ * ClutterTimeline:
+ * 
+ * A class for time-based events
  *
  * #ClutterTimeline is a base class for managing time-based event that cause
  * Clutter to redraw a stage, such as animations.
  *
  * Each #ClutterTimeline instance has a duration: once a timeline has been
- * started, using clutter_timeline_start(), it will emit a signal that can
+ * started, using [method@Timeline.start], it will emit a signal that can
  * be used to update the state of the actors.
  *
  * It is important to note that #ClutterTimeline is not a generic API for
  * calling closures after an interval; each Timeline is tied into a frame
  * clock used to drive the frame cycle. If you need to schedule a closure
- * after an interval, see clutter_threads_add_timeout() instead.
+ * after an interval, see [func@threads_add_timeout] instead.
  *
- * Users of #ClutterTimeline should connect to the #ClutterTimeline::new-frame
+ * Users of #ClutterTimeline should connect to the [signal@Timeline::new-frame]
  * signal, which is emitted each time a timeline is advanced during the maste
- * clock iteration. The #ClutterTimeline::new-frame signal provides the time
+ * clock iteration. The [signal@Timeline::new-frame] signal provides the time
  * elapsed since the beginning of the timeline, in milliseconds. A normalized
- * progress value can be obtained by calling clutter_timeline_get_progress().
- * By using clutter_timeline_get_delta() it is possible to obtain the wallclock
- * time elapsed since the last emission of the #ClutterTimeline::new-frame
+ * progress value can be obtained by calling [method@Timeline.get_progress].
+ * By using [method@Timeline.get_delta] it is possible to obtain the wallclock
+ * time elapsed since the last emission of the [signal@Timeline::new-frame]
  * signal.
  *
- * Initial state can be set up by using the #ClutterTimeline::started signal,
- * while final state can be set up by using the #ClutterTimeline::stopped
+ * Initial state can be set up by using the [signal@Timeline::started] signal,
+ * while final state can be set up by using the [signal@Timeline::stopped]
  * signal. The #ClutterTimeline guarantees the emission of at least a single
- * #ClutterTimeline::new-frame signal, as well as the emission of the
- * #ClutterTimeline::completed signal every time the #ClutterTimeline reaches
- * its #ClutterTimeline:duration.
+ * [signal@Timeline::new-frame] signal, as well as the emission of the
+ * [signal@Timeline::completed] signal every time the #ClutterTimeline reaches
+ * its [property@Timeline:duration].
  *
  * It is possible to connect to specific points in the timeline progress by
- * adding markers using clutter_timeline_add_marker_at_time() and connecting
- * to the #ClutterTimeline::marker-reached signal.
+ * adding markers using [method@Timeline.add_marker_at_time] and connecting
+ * to the [signal@Timeline::marker-reached] signal.
  *
  * Timelines can be made to loop once they reach the end of their duration, by
  * using clutter_timeline_set_repeat_count(); a looping timeline will still
- * emit the #ClutterTimeline::completed signal once it reaches the end of its
+ * emit the [signal@Timeline::completed] signal once it reaches the end of its
  * duration at each repeat. If you want to be notified of the end of the last
- * repeat, use the #ClutterTimeline::stopped signal.
+ * repeat, use the [signal@Timeline::stopped] signal.
  *
- * Timelines have a #ClutterTimeline:direction: the default direction is
+ * Timelines have a [property@Timeline:direction]: the default direction is
  * %CLUTTER_TIMELINE_FORWARD, and goes from 0 to the duration; it is possible
  * to change the direction to %CLUTTER_TIMELINE_BACKWARD, and have the timeline
  * go from the duration to 0. The direction can be automatically reversed
- * when reaching completion by using the #ClutterTimeline:auto-reverse property.
+ * when reaching completion by using the [property@Timeline:auto-reverse] property.
  *
  * Timelines are used in the Clutter animation framework by classes like
- * #ClutterTransition.
+ * [class@Transition].
  *
  * ## Defining Timelines in ClutterScript
  *
- * A #ClutterTimeline can be described in #ClutterScript like any
+ * A #ClutterTimeline can be described in [class@Script] like any
  * other object. Additionally, it is possible to define markers directly
  * inside the JSON definition by using the `markers` JSON object member,
  * such as:
  *
- * |[
-{
-  "type" : "ClutterTimeline",
-  "duration" : 1000,
-  "markers" : [
-    { "name" : "quarter", "time" : 250 },
-    { "name" : "half-time", "time" : 500 },
-    { "name" : "three-quarters", "time" : 750 }
-  ]
-}
- * ]|
+ * ```json
+ * {
+ *   "type" : "ClutterTimeline",
+ *   "duration" : 1000,
+ *   "markers" : [
+ *     { "name" : "quarter", "time" : 250 },
+ *     { "name" : "half-time", "time" : 500 },
+ *     { "name" : "three-quarters", "time" : 750 }
+ *   ]
+ * }
+ * ```
+ *
+ * Since: 0.2
  */
 
 #include "clutter-build-config.h"
@@ -815,7 +818,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * ClutterTimeline:duration:
    *
    * Duration of the timeline in milliseconds, depending on the
-   * ClutterTimeline:fps value.
+   * [property@Timeline:frame-clock] value.
    *
    * Since: 0.6
    */
@@ -916,7 +919,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * @timeline: the timeline which received the signal
    * @msecs: the elapsed time between 0 and duration
    *
-   * The ::new-frame signal is emitted for each timeline running
+   * The signal is emitted for each timeline running
    * timeline before a new frame is drawn to give animations a chance
    * to update the scene.
    */
@@ -932,8 +935,8 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * ClutterTimeline::completed:
    * @timeline: the #ClutterTimeline which received the signal
    *
-   * The #ClutterTimeline::completed signal is emitted when the timeline's
-   * elapsed time reaches the value of the #ClutterTimeline:duration
+   * The signal is emitted when the timeline's
+   * elapsed time reaches the value of the [property@Timeline:duration]
    * property.
    *
    * This signal will be emitted even if the #ClutterTimeline is set to be
@@ -941,7 +944,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    *
    * If you want to get notification on whether the #ClutterTimeline has
    * been stopped or has finished its run, including its eventual repeats,
-   * you should use the #ClutterTimeline::stopped signal instead.
+   * you should use the [signal@Timeline::stopped] signal instead.
    */
   timeline_signals[COMPLETED] =
     g_signal_new (I_("completed"),
@@ -954,9 +957,9 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * ClutterTimeline::started:
    * @timeline: the #ClutterTimeline which received the signal
    *
-   * The ::started signal is emitted when the timeline starts its run.
-   * This might be as soon as clutter_timeline_start() is invoked or
-   * after the delay set in the ClutterTimeline:delay property has
+   * The signal is emitted when the timeline starts its run.
+   * This might be as soon as [method@Timeline.start] is invoked or
+   * after the delay set in the [property@Timeline:delay] property has
    * expired.
    */
   timeline_signals[STARTED] =
@@ -970,7 +973,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * ClutterTimeline::paused:
    * @timeline: the #ClutterTimeline which received the signal
    *
-   * The ::paused signal is emitted when clutter_timeline_pause() is invoked.
+   * The signal is emitted when [method@Timeline.pause] is invoked.
    */
   timeline_signals[PAUSED] =
     g_signal_new (I_("paused"),
@@ -985,14 +988,14 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * @marker_name: the name of the marker reached
    * @msecs: the elapsed time
    *
-   * The ::marker-reached signal is emitted each time a timeline
-   * reaches a marker set with
-   * clutter_timeline_add_marker_at_time(). This signal is detailed
-   * with the name of the marker as well, so it is possible to connect
-   * a callback to the ::marker-reached signal for a specific marker
-   * with:
+   * The signal is emitted each time a timeline
+   * reaches a marker set with [method@Timeline.add_marker_at_time].
+   * 
+   * This signal is detailed with the name of the marker as well,
+   * so it is possible to connect a callback to the [signal@Timeline::marker-reached] 
+   * signal for a specific marker with:
    *
-   * <informalexample><programlisting>
+   * ```c
    *   clutter_timeline_add_marker_at_time (timeline, "foo", 500);
    *   clutter_timeline_add_marker_at_time (timeline, "bar", 750);
    *
@@ -1002,7 +1005,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    *                     G_CALLBACK (foo_marker_reached), NULL);
    *   g_signal_connect (timeline, "marker-reached::bar",
    *                     G_CALLBACK (bar_marker_reached), NULL);
-   * </programlisting></informalexample>
+   * ```
    *
    * In the example, the first callback will be invoked for both
    * the "foo" and "bar" marker, while the second and third callbacks
@@ -1027,11 +1030,11 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
    * @is_finished: %TRUE if the signal was emitted at the end of the
    *   timeline.
    *
-   * The #ClutterTimeline::stopped signal is emitted when the timeline
-   * has been stopped, either because clutter_timeline_stop() has been
+   * The signal is emitted when the timeline
+   * has been stopped, either because [method Timeline stop] has been
    * called, or because it has been exhausted.
    *
-   * This is different from the #ClutterTimeline::completed signal,
+   * This is different from the [signal@Timeline::completed] signal,
    * which gets emitted after every repeat finishes.
    *
    * If the #ClutterTimeline has is marked as infinitely repeating,
@@ -1537,9 +1540,9 @@ clutter_timeline_skip (ClutterTimeline *timeline,
  * Advance timeline to the requested point. The point is given as a
  * time in milliseconds since the timeline started.
  *
- * The @timeline will not emit the #ClutterTimeline::new-frame
- * signal for the given time. The first ::new-frame signal after the call to
- * clutter_timeline_advance() will be emit the skipped markers.
+ * The @timeline will not emit the [signal@Timeline::new-frame]
+ * signal for the given time. The first [signal@Timeline::new-frame] signal
+ * after the call to [method@Timeline.advance] will be emit the skipped markers.
  */
 void
 clutter_timeline_advance (ClutterTimeline *timeline,
@@ -1593,7 +1596,7 @@ clutter_timeline_is_playing (ClutterTimeline *timeline)
  * Creates a new #ClutterTimeline with a duration of @duration_ms milli seconds.
  *
  * Return value: the newly created #ClutterTimeline instance. Use
- *   g_object_unref() when done using it
+ *   [method@GObject.Object.unref] when done using it
  *
  * Since: 0.6
  */
@@ -1613,7 +1616,7 @@ clutter_timeline_new (guint duration_ms)
  * Creates a new #ClutterTimeline with a duration of @duration milli seconds.
  *
  * Return value: the newly created #ClutterTimeline instance. Use
- *   g_object_unref() when done using it
+ *   [method@GObject.Object.unref] when done using it
  */
 ClutterTimeline *
 clutter_timeline_new_for_actor (ClutterActor *actor,
@@ -1633,7 +1636,7 @@ clutter_timeline_new_for_actor (ClutterActor *actor,
  * Creates a new #ClutterTimeline with a duration of @duration_ms milli seconds.
  *
  * Return value: the newly created #ClutterTimeline instance. Use
- *   g_object_unref() when done using it
+ *   [method@GObject.Object.unref] when done using it
  */
 ClutterTimeline *
 clutter_timeline_new_for_frame_clock (ClutterFrameClock *frame_clock,
@@ -1649,7 +1652,7 @@ clutter_timeline_new_for_frame_clock (ClutterFrameClock *frame_clock,
  * clutter_timeline_get_delay:
  * @timeline: a #ClutterTimeline
  *
- * Retrieves the delay set using clutter_timeline_set_delay().
+ * Retrieves the delay set using [method@Timeline.set_delay].
  *
  * Return value: the delay in milliseconds.
  *
@@ -1694,7 +1697,7 @@ clutter_timeline_set_delay (ClutterTimeline *timeline,
  * @timeline: a #ClutterTimeline
  *
  * Retrieves the duration of a #ClutterTimeline in milliseconds.
- * See clutter_timeline_set_duration().
+ * See [method@Timeline.set_duration].
  *
  * Return value: the duration of the timeline, in milliseconds.
  *
@@ -1718,7 +1721,7 @@ clutter_timeline_get_duration (ClutterTimeline *timeline)
  * @msecs: duration of the timeline in milliseconds
  *
  * Sets the duration of the timeline, in milliseconds. The speed
- * of the timeline depends on the ClutterTimeline:fps setting.
+ * of the timeline depends on the [property@Timeline:frame-clock] setting.
  *
  * Since: 0.6
  */
@@ -1748,8 +1751,8 @@ clutter_timeline_set_duration (ClutterTimeline *timeline,
  * The position of the timeline in a normalized [-1, 2] interval.
  *
  * The return value of this function is determined by the progress
- * mode set using clutter_timeline_set_progress_mode(), or by the
- * progress function set using clutter_timeline_set_progress_func().
+ * mode set using [method@Timeline.set_progress_mode], or by the
+ * progress function set using [method@Timeline.set_progress_func].
  *
  * Return value: the normalized current position in the timeline.
  *
@@ -1779,7 +1782,7 @@ clutter_timeline_get_progress (ClutterTimeline *timeline)
  * @timeline: a #ClutterTimeline
  *
  * Retrieves the direction of the timeline set with
- * clutter_timeline_set_direction().
+ * [method@Timeline.set_direction].
  *
  * Return value: the direction of the timeline
  *
@@ -1830,7 +1833,7 @@ clutter_timeline_set_direction (ClutterTimeline          *timeline,
  * @timeline: a #ClutterTimeline
  *
  * Retrieves the amount of time elapsed since the last
- * ClutterTimeline::new-frame signal.
+ * [signal@Timeline::new-frame] signal.
  *
  * This function is only useful inside handlers for the ::new-frame
  * signal, and its behaviour is undefined if the timeline is not
@@ -1960,14 +1963,14 @@ _clutter_timeline_do_tick (ClutterTimeline *timeline,
  *
  * Markers are unique string identifiers for a given position on the
  * timeline. Once @timeline reaches the given @progress of its duration,
- * if will emit a ::marker-reached signal for each marker attached to
- * that particular point.
+ * if will emit a [signal@Timeline::marker-reached] signal for each marker
+ * attached to that particular point.
  *
- * A marker can be removed with clutter_timeline_remove_marker(). The
+ * A marker can be removed with [method@Timeline.remove_marker]. The
  * timeline can be advanced to a marker using
- * clutter_timeline_advance_to_marker().
+ * [method@Timeline.advance_to_marker].
  *
- * See also: clutter_timeline_add_marker_at_time()
+ * See also: [method@Timeline.add_marker_at_time]
  *
  * Since: 1.14
  */
@@ -1996,13 +1999,13 @@ clutter_timeline_add_marker (ClutterTimeline *timeline,
  *
  * Markers are unique string identifiers for a given position on the
  * timeline. Once @timeline reaches the given @msecs, it will emit
- * a ::marker-reached signal for each marker attached to that position.
+ * a [signal@Timeline::marker-reached] signal for each marker attached to that position.
  *
- * A marker can be removed with clutter_timeline_remove_marker(). The
+ * A marker can be removed with [method@Timeline.remove_marker]. The
  * timeline can be advanced to a marker using
- * clutter_timeline_advance_to_marker().
+ * [method@Timeline.advance_to_marker].
  *
- * See also: clutter_timeline_add_marker()
+ * See also: [method@Timeline.add_marker]
  *
  * Since: 0.8
  */
@@ -2059,7 +2062,7 @@ collect_markers (const gchar *key,
  *
  * Return value: (transfer full) (array zero-terminated=1 length=n_markers):
  *   a newly allocated, %NULL terminated string array containing the names
- *   of the markers. Use g_strfreev() when done.
+ *   of the markers. Use [func@GLib.strfreev] when done.
  *
  * Since: 0.8
  */
@@ -2125,9 +2128,9 @@ clutter_timeline_list_markers (ClutterTimeline *timeline,
  *
  * Advances @timeline to the time of the given @marker_name.
  *
- * Like clutter_timeline_advance(), this function will not
- * emit the #ClutterTimeline::new-frame for the time where @marker_name
- * is set, nor it will emit #ClutterTimeline::marker-reached for
+ * Like [method@Timeline.advance], this function will not
+ * emit the [signal@Timeline::new-frame] for the time where @marker_name
+ * is set, nor it will emit [signal@Timeline::marker-reached] for
  * @marker_name.
  *
  * Since: 0.8
@@ -2235,14 +2238,14 @@ clutter_timeline_has_marker (ClutterTimeline *timeline,
  * @reverse: %TRUE if the @timeline should reverse the direction
  *
  * Sets whether @timeline should reverse the direction after the
- * emission of the #ClutterTimeline::completed signal.
+ * emission of the [signal@Timeline::completed] signal.
  *
- * Setting the #ClutterTimeline:auto-reverse property to %TRUE is the
- * equivalent of connecting a callback to the #ClutterTimeline::completed
+ * Setting the [property@Timeline:auto-reverse] property to %TRUE is the
+ * equivalent of connecting a callback to the [signal@Timeline::completed]
  * signal and changing the direction of the timeline from that callback;
  * for instance, this code:
  *
- * |[
+ * ```c
  * static void
  * reverse_timeline (ClutterTimeline *timeline)
  * {
@@ -2261,15 +2264,15 @@ clutter_timeline_has_marker (ClutterTimeline *timeline,
  *   g_signal_connect (timeline, "completed",
  *                     G_CALLBACK (reverse_timeline),
  *                     NULL);
- * ]|
+ * ```
  *
  * can be effectively replaced by:
  *
- * |[
+ * ```c
  *   timeline = clutter_timeline_new (1000);
  *   clutter_timeline_set_repeat_count (timeline, -1);
  *   clutter_timeline_set_auto_reverse (timeline);
- * ]|
+ * ```
  *
  * Since: 1.6
  */
@@ -2298,7 +2301,7 @@ clutter_timeline_set_auto_reverse (ClutterTimeline *timeline,
  * clutter_timeline_get_auto_reverse:
  * @timeline: a #ClutterTimeline
  *
- * Retrieves the value set by clutter_timeline_set_auto_reverse().
+ * Retrieves the value set by [method@Timeline.set_auto_reverse].
  *
  * Return value: %TRUE if the timeline should automatically reverse, and
  *   %FALSE otherwise
@@ -2351,7 +2354,7 @@ clutter_timeline_set_repeat_count (ClutterTimeline *timeline,
  * clutter_timeline_get_repeat_count:
  * @timeline: a #ClutterTimeline
  *
- * Retrieves the number set using clutter_timeline_set_repeat_count().
+ * Retrieves the number set using [method@Timeline.set_repeat_count].
  *
  * Return value: the number of repeats
  *
@@ -2374,15 +2377,15 @@ clutter_timeline_get_repeat_count (ClutterTimeline *timeline)
  *    or the timeline is disposed
  *
  * Sets a custom progress function for @timeline. The progress function will
- * be called by clutter_timeline_get_progress() and will be used to compute
+ * be called by [method@Timeline.get_progress] and will be used to compute
  * the progress value based on the elapsed time and the total duration of the
  * timeline.
  *
- * If @func is not %NULL, the #ClutterTimeline:progress-mode property will
+ * If @func is not %NULL, the [property@Timeline:progress-mode] property will
  * be set to %CLUTTER_CUSTOM_MODE.
  *
  * If @func is %NULL, any previously set progress function will be unset, and
- * the #ClutterTimeline:progress-mode property will be set to %CLUTTER_LINEAR.
+ * the [property@Timeline:progress-mode] property will be set to %CLUTTER_LINEAR.
  *
  * Since: 1.10
  */
@@ -2472,7 +2475,7 @@ clutter_timeline_progress_func (ClutterTimeline *timeline,
  * @timeline: a #ClutterTimeline
  * @mode: the progress mode, as a #ClutterAnimationMode
  *
- * Sets the progress function using a value from the #ClutterAnimationMode
+ * Sets the progress function using a value from the [enum@AnimationMode]
  * enumeration. The @mode cannot be %CLUTTER_CUSTOM_MODE or bigger than
  * %CLUTTER_ANIMATION_LAST.
  *
@@ -2514,8 +2517,8 @@ clutter_timeline_set_progress_mode (ClutterTimeline      *timeline,
  * clutter_timeline_get_progress_mode:
  * @timeline: a #ClutterTimeline
  *
- * Retrieves the progress mode set using clutter_timeline_set_progress_mode()
- * or clutter_timeline_set_progress_func().
+ * Retrieves the progress mode set using [method@Timeline.set_progress_mode]
+ * or [method@Timeline.set_progress_func].
  *
  * Return value: a #ClutterAnimationMode
  *
@@ -2534,9 +2537,9 @@ clutter_timeline_get_progress_mode (ClutterTimeline *timeline)
  * @timeline: a #ClutterTimeline
  *
  * Retrieves the full duration of the @timeline, taking into account the
- * current value of the #ClutterTimeline:repeat-count property.
+ * current value of the [property@Timeline:repeat-count] property.
  *
- * If the #ClutterTimeline:repeat-count property is set to -1, this function
+ * If the [property@Timeline:repeat-count] property is set to -1, this function
  * will return %G_MAXINT64.
  *
  * The returned value is to be considered a hint, and it's only valid
@@ -2590,7 +2593,7 @@ clutter_timeline_get_current_repeat (ClutterTimeline *timeline)
  * @step_mode: whether the change should happen at the start
  *   or at the end of the step
  *
- * Sets the #ClutterTimeline:progress-mode of the @timeline to %CLUTTER_STEPS
+ * Sets the [property@Timeline:progress-mode] of the @timeline to %CLUTTER_STEPS
  * and provides the parameters of the step function.
  *
  * Since: 1.12
@@ -2658,7 +2661,7 @@ clutter_timeline_get_step_progress (ClutterTimeline *timeline,
  * @c_1: the first control point for the cubic bezier
  * @c_2: the second control point for the cubic bezier
  *
- * Sets the #ClutterTimeline:progress-mode of @timeline
+ * Sets the [property@Timeline:progress-mode] of @timeline
  * to %CLUTTER_CUBIC_BEZIER, and sets the two control
  * points for the cubic bezier.
  *
diff --git a/clutter/clutter/clutter-timeline.h b/clutter/clutter/clutter-timeline.h
index 022a927ce2..6e7bf37000 100644
--- a/clutter/clutter/clutter-timeline.h
+++ b/clutter/clutter/clutter-timeline.h
@@ -60,14 +60,6 @@ typedef gdouble (* ClutterTimelineProgressFunc) (ClutterTimeline *timeline,
                                                  gdouble          total,
                                                  gpointer         user_data);
 
-/**
- * ClutterTimeline:
- *
- * The #ClutterTimeline structure contains only private data
- * and should be accessed using the provided API
- *
- * Since: 0.2
- */
 struct _ClutterTimeline
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-transition-group.c b/clutter/clutter/clutter-transition-group.c
index 3d8c5a53b9..ee1e2323f0 100644
--- a/clutter/clutter/clutter-transition-group.c
+++ b/clutter/clutter/clutter-transition-group.c
@@ -22,11 +22,11 @@
  */
 
 /**
- * SECTION:clutter-transition-group
- * @Title: ClutterTransitionGroup
- * @Short_Description: Group transitions together
+ * ClutterTransitionGroup:
+ * 
+ * Group transitions together
  *
- * The #ClutterTransitionGroup allows running multiple #ClutterTransition
+ * The #ClutterTransitionGroup allows running multiple [class@Transition]
  * instances concurrently.
  *
  * The transitions inside a group will run within the boundaries of the
@@ -34,7 +34,7 @@
  * the group that contains it has a duration of 5 seconds, only the first
  * 5 seconds of the transition will be played.
  *
- * #ClutterTransitionGroup is available since Clutter 1.12
+ * Since: 1.12
  */
 
 #include "clutter-build-config.h"
@@ -177,7 +177,7 @@ clutter_transition_group_init (ClutterTransitionGroup *self)
  * Creates a new #ClutterTransitionGroup instance.
  *
  * Return value: the newly created #ClutterTransitionGroup. Use
- *   g_object_unref() when done to deallocate the resources it
+ *   [method@GObject.Object.unref] when done to deallocate the resources it
  *   uses
  *
  * Since: 1.12
@@ -196,7 +196,7 @@ clutter_transition_group_new (void)
  * Adds @transition to @group.
  *
  * This function acquires a reference on @transition that will be released
- * when calling clutter_transition_group_remove_transition().
+ * when calling [method@TransitionGroup.remove_transition].
  *
  * Since: 1.12
  */
@@ -218,7 +218,7 @@ clutter_transition_group_add_transition (ClutterTransitionGroup *group,
  * Removes @transition from @group.
  *
  * This function releases the reference acquired on @transition when
- * calling clutter_transition_group_add_transition().
+ * calling [method@TransitionGroup.add_transition].
  *
  * Since: 1.12
  */
@@ -238,7 +238,7 @@ clutter_transition_group_remove_transition (ClutterTransitionGroup *group,
  * Removes all transitions from @group.
  *
  * This function releases the reference acquired when calling
- * clutter_transition_group_add_transition().
+ * [method@TransitionGroup.add_transition].
  *
  * Since: 1.12
  */
diff --git a/clutter/clutter/clutter-transition-group.h b/clutter/clutter/clutter-transition-group.h
index a98b7715c3..f3bfe25221 100644
--- a/clutter/clutter/clutter-transition-group.h
+++ b/clutter/clutter/clutter-transition-group.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterTransitionGroupPrivate           ClutterTransitionGroupPrivate;
 typedef struct _ClutterTransitionGroupClass             ClutterTransitionGroupClass;
 
-/**
- * ClutterTransitionGroup:
- *
- * The #ClutterTransitionGroup structure contains
- * private data and should only be accessed using the provided API.
- *
- * Since: 1.12
- */
 struct _ClutterTransitionGroup
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-transition.c b/clutter/clutter/clutter-transition.c
index 146c525460..e2c8373783 100644
--- a/clutter/clutter/clutter-transition.c
+++ b/clutter/clutter/clutter-transition.c
@@ -22,12 +22,14 @@
  */
 
 /**
- * SECTION:clutter-transition
- * @Title: ClutterTransition
- * @Short_Description: Transition between two values
+ * ClutterTransition:
+ * 
+ * Transition between two values
  *
- * #ClutterTransition is an abstract subclass of #ClutterTimeline that
- * computes the interpolation between two values, stored by a #ClutterInterval.
+ * #ClutterTransition is an abstract subclass of [class@Timeline] that
+ * computes the interpolation between two values, stored by a [class@Interval].
+ * 
+ * Since: 1.10
  */
 
 #include "clutter-build-config.h"
@@ -231,7 +233,7 @@ clutter_transition_class_init (ClutterTransitionClass *klass)
   /**
    * ClutterTransition:interval:
    *
-   * The #ClutterInterval used to describe the initial and final states
+   * The [class@Interval] used to describe the initial and final states
    * of the transition.
    *
    * Since: 1.10
@@ -247,7 +249,7 @@ clutter_transition_class_init (ClutterTransitionClass *klass)
   /**
    * ClutterTransition:animatable:
    *
-   * The #ClutterAnimatable instance currently being animated.
+   * The [iface@Animatable] instance currently being animated.
    *
    * Since: 1.10
    */
@@ -263,11 +265,11 @@ clutter_transition_class_init (ClutterTransitionClass *klass)
    * ClutterTransition:remove-on-complete:
    *
    * Whether the #ClutterTransition should be automatically detached
-   * from the #ClutterTransition:animatable instance whenever the
-   * #ClutterTimeline::stopped signal is emitted.
+   * from the [property@Transition:animatable] instance whenever the
+   * [signal@Timeline::stopped] signal is emitted.
    *
-   * The #ClutterTransition:remove-on-complete property takes into
-   * account the value of the #ClutterTimeline:repeat-count property,
+   * The [property@Transition:remove-on-complete] property takes into
+   * account the value of the [property@Timeline:repeat-count] property,
    * and it only detaches the transition if the transition is not
    * repeating.
    *
@@ -294,7 +296,7 @@ clutter_transition_init (ClutterTransition *self)
  * @transition: a #ClutterTransition
  * @interval: (allow-none): a #ClutterInterval, or %NULL
  *
- * Sets the #ClutterTransition:interval property using @interval.
+ * Sets the [property@Transition:interval] property using @interval.
  *
  * The @transition will acquire a reference on the @interval, sinking
  * the floating flag on it if necessary.
@@ -327,9 +329,9 @@ clutter_transition_set_interval (ClutterTransition *transition,
  * clutter_transition_get_interval:
  * @transition: a #ClutterTransition
  *
- * Retrieves the interval set using clutter_transition_set_interval()
+ * Retrieves the interval set using [method@Transition.set_interval]
  *
- * Return value: (transfer none): a #ClutterInterval, or %NULL; the returned
+ * Return value: (transfer none): a [class@Interval], or %NULL; the returned
  *   interval is owned by the #ClutterTransition and it should not be freed
  *   directly
  *
@@ -348,13 +350,13 @@ clutter_transition_get_interval (ClutterTransition *transition)
  * @transition: a #ClutterTransition
  * @animatable: (allow-none): a #ClutterAnimatable, or %NULL
  *
- * Sets the #ClutterTransition:animatable property.
+ * Sets the [property@Transition:animatable] property.
  *
  * The @transition will acquire a reference to the @animatable instance,
- * and will call the #ClutterTransitionClass.attached() virtual function.
+ * and will call the [vfunc@Transition.attached] virtual function.
  *
- * If an existing #ClutterAnimatable is attached to @transition, the
- * reference will be released, and the #ClutterTransitionClass.detached()
+ * If an existing [iface@Animatable] is attached to @transition, the
+ * reference will be released, and the [vfunc@Transition.detached]
  * virtual function will be called.
  *
  * Since: 1.10
@@ -393,9 +395,9 @@ clutter_transition_set_animatable (ClutterTransition *transition,
  * clutter_transition_get_animatable:
  * @transition: a #ClutterTransition
  *
- * Retrieves the #ClutterAnimatable set using clutter_transition_set_animatable().
+ * Retrieves the [iface@Animatable] set using [method@Transition.set_animatable].
  *
- * Return value: (transfer none): a #ClutterAnimatable, or %NULL; the returned
+ * Return value: (transfer none): a [iface@Animatable], or %NULL; the returned
  *   animatable is owned by the #ClutterTransition, and it should not be freed
  *   directly.
  *
@@ -414,9 +416,9 @@ clutter_transition_get_animatable (ClutterTransition *transition)
  * @transition: a #ClutterTransition
  * @remove_complete: whether to detach @transition when complete
  *
- * Sets whether @transition should be detached from the #ClutterAnimatable
- * set using clutter_transition_set_animatable() when the
- * #ClutterTimeline::completed signal is emitted.
+ * Sets whether @transition should be detached from the [iface@Animatable]
+ * set using [method@Transition.set_animatable] when the
+ * [signal@Timeline::completed] signal is emitted.
  *
  * Since: 1.10
  */
@@ -441,7 +443,7 @@ clutter_transition_set_remove_on_complete (ClutterTransition *transition,
  * clutter_transition_get_remove_on_complete:
  * @transition: a #ClutterTransition
  *
- * Retrieves the value of the #ClutterTransition:remove-on-complete property.
+ * Retrieves the value of the [property@Transition:remove-on-complete] property.
  *
  * Return value: %TRUE if the @transition should be detached when complete,
  *   and %FALSE otherwise
@@ -517,15 +519,15 @@ clutter_transition_set_value (ClutterTransition *transition,
  * Sets the initial value of the transition.
  *
  * This is a convenience function that will either create the
- * #ClutterInterval used by @transition, or will update it if
- * the #ClutterTransition:interval is already set.
+ * [class@Interval] used by @transition, or will update it if
+ * the [property@Transition:interval] is already set.
  *
  * This function will copy the contents of @value, so it is
- * safe to call g_value_unset() after it returns.
+ * safe to call [method@GObject.Value.unset] after it returns.
  *
- * If @transition already has a #ClutterTransition:interval set,
+ * If @transition already has a [property@Transition:interval] set,
  * then @value must hold the same type, or a transformable type,
- * as the interval's #ClutterInterval:value-type property.
+ * as the interval's [property@Interval:value-type] property.
  *
  * This function is meant to be used by language bindings.
  *
@@ -552,14 +554,14 @@ clutter_transition_set_from_value (ClutterTransition *transition,
  *
  * This is a convenience function that will either create the
  * #ClutterInterval used by @transition, or will update it if
- * the #ClutterTransition:interval is already set.
+ * the [property@Transition:interval] is already set.
  *
  * This function will copy the contents of @value, so it is
- * safe to call g_value_unset() after it returns.
+ * safe to call [method@GObject.Value.unset] after it returns.
  *
- * If @transition already has a #ClutterTransition:interval set,
+ * If @transition already has a [property@Transition:interval] set,
  * then @value must hold the same type, or a transformable type,
- * as the interval's #ClutterInterval:value-type property.
+ * as the interval's [property@Interval:value-type] property.
  *
  * This function is meant to be used by language bindings.
  *
@@ -587,14 +589,14 @@ clutter_transition_set_to_value (ClutterTransition *transition,
  *
  * This is a convenience function that will either create the
  * #ClutterInterval used by @transition, or will update it if
- * the #ClutterTransition:interval is already set.
+ * the [property@Transition:interval] is already set.
  *
- * If @transition already has a #ClutterTransition:interval set,
+ * If @transition already has a [property@Transition:interval] set,
  * then @value must hold the same type, or a transformable type,
- * as the interval's #ClutterInterval:value-type property.
+ * as the interval's [property@Interval:value-type] property.
  *
  * This is a convenience function for the C API; language bindings
- * should use clutter_transition_set_from_value() instead.
+ * should use [method@Transition.set_from_value] instead.
  *
  * Since: 1.12
  */
@@ -640,14 +642,14 @@ clutter_transition_set_from (ClutterTransition *transition,
  *
  * This is a convenience function that will either create the
  * #ClutterInterval used by @transition, or will update it if
- * the #ClutterTransition:interval is already set.
+ * the [property@Transition:interval] is already set.
  *
- * If @transition already has a #ClutterTransition:interval set,
+ * If @transition already has a [property@Transition:interval] set,
  * then @value must hold the same type, or a transformable type,
- * as the interval's #ClutterInterval:value-type property.
+ * as the interval's [property@Interval:value-type] property.
  *
  * This is a convenience function for the C API; language bindings
- * should use clutter_transition_set_to_value() instead.
+ * should use [method@Transition.set_to_value] instead.
  *
  * Since: 1.12
  */
diff --git a/clutter/clutter/clutter-transition.h b/clutter/clutter/clutter-transition.h
index 6f8e4dc1a5..bc089df22f 100644
--- a/clutter/clutter/clutter-transition.h
+++ b/clutter/clutter/clutter-transition.h
@@ -43,14 +43,6 @@ G_BEGIN_DECLS
 typedef struct _ClutterTransitionPrivate        ClutterTransitionPrivate;
 typedef struct _ClutterTransitionClass          ClutterTransitionClass;
 
-/**
- * ClutterTransition:
- *
- * The #ClutterTransition structure contains private
- * data and should only be accessed using the provided API.
- *
- * Since: 1.10
- */
 struct _ClutterTransition
 {
   /*< private >*/
diff --git a/clutter/clutter/clutter-types.h b/clutter/clutter/clutter-types.h
index b6ea8fb66e..7ab69644b2 100644
--- a/clutter/clutter/clutter-types.h
+++ b/clutter/clutter/clutter-types.h
@@ -105,14 +105,11 @@ typedef struct _ClutterShader                   ClutterShader; /* deprecated */
 /**
  * ClutterPaintVolume:
  *
- * #ClutterPaintVolume is an opaque structure
- * whose members cannot be directly accessed.
+ * A #ClutterPaintVolume represents a bounding volume whose internal 
+ * representation isn't defined but can be set and queried in terms
+ * of an axis aligned bounding box.
  *
- * A #ClutterPaintVolume represents an
- * a bounding volume whose internal representation isn't defined but
- * can be set and queried in terms of an axis aligned bounding box.
- *
- * A #ClutterPaintVolume for a #ClutterActor
+ * A #ClutterPaintVolume for a [class@Actor]
  * is defined to be relative from the current actor modelview matrix.
  *
  * Other internal representation and methods for describing the
@@ -129,8 +126,10 @@ typedef struct _ClutterPaintVolume      ClutterPaintVolume;
  * @x2: X coordinate of the bottom right corner
  * @y2: Y coordinate of the bottom right corner
  *
- * Bounding box of an actor. The coordinates of the top left and right bottom
- * corners of an actor. The coordinates of the two points are expressed in
+ * Bounding box of an actor. 
+ * 
+ * The coordinates of the top left and right bottom corners
+ * of an actor. The coordinates of the two points are expressed in
  * pixels with sub-pixel precision
  */
 struct _ClutterActorBox
@@ -152,9 +151,9 @@ struct _ClutterActorBox
  * A simple macro for initializing a #ClutterActorBox when declaring
  * it, e.g.:
  *
- * |[
+ * ```c
  *   ClutterActorBox box = CLUTTER_ACTOR_BOX_INIT (0, 0, 400, 600);
- * ]|
+ * ```
  *
  * Since: 1.10
  */
@@ -166,9 +165,9 @@ struct _ClutterActorBox
  * A simple macro for initializing a #ClutterActorBox to 0 when
  * declaring it, e.g.:
  *
- * |[
+ * ```c
  *   ClutterActorBox box = CLUTTER_ACTOR_BOX_INIT_ZERO;
- * ]|
+ * ```
  *
  * Since: 1.12
  */
@@ -180,9 +179,9 @@ struct _ClutterActorBox
  * A simple macro for creating a #ClutterActorBox with a size of -1 when
  * declaring it, e.g.:
  *
- * |[
+ * ```c
  *   ClutterActorBox box = CLUTTER_ACTOR_BOX_UNINITIALIZED;
- * ]|
+ * ```
  */
 
 
diff --git a/clutter/clutter/clutter-units.c b/clutter/clutter/clutter-units.c
index a5f5824715..cfc62d1230 100644
--- a/clutter/clutter/clutter-units.c
+++ b/clutter/clutter/clutter-units.c
@@ -26,21 +26,22 @@
  */
 
 /**
- * SECTION:clutter-units
- * @short_description: A logical distance unit
+ * ClutterUnits:
+ * 
+ * A logical distance unit
  *
  * #ClutterUnits is a structure holding a logical distance value along with
- * its type, expressed as a value of the #ClutterUnitType enumeration. It is
+ * its type, expressed as a value of the [enum@UnitType] enumeration. It is
  * possible to use #ClutterUnits to store a position or a size in units
  * different than pixels, and convert them whenever needed (for instance
- * inside the #ClutterActorClass.allocate() virtual function, or inside the
- * #ClutterActorClass.get_preferred_width() and #ClutterActorClass.get_preferred_height()
+ * inside the [vfunc@Actor.allocate] virtual function, or inside the
+ * [vfunc@Actor.get_preferred_width] and [vfunc@Actor.get_preferred_height]
  * virtual functions.
  *
- * In order to register a #ClutterUnits property, the #ClutterParamSpecUnits
- * #GParamSpec sub-class should be used:
+ * In order to register a #ClutterUnits property, the [class@ParamSpecUnit]
+ * [class@GObject.ParamSpec] sub-class should be used:
  *
- * |[
+ * ```c
  *   GParamSpec *pspec;
  *
  *   pspec = clutter_param_spec_units ("active-width",
@@ -51,15 +52,15 @@
  *                                     12.0,
  *                                     G_PARAM_READWRITE);
  *   g_object_class_install_property (gobject_class, PROP_WIDTH, pspec);
- * ]|
+ * ```
  *
- * A #GValue holding units can be manipulated using clutter_value_set_units()
- * and clutter_value_get_units(). #GValue<!-- -->s containing a #ClutterUnits
- * value can also be transformed to #GValue<!-- -->s initialized with
+ * A [struct@GObject.Value] holding units can be manipulated using [func@value_set_units]
+ * and [func@value_get_units]. [struct@GObject.Value]s containing a #ClutterUnits
+ * value can also be transformed to [struct@GObject.Value]s initialized with
  * %G_TYPE_INT, %G_TYPE_FLOAT and %G_TYPE_STRING through implicit conversion
- * and using g_value_transform().
+ * and using [method@GObject.Value.transform].
  *
- * #ClutterUnits is available since Clutter 1.0
+ * Since: 1.0
  */
 
 #include "clutter-build-config.h"
@@ -223,7 +224,7 @@ clutter_units_from_pt (ClutterUnits *units,
  * @em: em
  *
  * Stores a value in em inside @units, using the default font
- * name as returned by clutter_backend_get_font_name()
+ * name
  *
  * Since: 1.0
  */
@@ -341,7 +342,7 @@ clutter_units_get_unit_value (const ClutterUnits *units)
  * Copies @units
  *
  * Return value: (transfer full): the newly created copy of a
- *   #ClutterUnits structure. Use clutter_units_free() to free
+ *   #ClutterUnits structure. Use [method Units free] to free
  *   the allocated resources
  *
  * Since: 1.0
@@ -362,7 +363,7 @@ clutter_units_copy (const ClutterUnits *units)
  * Frees the resources allocated by @units
  *
  * You should only call this function on a #ClutterUnits
- * created using clutter_units_copy()
+ * created using [method Units copy]
  *
  * Since: 1.0
  */
@@ -436,7 +437,7 @@ clutter_units_to_pixels (ClutterUnits *units)
  *
  * A #ClutterUnits expressed in string should match:
  *
- * |[
+ * ```
  *   units: wsp* unit-value wsp* unit-name? wsp*
  *   unit-value: number
  *   unit-name: 'px' | 'pt' | 'mm' | 'em' | 'cm'
@@ -445,24 +446,24 @@ clutter_units_to_pixels (ClutterUnits *units)
  *   sep: '.' | ','
  *   digit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
  *   wsp: (#0x20 | #0x9 | #0xA | #0xB | #0xC | #0xD)+
- * ]|
+ * ```
  *
  * For instance, these are valid strings:
  *
- * |[
+ * ```
  *   10 px
  *   5.1 em
  *   24 pt
  *   12.6 mm
  *   .3 cm
- * ]|
+ * ```
  *
  * While these are not:
  *
- * |[
+ * ```
  *   42 cats
  *   omg!1!ponies
- * ]|
+ * ```
  *
  * If no unit is specified, pixels are assumed.
  *
@@ -590,7 +591,7 @@ clutter_unit_type_name (ClutterUnitType unit_type)
  *
  * Converts @units into a string
  *
- * See clutter_units_from_string() for the units syntax and for
+ * See [func@Units.from_string] for the units syntax and for
  * examples of output
  *
  * Fractional values are truncated to the second decimal
@@ -598,7 +599,7 @@ clutter_unit_type_name (ClutterUnitType unit_type)
  * typographic points. Pixels are integers.
  *
  * Return value: a newly allocated string containing the encoded
- *   #ClutterUnits value. Use g_free() to free the string
+ *   #ClutterUnits value. Use [func GLib free] to free the string
  *
  * Since: 1.0
  */
@@ -767,7 +768,7 @@ clutter_value_set_units (GValue             *value,
  *
  * Gets the #ClutterUnits contained in @value.
  *
- * Return value: the units inside the passed #GValue
+ * Return value: the units inside the passed [struct@GObject.Value]
  *
  * Since: 0.8
  */
@@ -898,9 +899,9 @@ clutter_param_units_get_type (void)
  * @default_value: default value
  * @flags: flags for the param spec
  *
- * Creates a #GParamSpec for properties using #ClutterUnits.
+ * Creates a [class@GObject.ParamSpec] for properties using [struct@Units].
  *
- * Return value: the newly created #GParamSpec
+ * Return value: the newly created [class@GObject.ParamSpec]
  *
  * Since: 1.0
  */
diff --git a/clutter/clutter/clutter-units.h b/clutter/clutter/clutter-units.h
index 900f90d2bb..11dc739af8 100644
--- a/clutter/clutter/clutter-units.h
+++ b/clutter/clutter/clutter-units.h
@@ -37,14 +37,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * ClutterUnits:
- *
- * An opaque structure, to be used to store sizing and positioning
- * values along with their unit.
- *
- * Since: 1.0
- */
 typedef struct _ClutterUnits    ClutterUnits;
 
 struct _ClutterUnits
diff --git a/clutter/clutter/clutter-util.c b/clutter/clutter/clutter-util.c
index a5de007f33..07dd923185 100644
--- a/clutter/clutter/clutter-util.c
+++ b/clutter/clutter/clutter-util.c
@@ -304,18 +304,18 @@ progress_data_destroy (gpointer data_)
  *
  * Sets the progress function for a given @value_type, like:
  *
- * |[
+ * ```c
  *   clutter_interval_register_progress_func (MY_TYPE_FOO,
  *                                            my_foo_progress);
- * ]|
+ * ```
  *
- * Whenever a #ClutterInterval instance using the default
- * #ClutterInterval::compute_value implementation is set as an
- * interval between two #GValue of type @value_type, it will call
+ * Whenever a [class@Interval] instance using the default
+ * [method@Interval.compute_value] implementation is set as an
+ * interval between two [struct@GObject.Value] of type @value_type, it will call
  * @func to establish the value depending on the given progress,
  * for instance:
  *
- * |[
+ * ```c
  *   static gboolean
  *   my_int_progress (const GValue *a,
  *                    const GValue *b,
@@ -332,9 +332,9 @@ progress_data_destroy (gpointer data_)
  *   }
  *
  *   clutter_interval_register_progress_func (G_TYPE_INT, my_int_progress);
- * ]|
+ * ```
  *
- * To unset a previously set progress function of a #GType, pass %NULL
+ * To unset a previously set progress function of a [alias GObject Type], pass %NULL
  * for @func.
  *
  * Since: 1.0
diff --git a/clutter/clutter/clutter-zoom-action.c b/clutter/clutter/clutter-zoom-action.c
index 4e87e23302..57996f12f2 100644
--- a/clutter/clutter/clutter-zoom-action.c
+++ b/clutter/clutter/clutter-zoom-action.c
@@ -23,22 +23,22 @@
  */
 
 /**
- * SECTION:clutter-zoom-action
- * @Title: ClutterZoomAction
- * @Short_Description: Action enabling zooming on actors
+ * ClutterZoomAction:
+ * 
+ * Action enabling zooming on actors
  *
- * #ClutterZoomAction is a sub-class of #ClutterGestureAction that
+ * #ClutterZoomAction is a sub-class of [class@GestureAction] that
  * implements all the necessary logic for zooming actors using a "pinch"
  * gesture between two touch points.
  *
- * The simplest usage of #ClutterZoomAction consists in adding it to
- * a #ClutterActor and setting it as reactive; for instance, the following
+ * The simplest usage of [class@ZoomAction] consists in adding it to
+ * a [class@Actor] and setting it as reactive; for instance, the following
  * code:
  *
- * |[
+ * ```c
  *   clutter_actor_add_action (actor, clutter_zoom_action_new ());
  *   clutter_actor_set_reactive (actor, TRUE);
- * ]|
+ * ```
  *
  * will automatically result in the actor to be scale according to the
  * distance between two touch points.
@@ -258,11 +258,11 @@ clutter_zoom_action_class_init (ClutterZoomActionClass *klass)
    * @focal_point: the focal point of the zoom
    * @factor: the initial distance between the 2 touch points
    *
-   * The ::zoom signal is emitted for each series of touch events that
+   * The signal is emitted for each series of touch events that
    * change the distance and focal point between the touch points.
    *
    * The default handler of the signal will call
-   * clutter_actor_set_scale() on @actor using the ratio of the first
+   * [method@Actor.set_scale] on @actor using the ratio of the first
    * distance between the touch points and the current distance. To
    * override the default behaviour, connect to this signal and return
    * %FALSE.
diff --git a/clutter/clutter/clutter-zoom-action.h b/clutter/clutter/clutter-zoom-action.h
index 7cd944d954..da8ae9e219 100644
--- a/clutter/clutter/clutter-zoom-action.h
+++ b/clutter/clutter/clutter-zoom-action.h
@@ -46,14 +46,6 @@ typedef struct _ClutterZoomAction               ClutterZoomAction;
 typedef struct _ClutterZoomActionPrivate        ClutterZoomActionPrivate;
 typedef struct _ClutterZoomActionClass          ClutterZoomActionClass;
 
-/**
- * ClutterZoomAction:
- *
- * The #ClutterZoomAction structure contains only
- * private data and should be accessed using the provided API
- *
- * Since: 1.12
- */
 struct _ClutterZoomAction
 {
   /*< private >*/


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]