More documentation. Coverage now at 25%

docs/libs/ges-docs.sgml

@@ -13,7 +13,22 @@
     </releaseinfo>
   </bookinfo>
 
+  <chapter>
+    <title>GStreamer Editing Services Overview</title>
+    <para>
+      The "GStreamer Editing Services" is a library to simplify the creation
+of multimedia editing applications. Based on the GStreamer multimedia framework
+and the GNonLin set of plugins, its goals are to suit all types of editing-related
+applications.
+    </para>
+
+    <para>
+      The GStreamer Editing Services are cross-platform and work on most UNIX-like
+platform as well as Windows. It is released under the GNU Library General Public License
+(GNU LGPL).
+    </para>
   <xi:include href="xml/ges.xml"/>
+  </chapter>
 
   <chapter>
     <title>Base Classes</title>

docs/libs/ges-sections.txt

@@ -10,8 +10,6 @@ ges_init
 <TITLE>GESTrack</TITLE>
 GESTrack
 GESTrackClass
-FillTrackObjectFunc
-FillTrackObjectUserFunc
 GESTrackType
 ges_track_add_object
 ges_track_audio_raw_new
@@ -37,6 +35,8 @@ GES_TYPE_TRACK_TYPE
 <TITLE>GESTrackObject</TITLE>
 GESTrackObject
 GESTrackObjectClass
+FillTrackObjectFunc
+FillTrackObjectUserFunc
 ges_track_object_new
 ges_track_object_set_duration_internal
 ges_track_object_set_inpoint_internal

ges/ges-custom-timeline-source.c

@@ -17,6 +17,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-custom-timeline-source
+ * @short_description: Convenience #GESTimelineSource
+ *
+ * #GESCustomTimelineSource allows creating #GESTimelineSource(s) without the
+ * need to subclass.
+ * 
+ * Its usage should be limited to testing and prototyping purposes.
+ */
+
 #include "ges-internal.h"
 #include "ges-custom-timeline-source.h"
 #include "ges-timeline-source.h"

ges/ges-simple-timeline-layer.c

@@ -17,6 +17,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-simple-timeline-layer
+ * @short_description: High-level #GESTimelineLayer
+ *
+ * #GESSimpleTimelineLayer allows using #GESTimelineObject(s) with a list-like
+ * API.
+ */
+
 #include "ges-internal.h"
 #include "ges-simple-timeline-layer.h"
 

ges/ges-timeline-layer.c

@@ -17,17 +17,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-timeline-layer
+ * @short_description: Non-overlaping sequence of #GESTimelineObject
+ *
+ * Responsible for the ordering of the various contained TimelineObject(s)
+ */
+
 #include "ges-internal.h"
 #include "gesmarshal.h"
 #include "ges-timeline-layer.h"
 #include "ges.h"
 
-/**
- * GESTimelineLayer
- *
- * Responsible for the ordering of the various contained TimelineObject(s)
- */
-
 G_DEFINE_TYPE (GESTimelineLayer, ges_timeline_layer, G_TYPE_OBJECT);
 
 enum

ges/ges-timeline-object.c

@@ -17,18 +17,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-timeline-object
+ * @short_description: Base Class for objects in a #GESTimelineLayer
+ *
+ * Responsible for creating the #GESTrackObject(s) for given #GESTimelineTrack(s)
+ *
+ * Keeps a reference to the #GESTrackObject(s) it created and sets/updates their properties.
+ */
+
 #include "ges-timeline-object.h"
 #include "ges.h"
 #include "ges-internal.h"
 
-/**
- * GESTimelineObject
- *
- * Responsible for creating the TrackObject(s) for given TimelineTrack(s)
- *
- * Keeps a reference to the TrackObject(s) it created and sets/updates their properties.
- */
-
 
 G_DEFINE_TYPE (GESTimelineObject, ges_timeline_object, G_TYPE_OBJECT);
 

ges/ges-timeline-pipeline.c

@@ -17,13 +17,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-timeline-pipeline
+ * @short_description: Convenience #GstPipeline for editing.
+ *
+ * #GESTimelinePipeline allows developers to view and render #GESTimeline
+ * in a simple fashion.
+ * Its usage is inspired by the 'playbin' element from gst-plugins-base.
+ */
+
 #include "ges-internal.h"
 #include "ges-timeline-pipeline.h"
 
