More documentation. Coverage now at 25%

diff --git a/docs/libs/ges-docs.sgml b/docs/libs/ges-docs.sgml
index 3f740be..e2c91f6 100644 (file)
--- a/docs/libs/ges-docs.sgml
+++ b/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>

diff --git a/docs/libs/ges-sections.txt b/docs/libs/ges-sections.txt
index ea05558..9606441 100644 (file)
--- a/docs/libs/ges-sections.txt
+++ b/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

diff --git a/ges/ges-custom-timeline-source.c b/ges/ges-custom-timeline-source.c
index c9102d7..772fa04 100644 (file)
--- a/ges/ges-custom-timeline-source.c
+++ b/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"

diff --git a/ges/ges-simple-timeline-layer.c b/ges/ges-simple-timeline-layer.c
index bca635b..cd85a2c 100644 (file)
--- a/ges/ges-simple-timeline-layer.c
+++ b/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"
 

diff --git a/ges/ges-timeline-layer.c b/ges/ges-timeline-layer.c
index 8cdf517..ba6712a 100644 (file)
--- a/ges/ges-timeline-layer.c
+++ b/ges/ges-timeline-layer.c
@@ -17,17 +17,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
-#include "ges-internal.h"
-#include "gesmarshal.h"
-#include "ges-timeline-layer.h"
-#include "ges.h"
-
 /**
- * GESTimelineLayer
+ * 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"
+
 G_DEFINE_TYPE (GESTimelineLayer, ges_timeline_layer, G_TYPE_OBJECT);
 
 enum

diff --git a/ges/ges-timeline-object.c b/ges/ges-timeline-object.c
index c7071a9..0c77c2d 100644 (file)
--- a/ges/ges-timeline-object.c
+++ b/ges/ges-timeline-object.c
@@ -17,18 +17,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
-#include "ges-timeline-object.h"
-#include "ges.h"
-#include "ges-internal.h"
-
 /**
- * GESTimelineObject
+ * SECTION:ges-timeline-object
+ * @short_description: Base Class for objects in a #GESTimelineLayer
  *
- * Responsible for creating the TrackObject(s) for given TimelineTrack(s)
+ * Responsible for creating the #GESTrackObject(s) for given #GESTimelineTrack(s)
  *
- * Keeps a reference to the TrackObject(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"
+#include "ges.h"
+#include "ges-internal.h"
+
 
 G_DEFINE_TYPE (GESTimelineObject, ges_timeline_object, G_TYPE_OBJECT);
 

diff --git a/ges/ges-timeline-pipeline.c b/ges/ges-timeline-pipeline.c
index ec7f02a..5c9fe85 100644 (file)
--- a/ges/ges-timeline-pipeline.c
+++ b/ges/ges-timeline-pipeline.c
@@ -17,13 +17,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
-#include "ges-internal.h"
-#include "ges-timeline-pipeline.h"
-
-/* TimelinePipeline
+/**
+ * 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"
+
 /* Structure corresponding to a timeline - sink link */
 /* TODO : Don't forget we want to render also :) */
 

diff --git a/ges/ges-timeline-source.c b/ges/ges-timeline-source.c
index 746d5d4..5fe1ab7 100644 (file)
--- a/ges/ges-timeline-source.c
+++ b/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"

diff --git a/ges/ges-timeline-transition.c b/ges/ges-timeline-transition.c
index a927704..c4bf143 100644 (file)
--- a/ges/ges-timeline-transition.c
+++ b/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"
 

diff --git a/ges/ges-timeline.c b/ges/ges-timeline.c
index 0892883..ba2e6a2 100644 (file)
--- a/ges/ges-timeline.c
+++ b/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);
 

diff --git a/ges/ges-track-object.c b/ges/ges-track-object.c
index 01d4b0a..5dc31c8 100644 (file)
--- a/ges/ges-track-object.c
+++ b/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"

diff --git a/ges/ges-track-source.c b/ges/ges-track-source.c
index 1be5cc9..855e5db 100644 (file)
--- a/ges/ges-track-source.c
+++ b/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"

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

diff --git a/ges/ges-track.h b/ges/ges-track.h
index ccc4682..115717f 100644 (file)
--- a/ges/ges-track.h
+++ b/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 */

diff --git a/ges/ges.c b/ges/ges.c
index 7ab00c5..524055b 100644 (file)
--- a/ges/ges.c
+++ b/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)
 {