Fixes for the API reference

Typos, missing symbols, and missing documentation.

clutter/clutter-animatable.c

@@ -30,16 +30,16 @@
  * to control how a #ClutterAnimation will animate a property.
  *
  * Each #ClutterAnimatable should implement the
- * <function>animate_property</function> virtual function of the interface
+ * #ClutterAnimatableIface.interpolate_property() virtual function of the
- * to compute the animation state between two values of an interval depending
+ * interface to compute the animation state between two values of an interval
- * on a progress factor, expressed as a floating point value.
+ * depending on a progress factor, expressed as a floating point value.
  *
  * If a #ClutterAnimatable is animated by a #ClutterAnimation
  * instance, the #ClutterAnimation will call
- * clutter_animatable_animate_property() passing the name of the
+ * clutter_animatable_interpolate_property() passing the name of the
- * currently animated property; the initial and final values of
+ * currently animated property; the values interval; and the progress factor.
- * the animation interval; the progress factor. The #ClutterAnimatable
+ * The #ClutterAnimatable implementation should return the computed value for
- * implementation should return the computed value for the animated
+ * the animated
  * property.
  *
  * #ClutterAnimatable is available since Clutter 1.0

clutter/clutter-cairo.c

@@ -1,3 +1,32 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2012 Intel Corporation
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * SECTION:clutter-cairo
+ * @Title: Cairo integration
+ * @Short_Description: Functions for interoperating with Cairo
+ *
+ * Clutter provides some utility functions for using Cairo.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

clutter/clutter-constraint.c

@@ -11,7 +11,7 @@
  * the position or size of the #ClutterActor to which it is applied, by
  * updating the actor's allocation. Each #ClutterConstraint can change the
  * allocation of the actor to which they are applied by overriding the
- * <function>update_allocation()</function> virtual function.
+ * #ClutterConstraintClass.update_allocation() virtual function.
  *
  * <refsect2 id="ClutterConstraint-usage">
  *   <title>Using Constraints</title>

clutter/clutter-deform-effect.c

@@ -42,7 +42,7 @@
  * <refsect2>
  *   <title>Implementing ClutterDeformEffect</title>
  *   <para>Sub-classes of #ClutterDeformEffect should override the
- *   <function>deform_vertex()</function> virtual function; this function
+ *   #ClutterDeformEffectClass.deform_vertex() virtual function; this function
  *   is called on every vertex that needs to be deformed by the effect.
  *   Each passed vertex is an in-out parameter that initially contains the
  *   position of the vertex and should be modified according to a specific

clutter/clutter-effect.c

@@ -34,7 +34,7 @@
  *
  * Effects should be the preferred way to affect the paint sequence of an
  * actor without sub-classing the actor itself and overriding the
- * #ClutterActor::paint virtual function.
+ * #ClutterActorClass.paint()_ virtual function.
  *
  * <refsect2 id="ClutterEffect-implementation">
  *   <title>Implementing a ClutterEffect</title>
@@ -91,18 +91,19 @@
  *   <para>
  *     With these two functions it is not possible to skip the rest of
  *     the paint sequence. The default implementation of the ‘paint’
- *     virtual calls pre_paint(), clutter_actor_continue_paint() and
+ *     virtual calls #ClutterEffectClass.pre_paint(), clutter_actor_continue_paint()
- *     then post_paint() so that existing actors that aren't using the
+ *     and then #ClutterEffectClass.post_paint() so that existing actors that aren't
- *     paint virtual will continue to work. New actors using the paint
+ *     using the #ClutterEffectClass.paint() virtual will continue to work. New
- *     virtual do not need to implement pre or post paint.
+ *     effects using the #ClutterEffectClass.paint() virtual do not need to implement
+ *     pre or post paint.
  *   </para>
  *   <example id="ClutterEffect-example">
  *     <title>A simple ClutterEffect implementation</title>
  *     <para>The example below creates two rectangles: one will be
  *     painted "behind" the actor, while another will be painted "on
- *     top" of the actor.  The <function>set_actor()</function>
+ *     top" of the actor.  The #ClutterActorMetaClass.set_actor()
  *     implementation will create the two materials used for the two
- *     different rectangles; the <function>paint()</function> function
+ *     different rectangles; the #ClutterEffectClass.paint() implementation
  *     will paint the first material using cogl_rectangle(), before
  *     continuing and then it will paint paint the second material
  *     after.</para>

clutter/clutter-enums.h

