Documented the clocks.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstclock.c:
* gst/gstclock.h:
Documented the clocks.

ChangeLog

@@ -1,3 +1,10 @@
+2005-10-28  Wim Taymans  <wim@fluendo.com>
+
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gstclock.c:
+	* gst/gstclock.h:
+	Documented the clocks.
+
 2005-10-28  Stefan Kost  <ensonic@users.sf.net>
 
 	* docs/gst/gstreamer-sections.txt:

docs/gst/gstreamer-sections.txt

@@ -344,7 +344,6 @@ GstClockReturn
 GstClockFlags
 GST_CLOCK_FLAGS
 GST_CLOCK_BROADCAST
-GST_CLOCK_CAST
 GST_CLOCK_COND
 GST_CLOCK_TIMED_WAIT
 GST_CLOCK_WAIT
@@ -372,6 +371,7 @@ GST_TYPE_CLOCK
 GST_CLOCK_CLASS
 GST_IS_CLOCK_CLASS
 GST_CLOCK_GET_CLASS
+GST_CLOCK_CAST
 GST_TYPE_CLOCK_ENTRY_TYPE
 GST_TYPE_CLOCK_FLAGS
 GST_TYPE_CLOCK_RETURN

gst/gstclock.c

@@ -26,16 +26,58 @@
  * @short_description: Abstract class for global clocks
  * @see_also: #GstSystemClock
  *
- * GStreamer uses a global clock to synchronise the plugins in a pipeline.
+ * GStreamer uses a global clock to synchronize the plugins in a pipeline.
  * Different clock implementations are possible by implementing this abstract
  * base class.
  *
- * The clock time is always measured in nanoseconds and always increases. The
- * pipeline uses the clock to calculate the stream time.
- * Usually all renderers sync to the global clock using the buffer timestamps,
+ * The #GstClock returns a monotonically increasing time with the method
+ * gst_clock_get_time(). Its accuracy and base time depends on the specific clock
+ * implementation but time is always expessed in nanoseconds. Since the
+ * baseline of the clock is undefined, the clock time returned is not
+ * meaningfull in itself, what matters are the deltas between two clock
+ * times.
+ *
+ * The pipeline uses the clock to calculate the stream time.
+ * Usually all renderers synchronize to the global clock using the buffer timestamps,
  * the newsegment events and the element's base time.
  *
  * The time of the clock in itself is not very useful for an application.
+ *
+ * A clock implementation can support periodic and single shot clock notifications 
+ * both synchronous and asynchronous.
+ *
+ * One first needs to create a #GstClockID for the periodic or single shot
+ * notification using gst_clock_new_single_shot_id() or gst_clock_new_periodic_id().
+ *
+ * To perform a blocking wait for the specific time of the #GstClockID use the
+ * gst_clock_id_wait(). To receive a callback when the specific time is reached
+ * in the clock use gst_clock_id_wait_async(). Both these calls can be interrupted
+ * with the gst_clock_id_unschedule() call. If the blocking wait is unscheduled
+ * a return value of GST_CLOCK_UNSCHEDULED is returned.
+ *
+ * The async callbacks can happen from any thread, either provided by the
+ * core or from a streaming thread. The application should be prepared for this.
+ *
+ * A #GstClockID that has been unscheduled cannot be used again for any wait
+ * operation.
+ *
+ * It is possible to perform a blocking wait on the same #GstClockID from multiple
+ * threads. However, registering the same #GstClockID for multiple async notifications is
+ * not possible, the callback will only be called once.
+ *
+ * None of the wait operations unref the #GstClockID, the owner is
+ * responsible for unreffing the ids itself. This holds for both periodic and
+ * single shot notifications. The reason being that the owner of the #GstClockID
+ * has to keep a handle to the #GstClockID to unblock the wait on FLUSHING events
+ * or state changes and if we unref it automatically, the handle might be
+ * invalid.
+ *
+ * These clock operations do not operate on the stream time, so the callbacks
+ * will also occur when not in PLAYING state as if the clock just keeps on
+ * running. Some clocks however do not progress when the element that provided
+ * the clock is not PLAYING.
+ *
+ * Last reviewed on 2005-10-28 (0.9.4)
  */
 
 #include <time.h>

