Finish public API documentation

docs/libs/ges-sections.txt

@@ -73,14 +73,14 @@ ges_track_source_get_type
 <TITLE>GESTimeline</TITLE>
 GESTimeline
 GESTimelineClass
-ges_timeline_remove_layer
+ges_timeline_new
-ges_timeline_remove_track
-ges_timeline_save
 ges_timeline_add_layer
+ges_timeline_remove_layer
 ges_timeline_add_track
+ges_timeline_remove_track
 ges_timeline_get_track_for_pad
 ges_timeline_load_from_uri
-ges_timeline_new
+ges_timeline_save
 <SUBSECTION Standard>
 ges_timeline_get_type
 GES_IS_TIMELINE
@@ -100,8 +100,8 @@ GESTimelineLayerClass
 ges_timeline_layer_add_object
 ges_timeline_layer_new
 ges_timeline_layer_remove_object
-ges_timeline_layer_set_timeline
 <SUBSECTION Standard>
+ges_timeline_layer_set_timeline
 ges_timeline_layer_get_type
 GES_IS_TIMELINE_LAYER
 GES_IS_TIMELINE_LAYER_CLASS
@@ -119,15 +119,14 @@ GESTimelineObject
 GESTimelineObjectClass
 FillTrackObjectFunc
 ges_timeline_object_set_inpoint
-ges_timeline_object_set_layer
-ges_timeline_object_set_priority
 ges_timeline_object_set_start
-ges_timeline_object_create_track_object
-ges_timeline_object_fill_track_object
-ges_timeline_object_new
-ges_timeline_object_release_track_object
 ges_timeline_object_set_duration
 <SUBSECTION Standard>
+ges_timeline_object_create_track_object
+ges_timeline_object_fill_track_object
+ges_timeline_object_release_track_object
+ges_timeline_object_set_layer
+ges_timeline_object_set_priority
 GES_IS_TIMELINE_OBJECT
 GES_IS_TIMELINE_OBJECT_CLASS
 GES_TIMELINE_OBJECT
@@ -213,10 +212,9 @@ GES_TYPE_CUSTOM_TIMELINE_SOURCE
 <TITLE>GESSimpleTimelineLayer</TITLE>
 GESSimpleTimelineLayer
 GESSimpleTimelineLayerClass
+ges_simple_timeline_layer_new
 ges_simple_timeline_layer_add_object
 ges_simple_timeline_layer_move_object
-ges_simple_timeline_layer_new
-ges_simple_timeline_layer_remove_object
 <SUBSECTION Standard>
 ges_simple_timeline_layer_get_type
 GES_IS_SIMPLE_TIMELINE_LAYER

ges/ges-custom-timeline-source.c

@@ -107,6 +107,15 @@ ges_cust_timeline_src_fill_track_object (GESTimelineObject * object,
   return res;
 }
 
+/**
+ * ges_custom_timeline_source_new:
+ * @func: The #FillTrackObjectUserFunc that will be used to fill the track objects.
+ * @user_data: a gpointer that will be used when @func is called.
+ *
+ * Creates a new #GESCustomTimelineSource.
+ *
+ * Returns: The new #GESCustomTimelineSource.
+ */
 GESCustomTimelineSource *
 ges_custom_timeline_source_new (FillTrackObjectUserFunc func,
     gpointer user_data)

ges/ges-custom-timeline-source.h

@@ -43,6 +43,21 @@ G_BEGIN_DECLS
 #define GES_CUSTOM_TIMELINE_SOURCE_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_CUSTOM_TIMELINE_SOURCE, GESCustomTimelineSourceClass))
 