@@ -541,7 +541,7 @@ typedef enum {
  * @CLUTTER_LONG_PRESS_ACTIVATE: Activates the action on a long press
  * @CLUTTER_LONG_PRESS_CANCEL: The long press was cancelled
  *
- * The states for the #ClutterClikAction::long-press signal.
+ * The states for the #ClutterClickAction::long-press signal.
  *
  * Since: 1.8
  */

clutter/clutter-gesture-action.c

@@ -32,7 +32,7 @@
  * 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.
+ * and #ClutterGestureAction::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:

clutter/clutter-gesture-action.h

@@ -64,7 +64,7 @@ struct _ClutterGestureAction
 /**
  * ClutterGestureActionClass:
  * @gesture_begin: class handler for the #ClutterGestureAction::gesture-begin signal
- * @gesture_progress: class handler for the #ClutterGestureAction::gesture-progres signal
+ * @gesture_progress: class handler for the #ClutterGestureAction::gesture-progress signal
  * @gesture_end: class handler for the #ClutterGestureAction::gesture-end signal
  * @gesture_cancel: class handler for the #ClutterGestureAction::gesture-cancel signal
  *

clutter/clutter-layout-manager.c

@@ -42,13 +42,11 @@
  *   <title>Using a Layout Manager inside an Actor</title>
  *   <para>In order to use a #ClutterLayoutManager inside a #ClutterActor
  *   sub-class you should invoke clutter_layout_manager_get_preferred_width()
- *   inside the <structname>ClutterActor</structname>::get_preferred_width()
+ *   inside the #ClutterActorClass.get_preferred_width() virtual function and
- *   virtual function and clutter_layout_manager_get_preferred_height()
+ *   clutter_layout_manager_get_preferred_height() inside the
- *   inside the <structname>ClutterActor</structname>::get_preferred_height()
+ *   #ClutterActorClass.get_preferred_height() virtual functions implementation.
- *   virtual function implementations. You should also call
+ *   You should also call clutter_layout_manager_allocate() inside the
- *   clutter_layout_manager_allocate() inside the implementation of the
+ *   implementation of the #ClutterActorClass.allocate() virtual function.</para>
- *   <structname>ClutterActor</structname>::allocate() virtual
- *   function.</para>
  *   <para>In order to receive notifications for changes in the layout
  *   manager policies you should also connect to the
  *   #ClutterLayoutManager::layout-changed signal and queue a relayout
@@ -93,9 +91,9 @@
  *   <para>It is possible for a #ClutterLayoutManager sub-class to animate its
  *   children layout by using the base class animation support. The
  *   #ClutterLayoutManager animation support consists of three virtual
- *   functions: <function>begin_animation()</function>,
+ *   functions: #ClutterLayoutManagerClass.begin_animation(),
- *   <function>get_animation_progress()</function> and
+ *   #ClutterLayoutManagerClass.get_animation_progress(), and
- *   <function>end_animation()</function>.</para>
+ *   #ClutterLayoutManagerClass.end_animation().</para>
  *   <variablelist>
  *     <varlistentry>
  *       <term><function>begin_animation (duration, easing)</function></term>
@@ -131,20 +129,20 @@
  *   clutter_layout_manager_end_animation() to be called. The default
  *   implementation provided internally by #ClutterLayoutManager does exactly
  *   this, so most sub-classes should either not override any animation-related
- *   virtual function or simply override <function>begin_animation()</function>
+ *   virtual function or simply override #ClutterLayoutManagerClass.begin_animation()
- *   and <function>end_animation()</function> to set up ad hoc state, and then
+ *   and #ClutterLayoutManagerClass.end_animation() to set up ad hoc state, and then
  *   chain up to the parent's implementation.</para>
  *   <example id="example-ClutterLayoutManager-animation">
  *     <title>Animation of a Layout Manager</title>
  *     <para>The code below shows how a #ClutterLayoutManager sub-class should
  *     provide animating the allocation of its children from within the
- *     <function>allocate()</function> virtual function implementation. The
+ *     #ClutterLayoutManagerClass.allocate() virtual function implementation. The
  *     animation is computed between the last stable allocation performed
  *     before the animation started and the desired final allocation.</para>
  *     <para>The <varname>is_animating</varname> variable is stored inside the
  *     #ClutterLayoutManager sub-class and it is updated by overriding the
- *     <function>begin_animation()</function> and
+ *     #ClutterLayoutManagerClass.begin_animation() and the
- *     <function>end_animation()</function> virtual functions and chaining up
+ *     #ClutterLayoutManagerClass.end_animation() virtual functions and chaining up
  *     to the base class implementation.</para>
  *     <para>The last stable allocation is stored within a #ClutterLayoutMeta
  *     sub-class used by the implementation.</para>
@@ -254,13 +252,12 @@
  *   should exist only as the result of the presence of a specific (layout
  *   manager, container actor, child actor) combination, and it wishes to store
  *   those properties inside a #ClutterLayoutMeta, then it should override the
- *   <structname>ClutterLayoutManager</structname>::get_child_meta_type()
+ *   #ClutterLayoutManagerClass.get_child_meta_type() virtual function to return
- *   virtual function to return the #GType of the #ClutterLayoutMeta sub-class
+ *   the #GType of the #ClutterLayoutMeta sub-class used to store the layout
- *   used to store the layout properties; optionally, the #ClutterLayoutManager
+ *   properties; optionally, the #ClutterLayoutManager sub-class might also
- *   sub-class might also override the
+ *   override the #ClutterLayoutManagerClass.create_child_meta() virtual function
- *   <structname>ClutterLayoutManager</structname>::create_child_meta() virtual
+ *   to control how the #ClutterLayoutMeta instance is created, otherwise the
- *   function to control how the #ClutterLayoutMeta instance is created,
+ *   default implementation will be equivalent to:</para>
- *   otherwise the default implementation will be equivalent to:</para>
  *   <informalexample><programlisting>
  *  ClutterLayoutManagerClass *klass;
  *  GType meta_type;

clutter/clutter-offscreen-effect.c

@@ -46,14 +46,14 @@
  *   of overriding the #ClutterEffect virtual functions, to chain up to the
  *   #ClutterOffscreenEffect's implementation.</para>
  *   <para>On top of the #ClutterEffect's virtual functions,
- *   #ClutterOffscreenEffect also provides a <function>paint_target()</function>
+ *   #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target()
  *   function, which encapsulates the effective painting of the texture that
  *   contains the result of the offscreen redirection.</para>
  *   <para>The size of the target material is defined to be as big as the
  *   transformed size of the #ClutterActor using the offscreen effect.
  *   Sub-classes of #ClutterOffscreenEffect can change the texture creation
  *   code to provide bigger textures by overriding the
- *   <function>create_texture()</function> virtual function; no chain up
+ *   #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up
  *   to the #ClutterOffscreenEffect implementation is required in this
  *   case.</para>
  * </refsect2>

clutter/clutter-paint-node.h

@@ -75,6 +75,15 @@ void                    clutter_paint_node_add_primitive                (Clutter
                                                                          CoglPrimitive         *primitive);
 #endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API && CLUTTER_ENABLE_EXPERIMENTAL_API */
 
+/**
+ * CLUTTER_VALUE_HOLDS_PAINT_NODE:
+ * @value: a #GValue
+ *
+ * Evaluates to %TRUE if the @value has been initialized to hold
+ * a #ClutterPaintNode.
+ *
+ * Since: 1.10
+ */
 #define CLUTTER_VALUE_HOLDS_PAINT_NODE(value)   (G_VALUE_HOLDS (value, CLUTTER_TYPE_PAINT_NODE))
 
 CLUTTER_AVAILABLE_IN_1_10

clutter/clutter-shader-effect.c

@@ -37,11 +37,11 @@
  * <refsect2 id="ClutterShaderEffect-implementing">
  *   <title>Implementing a ClutterShaderEffect</title>
  *   <para>Creating a sub-class of #ClutterShaderEffect requires the
- *   overriding of the <function>paint_target()</function> virtual
+ *   overriding of the #ClutterOffscreenEffectClass.paint_target() virtual
  *   function from the #ClutterOffscreenEffect class as well as the
  *   <function>get_static_shader_source()</function> virtual from the
  *   #ClutterShaderEffect class.</para>
- *   <para>The <function>get_static_shader_source()</function>
+ *   <para>The #ClutterShaderEffectClass.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

clutter/clutter-types.h

@@ -132,7 +132,29 @@ struct _ClutterPoint
   float y;
 };
 
