clock: improve the GST_TIME_FORMAT/ARGS docs

diff --git a/gst/gstclock.h b/gst/gstclock.h
index cc1ed09..230e190 100644 (file)
--- a/gst/gstclock.h
+++ b/gst/gstclock.h
@@ -205,15 +205,22 @@ G_STMT_START {                                            \
 /**
  * GST_TIME_FORMAT:
  *
- * A format that can be used in printf like format strings to format
- * a #GstClockTime value.
+ * A string that can be used in printf-like format strings to display a
+ * #GstClockTime value in h:m:s format.  Use GST_TIME_ARGS() to construct
+ * the matching arguments.
+ *
+ * Example:
+ * |[
+ * printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
+ * ]|
  */
 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
 /**
  * GST_TIME_ARGS:
  * @t: a #GstClockTime
  *
- * Format @t for the GST_TIME_FORMAT format string.
+ * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
+ * evaluated more than once.
  */
 #define GST_TIME_ARGS(t) \
         GST_CLOCK_TIME_IS_VALID (t) ? \
@@ -407,7 +414,7 @@ typedef enum {
  * @tv: a #GTimeVal to wait.
  *
  * Wait on the clock until the entries changed or the specified timeout
- * occurred. 
+ * occurred.
  */
 #define GST_CLOCK_TIMED_WAIT(clock,tv)   g_cond_timed_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock),tv)
 /**
@@ -430,7 +437,7 @@ struct _GstClock {
   GMutex       *slave_lock; /* order: SLAVE_LOCK, OBJECT_LOCK */
 
   /*< protected >*/ /* with LOCK */
-  GstClockTime  internal_calibration; 
+  GstClockTime  internal_calibration;
   GstClockTime  external_calibration;
   GstClockTime  rate_numerator;
   GstClockTime  rate_denominator;
@@ -521,7 +528,7 @@ void                        gst_clock_get_calibration       (GstClock *clock, GstClockTime *internal,
 /* master/slave clocks */
 gboolean               gst_clock_set_master            (GstClock *clock, GstClock *master);
 GstClock*              gst_clock_get_master            (GstClock *clock);
-gboolean               gst_clock_add_observation       (GstClock *clock, GstClockTime slave, 
+gboolean               gst_clock_add_observation       (GstClock *clock, GstClockTime slave,
                                                         GstClockTime master, gdouble *r_squared);