docs: Avoid warnings from the g-ir-scanner

The scanner has some issues when parsing valid gtk-doc annotations; we
should make its (and, in return, ours) life easier.

We still get warnings for code declared in <programlisting> sections,
unfortunately.

clutter/clutter-actor.c

@@ -8669,10 +8669,10 @@ clutter_animatable_iface_init (ClutterAnimatableIface *iface)
  * nature of the operation. In general the error grows when the skewing
  * of the actor rectangle on screen increases.
  *
- * Note: This function is fairly computationally intensive.
+ * <note><para>This function can be computationally intensive.</para></note>
  *
- * Note: This function only works when the allocation is up-to-date,
- * i.e. inside of paint()
+ * <note><para>This function only works when the allocation is up-to-date,
+ * i.e. inside of paint().</para></note>
  *
  * Return value: %TRUE if conversion was successful.
  *
@@ -10582,12 +10582,12 @@ clutter_actor_get_text_direction (ClutterActor *self)
  *      &ast; the internal flag being set on a child of MyActor
  *      &ast;/
  *
- *     /&ast; internal child: a background texture &ast;/
+ *     /&ast; internal child - a background texture &ast;/
  *     self->priv->background_tex = clutter_texture_new ();
  *     clutter_actor_set_parent (self->priv->background_tex,
  *                               CLUTTER_ACTOR (self));
  *
- *     /&ast; internal child: a label &ast;/
+ *     /&ast; internal child - a label &ast;/
  *     self->priv->label = clutter_text_new ();
  *     clutter_actor_set_parent (self->priv->label,
  *                               CLUTTER_ACTOR (self));

clutter/clutter-align-constraint.c

@@ -230,10 +230,10 @@ clutter_align_constraint_class_init (ClutterAlignConstraintClass *klass)
    *
    * The alignment factor, as a normalized value between 0.0 and 1.0
    *
-   * The #ClutterAlignConstraint:factor depends on the
-   * #ClutterAlignConstraint:align-axis value: with %CLUTTER_ALIGN_X_AXIS,
-   * 0.0 means left and 1.0 means right; with %CLUTTER_ALIGN_Y_AXIS, 0.0
-   * means top and 1.0 means bottom
+   * The factor depends on the #ClutterAlignConstraint:align-axis property:
+   * with an align-axis value of %CLUTTER_ALIGN_X_AXIS, 0.0 means left and
+   * 1.0 means right; with a value of %CLUTTER_ALIGN_Y_AXIS, 0.0 means top
+   * and 1.0 means bottom.
    *
    * Since: 1.4
    */
@@ -263,8 +263,8 @@ clutter_align_constraint_init (ClutterAlignConstraint *self)
  * @factor: the alignment factor, between 0.0 and 1.0
  *
  * Creates a new constraint, aligning a #ClutterActor's position with
- * regards of the size of the actor to @source, with the given alignment
- * @factor
+ * regards of the size of the actor to @source, with the given
+ * alignment @factor
  *
  * Return value: the newly created #ClutterAlignConstraint
  *

clutter/clutter-alpha.c

@@ -27,8 +27,7 @@
 
 /**
  * SECTION:clutter-alpha
- * @short_description: A class for calculating an alpha value as a function
- * of time.
+ * @short_description: A class for calculating a value as a function of time
  *
  * #ClutterAlpha is a class for calculating an floating point value
  * dependent only on the position of a #ClutterTimeline.

clutter/clutter-units.c

@@ -462,7 +462,7 @@ clutter_units_to_pixels (ClutterUnits *units)
  *   omg!1!ponies
  * ]|
  *
- * <note>If no unit is specified, pixels are assumed.</note>
+ * <note><para>If no unit is specified, pixels are assumed.</para></note>
  *
  * Return value: %TRUE if the string was successfully parsed,
  *   and %FALSE otherwise