+/**
+ * CLUTTER_POINT_INIT:
+ * @x: X coordinate
+ * @y: Y coordinate
+ *
+ * A simple macro for initializing a #ClutterPoint when declaring it, e.g.:
+ *
+ * |[
+ *   ClutterPoint p = CLUTTER_POINT_INIT (100, 100);
+ * ]|
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_POINT_INIT(x,y)         { (x), (y) }
+
+/**
+ * CLUTTER_POINT_INIT_ZERO:
+ *
+ * A simple macro for initializing a #ClutterPoint to (0, 0) when
+ * declaring it.
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_POINT_INIT_ZERO         CLUTTER_POINT_INIT (0.f, 0.f)
 
 CLUTTER_AVAILABLE_IN_1_12
@@ -172,7 +194,29 @@ struct _ClutterSize
   float height;
 };
 
+/**
+ * CLUTTER_SIZE_INIT:
+ * @width: the width
+ * @height: the height
+ *
+ * A simple macro for initializing a #ClutterSize when declaring it, e.g.:
+ *
+ * |[
+ *   ClutterSize s = CLUTTER_SIZE_INIT (200, 200);
+ * ]|
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_SIZE_INIT(width,height) { (width), (height) }
+
+/**
+ * CLUTTER_SIZE_INIT_ZERO:
+ *
+ * A simple macro for initializing a #ClutterSize to (0, 0) when
+ * declaring it.
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_SIZE_INIT_ZERO          CLUTTER_SIZE_INIT (0.f, 0.f)
 
 CLUTTER_AVAILABLE_IN_1_12
@@ -219,7 +263,31 @@ struct _ClutterRect
   ClutterSize size;
 };
 
+/**
+ * CLUTTER_RECT_INIT:
+ * @x: the X coordinate
+ * @y: the Y coordinate
+ * @width: the width
+ * @height: the height
+ *
+ * A simple macro for initializing a #ClutterRect when declaring it, e.g.:
+ *
+ * |[
+ *   ClutterRect r = CLUTTER_RECT_INIT (100, 100, 200, 200);
+ * ]|
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_RECT_INIT(x,y,width,height)     { { (x), (y) }, { (width), (height) } }
+
+/**
+ * CLUTTER_RECT_INIT_ZERO:
+ *
+ * A simple macro for initializing a #ClutterRect to (0, 0, 0, 0) when
+ * declaring it.
+ *
+ * Since: 1.12
+ */
 #define CLUTTER_RECT_INIT_ZERO                  CLUTTER_RECT_INIT (0.f, 0.f, 0.f, 0.f)
 
 CLUTTER_AVAILABLE_IN_1_12
