docs: standardize GstClock documentation

* Don't mention explicitly that API is MT safe, this implies that
  other API is not. GStreamer API is assumed to be MT safe, thread
  safety should only be explicitly mentioned when API is *not* MT safe

* Don't repeat what annotations are stating with respect to ownership
  transfer, nullability

* Document virtual methods in standalone comments, so that parameters
  can be documented. This is not critical here, as parameters do not
  need annotations / specific documentation, but serves as an up to
  date example

* Document enumeration members in standalone comments, so that their
  Since tag is accounted for by gobject-introspection

* Misc cleanup / typo fixes / addition of links

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/756>

2 files changed, 137 insertions, 120 deletions

diff --git a/gst/gstclock.c b/gst/gstclock.c
index 827d2991de..11a02900a2 100644
--- a/gst/gstclock.c
+++ b/gst/gstclock.c
@@ -40,7 +40,7 @@
  *
  * The pipeline uses the clock to calculate the running time. Usually all
  * renderers synchronize to the global clock using the buffer timestamps, the
- * newsegment events and the element's base time, see #GstPipeline.
+ * #GST_EVENT_SEGMENT events and the element's base time, see #GstPipeline.
  *
  * A clock implementation can support periodic and single shot clock
  * notifications both synchronous and asynchronous.
@@ -49,14 +49,14 @@
  * 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
+ * To perform a blocking wait for the specific time of the #GstClockID use
  * 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.
  *
  * Periodic callbacks scheduled async will be repeatedly called automatically
- * until it is unscheduled. To schedule a sync periodic callback,
+ * until they are unscheduled. To schedule a sync periodic callback,
  * gst_clock_id_wait() should be called repeatedly.
  *
  * The async callbacks can happen from any thread, either provided by the core
@@ -84,7 +84,7 @@
  * the clock is not PLAYING.
  *
  * When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
- * slaved to another #GstClock with the gst_clock_set_master(). The clock will
+ * slaved to another #GstClock with gst_clock_set_master(). The clock will
  * then automatically be synchronized to this master clock by repeatedly
  * sampling the master clock and the slave clock and recalibrating the slave
  * clock with gst_clock_set_calibration(). This feature is mostly useful for
@@ -339,11 +339,9 @@ gst_clock_periodic_id_reinit (GstClock * clock, GstClockID id,
  * gst_clock_id_ref:
  * @id: The #GstClockID to ref
  *
- * Increase the refcount of given @id.
+ * Increases the refcount of given @id.
  *
  * Returns: (transfer full): The same #GstClockID with increased refcount.
- *
- * MT safe.
  */
 GstClockID
 gst_clock_id_ref (GstClockID id)
@@ -382,10 +380,8 @@ _gst_clock_id_free (GstClockID id)
  * gst_clock_id_unref:
  * @id: (transfer full): The #GstClockID to unref
  *
- * Unref given @id. When the refcount reaches 0 the
+ * Unrefs given @id. When the refcount reaches 0 the
  * #GstClockID will be freed.
- *
- * MT safe.
  */
 void
 gst_clock_id_unref (GstClockID id)
@@ -406,16 +402,11 @@ gst_clock_id_unref (GstClockID id)
  * @clock: The #GstClockID to get a single shot notification from
  * @time: the requested time
  *
- * Get a #GstClockID from @clock to trigger a single shot
- * notification at the requested time. The single shot id should be
- * unreffed after usage.
- *
- * Free-function: gst_clock_id_unref
+ * Gets a #GstClockID from @clock to trigger a single shot
+ * notification at the requested time.
  *
  * Returns: (transfer full): a #GstClockID that can be used to request the
  *     time notification.
- *
- * MT safe.
  */
 GstClockID
 gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
@@ -432,17 +423,12 @@ gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
  * @start_time: the requested start time
  * @interval: the requested interval
  *
- * Get an ID from @clock to trigger a periodic notification.
+ * Gets an ID from @clock to trigger a periodic notification.
  * The periodic notifications will start at time @start_time and
- * will then be fired with the given @interval. @id should be unreffed
- * after usage.
- *
- * Free-function: gst_clock_id_unref
+ * will then be fired with the given @interval.
  *
  * Returns: (transfer full): a #GstClockID that can be used to request the
  *     time notification.
- *
- * MT safe.
  */
 GstClockID
 gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
@@ -465,9 +451,7 @@ gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
  * Compares the two #GstClockID instances. This function can be used
  * as a GCompareFunc when sorting ids.
  *
- * Returns: negative value if a < b; zero if a = b; positive value if a > b
- *
- * MT safe.
+ * Returns: negative value if `a < b`; zero if `a = b`; positive value if `a > b`
  */
 gint
 gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2)