+/**
+ * FillTrackObjectUserFunc:
+ * @object: the #GESTimelineObject controlling the track object
+ * @trobject: the #GESTrackObject
+ * @gnlobj: the GNonLin object that needs to be filled.
+ * @user_data: the gpointer to optional user data
+ *
+ * A function that will be called when the GNonLin object of a corresponding
+ * track object needs to be filled.
+ *
+ * The implementer of this function shall add the proper #GstElement to @gnlobj
+ * using gst_bin_add().
+ *
+ * Returns: TRUE if the implementer succesfully filled the @gnlobj, else #FALSE.
+ */
 typedef gboolean (*FillTrackObjectUserFunc) (GESTimelineObject * object,
 					     GESTrackObject * trobject,
 					     GstElement * gnlobj,

ges/ges-simple-timeline-layer.c

@@ -79,6 +79,62 @@ ges_simple_timeline_layer_init (GESSimpleTimelineLayer * self)
 {
 }
 
+/**
+ * ges_simple_timeline_layer_add_object:
+ * @layer: a #GESSimpleTimelineLayer
+ * @object: the #GESTimelineObject to add
+ * @position: the position at which to add the object
+ *
+ * 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.
+ *
+ * The layer will steal a reference to the provided object.
+ *
+ * NOT IMPLEMENTED !
+ *
+ * Returns: TRUE if the object was successfuly added, else FALSE.
+ */
+gboolean
+ges_simple_timeline_layer_add_object (GESSimpleTimelineLayer * layer,
+    GESTimelineObject * object, gint position)
+{
+  /* NOT IMPLEMENTED */
+
+  return FALSE;
+}
+
+/**
+ * ges_simple_timeline_layer_move_object:
+ * @layer: a #GESSimpleTimelineLayer
+ * @object: the #GESTimelineObject to move
+ * @newposition: the new position at which to move the object
+ *
+ * Moves the object to the given position in the layer. To put the object before
+ * all other objects, use position 0. To put the objects after all objects, use
+ * position -1.
+ *
+ * NOT IMPLEMENTED !
+ *
+ * Returns: TRUE if the object was successfuly moved, else FALSE.
+ */
+
+gboolean
+ges_simple_timeline_layer_move_object (GESSimpleTimelineLayer * layer,
+    GESTimelineObject * object, gint newposition)
+{
+  /* NOT IMPLEMENTED */
+
+  return FALSE;
+}
+
+/**
+ * ges_simple_timeline_layer_new:
+ *
+ * Creates a new #GESSimpleTimelineLayer.
+ *
+ * Returns: The new #GESSimpleTimelineLayer
+ */
 GESSimpleTimelineLayer *
 ges_simple_timeline_layer_new (void)
 {

ges/ges-simple-timeline-layer.h

@@ -59,13 +59,9 @@ gboolean
 ges_simple_timeline_layer_add_object (GESSimpleTimelineLayer *layer,
 				      GESTimelineObject *object, gint position);
 
-gboolean
-ges_simple_timeline_layer_remove_object (GESSimpleTimelineLayer *layer,
-					 GESTimelineObject *object);
-
 gboolean
 ges_simple_timeline_layer_move_object (GESSimpleTimelineLayer *layer,
-				       GESTimelineObject, gint newposition);
+				       GESTimelineObject *object, gint newposition);
 
 G_END_DECLS
 

ges/ges-timeline-layer.c

@@ -89,12 +89,26 @@ ges_timeline_layer_class_init (GESTimelineLayerClass * klass)
   object_class->dispose = ges_timeline_layer_dispose;
   object_class->finalize = ges_timeline_layer_finalize;
 
+  /**
+   * GESTimelineLayer::object-added
+   * @layer: the #GESTimelineLayer
+   * @object: the #GESTimelineObject that was added.
+   *
+   * Will be emitted after the object was added to the layer.
+   */
   ges_timeline_layer_signals[OBJECT_ADDED] =
       g_signal_new ("object-added", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineLayerClass, object_added),
       NULL, NULL, ges_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
       GES_TYPE_TIMELINE_OBJECT);
 