@@ -305,7 +373,7 @@ struct _ClutterVertex
  * A simple macro for initializing a #ClutterVertex when declaring it, e.g.:
  *
  * |[
- *   ClutterVertext v = CLUTTER_VERTEX_INIT (x, y, z);
+ *   ClutterVertex v = CLUTTER_VERTEX_INIT (x, y, z);
  * ]|
  *
  * Since: 1.10

clutter/clutter-units.c

@@ -33,8 +33,8 @@
  * its type, expressed as a value of the #ClutterUnitType 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 #ClutterActor::allocate() virtual function, or inside the
+ * inside the #ClutterActorClass.allocate() virtual function, or inside the
- * #ClutterActor::get_preferred_width() and #ClutterActor::get_preferred_height()
+ * #ClutterActorClass.get_preferred_width() and #ClutterActorClass.get_preferred_height()
  * virtual functions.
  *
  * In order to register a #ClutterUnits property, the #ClutterParamSpecUnits

clutter/wayland/clutter-wayland-surface.c

@@ -217,6 +217,16 @@ set_size (ClutterWaylandSurface *self,
   clutter_actor_set_size (CLUTTER_ACTOR (self), priv->width, priv->height);
 }
 
+/**
+ * clutter_wayland_surface_get_surface:
+ * @self: a #ClutterWaylandSurface
+ *
+ * Retrieves a point to the Wayland surface used by the actor.
+ *
+ * Return value: (transfer none): a wl_surface pointer, or %NULL
+ *
+ * Since: 1.10
+ */
 struct wl_surface *
 clutter_wayland_surface_get_surface (ClutterWaylandSurface *self)
 {
@@ -224,6 +234,15 @@ clutter_wayland_surface_get_surface (ClutterWaylandSurface *self)
   return priv->surface;
 }
 
+/**
+ * clutter_wayland_surface_set_surface:
+ * @self: a #ClutterWaylandSurface
+ * @surface: a Wayland wl_surface pointer
+ *
+ * Sets the Wayland surface to be used by the actor.
+ *
+ * Since: 1.10
+ */
 void
 clutter_wayland_surface_set_surface (ClutterWaylandSurface *self,
                                      struct wl_surface *surface)
