libs/gst/: Documentation updates.

Original commit message from CVS:
* libs/gst/base/gstadapter.c:
* libs/gst/base/gstadapter.h:
* libs/gst/base/gstbasesink.c: (gst_base_sink_class_init),
(gst_base_sink_get_position):
* libs/gst/base/gstbasesink.h:
* libs/gst/base/gstbasesrc.c: (gst_base_src_class_init),
(gst_base_src_default_query), (gst_base_src_default_do_seek),
(gst_base_src_do_seek), (gst_base_src_perform_seek),
(gst_base_src_send_event), (gst_base_src_update_length),
(gst_base_src_get_range), (gst_base_src_loop),
(gst_base_src_start):
* libs/gst/base/gstbasesrc.h:
* libs/gst/base/gstbasetransform.h:
* libs/gst/base/gstcollectpads.h:
* libs/gst/base/gstpushsrc.c:
* libs/gst/base/gstpushsrc.h:
* libs/gst/dataprotocol/dataprotocol.c:
* libs/gst/dataprotocol/dataprotocol.h:
* libs/gst/net/gstnetclientclock.h:
* libs/gst/net/gstnettimeprovider.h:
Documentation updates.

ChangeLog

@@ -1,3 +1,27 @@
+2005-12-18  Wim Taymans  <wim@fluendo.com>
+
+	* libs/gst/base/gstadapter.c:
+	* libs/gst/base/gstadapter.h:
+	* libs/gst/base/gstbasesink.c: (gst_base_sink_class_init),
+	(gst_base_sink_get_position):
+	* libs/gst/base/gstbasesink.h:
+	* libs/gst/base/gstbasesrc.c: (gst_base_src_class_init),
+	(gst_base_src_default_query), (gst_base_src_default_do_seek),
+	(gst_base_src_do_seek), (gst_base_src_perform_seek),
+	(gst_base_src_send_event), (gst_base_src_update_length),
+	(gst_base_src_get_range), (gst_base_src_loop),
+	(gst_base_src_start):
+	* libs/gst/base/gstbasesrc.h:
+	* libs/gst/base/gstbasetransform.h:
+	* libs/gst/base/gstcollectpads.h:
+	* libs/gst/base/gstpushsrc.c:
+	* libs/gst/base/gstpushsrc.h:
+	* libs/gst/dataprotocol/dataprotocol.c:
+	* libs/gst/dataprotocol/dataprotocol.h:
+	* libs/gst/net/gstnetclientclock.h:
+	* libs/gst/net/gstnettimeprovider.h:
+	Documentation updates.
+
 2005-12-18  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* docs/manual/basics-helloworld.xml:

libs/gst/base/gstadapter.c

@@ -78,7 +78,9 @@
  * of GstAdapter is inside one pad's chain function, in which case access is
  * serialized via the pad's stream lock.
  *
- * Last reviewed on 2005-11-08 (0.9.5).
+ * Note that gst_adapter_push() takes ownership of the buffer passed.
+ *
+ * Last reviewed on 2005-12-18 (0.10.0).
  */
 
 #include <string.h>
@@ -303,7 +305,7 @@ gst_adapter_flush (GstAdapter * adapter, guint flush)
  * Returns a freshly allocated buffer containing the first @nbytes bytes of the
  * @adapter.
  *
- * Caller owns returned value.
+ * Caller owns returned value. g_free after usage.
  *
  * Returns: oven-fresh hot data, or #NULL if @nbytes bytes are not available
  */

libs/gst/base/gstadapter.h

@@ -44,6 +44,7 @@ typedef struct _GstAdapterClass GstAdapterClass;
 
 /**
  * GstAdapter:
+ * @object: the parent object.
  *
  * The opaque #GstAdapter data structure.
  */

libs/gst/base/gstbasesink.c

@@ -24,13 +24,13 @@
  * @short_description: Base class for sink elements
  * @see_also: #GstBaseTransform, #GstBaseSource
  *
