GESTrackObject: Document some more

docs/libs/ges-sections.txt

@@ -36,16 +36,13 @@ GES_TYPE_TRACK_TYPE
 <TITLE>GESTrackObject</TITLE>
 GESTrackObject
 GESTrackObjectClass
-FillTrackObjectFunc
-FillTrackObjectUserFunc
-ges_track_object_new
+<SUBSECTION Standard>
+ges_track_object_set_timeline_object
+ges_track_object_set_track
 ges_track_object_set_duration_internal
 ges_track_object_set_inpoint_internal
 ges_track_object_set_priority_internal
 ges_track_object_set_start_internal
-ges_track_object_set_timeline_object
-ges_track_object_set_track
-<SUBSECTION Standard>
 ges_track_object_get_type
 GES_IS_TRACK_OBJECT
 GES_IS_TRACK_OBJECT_CLASS
@@ -120,6 +117,7 @@ GES_TYPE_TIMELINE_LAYER
 <TITLE>GESTimelineObject</TITLE>
 GESTimelineObject
 GESTimelineObjectClass
+FillTrackObjectFunc
 ges_timeline_object_set_inpoint
 ges_timeline_object_set_layer
 ges_timeline_object_set_priority
@@ -197,6 +195,7 @@ ges_timeline_transition_get_type
 <TITLE>GESCustomTimelineSource</TITLE>
 GESCustomTimelineSource
 GESCustomTimelineSourceClass
+FillTrackObjectUserFunc
 ges_custom_timeline_source_new
 <SUBSECTION Standard>
 ges_cust_timeline_src_get_type

ges/ges-track-object.c

@@ -23,6 +23,10 @@
  *
  * #GESTrackObject is the Base Class for any object that can be contained in a
  * #GESTrack.
+ *
+ * It contains the basic information as to the location of the object within
+ * its container, like the start position, the in-point, the duration and the
+ * priority.
  */
 
 #include "ges-internal.h"
@@ -127,16 +131,51 @@ ges_track_object_class_init (GESTrackObjectClass * klass)
   object_class->dispose = ges_track_object_dispose;
   object_class->finalize = ges_track_object_finalize;
 
+  /**
+   * GESTrackObject:start
+   *
+   * The position of the object in the container #GESTrack (in nanoseconds).
+   */
   g_object_class_install_property (object_class, PROP_START,
       g_param_spec_uint64 ("start", "Start",
           "The position in the container", 0, G_MAXUINT64, 0,
           G_PARAM_READWRITE));
+
+  /**
+   * GESTrackObject:in-point
+   *
+   * The in-point at which this #GESTrackObject will start outputting data
+   * from its contents (in nanoseconds).
+   *
+   * Ex : an in-point of 5 seconds means that the first outputted buffer will
+   * be the one located 5 seconds in the controlled resource.
+   */
   g_object_class_install_property (object_class, PROP_INPOINT,
-      g_param_spec_uint64 ("inpoint", "In-point", "The in-point", 0,
+      g_param_spec_uint64 ("in-point", "In-point", "The in-point", 0,
           G_MAXUINT64, 0, G_PARAM_READWRITE));
+
+  /**
+   * GESTrackObject:duration
+   *
+   * The duration (in nanoseconds) which will be used in the container #GESTrack
+   * starting from 'in-point'.
+   *
+   */
   g_object_class_install_property (object_class, PROP_DURATION,
       g_param_spec_uint64 ("duration", "Duration", "The duration to use",
           0, G_MAXUINT64, GST_SECOND, G_PARAM_READWRITE));
+
+  /**
+   * GESTrackObject:priority
+   *
+   * The priority of the object within the containing #GESTrack.
+   * If two objects intersect over the same region of time, the @priority
+   * property is used to decide which one takes precedence.
+   *
+   * The highest priority (that supercedes everything) is 0, and then lowering
+   * priorities go in increasing numerical value (with #G_MAXUINT64 being the
+   * lowest priority).
+   */
   g_object_class_install_property (object_class, PROP_PRIORITY,
       g_param_spec_uint ("priority", "Priority",
           "The priority of the object", 0, G_MAXUINT, 0, G_PARAM_READWRITE));
@@ -149,23 +188,6 @@ ges_track_object_init (GESTrackObject * self)
 {
 }
 
-GESTrackObject *
-ges_track_object_new (GESTimelineObject * timelineobj, GESTrack * track)
-{
-  GESTrackObject *obj;
-
-  obj = g_object_new (GES_TYPE_TRACK_OBJECT, NULL);
-
-  /* FIXME : THIS IS TOTALLY BOGUS ! */
-
-  /* Set the timeline object and track */
-  obj->timelineobj = timelineobj;
-  obj->track = track;
-
-
-  return obj;
-}
-
 gboolean
 ges_track_object_set_start_internal (GESTrackObject * object, guint64 start)
 {

ges/ges-track-object.h

@@ -45,37 +45,58 @@ G_BEGIN_DECLS
 #define GES_TRACK_OBJECT_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TRACK_OBJECT, GESTrackObjectClass))
 
+/**
+ * GESTrackObject:
+ * @timelineobj: The #GESTimelineObject to which this object belongs.
+ * @track: The #GESTrack in which this object is.
+ * @valid: #TRUE if the content of the @gnlobject is valid.
+ * @start: Position (in nanoseconds) of the object the track.
+ * @inpoint: in-point (in nanoseconds) of the object in the track.
+ * @duration: Duration of the object
+ * @priority: Priority of the object in the track (0:top priority)
+ * @gnlobject: The GNonLin object this object is controlling.
+ *
+ * The GESTrackObject base class. Only sub-classes can access these fields.
+ */
 struct _GESTrackObject {
   GObject parent;
 
-  GESTimelineObject *timelineobj;	/* The associated timeline object */
-  GESTrack *track;			/* The associated Track */
+  /*< public >*/
+  GESTimelineObject *timelineobj;
+  GESTrack *track;
 
-  gboolean valid;	/* TRUE if the contents of gnlobject are valid/usable */
+  gboolean valid;
 
   /* Cached values of the gnlobject properties */
-  guint64 start;	/* position (in time) of the object in the layer */
-  guint64 inpoint;	/* in-point */
-  guint64 duration;	/* duration of the object used in the layer */
-  guint32 priority;	/* priority of the object in the layer (0:top priority) */
+  guint64 start;
+  guint64 inpoint;
+  guint64 duration;
+  guint32 priority;
 
-  GstElement *gnlobject;	/* The associated GnlObject */
+  GstElement *gnlobject;
 };
 
+/**
+ * GESTrackObjectClass:
+ * @create_gnl_object: method to create the GNonLin container object.
+ *
+ * Subclasses can override the @create_gnl_object method to override what type
+ * of GNonLin object will be created.
+ */ 
 struct _GESTrackObjectClass {
   GObjectClass parent_class;
 
-  /* signal callbacks */
+  /*< private >*/
+  /* signals */
   void	(*changed)	(GESTrackObject * object);
 
-  /* virtual methods */
+  /*< public >*/
+  /* virtual methods for subclasses */
   gboolean (*create_gnl_object) (GESTrackObject * object);
 };
 
 GType ges_track_object_get_type (void);
 
-GESTrackObject* ges_track_object_new (GESTimelineObject *timelineobj, GESTrack *track);
-
 gboolean ges_track_object_set_track (GESTrackObject * object, GESTrack * track);
 void ges_track_object_set_timeline_object (GESTrackObject * object, GESTimelineObject * tlobject);