@@ -435,7 +454,7 @@ clutter_wayland_surface_class_init (ClutterWaylandSurfaceClass *klass)
   g_object_class_install_property (object_class, PROP_COGL_TEXTURE, pspec);
 
   /**
-   * ClutterWaylandSurface::queue-damage-redraw
+   * ClutterWaylandSurface::queue-damage-redraw:
    * @texture: the object which received the signal
    * @x: The top left x position of the damage region
    * @y: The top left y position of the damage region
@@ -613,6 +632,16 @@ clutter_wayland_surface_damage_buffer (ClutterWaylandSurface *self,
                  x, y, width, height);
 }
 
+/**
+ * clutter_wayland_surface_get_cogl_texture:
+ * @self: a #ClutterWaylandSurface
+ *
+ * Retrieves the Cogl texture with the contents of the Wayland surface.
+ *
+ * Return value: (transfer none): a Cogl texture, or %NULL
+ *
+ * Since: 1.10
+ */
 CoglTexture *
 clutter_wayland_surface_get_cogl_texture (ClutterWaylandSurface *self)
 {

doc/reference/clutter/clutter-sections.txt

@@ -992,8 +992,11 @@ clutter_feature_get_all
 <SECTION>
 <FILE>clutter-color</FILE>
 <TITLE>Colors</TITLE>
+CLUTTER_COLOR_INIT
 ClutterColor
 clutter_color_new
+clutter_color_alloc
+clutter_color_init
 clutter_color_copy
 clutter_color_free
 clutter_color_equal
@@ -1076,6 +1079,9 @@ clutter_event_set_flags
 clutter_event_get_flags
 clutter_event_get_axes
 clutter_event_get_event_sequence
+clutter_event_get_angle
+clutter_event_get_distance
+clutter_event_get_position
 
 <SUBSECTION>
 clutter_event_get
@@ -1452,6 +1458,7 @@ CLUTTER_VERSION_1_4
 CLUTTER_VERSION_1_6
 CLUTTER_VERSION_1_8
 CLUTTER_VERSION_1_10
+CLUTTER_VERSION_1_12
 CLUTTER_VERSION_MAX_ALLOWED
 CLUTTER_VERSION_MIN_REQUIRED
 
@@ -1470,6 +1477,7 @@ CLUTTER_AVAILABLE_IN_1_4
 CLUTTER_AVAILABLE_IN_1_6
 CLUTTER_AVAILABLE_IN_1_8
 CLUTTER_AVAILABLE_IN_1_10
+CLUTTER_AVAILABLE_IN_1_12
 CLUTTER_DEPRECATED_IN_1_0
 CLUTTER_DEPRECATED_IN_1_0_FOR
 CLUTTER_DEPRECATED_IN_1_2
@@ -1482,6 +1490,8 @@ CLUTTER_DEPRECATED_IN_1_8
 CLUTTER_DEPRECATED_IN_1_8_FOR
 CLUTTER_DEPRECATED_IN_1_10
 CLUTTER_DEPRECATED_IN_1_10_FOR
+CLUTTER_DEPRECATED_IN_1_12
+CLUTTER_DEPRECATED_IN_1_12_FOR
 CLUTTER_UNAVAILABLE
 </SECTION>
 
@@ -1870,10 +1880,16 @@ ClutterIntervalPrivate
 clutter_interval_get_type
 </SECTION>
 
+<SECTION>
+<FILE>clutter-cairo</FILE>
+CLUTTER_CAIRO_FORMAT_ARGB32
+clutter_cairo_clear
+clutter_cairo_set_source_color
+</SECTION>
+
 <SECTION>
 <FILE>clutter-cairo-texture</FILE>
 <TITLE>ClutterCairoTexture</TITLE>
-CLUTTER_CAIRO_FORMAT_ARGB32
 ClutterCairoTexture
 ClutterCairoTextureClass
 clutter_cairo_texture_new
@@ -1891,9 +1907,6 @@ clutter_cairo_texture_invalidate_rectangle
 clutter_cairo_texture_invalidate
 clutter_cairo_texture_clear
 
-<SUBSECTION>
-clutter_cairo_set_source_color
-
 <SUBSECTION Standard>
 CLUTTER_TYPE_CAIRO_TEXTURE
 CLUTTER_CAIRO_TEXTURE
@@ -2897,6 +2910,10 @@ clutter_drop_action_get_type
 <FILE>clutter-transition</FILE>
 ClutterTransition
 ClutterTransitionClass
+clutter_transition_set_from
+clutter_transition_set_from_value
+clutter_transition_set_to
+clutter_transition_set_to_value
 clutter_transition_set_interval
 clutter_transition_get_interval
 clutter_transition_set_animatable
@@ -3237,7 +3254,7 @@ clutter_keyframe_transition_get_n_key_frames
 clutter_keyframe_transition_set_key_frame
 clutter_keyframe_transition_get_key_frame
 clutter_keyframe_transition_clear
-<SECTION Standard>
+<SUBSECTION Standard>
 CLUTTER_TYPE_KEYFRAME_TRANSITION
 CLUTTER_KEYFRAME_TRANSITION
 CLUTTER_KEYFRAME_TRANSITION_CLASS