- * GstBaseSink is the base class for sink elements in GStreamer, such as
+ * #GstBaseSink is the base class for sink elements in GStreamer, such as
  * xvimagesink or filesink. It is a layer on top of #GstElement that provides a
- * simplified interface to plugin writers. GstBaseSink handles many details for
+ * simplified interface to plugin writers. #GstBaseSink handles many details for
  * you, for example preroll, clock synchronization, state changes, activation in
  * push or pull mode, and queries. In most cases, when writing sink elements,
  * there is no need to implement class methods from #GstElement or to set
- * functions on pads, because the GstBaseSink infrastructure is sufficient.
+ * functions on pads, because the #GstBaseSink infrastructure is sufficient.
  *
  * There is only support in GstBaseSink for one sink pad, which should be named
  * "sink". A sink implementation (subclass of GstBaseSink) should install a pad
@@ -50,26 +50,55 @@
  * }
  * </programlisting>
  *
- * The one method which all subclasses of GstBaseSink must implement is
+ * #GstBaseSink will handle the prerolling correctly. This means that it will
- * GstBaseSink::render. This method will be called...
+ * return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first buffer
+ * arrives in this element. The base class will call the GstBaseSink::preroll
+ * vmethod with this preroll buffer and will then commit the state change to
+ * PAUSED. 
+ *
+ * When the element is set to PLAYING, #GstBaseSink will synchronize on the clock
+ * using the times returned from ::get_times. If this function returns
+ * #GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done.
+ * Synchronisation can be disabled entirely by setting the sync property to FALSE.
+ *
+ * After synchronisation the virtual method #GstBaseSink::render will be called.
+ * Subclasses should minimally implement this method.
+ *
+ * Upon receiving the EOS event in th PLAYING state, #GstBaseSink will wait for 
+ * the clock to reach the time indicated by the stop time of the last ::get_times 
+ * call before posting an EOS message. When the element receives EOS in PAUSED,
+ * the event is queued and an EOS message is posted when going to PLAYING.
  * 
- * preroll()
+ * #GstBaseSink will internally use the GST_EVENT_NEW_SEGMENT events to schedule
+ * synchronisation and clipping of buffers. Buffers that fall completely outside
+ * of the segment are dropped. Buffers that fall partially in the segment are 
+ * rendered (and prerolled), subclasses should do any subbuffer clipping themselves
+ * when needed.
+ * 
+ * #GstBaseSink will by default report the current playback position in 
+ * GST_FORMAT_TIME based on the current clock time and segment information. 
+ * If the element is EOS however, the query will be forwarded upstream.
  *
- * event(): mostly useful for file-like sinks (seeking or flushing)
+ * The ::set_caps function will be called when the subclass should configure itself
+ * to precess a specific media type.
+ * 
+ * The ::start and ::stop virtual methods will be called when resources should be
+ * allocated. Any ::preroll, ::render  and ::set_caps function will be called
+ * between the ::start and ::stop calls. 
  *
- * get_caps/set_caps/buffer_alloc
+ * The ::event virtual method will be called when an event is received by 
+ * #GstBaseSink. Normally this method should only be overriden by very specific
+ * elements such as file sinks that need to handle the newsegment event specially.
+ * 
+ * #GstBaseSink provides an overridable ::buffer_alloc function that can be used
+ * by specific sinks that want to do reverse negotiation or want to provided 
+ * hardware accelerated buffers for downstream elements.
  *
- * start/stop for resource allocation
+ * The ::unlock method is called when the elements should unblock any blocking
+ * operations they perform in the ::render method. This is mostly usefull when
+ * the ::render method performs a blocking write on a file descripter.
  *