@@ -490,11 +474,9 @@ gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2)
  * gst_clock_id_get_time:
  * @id: The #GstClockID to query
  *
- * Get the time of the clock ID
+ * Gets the time of the clock ID
  *
  * Returns: the time of the given clock id.
- *
- * MT safe.
  */
 GstClockTime
 gst_clock_id_get_time (GstClockID id)
@@ -510,7 +492,7 @@ gst_clock_id_get_time (GstClockID id)
  * @jitter: (out) (allow-none): a pointer that will contain the jitter,
  *     can be %NULL.
  *
- * Perform a blocking wait on @id.
+ * Performs a blocking wait on @id.
  * @id should have been created with gst_clock_new_single_shot_id()
  * or gst_clock_new_periodic_id() and should not have been unscheduled
  * with a call to gst_clock_id_unschedule().
@@ -528,8 +510,6 @@ gst_clock_id_get_time (GstClockID id)
  * if the current clock time is past the time of @id, #GST_CLOCK_OK if
  * @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
  * unscheduled with gst_clock_id_unschedule().
- *
- * MT safe.
  */
 GstClockReturn
 gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
@@ -601,18 +581,16 @@ invalid_entry:
  * @user_data: User data passed in the callback
  * @destroy_data: #GDestroyNotify for user_data
  *
- * Register a callback on the given #GstClockID @id with the given
+ * Registers a callback on the given #GstClockID @id with the given
  * function and user_data. When passing a #GstClockID with an invalid
  * time to this function, the callback will be called immediately
- * with  a time set to GST_CLOCK_TIME_NONE. The callback will
+ * with  a time set to %GST_CLOCK_TIME_NONE. The callback will
  * be called when the time of @id has been reached.
  *
  * The callback @func can be invoked from any thread, either provided by the
  * core or from a streaming thread. The application should be prepared for this.
  *
  * Returns: the result of the non blocking wait.
