docs: Clean up ClutterActor's long description

The Actor's long description is a bit cluttered; it contains a section
on the actor's box semantics, on the transformation order and on the
event handling.

We should use <refsect2> tags to divide the Actor's description into
logically separated sections.

We should also add a section about the custom Scriptable properties that
ClutterActor defines, and the special handling of unit-based properties.

clutter/clutter-actor.c

@@ -36,24 +36,23 @@
  * it parent with the childs origin being its anchor point (also top
  * left by default).
  *
- * The actors 2D surface is contained inside its bounding box,
- * described by the #ClutterActorBox structure:
- *
+ * <refsect2 id="ClutterActor-box">
+ *   <title>Actor bounding box and transformations</title>
+ *   <para>Any actor's 2D surface is contained inside its bounding box,
+ *   as described by the #ClutterActorBox structure:</para>
  *   <figure id="actor-box">
  *     <title>Bounding box of an Actor</title>
  *     <graphic fileref="actor-box.png" format="PNG"/>
  *   </figure>
- *
- * The actor box represents the untransformed area occupied by an
+ *   <para>The actor box represents the untransformed area occupied by an
  *   actor. Each visible actor that has been put on a #ClutterStage also
  *   has a transformed area, depending on the actual transformations
  *   applied to it by the developer (scale, rotation). Tranforms will
  *   also be applied to any child actors. Also applied to all actors by
  *   the #ClutterStage is a perspective transformation. API is provided
- * for both tranformed and untransformed actor geometry information.
- *
- * The 'modelview' transform matrix for the actor is constructed from
- * the actor settings by the following order of operations:
+ *   for both tranformed and untransformed actor geometry information.</para>
+ *   <para>The GL 'modelview' transform matrix for the actor is constructed
+ *   from the actor settings by the following order of operations:</para>
  *   <orderedlist>
  *     <listitem><para>Translation by actor x, y coords,</para></listitem>
  *     <listitem><para>Translation by actor depth (z),</para></listitem>
@@ -63,32 +62,32 @@
  *     <listitem><para>Rotation around x axis,</para></listitem>
  *     <listitem><para>Negative translation by anchor point x,
  *     y,</para></listitem>
- *   <listitem><para>Rectangular Clip is applied (this is not an operation on
- *   the matrix as such, but it is done as part of the transform set
+ *     <listitem><para>Rectangular Clip is applied (this is not an operation
+ *     on the matrix as such, but it is done as part of the transform set
  *     up).</para></listitem>
  *   </orderedlist>
- *
- * An actor can either be explicitly sized and positioned, using the
+ *   <para>An actor can either be explicitly sized and positioned, using the
  *   various size and position accessors, like clutter_actor_set_x() or
  *   clutter_actor_set_width(); or it can have a preferred width and
  *   height, which then allows a layout manager to implicitly size and
  *   position it by "allocating" an area for an actor. This allows for
  *   actors to be manipulated in both a fixed (or static) parent container
  *   (i.e. children of #ClutterGroup) and a more automatic (or dynamic)
- * layout based parent container.
- *
- * When accessing the position and size of an actor, the simple accessors
- * like clutter_actor_get_width() and clutter_actor_get_x() will return
- * a value depending on whether the actor has been explicitly sized and
- * positioned by the developer or implicitly by the layout manager.
- *
- * Depending on whether you are querying an actor or implementing a
+ *   layout based parent container.</para>
+ *   <para>When accessing the position and size of an actor, the simple
+ *   accessors like clutter_actor_get_width() and clutter_actor_get_x()
+ *   will return a value depending on whether the actor has been explicitly
+ *   sized and positioned by the developer or implicitly by the layout
+ *   manager.</para>
+ *   <para>Depending on whether you are querying an actor or implementing a
  *   layout manager, you should either use the simple accessors or use the
- * size negotiation API.
- *
- * Clutter actors are also able to receive input events and react to
- * them. Events are handled in the following ways:
+ *   size negotiation API.</para>
+ * </refsect2>
  *
+ * <refsect2 id="ClutterActor-event-handling">
+ *   <title>Event Handling</title>
+ *   <para>Clutter actors are also able to receive input events and react to
+ *   them. Events are handled in the following ways:</para>
  *   <orderedlist>
  *     <listitem><para>Actors emit pointer events if set reactive, see
  *     clutter_actor_set_reactive()</para></listitem>
@@ -115,18 +114,47 @@
  *     <listitem><para>Pointer events will 'pass through' non reactive
  *     overlapping actors.</para></listitem>
  *   </orderedlist>
- *
  *   <figure id="event-flow">
  *     <title>Event flow in Clutter</title>
  *     <graphic fileref="event-flow.png" format="PNG"/>
  *   </figure>
+ *   <para>Every '?' box in the diagram above is an entry point for
+ *   application code.</para>
+ * </refsect2>
  *
- * Every '?' box in the diagram above is an entry point for application
- * code.
+ * <refsect2 id="ClutterActor-subclassing">
+ *   <title>Implementing a ClutterActor</title>
+ *   <para>For implementing a new custom actor class, please read <link
+ *   linkend="clutter-subclassing-ClutterActor">the corresponding
+ *   section</link> of the API reference.</para>
+ * </refsect2>
  *
- * For implementing a new custom actor class, please read <link
- * linkend="clutter-subclassing-ClutterActor">the corresponding section</link>
- * of the API reference.
+ * <refsect2 id="ClutterActor-script">
+ *   <title>ClutterActor custom properties for #ClutterScript</title>
+ *   <para>#ClutterActor defines a custom "rotation" property which
+ *   allows a short-hand description of the rotations to be applied
+ *   to an actor.</para>
+ *   <para>The syntax of the "rotation" property is the following:</para>
+ *   <informalexample>
+ *     <programlisting>
+ * "rotation" : [
+ *   { "&lt;axis&gt;" : [ &lt;angle&gt;, [ &lt;center&gt; ] ] }
+ * ]
+ *     </programlisting>
+ *   </informalexample>
+ *   <para>where the <emphasis>axis</emphasis> is the name of an enumeration
+ *   value of type #ClutterRotateAxis and <emphasis>angle</emphasis> is a
+ *   floating point value representing the rotation angle on the given axis,
+ *   in degrees.</para>
+ *   <para>The <emphasis>center</emphasis> array is optional, and if present
+ *   it must contain the center of rotation as described by two coordinates:
+ *   Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for
+ *   "z-axis".</para>
+ *   <para>#ClutterActor will also parse every positional and dimensional
+ *   property defined as a string through clutter_units_from_string(); you
+ *   should read the documentation for the #ClutterUnits parser format for
+ *   the valid units and syntax.</para>
+ * </refsect2>
  */
 
 /**