GESTimelineObject: Clarify usage of create_track_object(s) by subclasses

docs/libs/ges-sections.txt

@@ -263,6 +263,7 @@ GES_TYPE_TIMELINE_LAYER
 GESTimelineObject
 GESTimelineObjectClass
 CreateTrackObjectFunc
+CreateTrackObjectsFunc
 FillTrackObjectFunc
 GES_TIMELINE_OBJECT_DURATION
 GES_TIMELINE_OBJECT_INPOINT
@@ -274,7 +275,6 @@ ges_timeline_object_set_start
 ges_timeline_object_set_duration
 ges_timeline_object_get_layer
 ges_timeline_object_find_track_object
-CreateTrackObjectsFunc
 ges_timeline_object_add_track_object
 <SUBSECTION Standard>
 ges_timeline_object_create_track_objects

ges/ges-timeline-object.c

@@ -22,9 +22,11 @@
  * SECTION:ges-timeline-object
  * @short_description: Base Class for objects in a #GESTimelineLayer
  *
- * Responsible for creating the #GESTrackObject(s) for given #GESTrack(s)
+ * A #GESTimelineObject is a 'natural' object which controls one or more
+ * #GESTrackObject(s) in one or more #GESTrack(s).
  *
- * Keeps a reference to the #GESTrackObject(s) it created and sets/updates their properties.
+ * Keeps a reference to the #GESTrackObject(s) it created and
+ * sets/updates their properties.
  */
 
 #include "ges-timeline-object.h"
@@ -263,11 +265,11 @@ ges_timeline_object_create_track_object (GESTimelineObject * object,
  * @track: The #GESTrack to create each #GESTrackObject for.
  *
  * Creates all #GESTrackObjects supported by this object and adds them to the
- * provided track. The the track is responsible for calling
+ * provided track. The track is responsible for calling
  * #ges_timeline_release_track_object on these objects when it is finished
  * with them.
  *
- * Returns: True if each track object was created successfully, or false if an
+ * Returns: %TRUE if each track object was created successfully, or %FALSE if an
  * error occured.
  */
 
@@ -280,13 +282,16 @@ ges_timeline_object_create_track_objects (GESTimelineObject * object,
   klass = GES_TIMELINE_OBJECT_GET_CLASS (object);
 
   if (!(klass->create_track_objects)) {
-    GST_INFO ("no create_track_objects implentation");
+    GST_WARNING ("no GESTimelineObject::create_track_objects implentation");
     return FALSE;
   }
 
   return klass->create_track_objects (object, track);
 }
 
+/*
+ * default implementation of GESTimelineObjectClass::create_track_objects
+ */
 gboolean
 ges_timeline_object_create_track_objects_func (GESTimelineObject * object,
     GESTrack * track)
@@ -360,7 +365,8 @@ ges_timeline_object_release_track_object (GESTimelineObject * object,
     return FALSE;
   }
 
-  /* FIXME : Do we need to tell the subclasses ? If so, add a new virtual-method */
+  /* FIXME : Do we need to tell the subclasses ?
+   * If so, add a new virtual-method */
 
   object->priv->trackobjects =
       g_list_remove (object->priv->trackobjects, trobj);

ges/ges-timeline-object.h

@@ -69,18 +69,23 @@ typedef gboolean (*FillTrackObjectFunc) (GESTimelineObject * object,
  * @object: a #GESTimelineObject
  * @track: a #GESTrack
  *
- * Creates the 'primary track object for this @object.
+ * Creates the 'primary' track object for this @object.
  *
- * Implementors should override this function if they only interested in
+ * Subclasses should implement this method if they only provide a
- * creating a single custom track object per track.
+ * single #GESTrackObject per track.
+ *
+ * If the subclass needs to create more than one #GESTrackObject for a
+ * given track, then it should implement the 'create_track_objects'
+ * method instead.
  *
  * The implementer of this function shall return the proper #GESTrackObject
  * that should be controlled by @object for the given @track.
  *
- * If the @object can't support the media-type of the @track, this function
+ * The returned #GESTrackObject will be automatically added to the list
- * should return %NULL.
+ * of objects controlled by the #GESTimelineObject.
  *
- * Returns: the #GESTrackObject to be used, or %NULL.
+ * Returns: the #GESTrackObject to be used, or %NULL if it can't provide one
+ * for the given @track.
  */
 typedef GESTrackObject* (*CreateTrackObjectFunc) (GESTimelineObject * object,
                          GESTrack * track);
@@ -92,6 +97,13 @@ typedef GESTrackObject* (*CreateTrackObjectFunc) (GESTimelineObject * object,
  *
  * Create all track objects this object handles for this type of track.
  *
+ * Subclasses should implement this method if they potentially need to
+ * return more than one #GESTrackObject(s) for a given #GESTrack.
+ *
+ * For each object created, the subclass must call
+ * ges_timeline_object_add_track_object() with the newly created object
+ * and provided @track.
+ *
  * Returns: %TRUE on success %FALSE on failure.
  */
 typedef gboolean (*CreateTrackObjectsFunc) (GESTimelineObject * object,