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 >*/