-/* TimelinePipeline
- *
- */
-
 /* Structure corresponding to a timeline - sink link */
 /* TODO : Don't forget we want to render also :) */
 

ges/ges-timeline-source.c

@@ -17,6 +17,11 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-timeline-source
+ * @short_description: Base Class for sources of a #GESTimelineLayer
+ */
+
 #include "ges-internal.h"
 #include "ges-timeline-object.h"
 #include "ges-timeline-source.h"

ges/ges-timeline-transition.c

@@ -17,6 +17,11 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION: ges-timeline-transition
+ * @short_description: Base Class for transitions in a #GESTimelineLayer
+ */
+
 #include "ges-internal.h"
 #include "ges-timeline-transition.h"
 

ges/ges-timeline.c

@@ -17,6 +17,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-timeline
+ * @short_description: Multimedia timeline
+ *
+ * #GESTimeline is the central object for any multimedia timeline.
+ * 
+ * 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 #GESTimeline.
+ */
+
 #include "gesmarshal.h"
 #include "ges-internal.h"
 #include "ges-timeline.h"
@@ -24,15 +37,6 @@
 #include "ges-timeline-layer.h"
 #include "ges.h"
 
-/**
- * GESTimelinePipeline
- *
- * Top-level container for pipelines
- * 
- * Contains a list of TimelineLayer which users should use to arrange the
- * various timeline objects.
- *
- */
 
 G_DEFINE_TYPE (GESTimeline, ges_timeline, GST_TYPE_BIN);
 

ges/ges-track-object.c

@@ -17,6 +17,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-track-object
+ * @short_description: Base Class for objects contained in a #GESTrack
+ *
+ * #GESTrackObject is the Base Class for any object that can be contained in a
+ * #GESTrack.
+ */
+
 #include "ges-internal.h"
 #include "ges-track-object.h"
 #include "ges-timeline-object.h"

ges/ges-track-source.c

@@ -17,6 +17,11 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-track-source
+ * @short_description: Base Class for single-media sources
+ */
+
 #include "ges-internal.h"
 #include "ges-track-object.h"
 #include "ges-track-source.h"

ges/ges-track.c

@@ -17,18 +17,21 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:ges-track
+ * @short_description: Composition of objects
+ *
+ * Corresponds to one output format (i.e. audio OR video).
+ *
+ * Contains the compatible TrackObject(s).
+ *
+ * Wraps GNonLin's 'gnlcomposition' element.
+ */
+
 #include "ges-internal.h"
 #include "ges-track.h"
 #include "ges-track-object.h"
 
-/**
- * GESTrack
- *
- * Corresponds to one output format (i.e. audio OR video)
- *
- * Contains the compatible TrackObject(s)
- */
-
 G_DEFINE_TYPE (GESTrack, ges_track, GST_TYPE_BIN);
 
 enum

ges/ges-track.h

@@ -54,7 +54,9 @@ GType ges_track_type_get_type (void);
  * @GES_TRACK_TYPE_TEXT: A text (subtitle) track
  * @GES_TRACK_TYPE_CUSTOM: A custom-content track
  *
- * Types of content handled by a track.
+ * Types of content handled by a track. If the content is not one of
+ * @GEST_TRACK_TYPE_AUDIO, @GES_TRACK_TYPE_VIDEO or @GES_TRACK_TYPE_TEXT,
+ * the user of the #GESTrack must set the type to @GES_TRACK_TYPE_CUSTOM.
  */
 
 typedef enum {
@@ -67,9 +69,12 @@ typedef enum {
 struct _GESTrack {
   GstBin parent;
 
-  GESTimeline * timeline;
+  /*< public >*/ /* READ-ONLY */
   GESTrackType type;
 
+  /*< private >*/
+  GESTimeline * timeline;
+
   GstCaps * caps;
 
   GstElement * composition;	/* The composition associated with this track */

ges/ges.c

@@ -22,6 +22,18 @@
 
 GST_DEBUG_CATEGORY (ges_debug);
 
+/**
+ * SECTION:ges
+ * @short_description: Initialization.
+ */
+
+/**
+ * ges_init:
+ *
+ * Initialize the GStreamer Editing Service. Call this before any usage of
+ * GES.
+ */
+
 void
 ges_init (void)
 {