+  /**
+   * GESTimelineLayer::object-removed
+   * @layer: the #GESTimelineLayer
+   * @object: the #GESTimelineObject that was removed
+   *
+   * Will be emitted after the object was removed from the layer.
+   */
   ges_timeline_layer_signals[OBJECT_REMOVED] =
       g_signal_new ("object-removed", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineLayerClass,
@@ -108,6 +122,13 @@ ges_timeline_layer_init (GESTimelineLayer * self)
 {
 }
 
+/**
+ * ges_timeline_layer_new:
+ *
+ * Creates a new #GESTimelineLayer.
+ *
+ * Returns: A new #GESTimelineLayer
+ */
 GESTimelineLayer *
 ges_timeline_layer_new (void)
 {

ges/ges-timeline-object.c

@@ -112,13 +112,35 @@ ges_timeline_object_class_init (GESTimelineObjectClass * klass)
   object_class->dispose = ges_timeline_object_dispose;
   object_class->finalize = ges_timeline_object_finalize;
 
+  /**
+   * GESTimelineObject:start
+   *
+   * The position of the object in the #GESTimelineLayer (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));
+
+  /**
+   * GESTimelineObject:in-point
+   *
+   * The in-point at which this #GESTimelineObject 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));
+
+  /**
+   * GESTimelineObject: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));
@@ -132,12 +154,6 @@ ges_timeline_object_init (GESTimelineObject * self)
 {
 }
 
-GESTimelineObject *
-ges_timeline_object_new (void)
-{
-  return g_object_new (GES_TYPE_TIMELINE_OBJECT, NULL);
-}
-
 /**
  * ges_timeline_object_create_track_object:
  * @object: The origin #GESTimelineObject

ges/ges-timeline-object.h

@@ -43,15 +43,37 @@ G_BEGIN_DECLS
 #define GES_TIMELINE_OBJECT_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_TIMELINE_OBJECT, GESTimelineObjectClass))
 
+/**
+ * FillTrackObjectFunc:
+ * @object: the #GESTimelineObject controlling the track object
+ * @trobject: the #GESTrackObject
+ * @gnlobj: the GNonLin object that needs to be filled.
+ *
+ * A function that will be called when the GNonLin object of a corresponding
+ * track object needs to be filled.
+ *
+ * The implementer of this function shall add the proper #GstElement to @gnlobj
+ * using gst_bin_add().
+ *
+ * Returns: TRUE if the implementer succesfully filled the @gnlobj, else #FALSE.
+ */
 typedef gboolean (*FillTrackObjectFunc) (GESTimelineObject * object,
 					 GESTrackObject * trobject,
 					 GstElement * gnlobj);
 
+/**
+ * GESTimelineObject:
+ * @layer: the #GESTImelineLayer where this object is being used.
+ *
+ * The GESTimelineObject subclass. Subclasses can access these fields.
+ */
 struct _GESTimelineObject {
   GObject parent;
 
-  GESTimelineLayer * layer;	/* The layer where this object is being used */
+  /*< public >*/
+  GESTimelineLayer * layer;
 
+  /*< private >*/
   GList *trackobjects;	/* A list of TrackObject controlled by this TimelineObject */
 
   /* start, inpoint, duration and fullduration are in nanoseconds */
@@ -63,6 +85,14 @@ struct _GESTimelineObject {
   guint64 fullduration; /* Full usable duration of the object (-1: no duration) */
 };
 
+/**
+ * GESTimelineObjectClass:
+ * @parent_class: object parent class
+ * @create_track_object: method to create a #GESTrackObject for a given #GESTrack.
+ * @fill_track_object: method to fill an associated #GESTrackObject.
+ *
+ * Subclasses can override the @create_track_object and @fill_track_object methods.
+ */
 struct _GESTimelineObjectClass {
   GObjectClass parent_class;
 
@@ -74,9 +104,6 @@ struct _GESTimelineObjectClass {
 
 GType ges_timeline_object_get_type (void);
 
-GESTimelineObject*
-ges_timeline_object_new (void);
-
 void ges_timeline_object_set_start (GESTimelineObject * object, guint64 start);
 void ges_timeline_object_set_inpoint (GESTimelineObject * object, guint64 inpoint);
 void ges_timeline_object_set_duration (GESTimelineObject * object, guint64 duration);

ges/ges-timeline-pipeline.c

@@ -118,6 +118,13 @@ ges_timeline_pipeline_init (GESTimelinePipeline * self)
   }
 }
 
+/**
+ * ges_timeline_pipeline_new:
+ *
+ * Creates a new conveninence #GESTimelinePipeline.
+ *
+ * Returns: the new #GESTimelinePipeline.
+ */
 GESTimelinePipeline *
 ges_timeline_pipeline_new (void)
 {
@@ -226,7 +233,18 @@ pad_removed_cb (GstElement * timeline, GstPad * pad, GESTimelinePipeline * self)
   GST_DEBUG ("done");
 }
 
-
+/**
+ * ges_timeline_pipeline_add_timeline:
+ * @pipeline: a #GESTimelinePipeline
+ * @timeline: the #GESTimeline to set on the @pipeline.
+ *
+ * Sets the timeline to use in this pipeline.
+ *
+ * The reference to the @timeline will be stolen by the @pipeline.
+ *
+ * Returns: TRUE if the @timeline could be successfully set on the @pipeline,
+ * else FALSE.
+ */
 gboolean
 ges_timeline_pipeline_add_timeline (GESTimelinePipeline * pipeline,
     GESTimeline * timeline)

ges/ges-timeline.c

@@ -104,28 +104,50 @@ ges_timeline_class_init (GESTimelineClass * klass)
   object_class->dispose = ges_timeline_dispose;
   object_class->finalize = ges_timeline_finalize;
 
-  /* Signals
-   * 'track-added'
-   * 'track-removed'
-   * 'layer-added'
-   * 'layer-removed'
-   */
 
+  /**
+   * GESTimeline::track-added
+   * @timeline: the #GESTimeline
+   * @track: the #GESTrack that was added to the timeline
+   *
+   * Will be emitted after the track was added to the timeline.
+   */
   ges_timeline_signals[TRACK_ADDED] =
       g_signal_new ("track-added", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineClass, track_added), NULL,
       NULL, ges_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GES_TYPE_TRACK);
 
+  /**
+   * GESTimeline::track-removed
+   * @timeline: the #GESTimeline
+   * @track: the #GESTrack that was removed from the timeline
+   *
+   * Will be emitted after the track was removed from the timeline.
+   */
   ges_timeline_signals[TRACK_REMOVED] =
       g_signal_new ("track-removed", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineClass, track_removed),
       NULL, NULL, ges_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GES_TYPE_TRACK);
 
+  /**
+   * GESTimeline::layer-added
+   * @timeline: the #GESTimeline
+   * @layer: the #GESTimelineLayer that was added to the timeline
+   *
+   * Will be emitted after the layer was added to the timeline.
+   */
   ges_timeline_signals[LAYER_ADDED] =
       g_signal_new ("layer-added", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineClass, layer_added), NULL,
       NULL, ges_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GES_TYPE_TIMELINE_LAYER);
 