gst/gstclock.h

@@ -44,6 +44,11 @@ G_BEGIN_DECLS
  */
 typedef guint64	GstClockTime;
 
+/**
+ * GST_TYPE_CLOCK_TIME:
+ *
+ * The GType of a GstClockTime.
+ */
 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
 
 /**
@@ -55,14 +60,14 @@ typedef gint64 GstClockTimeDiff;
 /**
  * GstClockID:
  *
- * A detatype to hold the handle to an outstanding async clock callback
+ * A datatype to hold the handle to an outstanding async clock callback.
  */
 typedef gpointer GstClockID;
 
 /**
  * GST_CLOCK_TIME_NONE:
  *
- * Constant to define an undefined clock time
+ * Constant to define an undefined clock time.
  */
 #define GST_CLOCK_TIME_NONE		((GstClockTime) -1)
 /**
@@ -76,19 +81,19 @@ typedef gpointer GstClockID;
 /**
  * GST_SECOND:
  *
- * Constant that defines one GStreamer second
+ * Constant that defines one GStreamer second.
  */
 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
 /**
  * GST_MSECOND:
  *
- * Constant that defines one GStreamer millisecond
+ * Constant that defines one GStreamer millisecond.
  */
 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
 /**
  * GST_USECOND:
  *
- * Constant that defines one GStreamer microsecond
+ * Constant that defines one GStreamer microsecond.
  */
 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
 /**
@@ -155,7 +160,18 @@ G_STMT_START {						\
 } G_STMT_END
 
 /* timestamp debugging macros */
+/**
+ * GST_TIME_FORMAT:
+ *
+ * A format that can be used in printf like format strings to format
+ * a GstClockTime value.
+ */
 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
+/**
+ * GST_TIME_ARGS:
+ *
+ * Format the GstClockTime argument for the GST_TIME_FORMAT format string.
+ */
 #define GST_TIME_ARGS(t) \
         (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)), \
         (guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60), \
@@ -310,11 +326,45 @@ typedef enum {
  */
 #define GST_CLOCK_FLAGS(clock)  (GST_CLOCK(clock)->flags)
 
+/**
+ * GST_CLOCK_COND:
+ * @clock: the clock to query
+ *
+ * Gets the #GCond that gets signaled when the entries of the clock
+ * changed.
+ */
 #define GST_CLOCK_COND(clock)            (GST_CLOCK_CAST(clock)->entries_changed)
+/**
+ * GST_CLOCK_WAIT:
+ * @clock: the clock to wait on
+ *
+ * Wait on the clock until the entries changed.
+ */
 #define GST_CLOCK_WAIT(clock)            g_cond_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock))
+/**
+ * GST_CLOCK_TIMED_WAIT:
+ * @clock: the clock to wait on
+ * @tv: a GTimeVal to wait.
+ *
+ * Wait on the clock until the entries changed or the specified timeout
+ * occured. 
+ */
 #define GST_CLOCK_TIMED_WAIT(clock,tv)   g_cond_timed_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock),tv)
+/**
+ * GST_CLOCK_BROADCAST:
+ * @clock: the clock to broadcast
+ *
+ * Signal that the entries in the clock have changed.
+ */
 #define GST_CLOCK_BROADCAST(clock)       g_cond_broadcast(GST_CLOCK_COND(clock))
 
+/**
+ * GstClock:
+ * @flags: The flags specifying the capabilities of the clock.
+ *
+ * GstClock base structure. The values of this structure are
+ * protected for subclasses, use the methods to use the #GstClock.
+ */
 struct _GstClock {
   GstObject	 object;