- * unlock if you block on an fd, for example
+ * Last reviewed on 2005-12-18 (0.10.0)
- *
- * get_times i'm sure is for something :P
- *
- * provide example of textsink
- *
- * admonishment not to try to implement your own sink with prerolling...
- *
- * extending via subclassing, setting pad functions, gstelement vmethods.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -188,12 +217,13 @@ gst_base_sink_class_init (GstBaseSinkClass * klass)
   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_base_sink_get_property);
 
   /* FIXME, this next value should be configured using an event from the
-   * upstream element */
+   * upstream element, ie, the BUFFER_SIZE event. */
   g_object_class_install_property (G_OBJECT_CLASS (klass),
       PROP_PREROLL_QUEUE_LEN,
       g_param_spec_uint ("preroll-queue-len", "preroll-queue-len",
           "Number of buffers to queue during preroll", 0, G_MAXUINT, 0,
           G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
+
   g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_SYNC,
       g_param_spec_boolean ("sync", "Sync", "Sync on the clock", DEFAULT_SYNC,
           G_PARAM_READWRITE));

libs/gst/base/gstbasesink.h

@@ -49,6 +49,7 @@ typedef struct _GstBaseSinkClass GstBaseSinkClass;
 
 /**
  * GstBaseSink:
+ * @element: the parent element.
  *
  * The opaque #GstBaseSink data structure.
  */

libs/gst/base/gstbasesrc.c

@@ -82,9 +82,28 @@
  *
  * The #GstBaseSrc::get_times method can be used to implement pseudo-live sources.
  * The base source will wait for the specified stream time returned in 
- * #GstBaseSrc::get_times before pushing out the buffer.
+ * #GstBaseSrc::get_times before pushing out the buffer. It only makes sense to implement
+ * the ::get_times function if the source is a live source.
  *
- * Last reviewed on 2005-12-10 (0.10.0)
+ * There is only support in GstBaseSrc for one source pad, which should be named
+ * "src". A source implementation (subclass of GstBaseSrc) should install a pad
+ * template in its base_init function, like so:
+ *
+ * <programlisting>
+ * static void
+ * my_element_base_init (gpointer g_class)
+ * {
+ *   GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
+ *   // srctemplate should be a #GstStaticPadTemplate with direction
+ *   // #GST_PAD_SRC and name "src"
+ *   gst_element_class_add_pad_template (gstelement_class,
+ *       gst_static_pad_template_get (&amp;srctemplate));
+ *   // see #GstElementDetails
+ *   gst_element_class_set_details (gstelement_class, &amp;details);
+ * }
+ * </programlisting>
+ *
+ * Last reviewed on 2005-12-18 (0.10.0)
  */
 
 #include <stdlib.h>

libs/gst/base/gstbasesrc.h

@@ -63,6 +63,7 @@ typedef struct _GstBaseSrcClass GstBaseSrcClass;
 
 /**
  * GstBaseSrc:
+ * @element: the parent element.
  *
  * The opaque #GstBaseSrc data structure.
  */

libs/gst/base/gstbasetransform.h

@@ -51,6 +51,7 @@ typedef struct _GstBaseTransformClass GstBaseTransformClass;
 
 /**
  * GstBaseTransform:
+ * @element: the parent element.
  *
  * The opaque #GstBaseTransform data structure.
  */

libs/gst/base/gstcollectpads.h

@@ -77,6 +77,7 @@ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer
 
 /**
  * GstCollectPads:
+ * @object: the #GstObject parent structure.
  * @data: #GList of #GstCollectData managed by this #GstCollectPads.
  *
  * Collectpads object. 

libs/gst/base/gstpushsrc.c

@@ -29,6 +29,9 @@
  * random access, or at least very slowly. The source usually
  * prefers to push out a fixed size buffer.
  *
+ * Subclasses usually operate in a format that is different from the
+ * default GST_FORMAT_BYTES format of #GstBaseSrc.
+ *
  * Classes extending this base class will usually be scheduled
  * in a push based mode. If the peer accepts to operate without
  * offsets and withing the limits of the allowed block size, this

libs/gst/base/gstpushsrc.h

@@ -41,6 +41,7 @@ typedef struct _GstPushSrcClass GstPushSrcClass;
 
 /**
  * GstPushSrc:
+ * @parent: the parent base source object.
  *
  * The opaque #GstPushSrc data structure.
  */

libs/gst/dataprotocol/dataprotocol.c

@@ -124,6 +124,8 @@ gst_dp_init (void)
  * gst_dp_header_payload_length:
  * @header: the byte header of the packet array
  *
+ * Get the length of the payload described by @header.
+ *
  * Returns: the length of the payload this header describes.
  */
 guint32
@@ -136,6 +138,8 @@ gst_dp_header_payload_length (const guint8 * header)
  * gst_dp_header_payload_type:
  * @header: the byte header of the packet array
  *
+ * Get the type of the payload described by @header.
+ *
  * Returns: the #GstDPPayloadType the payload this header describes.
  */
 GstDPPayloadType

libs/gst/dataprotocol/dataprotocol.h

@@ -29,14 +29,35 @@
 
 G_BEGIN_DECLS
 
-/* GStreamer Data Protocol Version */
+/**
+ * GST_DP_VERSION_MAJOR:
+ * 
+ * The major version number of the GStreamer Data Protocol.
+ */
 #define GST_DP_VERSION_MAJOR 0
+/**
+ * GST_DP_VERSION_MINOR:
+ * 
+ * The minor version number of the GStreamer Data Protocol.
+ */
 #define GST_DP_VERSION_MINOR 2
 
-#define GST_DP_HEADER_LENGTH 62 /* header size in bytes */
+/**
+ * GST_DP_HEADER_LENGTH:
+ * 
+ * The header size in bytes.
+ */
+#define GST_DP_HEADER_LENGTH 62 
 
-
+/**
-/* header flags */
+ * GstDPHeaderFlag:
+ * @GST_DP_HEADER_FLAG_NONE: No flag present.
+ * @GST_DP_HEADER_FLAG_CRC_HEADER: a header CRC field is present.
+ * @GST_DP_HEADER_FLAG_CRC_PAYLOAD: a payload CRC field is present.
+ * @GST_DP_HEADER_FLAG_CRC: a CRC for header and payload is present.
+ *
+ * header flags for the dataprotocol.
+ */
 typedef enum {
   GST_DP_HEADER_FLAG_NONE        = 0,
   GST_DP_HEADER_FLAG_CRC_HEADER  = (1 << 0),
@@ -44,7 +65,16 @@ typedef enum {
   GST_DP_HEADER_FLAG_CRC         = (1 << 1) | (1 <<0),
 } GstDPHeaderFlag;
 
-/* payload types */
+/**
+ * GstDPPayloadType:
+ * @GST_DP_PAYLOAD_NONE: Invalid payload type.
+ * @GST_DP_PAYLOAD_BUFFER: #GstBuffer payload packet.
+ * @GST_DP_PAYLOAD_CAPS: #GstCaps payload packet.
+ * @GST_DP_PAYLOAD_EVENT_NONE: First value of #GstEvent payload packets.
+ *
+ * The GDP payload types. a #GstEvent payload type is encoded with the
+ * event type number starting from @GST_DP_PAYLOAD_EVENT_NONE.
+ */
 typedef enum {
   GST_DP_PAYLOAD_NONE            = 0,
   GST_DP_PAYLOAD_BUFFER,

libs/gst/net/gstnetclientclock.h

@@ -57,6 +57,7 @@ typedef struct _GstNetClientClockClass GstNetClientClockClass;
 
 /**
  * GstNetClientClock:
+ * @clock: the parent clock structure.
  *
  * Opaque #GstNetClientClock structure.
  */

libs/gst/net/gstnettimeprovider.h

@@ -51,6 +51,7 @@ typedef struct _GstNetTimeProviderClass GstNetTimeProviderClass;
 
 /**
  * GstNetTimeProvider:
+ * @parent: the parent object structure.
  *
  * Opaque #GstNetTimeProvider structure.
  */
@@ -74,6 +75,7 @@ struct _GstNetTimeProvider {
     gint active;
   } active;
   
+  /*< private >*/
   gpointer _gst_reserved[GST_PADDING - 1];
 };