Add missing documentation

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>

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;
 };

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.
  *

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);

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"

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);

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",

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;
 

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.
  */

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.
  */

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);

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);

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);

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.
  */
 

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);

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);

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

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 */
-

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"

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);

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;
 };