docs: Rework the gdk docs

Convert links, make things more concise.

1 files changed, 60 insertions, 55 deletions

diff --git a/gdk/gdkframetimings.c b/gdk/gdkframetimings.c
index 797638d844..22d9623746 100644
--- a/gdk/gdkframetimings.c
+++ b/gdk/gdkframetimings.c
@@ -22,23 +22,16 @@
 #include "gdkframeclockprivate.h"
 
 /**
- * SECTION:gdkframetimings
- * @Short_description: Object holding timing information for a single frame
- * @Title: Frame timings
- *
- * A #GdkFrameTimings object holds timing information for a single frame
- * of the application’s displays. To retrieve #GdkFrameTimings objects,
- * use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings().
- * The information in #GdkFrameTimings is useful for precise synchronization
- * of video with the event or audio streams, and for measuring
- * quality metrics for the application’s display, such as latency and jitter.
- */
-
-/**
  * GdkFrameTimings:
  *
- * The GdkFrameTimings struct contains only private fields and
- * should not be accessed directly.
+ * A `GdkFrameTimings` object holds timing information for a single frame
+ * of the application’s displays.
+ *
+ * To retrieve `GdkFrameTimings` objects, use [method@Gdk.FrameClock.get_timings]
+ * or [method@Gdk.FrameClock.get_current_timings]. The information in
+ * `GdkFrameTimings` is useful for precise synchronization of video with
+ * the event or audio streams, and for measuring quality metrics for the
+ * application’s display, such as latency and jitter.
  */
 
 G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
@@ -74,7 +67,7 @@ _gdk_frame_timings_steal (GdkFrameTimings *timings,
 
 /**
  * gdk_frame_timings_ref:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
  *
  * Increases the reference count of @timings.
  *
@@ -92,10 +85,11 @@ gdk_frame_timings_ref (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_unref:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
  *
- * Decreases the reference count of @timings. If @timings
- * is no longer referenced, it will be freed.
+ * Decreases the reference count of @timings.
+ *
+ * If @timings is no longer referenced, it will be freed.
  */
 void
 gdk_frame_timings_unref (GdkFrameTimings *timings)
@@ -112,9 +106,9 @@ gdk_frame_timings_unref (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_frame_counter:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
  *
- * Gets the frame counter value of the #GdkFrameClock when this
+ * Gets the frame counter value of the `GdkFrameClock` when
  * this frame was drawn.
  *
  * Returns: the frame counter value for this frame
@@ -127,20 +121,24 @@ gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_complete:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
+ *
+ * Returns whether @timings are complete.
  *
- * The timing information in a #GdkFrameTimings is filled in
+ * The timing information in a `GdkFrameTimings` is filled in
  * incrementally as the frame as drawn and passed off to the
  * window system for processing and display to the user. The
- * accessor functions for #GdkFrameTimings can return 0 to
+ * accessor functions for `GdkFrameTimings` can return 0 to
  * indicate an unavailable value for two reasons: either because
  * the information is not yet available, or because it isn't
- * available at all. Once gdk_frame_timings_get_complete() returns
- * %TRUE for a frame, you can be certain that no further values
- * will become available and be stored in the #GdkFrameTimings.
+ * available at all.
+ *
+ * Once this function returns %TRUE for a frame, you can be
+ * certain that no further values will become available and be
+ * stored in the `GdkFrameTimings`.
  *
  * Returns: %TRUE if all information that will be available
- *  for the frame has been filled in.
+ *   for the frame has been filled in.
  */
 gboolean
 gdk_frame_timings_get_complete (GdkFrameTimings *timings)
@@ -152,11 +150,12 @@ gdk_frame_timings_get_complete (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_frame_time:
- * @timings: A #GdkFrameTimings
+ * @timings: A `GdkFrameTimings`
  *
- * Returns the frame time for the frame. This is the time value
- * that is typically used to time animations for the frame. See
- * gdk_frame_clock_get_frame_time().
+ * Returns the frame time for the frame.
+ *
+ * This is the time value that is typically used to time
+ * animations for the frame. See [method@Gdk.FrameClock.get_frame_time].
  *
  * Returns: the frame time for the frame, in the timescale
  *  of g_get_monotonic_time()
@@ -171,14 +170,15 @@ gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_presentation_time:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
+ *
+ * Reurns the presentation time.
  *
- * Reurns the presentation time. This is the time at which the frame
- * became visible to the user.
+ * This is the time at which the frame became visible to the user.
  *
  * Returns: the time the frame was displayed to the user, in the
- *  timescale of g_get_monotonic_time(), or 0 if no presentation
- *  time is available. See gdk_frame_timings_get_complete()
+ *   timescale of g_get_monotonic_time(), or 0 if no presentation
+ *   time is available. See [method@Gdk.FrameTimings.get_complete]
  */
 gint64
 gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
@@ -190,21 +190,24 @@ gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_predicted_presentation_time:
- * @timings: a #GdkFrameTimings
- *
- * Gets the predicted time at which this frame will be displayed. Although
- * no predicted time may be available, if one is available, it will
- * be available while the frame is being generated, in contrast to
- * gdk_frame_timings_get_presentation_time(), which is only available
- * after the frame has been presented. In general, if you are simply
- * animating, you should use gdk_frame_clock_get_frame_time() rather
- * than this function, but this function is useful for applications
- * that want exact control over latency. For example, a movie player
- * may want this information for Audio/Video synchronization.
+ * @timings: a `GdkFrameTimings`
+ *
+ * Gets the predicted time at which this frame will be displayed.
+ *
+ * Although no predicted time may be available, if one is available,
+ * it will be available while the frame is being generated, in contrast
+ * to [method@Gdk.FrameTimings.get_presentation_time], which is only
+ * available after the frame has been presented.
+ *
+ * In general, if you are simply animating, you should use
+ * [method@Gdk.FrameClock.get_frame_time] rather than this function,
+ * but this function is useful for applications that want exact control
+ * over latency. For example, a movie player may want this information
+ * for Audio/Video synchronization.
  *
  * Returns: The predicted time at which the frame will be presented,
- *  in the timescale of g_get_monotonic_time(), or 0 if no predicted
- *  presentation time is available.
+ *   in the timescale of g_get_monotonic_time(), or 0 if no predicted
+ *   presentation time is available.
  */
 gint64
 gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
@@ -216,15 +219,17 @@ gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
 
 /**
  * gdk_frame_timings_get_refresh_interval:
- * @timings: a #GdkFrameTimings
+ * @timings: a `GdkFrameTimings`
  *
  * Gets the natural interval between presentation times for
- * the display that this frame was displayed on. Frame presentation
- * usually happens during the “vertical blanking interval”.
+ * the display that this frame was displayed on.
+ *
+ * Frame presentation usually happens during the “vertical
+ * blanking interval”.
  *
  * Returns: the refresh interval of the display, in microseconds,
- *  or 0 if the refresh interval is not available.
- *  See gdk_frame_timings_get_complete().
+ *   or 0 if the refresh interval is not available.
+ *   See [method@Gdk.FrameTimings.get_complete].
  */
 gint64
 gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings)