diff --git a/docs/libs/ges-sections.txt b/docs/libs/ges-sections.txt
index 44d7930582..262af426f3 100644
--- a/docs/libs/ges-sections.txt
+++ b/docs/libs/ges-sections.txt
@@ -6,6 +6,12 @@
 ges_init
 </SECTION>
 
+<SECTION>
+<FILE>ges-utils</FILE>
+<TITLE>Utilities</TITLE>
+
+</SECTION>
+
 <SECTION>
 <FILE>ges-track</FILE>
 <TITLE>GESTrack</TITLE>
diff --git a/ges/ges-custom-timeline-source.h b/ges/ges-custom-timeline-source.h
index a4d0e632cb..40ec1f0d95 100644
--- a/ges/ges-custom-timeline-source.h
+++ b/ges/ges-custom-timeline-source.h
@@ -64,14 +64,25 @@ typedef gboolean (*FillTrackObjectUserFunc) (GESTimelineObject * object,
 					     GstElement * gnlobj,
 					     gpointer user_data);
 
+/**
+ * GESCustomTimelineSource:
+ *
+ */
 
 struct _GESCustomTimelineSource {
   GESTimelineSource parent;
 
+  /*< private >*/
   FillTrackObjectUserFunc filltrackobjectfunc;
   gpointer user_data;
 };
 
+/**
+ * GESCustomTimelineSourceClass:
+ * @parent_class: parent class
+ *
+ */
+
 struct _GESCustomTimelineSourceClass {
   GESTimelineSourceClass parent_class;
 };
diff --git a/ges/ges-simple-timeline-layer.c b/ges/ges-simple-timeline-layer.c
index 4e4131e1b6..b14ed23f2e 100644
--- a/ges/ges-simple-timeline-layer.c
+++ b/ges/ges-simple-timeline-layer.c
@@ -23,7 +23,14 @@
  * @short_description: High-level #GESTimelineLayer
  *
  * #GESSimpleTimelineLayer allows using #GESTimelineObject(s) with a list-like
- * API.
+ * API. Clients can add any type of GESTimelineObject to a
+ * GESSimpleTimelineLayer, and the layer will automatically compute the
+ * appropriate start times. 
+ 
+ * Users should be aware that GESTimelineTransition objects are considered to
+ * have a negative duration for the purposes of positioning GESTimelineSource
+ * objects (i.e., adding a GESTimelineTransition creates an overlap between
+ * the two adjacent sources 
  */
 
 #include "ges-internal.h"
@@ -171,6 +178,11 @@ gstl_recalculate (GESSimpleTimelineLayer * self)
  * Adds the object at the given position in the layer. The position is where
  * the object will be inserted. To put the object before all objects, use
  * position 0. To put after all objects, use position -1.
+ * 
+ * When adding transitions, it is important that the adjacent objects
+ * (objects at position, and position + 1) be (1) A derivative of
+ * GESTimelineSource or other non-transition, and (2) have a duration at least
+ * as long as the duration of the transition.
  *
  * The layer will steal a reference to the provided object.
  *
diff --git a/ges/ges-simple-timeline-layer.h b/ges/ges-simple-timeline-layer.h
index 3042e9071e..8111510370 100644
--- a/ges/ges-simple-timeline-layer.h
+++ b/ges/ges-simple-timeline-layer.h
@@ -44,6 +44,11 @@ G_BEGIN_DECLS
 #define GES_SIMPLE_TIMELINE_LAYER_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_SIMPLE_TIMELINE_LAYER, GESSimpleTimelineLayerClass))
 
+/**
+ * GESSimpleTimelineLayer:
+ * 
+ */
+
 struct _GESSimpleTimelineLayer {
   GESTimelineLayer parent;
 
@@ -54,8 +59,15 @@ struct _GESSimpleTimelineLayer {
   gboolean adding_object;
 };
 
+/**
+ * GESSimpleTimelineLayerClass:
+ * @parent_class: parent class
+ *
+ */
+
 struct _GESSimpleTimelineLayerClass {
   GESTimelineLayerClass parent_class;
+  /*< private >*/
 };
 
 GType ges_simple_timeline_layer_get_type (void);
diff --git a/ges/ges-timeline-file-source.c b/ges/ges-timeline-file-source.c
index 8c39aa24c3..c0f1c9365e 100644
--- a/ges/ges-timeline-file-source.c
+++ b/ges/ges-timeline-file-source.c
@@ -20,7 +20,10 @@
 
 /**
  * SECTION:ges-timeline-filesource
- * @short_description: 
+ * @short_description: An object for manipulating media files in a GESTimeline
+ * 
+ * Represents all the output treams from a particular uri. It is assumed that
+ * the URI points to a file of some type.
  */
 
 #include "ges-internal.h"
diff --git a/ges/ges-timeline-file-source.h b/ges/ges-timeline-file-source.h
index 8426994f84..a0ad51567a 100644
--- a/ges/ges-timeline-file-source.h
+++ b/ges/ges-timeline-file-source.h
@@ -45,6 +45,10 @@ G_BEGIN_DECLS
 #define GES_TIMELINE_FILE_SOURCE_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TIMELINE_FILE_SOURCE, GESTimelineFileSourceClass))
 
+/**
+ * GESTimelineSource:
+ * 
+ */
 
 struct _GESTimelineFileSource {
   GESTimelineSource parent;
@@ -61,8 +65,15 @@ struct _GESTimelineFileSource {
   GESTrackType supportedformats;
 };
 
+/**
+ * GESTimelineFileSourceClass:
+ * @parent_class: parent class
+ */
+
 struct _GESTimelineFileSourceClass {
   GESTimelineSourceClass parent_class;
+
+  /*< public >*/
 };
 
 GType ges_tl_filesource_get_type (void);
diff --git a/ges/ges-timeline-layer.c b/ges/ges-timeline-layer.c
index 663ddb1775..d4b06da431 100644
--- a/ges/ges-timeline-layer.c
+++ b/ges/ges-timeline-layer.c
@@ -22,7 +22,10 @@
  * SECTION:ges-timeline-layer
  * @short_description: Non-overlaping sequence of #GESTimelineObject
  *
- * Responsible for the ordering of the various contained TimelineObject(s)
+ * Responsible for the ordering of the various contained TimelineObject(s). A
+ * timeline layer has a "priority" property, which is used to manage the
+ * priorities of individual TimelineObjects. Two layers should not have the
+ * same priority within a given timeline.
  */
 
 #include "ges-internal.h"
@@ -110,7 +113,9 @@ ges_timeline_layer_class_init (GESTimelineLayerClass * klass)
    * GESTimelineLayer:priority
    *
    * The priority of the layer in the #GESTimeline. 0 is the highest
-   * priority.
+   * priority. Conceptually, a #GESTimeline is a stack of GESTimelineLayers,
+   * and the priority of the layer represents its position in the stack. Two
+   * layers should not have the same priority within a given GESTimeline.
    */
   g_object_class_install_property (object_class, PROP_PRIORITY,
       g_param_spec_uint ("priority", "Priority",
diff --git a/ges/ges-timeline-layer.h b/ges/ges-timeline-layer.h
index d8191a08f0..0bef229932 100644
--- a/ges/ges-timeline-layer.h
+++ b/ges/ges-timeline-layer.h
@@ -43,22 +43,33 @@ G_BEGIN_DECLS
 #define GES_TIMELINE_LAYER_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TIMELINE_LAYER, GESTimelineLayerClass))
 
+/**
+ * GESTimelineLayer:
+ * @timeline: the #GESTimeline where this layer is being used.
+ */
 struct _GESTimelineLayer {
-  GObject parent;
+  GObject parent; 
+
+  /*< public >*/
 
   GESTimeline *timeline;	/* The timeline where this layer is being used
 				 */
 
+  /*< private >*/
   GSList * objects_start;	/* The TimelineObjects sorted by start and
 				 * priority */
 
   guint32 priority;		/* The priority of the layer within the 
 				 * containing timeline */
 
-  /*< private >*/
   guint32 min_gnl_priority, max_gnl_priority;
 };
 
+/**
+ * GESTimelineLayerClass:
+ * @parent_class: parent class
+ *
+ */
 struct _GESTimelineLayerClass {
   GObjectClass parent_class;
 
diff --git a/ges/ges-timeline-object.c b/ges/ges-timeline-object.c
index e409372818..4e9ed9b082 100644
--- a/ges/ges-timeline-object.c
+++ b/ges/ges-timeline-object.c
@@ -22,7 +22,7 @@
  * SECTION:ges-timeline-object
  * @short_description: Base Class for objects in a #GESTimelineLayer
  *
- * Responsible for creating the #GESTrackObject(s) for given #GESTimelineTrack(s)
+ * Responsible for creating the #GESTrackObject(s) for given #GESTrack(s)
  *
  * Keeps a reference to the #GESTrackObject(s) it created and sets/updates their properties.
  */
diff --git a/ges/ges-timeline-object.h b/ges/ges-timeline-object.h
index c7495470f7..fc47297701 100644
--- a/ges/ges-timeline-object.h
+++ b/ges/ges-timeline-object.h
@@ -115,7 +115,7 @@ typedef GESTrackObject* (*CreateTrackObjectFunc) (GESTimelineObject * object,
 
 /**
  * GESTimelineObject:
- * @layer: the #GESTImelineLayer where this object is being used.
+ * @layer: the #GESTimelineLayer where this object is being used.
  *
  * The GESTimelineObject subclass. Subclasses can access these fields.
  */
diff --git a/ges/ges-timeline-pipeline.h b/ges/ges-timeline-pipeline.h
index 04e1f7b00f..f378419ad4 100644
--- a/ges/ges-timeline-pipeline.h
+++ b/ges/ges-timeline-pipeline.h
@@ -62,6 +62,11 @@ typedef enum {
   TIMELINE_MODE_SMART_RENDER	= 1 << 3
 } GESPipelineFlags;
 
+/**
+ * GESTimelinePipeline:
+ *
+ */
+
 struct _GESTimelinePipeline {
   GstPipeline parent;
 
@@ -79,8 +84,15 @@ struct _GESTimelinePipeline {
   GstEncodingProfile *profile;
 };
 
+/**
+ * GESTimelinePipelineClass:
+ * @parent_class: parent class
+ *
+ */
+
 struct _GESTimelinePipelineClass {
   GstPipelineClass parent_class;
+  /* <public> */
 };
 
 GType ges_timeline_pipeline_get_type (void);
diff --git a/ges/ges-timeline-source.h b/ges/ges-timeline-source.h
index 2420ac2b22..b5b25ce313 100644
--- a/ges/ges-timeline-source.h
+++ b/ges/ges-timeline-source.h
@@ -44,12 +44,24 @@ G_BEGIN_DECLS
 #define GES_TIMELINE_SOURCE_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TIMELINE_SOURCE, GESTimelineSourceClass))
 
+/**
+ * GESTimelineSource:
+ *
+ */
+
 struct _GESTimelineSource {
   GESTimelineObject parent;
+  /*< public >*/
 };
 
+/**
+ * GESTimelineSourceClass:
+ * @parent_class: parent class
+ */
+
 struct _GESTimelineSourceClass {
   GESTimelineObjectClass parent_class;
+  /*< public >*/
 };
 
 GType ges_timeline_source_get_type (void);
diff --git a/ges/ges-timeline-transition.h b/ges/ges-timeline-transition.h
index 4a612a1ad7..330b6557d2 100644
--- a/ges/ges-timeline-transition.h
+++ b/ges/ges-timeline-transition.h
@@ -43,13 +43,26 @@ G_BEGIN_DECLS
 #define GES_TIMELINE_TRANSITION_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TIMELINE_TRANSITION, GESTimelineTransitionClass))
 
+/**
+ * GESTimelineTransition:
+ * @vtype: a #GEnumValue indicating the type of video transition to apply.
+ *
+ */
 struct _GESTimelineTransition {
   GESTimelineObject parent;
+  /*< public >*/
   GEnumValue *vtype;
 };
 
+/**
+ * GESTimelineTransitionClass:
+ * @parent_class: parent class
+ *
+ */
+
 struct _GESTimelineTransitionClass {
   GESTimelineObjectClass parent_class;
+  /*< public >*/
 };
 
 GType ges_timeline_transition_get_type (void);
diff --git a/ges/ges-timeline.c b/ges/ges-timeline.c
index 930a0a2b67..589a62ee48 100644
--- a/ges/ges-timeline.c
+++ b/ges/ges-timeline.c
@@ -27,7 +27,7 @@
  * Contains a list of #GESTimelineLayer which users should use to arrange the
  * various timeline objects through time.
  *
- * The output type is determined by the #GESTimelineTrack that are set on
+ * The output type is determined by the #GESTrack that are set on
  * the #GESTimeline.
  */
 
diff --git a/ges/ges-timeline.h b/ges/ges-timeline.h
index e62cc52fd1..b8c4b4050e 100644
--- a/ges/ges-timeline.h
+++ b/ges/ges-timeline.h
@@ -47,7 +47,7 @@ G_BEGIN_DECLS
 
 /**
  * GESTimeline:
- * @tracks: a list of #GESTrack
+ *
  */
 struct _GESTimeline {
   GstBin parent;
@@ -64,9 +64,16 @@ struct _GESTimeline {
   gboolean async_pending;
 };
 
+/**
+ * GESTimelineClass:
+ * @parent_class: parent class
+ */
+
 struct _GESTimelineClass {
   GstBinClass parent_class;
 
+  /*< private >*/
+
   void (*track_added)	(GESTimeline *timeline, GESTrack * track);
   void (*track_removed)	(GESTimeline *timeline, GESTrack * track);
   void (*layer_added)	(GESTimeline *timeline, GESTimelineLayer *layer);
diff --git a/ges/ges-track-filesource.h b/ges/ges-track-filesource.h
index 84573ebf5e..ddf89c4b77 100644
--- a/ges/ges-track-filesource.h
+++ b/ges/ges-track-filesource.h
@@ -43,7 +43,11 @@ G_BEGIN_DECLS
 
 #define GES_TRACK_FILESOURCE_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TRACK_FILESOURCE, GESTrackFileSourceClass))
-
+/** 
+ * GESTrackFileSource
+ * @uri: #gchar *, the URI of the media file to play
+ *
+ */
 struct _GESTrackFileSource {
   GESTrackObject parent;
 
@@ -51,8 +55,15 @@ struct _GESTrackFileSource {
   gchar *uri;
 };
 
+/**
+ * GESTrackFileSourceClass
+ * @parent_class: parent class
+ */
+
 struct _GESTrackFileSourceClass {
   GESTrackObjectClass parent_class;
+
+  /* <public> */
 };
 
 GType ges_track_filesource_get_type (void);
diff --git a/ges/ges-track-object.h b/ges/ges-track-object.h
index cc5df07ed8..6b36da6b79 100644
--- a/ges/ges-track-object.h
+++ b/ges/ges-track-object.h
@@ -120,6 +120,7 @@ struct _GESTrackObject {
 
 /**
  * GESTrackObjectClass:
+ * @parent_class: parent class
  * @create_gnl_object: method to create the GNonLin container object.
  *
  * Subclasses can override the @create_gnl_object method to override what type
diff --git a/ges/ges-track-source.h b/ges/ges-track-source.h
index fb4ba0998f..89b164e5ce 100644
--- a/ges/ges-track-source.h
+++ b/ges/ges-track-source.h
@@ -44,10 +44,27 @@ G_BEGIN_DECLS
 #define GES_TRACK_SOURCE_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TRACK_SOURCE, GESTrackSourceClass))
 
+/**
+ * GESTrackSource:
+ * @parent: parent
+ *
+ * Base class for single-media sources
+ *
+ */
+
 struct _GESTrackSource {
+  /* <public> */
   GESTrackObject parent;
 };
 
+/**
+ * GESTrackSourceClass:
+ * @parent_class: the parent class
+ *
+ * Base class for track objects which produce data but do not consuem it.
+ *
+ */
+
 struct _GESTrackSourceClass {
   GESTrackObjectClass parent_class;
 };
@@ -59,4 +76,3 @@ GESTrackSource* ges_track_source_new (void);
 G_END_DECLS
 
 #endif /* _GES_TRACK_SOURCE */
-
diff --git a/ges/ges-track-transition.c b/ges/ges-track-transition.c
index 139da68a19..2696d688b7 100644
--- a/ges/ges-track-transition.c
+++ b/ges/ges-track-transition.c
@@ -18,6 +18,12 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/** 
+ * SECTION:ges-track-transition
+ * @short_description: Concrete, track-level implemenation of audio and video
+ * transitinos.
+ */
+
 #include "ges-internal.h"
 #include "ges-track-object.h"
 #include "ges-track-transition.h"
diff --git a/ges/ges-track-transition.h b/ges/ges-track-transition.h
index 716db094ee..a2e6e18c8d 100644
--- a/ges/ges-track-transition.h
+++ b/ges/ges-track-transition.h
@@ -49,16 +49,37 @@ G_BEGIN_DECLS
     (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TRACK_TRANSITION,\
         GESTrackTransitionClass)
 
+/**
+ * GESTrackTransition:
+ * @parent: parent
+ * @vtype: a #GEnumValue representing the type of transition to apply.
+ *
+ * Track level representation of a transition. Has a concrete implementation
+ * for both audio and video streams.
+ *
+ */
+
 struct _GESTrackTransition
 {
   GESTrackObject parent;
-  GstController                 *vcontroller;
 
-  GstInterpolationControlSource *vcontrol_source;
+  /*< public >*/
+  /* given to to smpte alpha element */
   GEnumValue                    *vtype;
+
+  /*< private >*/
+  
+  /* these enable video interpolation */
+  GstController                 *vcontroller;
+  GstInterpolationControlSource *vcontrol_source;
+  
+  /* these will be different depending on whether smptealpha or alpha element
+   * is used */
   gdouble                       vstart_value;
   gdouble                       vend_value;
 
+  /* these enable volume interpolation. Unlike video, both inputs are adjusted
+   * simultaneously */
   GstController                 *a_acontroller;
   GstInterpolationControlSource *a_acontrol_source;
 
@@ -66,8 +87,14 @@ struct _GESTrackTransition
   GstInterpolationControlSource *a_bcontrol_source;
 };
 
+/**
+ * GESTrackTransitionClass
+ * @parent_class: parent class
+ */
+
 struct _GESTrackTransitionClass {
     GESTrackObjectClass parent_class;
+    /* <public> */
 };
 
 GType ges_track_transition_get_type (void);
diff --git a/ges/ges-track.h b/ges/ges-track.h
index ab83ca8230..d6c2e29f6c 100644
--- a/ges/ges-track.h
+++ b/ges/ges-track.h
@@ -72,6 +72,12 @@ typedef enum {
   GES_TRACK_TYPE_CUSTOM  = 1 << 4,
 } GESTrackType;
 
+/**
+ * GESTrack:
+ * @type: a #GESTrackType indicting the basic type of the track.
+ *
+ */
+
 struct _GESTrack {
   GstBin parent;
 
@@ -87,6 +93,11 @@ struct _GESTrack {
   GstPad * srcpad;		/* The source GhostPad */
 };
 
+/**
+ * GESTrackClass:
+ * @parent_class: parent class
+ */
+
 struct _GESTrackClass {
   GstBinClass parent_class;
 };