- *
- * MT safe.
  */
 GstClockReturn
 gst_clock_id_wait_async (GstClockID id,
@@ -677,12 +655,10 @@ invalid_entry:
  * gst_clock_id_unschedule:
  * @id: The id to unschedule
  *
- * Cancel an outstanding request with @id. This can either
+ * Cancels an outstanding request with @id. This can either
  * be an outstanding async notification or a pending sync notification.
  * After this call, @id cannot be used anymore to receive sync or
  * async notifications, you need to create a new #GstClockID.
- *
- * MT safe.
  */
 void
 gst_clock_id_unschedule (GstClockID id)
@@ -747,10 +723,10 @@ gst_clock_class_init (GstClockClass * klass)
 
   /**
    * GstClock::synced:
-   * @clock: the clock
+   * @self: the clock
    * @synced: if the clock is synced now
    *
-   * Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once
+   * Signaled on clocks with %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once
    * the clock is synchronized, or when it completely lost synchronization.
    * This signal will not be emitted on clocks without the flag.
    *
@@ -830,7 +806,7 @@ gst_clock_finalize (GObject * object)
  * @clock: a #GstClock
  * @resolution: The resolution to set
  *
- * Set the accuracy of the clock. Some clocks have the possibility to operate
+ * Sets the accuracy of the clock. Some clocks have the possibility to operate
  * with different accuracy at the expense of more resource usage. There is
  * normally no need to change the default resolution of a clock. The resolution
  * of a clock can only be changed if the clock has the
@@ -861,12 +837,10 @@ gst_clock_set_resolution (GstClock * clock, GstClockTime resolution)
  * gst_clock_get_resolution:
  * @clock: a #GstClock
  *
- * Get the accuracy of the clock. The accuracy of the clock is the granularity
+ * Gets the accuracy of the clock. The accuracy of the clock is the granularity
  * of the values returned by gst_clock_get_time().
  *
  * Returns: the resolution of the clock in units of #GstClockTime.
- *
- * MT safe.
  */
 GstClockTime
 gst_clock_get_resolution (GstClock * clock)
@@ -1063,10 +1037,8 @@ gst_clock_unadjust_unlocked (GstClock * clock, GstClockTime external)
  * Gets the current internal time of the given clock. The time is returned
  * unadjusted for the offset and the rate.
  *
- * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when
+ * Returns: the internal time of the clock. Or %GST_CLOCK_TIME_NONE when
  * given invalid input.
- *
- * MT safe.
  */
 GstClockTime
 gst_clock_get_internal_time (GstClock * clock)
@@ -1110,10 +1082,8 @@ not_supported:
  * monotonically increasing and adjusted according to the current
  * offset and rate.
  *
- * Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when
+ * Returns: the time of the clock. Or %GST_CLOCK_TIME_NONE when
  * given invalid input.
- *
- * MT safe.
  */
 GstClockTime
 gst_clock_get_time (GstClock * clock)
@@ -1159,9 +1129,9 @@ gst_clock_get_time (GstClock * clock)
  * Subsequent calls to gst_clock_get_time() will return clock times computed as
  * follows:
  *
- * |[
+ * ``` C
  *   time = (internal_time - internal) * rate_num / rate_denom + external
- * ]|
+ * ```
  *
  * This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
  * tries to do the integer arithmetic as precisely as possible.
@@ -1169,8 +1139,6 @@ gst_clock_get_time (GstClock * clock)
  * Note that gst_clock_get_time() always returns increasing values so when you
  * move the clock backwards, gst_clock_get_time() will report the previous value
  * until the clock catches up.
- *
- * MT safe.
  */
 void
 gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
@@ -1211,8 +1179,6 @@ gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
  *
  * @internal, @external, @rate_num, and @rate_denom can be left %NULL if the
  * caller is not interested in the values.
- *
- * MT safe.
  */
 void
 gst_clock_get_calibration (GstClock * clock, GstClockTime * internal,
@@ -1273,7 +1239,7 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time,
  * @clock: a #GstClock
  * @master: (allow-none): a master #GstClock
  *
- * Set @master as the master clock for @clock. @clock will be automatically
+ * Sets @master as the master clock for @clock. @clock will be automatically
  * calibrated so that gst_clock_get_time() reports the same time as the
  * master clock.
  *
@@ -1287,8 +1253,6 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time,
  * Returns: %TRUE if the clock is capable of being slaved to a master clock.
  * Trying to set a master on a clock without the
  * #GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE.
- *
- * MT safe.
  */
 gboolean
 gst_clock_set_master (GstClock * clock, GstClock * master)
@@ -1360,14 +1324,11 @@ master_not_synced:
  * gst_clock_get_master:
  * @clock: a #GstClock
  *
- * Get the master clock that @clock is slaved to or %NULL when the clock is
+ * Gets the master clock that @clock is slaved to or %NULL when the clock is
  * not slaved to any master clock.
  *
  * Returns: (transfer full) (nullable): a master #GstClock or %NULL
- *     when this clock is not slaved to a master clock. Unref after
- *     usage.
- *
- * MT safe.
+ *     when this clock is not slaved to a master clock.
  */
 GstClock *
 gst_clock_get_master (GstClock * clock)
@@ -1394,10 +1355,7 @@ gst_clock_get_master (GstClock * clock)
  * This function returns the underlying clock.
  *
  * Returns: (transfer full) (nullable): a #GstClock or %NULL when the
- *     underlying clock has been freed.  Unref after usage.
- *
- * MT safe.
- *
+ *     underlying clock has been freed.
  * Since: 1.16
  */
 GstClock *
@@ -1422,9 +1380,6 @@ gst_clock_id_get_clock (GstClockID id)
  * no longer usable and should be freed.
  *
  * Returns: whether the clock @id uses the same underlying #GstClock @clock.
- *
- * MT safe.
- *
  * Since: 1.16
  */
 gboolean
@@ -1469,8 +1424,6 @@ gst_clock_id_uses_clock (GstClockID id, GstClock * clock)
  *
  * Returns: %TRUE if enough observations were added to run the
  * regression algorithm.
- *
- * MT safe.
  */
 gboolean
 gst_clock_add_observation (GstClock * clock, GstClockTime slave,
@@ -1506,6 +1459,8 @@ gst_clock_add_observation (GstClock * clock, GstClockTime slave,
  * The caller can then take the results and call gst_clock_set_calibration()
  * with the values, or some modified version of them.
  *
+ * Returns: %TRUE if enough observations were added to run the
+ * regression algorithm.
  * Since: 1.6
  */
 gboolean
@@ -1581,7 +1536,7 @@ invalid:
  * @clock: a #GstClock
  * @timeout: a timeout
  *
- * Set the amount of time, in nanoseconds, to sample master and slave
+ * Sets the amount of time, in nanoseconds, to sample master and slave
  * clocks
  */
 void
@@ -1598,7 +1553,7 @@ gst_clock_set_timeout (GstClock * clock, GstClockTime timeout)
  * gst_clock_get_timeout:
  * @clock: a #GstClock
  *
- * Get the amount of time that master and slave clocks are sampled.
+ * Gets the amount of time that master and slave clocks are sampled.
  *
  * Returns: the interval between samples.
  */
@@ -1692,9 +1647,9 @@ gst_clock_get_property (GObject * object, guint prop_id,
  * is %GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out
  * after @timeout nanoseconds.
  *
- * For asynchronous waiting, the GstClock::synced signal can be used.
+ * For asynchronous waiting, the #GstClock::synced signal can be used.
  *
- * This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
+ * This returns immediately with %TRUE if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
  * is not set on the clock, or if the clock is already synced.
  *
  * Returns: %TRUE if waiting was successful, or %FALSE on timeout
@@ -1739,9 +1694,8 @@ gst_clock_wait_for_sync (GstClock * clock, GstClockTime timeout)
  * gst_clock_is_synced:
  * @clock: a GstClock
  *
- * Checks if the clock is currently synced.
- *
- * This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock.
+ * Checks if the clock is currently synced, by looking at whether
+ * %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set.
  *
  * Returns: %TRUE if the clock is currently synced
  *
@@ -1761,10 +1715,10 @@ gst_clock_is_synced (GstClock * clock)
  * @clock: a GstClock
  * @synced: if the clock is synced
  *
- * Sets @clock to synced and emits the GstClock::synced signal, and wakes up any
+ * Sets @clock to synced and emits the #GstClock::synced signal, and wakes up any
  * thread waiting in gst_clock_wait_for_sync().
  *
- * This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
+ * This function must only be called if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
  * is set on the clock, and is intended to be called by subclasses only.
  *
  * Since: 1.6
diff --git a/gst/gstclock.h b/gst/gstclock.h
index b9bd230ffa..6d1fb522ab 100644
--- a/gst/gstclock.h
+++ b/gst/gstclock.h
@@ -125,28 +125,28 @@ typedef gpointer GstClockID;
  * GST_TIME_AS_SECONDS:
  * @time: the time
  *
- * Convert a #GstClockTime to seconds.
+ * Converts a #GstClockTime to seconds.
  */
 #define GST_TIME_AS_SECONDS(time)  ((time) / GST_SECOND)
 /**
  * GST_TIME_AS_MSECONDS:
  * @time: the time
  *
- * Convert a #GstClockTime to milliseconds (1/1000 of a second).
+ * Converts a #GstClockTime to milliseconds (1/1000 of a second).
  */
 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
 /**
  * GST_TIME_AS_USECONDS:
  * @time: the time
  *
- * Convert a #GstClockTime to microseconds (1/1000000 of a second).
+ * Converts a #GstClockTime to microseconds (1/1000000 of a second).
  */
 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
 /**
  * GST_TIME_AS_NSECONDS:
  * @time: the time
  *
- * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
+ * Converts a #GstClockTime to nanoseconds (1/1000000000 of a second).
  */
 #define GST_TIME_AS_NSECONDS(time) (time)
 
@@ -155,7 +155,7 @@ typedef gpointer GstClockID;
  * @s: the first time
  * @e: the second time
  *
- * Calculate a difference between two clock times as a #GstClockTimeDiff.
+ * Calculates a difference between two clock times as a #GstClockTimeDiff.
  * The difference is calculated as @e - @s.
  */
 #define GST_CLOCK_DIFF(s, e)            (GstClockTimeDiff)((e) - (s))
@@ -164,7 +164,7 @@ typedef gpointer GstClockID;
  * GST_TIMEVAL_TO_TIME:
  * @tv: the timeval to convert
  *
- * Convert a GTimeVal to a #GstClockTime.
+ * Converts a GTimeVal to a #GstClockTime.
  */
 #define GST_TIMEVAL_TO_TIME(tv)         (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
 
@@ -173,7 +173,7 @@ typedef gpointer GstClockID;
  * @t: The #GstClockTime to convert
  * @tv: The target timeval
  *
- * Convert a #GstClockTime to a GTimeVal
+ * Converts a #GstClockTime to a GTimeVal
  *
  * > on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
  * > which is about 68 years.  Expect trouble if you want to schedule stuff
@@ -193,7 +193,7 @@ G_STMT_START {                                                  \
  * GST_TIMESPEC_TO_TIME:
  * @ts: the timespec to convert
  *
- * Convert a struct timespec (see man pselect) to a #GstClockTime.
+ * Converts a struct timespec (see `man pselect`) to a #GstClockTime.
  */
 #define GST_TIMESPEC_TO_TIME(ts)        (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
 /**
@@ -201,7 +201,7 @@ G_STMT_START {                                                  \
  * @t: The #GstClockTime to convert
  * @ts: The target timespec
  *
- * Convert a #GstClockTime to a struct timespec (see man pselect)
+ * Converts a #GstClockTime to a struct timespec (see `man pselect`)
  */
 #define GST_TIME_TO_TIMESPEC(t,ts)                                \
 G_STMT_START {                                                    \
@@ -216,20 +216,21 @@ G_STMT_START {                                                    \
  * GST_TIME_FORMAT: (skip):
  *
  * 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
+ * #GstClockTime value in `h:m:s` format.  Use GST_TIME_ARGS() to construct
  * the matching arguments.
  *
  * Example:
- * |[<!-- language="C" -->
+ *
+ * ``` C
  * printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
- * ]|
+ * ``` 
  */
 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
 /**
  * GST_TIME_ARGS: (skip):
  * @t: a #GstClockTime
  *
- * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
+ * Formats @t for the #GST_TIME_FORMAT format string. Note: @t will be
  * evaluated more than once.
  */
 #define GST_TIME_ARGS(t) \
@@ -245,13 +246,14 @@ G_STMT_START {                                                    \
  * GST_STIME_FORMAT: (skip):
  *
  * A string that can be used in printf-like format strings to display a signed
- * #GstClockTimeDiff or #gint64 value in h:m:s format.  Use GST_TIME_ARGS() to
+ * #GstClockTimeDiff or #gint64 value in `h:m:s` format.  Use GST_TIME_ARGS() to
  * construct the matching arguments.
  *
  * Example:
- * |[
+ *
+ * ``` C
  * printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts));
- * ]|
+ * ```
  *
  * Since: 1.6
  */
@@ -260,7 +262,7 @@ G_STMT_START {                                                    \
  * GST_STIME_ARGS: (skip):
  * @t: a #GstClockTimeDiff or #gint64
  *
- * Format @t for the #GST_STIME_FORMAT format string. Note: @t will be
+ * Formats @t for the #GST_STIME_FORMAT format string. Note: @t will be
  * evaluated more than once.
  *
  * Since: 1.6
@@ -336,7 +338,7 @@ typedef enum {
  * GST_CLOCK_ENTRY:
  * @entry: the entry to cast
  *
- * Cast to a clock entry
+ * Casts to a clock entry
  */
 #define GST_CLOCK_ENTRY(entry)          ((GstClockEntry *)(entry))
 
@@ -345,7 +347,7 @@ typedef enum {
  * GST_CLOCK_ENTRY_CLOCK:
  * @entry: the entry to query
  *
- * Get the owner clock of the entry
+ * Gets the owner clock of the entry
  *
  * Deprecated: Use gst_clock_id_get_clock() instead.
  */
@@ -355,21 +357,21 @@ typedef enum {
  * GST_CLOCK_ENTRY_TYPE:
  * @entry: the entry to query
  *
- * Get the type of the clock entry
+ * Gets the type of the clock entry
  */
 #define GST_CLOCK_ENTRY_TYPE(entry)     ((entry)->type)
 /**
  * GST_CLOCK_ENTRY_TIME:
  * @entry: the entry to query
  *
- * Get the requested time of this entry
+ * Gets the requested time of this entry
  */
 #define GST_CLOCK_ENTRY_TIME(entry)     ((entry)->time)
 /**
  * GST_CLOCK_ENTRY_INTERVAL:
  * @entry: the entry to query
  *
- * Get the interval of this periodic entry
+ * Gets the interval of this periodic entry
  */
 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
 /**
@@ -391,7 +393,7 @@ typedef enum {
  */
 struct _GstClockEntry {
   gint                  refcount;
-  /*< protected >*/
+  /*< private >*/
 #ifndef GST_REMOVE_DEPRECATED
 #ifndef GST_DISABLE_DEPRECATED
   GstClock              *clock;
@@ -423,8 +425,6 @@ struct _GstClockEntry {
  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
  * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
  * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
- * @GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC: clock needs to be synced before it can be used
- *     (Since: 1.6)
  * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
  *
  * The capabilities of this clock
@@ -436,6 +436,14 @@ typedef enum {
   GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (GST_OBJECT_FLAG_LAST << 3),
   GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (GST_OBJECT_FLAG_LAST << 4),
   GST_CLOCK_FLAG_CAN_SET_MASTER         = (GST_OBJECT_FLAG_LAST << 5),
+
+  /**
+   * GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC:
+   *
+   * clock needs to be synced before it can be used
+   *
+   * Since: 1.6
+   */
   GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC     = (GST_OBJECT_FLAG_LAST << 6),
   /* padding */
   GST_CLOCK_FLAG_LAST                   = (GST_OBJECT_FLAG_LAST << 8)
@@ -451,9 +459,9 @@ typedef enum {
 
 /**
  * GstClock:
+ * @object: the parent structure
  *
- * #GstClock base structure. The values of this structure are
- * protected for subclasses, use the methods to use the #GstClock.
+ * #GstClock base structure.
  */
 struct _GstClock {
   GstObject      object;
@@ -467,15 +475,6 @@ struct _GstClock {
 /**
  * GstClockClass:
  * @parent_class: the parent class structure
- * @change_resolution: change the resolution of the clock. Not all values might
- *                     be acceptable. The new resolution should be returned.
- * @get_resolution: get the resolution of the clock.
- * @get_internal_time: get the internal unadjusted time of the clock.
- *        implement @wait_jitter instead.
- * @wait: perform a blocking wait on the given #GstClockEntry and return
- *               the jitter.
- * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
- * @unschedule: unblock a blocking or async wait operation.
  *
  * GStreamer clock class. Override the vmethods to implement the clock
  * functionality.
@@ -485,17 +484,81 @@ struct _GstClockClass {
 
   /*< public >*/
   /* vtable */
+
+  /**
+   * GstClockClass::change_resolution:
+   * @clock: the #GstClock
+   * @old_resolution: the previous resolution
+   * @new_resolution: the new resolution
+   *
+   * Change the resolution of the clock. Not all values might
+   * be acceptable.
+   *
+   * Returns: the new resolution
+   */
   GstClockTime          (*change_resolution)    (GstClock *clock,
                                                  GstClockTime old_resolution,
                                                  GstClockTime new_resolution);
+
+  /**
+   * GstClockClass::get_resolution:
+   * @clock: the #GstClock
+   *
+   * Get the resolution of the clock.
+   *
+   * Returns: the current resolution
+   */
   GstClockTime          (*get_resolution)       (GstClock *clock);
 
+  /**
+   * GstClockClass::get_internal_time:
+   * @clock: the #GstClock
+   *
+   * Get the internal unadjusted time of the clock.
+   *
+   * Implement #GstClockClass::wait instead.
+   *
+   * Returns: the internal time
+   */
   GstClockTime          (*get_internal_time)    (GstClock *clock);
 
   /* waiting on an ID */
+
+  /**
+   * GstClockClass::wait:
+   * @clock: the #GstClock
+   * @entry: the entry to wait on
+   * @jitter: (out) (allow-none): a pointer that will contain the jitter
+   *
+   * Perform a blocking wait on the given #GstClockEntry and return
+   * the jitter.
+   *
+   * Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
+   * if the current clock time is past the time of @id, #GST_CLOCK_OK if
+   * @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
+   * unscheduled with gst_clock_id_unschedule().
+   */
   GstClockReturn        (*wait)                 (GstClock *clock, GstClockEntry *entry,
                                                  GstClockTimeDiff *jitter);
+
+  /**
+   * GstClockClass::wait_async:
+   * @clock: the #GstClock
+   * @entry: the entry to wait on
+   *
+   * Perform an asynchronous wait on the given #GstClockEntry.
+   *
+   * Returns: the result of the non blocking wait.
+   */
   GstClockReturn        (*wait_async)           (GstClock *clock, GstClockEntry *entry);
+
+  /**
+   * GstClockClass::unschedule:
+   * @clock: the #GstClock
+   * @entry: the entry to unschedule
+   *
+   * Unblock a blocking or async wait operation.
+   */
   void                  (*unschedule)           (GstClock *clock, GstClockEntry *entry);
 
   /*< private >*/