+  /**
+   * GESTimeline::layer-removed
+   * @timeline: the #GESTimeline
+   * @layer: the #GESTimelineLayer that was removed from the timeline
+   *
+   * Will be emitted after the layer was removed from the timeline.
+   */
   ges_timeline_signals[LAYER_REMOVED] =
       g_signal_new ("layer-removed", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GESTimelineClass, layer_removed),
@@ -140,12 +162,31 @@ ges_timeline_init (GESTimeline * self)
   self->tracks = NULL;
 }
 
+/**
+ * ges_timeline_new:
+ *
+ * Creates a new empty #GESTimeline.
+ *
+ * Returns: The new timeline.
+ */
+
 GESTimeline *
 ges_timeline_new (void)
 {
   return g_object_new (GES_TYPE_TIMELINE, NULL);
 }
 
+/**
+ * ges_timeline_load_from_uri:
+ * @uri: The URI to load from
+ *
+ * Creates a timeline from the contents of given uri.
+ *
+ * NOT_IMPLEMENTED !
+ *
+ * Returns: A new #GESTimeline if loading was successful, else NULL.
+ */
+
 GESTimeline *
 ges_timeline_load_from_uri (gchar * uri)
 {
@@ -153,6 +194,19 @@ ges_timeline_load_from_uri (gchar * uri)
   return NULL;
 }
 
+/**
+ * ges_timeline_save:
+ * @timeline: a #GESTimeline
+ * @uri: The location to save to
+ *
+ * Saves the timeline to the given location
+ *
+ * NOT_IMPLEMENTED !
+ *
+ * Returns: TRUE if the timeline was successfully saved to the given location,
+ * else FALSE.
+ */
+
 gboolean
 ges_timeline_save (GESTimeline * timeline, gchar * uri)
 {
@@ -265,6 +319,18 @@ ges_timeline_add_layer (GESTimeline * timeline, GESTimelineLayer * layer)
   return TRUE;
 }
 
+/**
+ * ges_timeline_remove_layer:
+ * @timeline: a #GESTimeline
+ * @layer: the #GESTimelineLayer to remove
+ *
+ * Removes the layer from the timeline. The reference that the @timeline holds on
+ * the layer will be dropped. If you wish to use the @layer after calling this
+ * method, you need to take a reference before calling.
+ *
+ * Returns: TRUE if the layer was properly removed, else FALSE.
+ */
+
 gboolean
 ges_timeline_remove_layer (GESTimeline * timeline, GESTimelineLayer * layer)
 {