[gtk/ebassi/gidocgen: 98/200] docs: Rework the gdk docs




commit bc042989254a12d3b48b49348118932bb0269b86
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 21 00:13:57 2021 -0500

    docs: Rework the gdk docs
    
    Convert links, make things more concise.

 gdk/gdkapplaunchcontext.c    |  54 ++---
 gdk/gdkcairocontext.c        |  29 +--
 gdk/gdkclipboard.c           | 309 ++++++++++++------------
 gdk/gdkcontentdeserializer.c |  97 +++++---
 gdk/gdkcontentdeserializer.h |   6 +-
 gdk/gdkcontentformats.c      | 247 +++++++++----------
 gdk/gdkcontentprovider.c     |  84 ++++---
 gdk/gdkcontentprovider.h     |   6 -
 gdk/gdkcontentserializer.c   |  95 +++++---
 gdk/gdkcontentserializer.h   |   6 +-
 gdk/gdkcursor.c              | 135 +++++++----
 gdk/gdkdevice.c              | 248 +++++++++++--------
 gdk/gdkdevicepad.c           |  51 ++--
 gdk/gdkdevicetool.c          |  69 ++++--
 gdk/gdkdevicetool.h          |   5 -
 gdk/gdkdisplaymanager.c      | 117 +++++----
 gdk/gdkdrag.c                | 144 +++++------
 gdk/gdkdrag.h                |   2 +-
 gdk/gdkdragsurface.c         |   7 +-
 gdk/gdkdrawcontext.c         |  99 ++++----
 gdk/gdkdrop.c                | 181 +++++++-------
 gdk/gdkevents.c              | 230 ++++++++++--------
 gdk/gdkevents.h              |  21 +-
 gdk/gdkframeclock.c          | 221 ++++++++---------
 gdk/gdkframeclock.h          |   8 +-
 gdk/gdkframetimings.c        | 115 ++++-----
 gdk/gdkglcontext.c           | 182 +++++++-------
 gdk/gdkgltexture.c           |  23 +-
 gdk/gdkgltexture.h           |   5 -
 gdk/gdkmemorytexture.c       |  13 +-
 gdk/gdkmemorytexture.h       |  24 +-
 gdk/gdkmonitor.c             | 144 ++++++++---
 gdk/gdkpaintable.c           | 202 +++++++++-------
 gdk/gdkpaintable.h           |  29 +--
 gdk/gdkpopup.c               |  63 +++--
 gdk/gdkpopup.h               |   5 -
 gdk/gdkpopuplayout.c         |  96 ++++----
 gdk/gdkrectangle.c           |  50 ++--
 gdk/gdkrgba.c                | 102 ++++----
 gdk/gdkseat.c                | 145 ++++++-----
 gdk/gdksnapshot.c            |   8 +
 gdk/gdksnapshot.h            |   5 -
 gdk/gdksurface.c             | 557 +++++++++++++++++++++++--------------------
 gdk/gdktexture.c             |  84 ++++---
 gdk/gdktoplevel.c            | 224 +++++++++++------
 gdk/gdktoplevel.h            |  19 +-
 gdk/gdktoplevellayout.c      |  12 +-
 gdk/gdktoplevelsize.c        |  37 +--
 gdk/gdktypes.h               |  31 +--
 gdk/gdkvulkancontext.c       |  53 ++--
 50 files changed, 2514 insertions(+), 2185 deletions(-)
---
diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c
index b34cdaad80..30e9ee3bd0 100644
--- a/gdk/gdkapplaunchcontext.c
+++ b/gdk/gdkapplaunchcontext.c
@@ -26,18 +26,17 @@
 
 
 /**
- * SECTION:gdkapplaunchcontext
- * @Short_description: Startup notification for applications
- * @Title: Application launching
+ * GdkAppLaunchContext:
+ *
+ * `GdkAppLaunchContext` handles launching an application in a graphical context.
  *
- * GdkAppLaunchContext is an implementation of #GAppLaunchContext that
- * handles launching an application in a graphical context. It provides
- * startup notification and allows to launch applications on a specific
- * screen or workspace.
+ * It is an implementation of `GAppLaunchContext` that provides startup
+ * notification and allows to launch applications on a specific screen
+ * or workspace.
  *
  * ## Launching an application
  *
- * |[<!-- language="C" -->
+ * ```c
  * GdkAppLaunchContext *context;
  *
  * context = gdk_display_get_app_launch_context (display);
@@ -49,14 +48,7 @@
  *   g_warning ("Launching failed: %s\n", error->message);
  *
  * g_object_unref (context);
- * ]|
- */
-
-/**
- * GdkAppLaunchContext:
- *
- * The GdkAppLaunchContext struct contains only private fields
- * and should not be accessed directly.
+ * ```
  */
 
 static void    gdk_app_launch_context_finalize    (GObject           *object);
@@ -175,9 +167,9 @@ gdk_app_launch_context_get_display_name (GAppLaunchContext *context,
 
 /**
  * gdk_app_launch_context_get_display:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
  *
- * Gets the #GdkDisplay that @context is for.
+ * Gets the `GdkDisplay` that @context is for.
  *
  * Returns: (transfer none): the display of @context
  */
@@ -191,11 +183,12 @@ gdk_app_launch_context_get_display (GdkAppLaunchContext *context)
 
 /**
  * gdk_app_launch_context_set_desktop:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
  * @desktop: the number of a workspace, or -1
  *
- * Sets the workspace on which applications will be launched when
- * using this context when running under a window manager that
+ * Sets the workspace on which applications will be launched.
+ *
+ * This only works when running under a window manager that
  * supports multiple workspaces, as described in the
  * [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec).
  *
@@ -214,11 +207,13 @@ gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,
 
 /**
  * gdk_app_launch_context_set_timestamp:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
  * @timestamp: a timestamp
  *
- * Sets the timestamp of @context. The timestamp should ideally
- * be taken from the event that triggered the launch.
+ * Sets the timestamp of @context.
+ *
+ * The timestamp should ideally be taken from the event that
+ * triggered the launch.
  *
  * Window managers can use this information to avoid moving the
  * focus to the newly launched application when the user is busy
@@ -236,7 +231,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
 
 /**
  * gdk_app_launch_context_set_icon:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
  * @icon: (allow-none): a #GIcon, or %NULL
  *
  * Sets the icon for applications that are launched with this
@@ -245,7 +240,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
  * Window Managers can use this information when displaying startup
  * notification.
  *
- * See also gdk_app_launch_context_set_icon_name().
+ * See also [method@Gdk.AppLaunchContext.set_icon_name].
  */
 void
 gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
@@ -266,16 +261,17 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
 
 /**
  * gdk_app_launch_context_set_icon_name:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
  * @icon_name: (allow-none): an icon name, or %NULL
  *
  * Sets the icon for applications that are launched with this context.
+ *
  * The @icon_name will be interpreted in the same way as the Icon field
- * in desktop files. See also gdk_app_launch_context_set_icon().
+ * in desktop files. See also [method@Gdk.AppLaunchContext.set_icon()].
  *
  * If both @icon and @icon_name are set, the @icon_name takes priority.
  * If neither @icon or @icon_name is set, the icon is taken from either
- * the file that is passed to launched application or from the #GAppInfo
+ * the file that is passed to launched application or from the `GAppInfo`
  * for the launched application itself.
  */
 void
diff --git a/gdk/gdkcairocontext.c b/gdk/gdkcairocontext.c
index cad9de9833..bfb7c24452 100644
--- a/gdk/gdkcairocontext.c
+++ b/gdk/gdkcairocontext.c
@@ -28,23 +28,14 @@
 #include "gdkinternals.h"
 
 /**
- * SECTION:gdkcairocontext
- * @Title: GdkCairoContext
- * @Short_description: Cairo draw context
+ * GdkCairoContext:
  *
- * #GdkCairoContext is an object representing the platform-specific
+ * `GdkCairoContext` is an object representing the platform-specific
  * draw context.
  *
- * #GdkCairoContexts are created for a #GdkDisplay using
- * gdk_surface_create_cairo_context(), and the context can then be used
- * to draw on that #GdkSurface.
- */
-
-/**
- * GdkCairoContext:
- *
- * The GdkCairoContext struct contains only private fields and should not
- * be accessed directly.
+ * `GdkCairoContext`s are created for a surface using
+ * [method@Gdk.Surface.create_cairo_context], and the context can then be used
+ * to draw on that surface.
  */
 
 typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate;
@@ -70,15 +61,17 @@ gdk_cairo_context_init (GdkCairoContext *self)
  * gdk_cairo_context_cairo_create:
  * @self: a #GdkCairoContext that is currently drawing
  *
- * Retrieves a Cairo context to be used to draw on the #GdkSurface
- * of @context. A call to gdk_draw_context_begin_frame() with this
+ * Retrieves a Cairo context to be used to draw on the `GdkSurface`
+ * of @context.
+ *
+ * A call to [method@Gdk.DrawContext.begin_frame] with this
  * @context must have been done or this function will return %NULL.
  *
  * The returned context is guaranteed to be valid until
- * gdk_draw_context_end_frame() is called.
+ * [method@Gdk.DrawContext.end_frame] is called.
  *
  * Returns: (transfer full) (nullable): a Cairo context to be used
- *   to draw the contents of the #GdkSurface. %NULL is returned
+ *   to draw the contents of the `GdkSurface`. %NULL is returned
  *   when @context is not drawing.
  */
 cairo_t *
diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c
index 8ed2acef6b..783bd75a62 100644
--- a/gdk/gdkclipboard.c
+++ b/gdk/gdkclipboard.c
@@ -33,33 +33,25 @@
 #include <gobject/gvaluecollector.h>
 
 /**
- * SECTION:gdkclipboard
- * @Short_description: Share data between applications for Copy-and-Paste
- * @Title: Clipboards
- * @See_also: #GdkContentProvider, #GdkContentFormats
- *
- * The #GdkClipboard object represents a clipboard of data shared
- * between different applications or between different parts of
- * the same application.
+ * GdkClipboard:
  *
- * To get a GdkClipboard object, use gdk_display_get_clipboard() or
- * gdk_display_get_primary_clipboard(). You can find out about the data that
- * is currently available in a clipboard using gdk_clipboard_get_formats().
+ * The `GdkClipboard` object represents data shared between applications or
+ * inside an application.
  *
- * To make text or image data available in a clipboard, use gdk_clipboard_set_text() or
- * gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(),
- * which takes a #GdkContentProvider object.
+ * To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or
+ * [method@Gdk.Display.get_primary_clipboard]. You can find out about the data
+ * that is currently available in a clipboard using
+ * [method@Gdk.Clipboard.get_formats].
  *
- * To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or
- * gdk_clipboard_read_texture_async(). For other data, use gdk_clipboard_read_async(),
- * which provides a #GInputStream object.
- */
-
-/**
- * GdkClipboard:
+ * To make text or image data available in a clipboard, use
+ * [method@Gdk.Clipboard.set_text] or [method@Gdk.Clipboard.set_texture].
+ * For other data, you can use [method@Gdk.Clipboard.set_content], which
+ * takes a [class@Gdk.ContentProvider] object.
  *
- * The GdkClipboard struct contains only private fields and should not be
- * accessed directly.
+ * To read textual or image data from a clipboard, use
+ * [method@Gdk.Clipboard.read_text_async] or
+ * [method@Gdk.Clipboard.read_texture_async]. For other data, use
+ * [method@Gdk.Clipboard.read_async], which provides a `GInputStream` object.
  */
 
 typedef struct _GdkClipboardPrivate GdkClipboardPrivate;
@@ -362,7 +354,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
   /**
    * GdkClipboard:display:
    *
-   * The #GdkDisplay that the clipboard belongs to.
+   * The `GdkDisplay` that the clipboard belongs to.
    */
   properties[PROP_DISPLAY] =
     g_param_spec_object ("display",
@@ -405,7 +397,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
   /**
    * GdkClipboard:content:
    *
-   * The #GdkContentProvider or %NULL if the clipboard is empty or contents are
+   * The `GdkContentProvider` or %NULL if the clipboard is empty or contents are
    * provided otherwise.
    */
   properties[PROP_CONTENT] =
@@ -421,7 +413,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
    * GdkClipboard::changed:
    * @clipboard: the object on which the signal was emitted
    *
-   * The ::changed signal is emitted when the clipboard changes ownership.
+   * Emitted when the clipboard changes ownership.
    */
   signals[CHANGED] =
     g_signal_new ("changed",
@@ -445,12 +437,12 @@ gdk_clipboard_init (GdkClipboard *clipboard)
 
 /**
  * gdk_clipboard_get_display:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  *
- * Gets the #GdkDisplay that the clipboard was created for.
+ * Gets the `GdkDisplay` that the clipboard was created for.
  *
- * Returns: (transfer none): a #GdkDisplay
- **/
+ * Returns: (transfer none): a `GdkDisplay`
+ */
 GdkDisplay *
 gdk_clipboard_get_display (GdkClipboard *clipboard)
 {
@@ -463,12 +455,12 @@ gdk_clipboard_get_display (GdkClipboard *clipboard)
 
 /**
  * gdk_clipboard_get_formats:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  *
  * Gets the formats that the clipboard can provide its current contents in.
  *
  * Returns: (transfer none): The formats of the clipboard
- **/
+ */
 GdkContentFormats *
 gdk_clipboard_get_formats (GdkClipboard *clipboard)
 {
@@ -481,16 +473,18 @@ gdk_clipboard_get_formats (GdkClipboard *clipboard)
 
 /**
  * gdk_clipboard_is_local:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
+ *
+ * Returns if the clipboard is local.
  *
- * Returns if the clipboard is local. A clipboard is considered local if it was
- * last claimed by the running application.
+ * A clipboard is considered local if it was last claimed
+ * by the running application.
  *
- * Note that gdk_clipboard_get_content() may return %NULL even on a local
- * clipboard. In this case the clipboard is empty.
+ * Note that [method@Gdk.Clipboard.get_content] may return %NULL
+ * even on a local clipboard. In this case the clipboard is empty.
  *
  * Returns: %TRUE if the clipboard is local
- **/
+ */
 gboolean
 gdk_clipboard_is_local (GdkClipboard *clipboard)
 {
@@ -503,15 +497,16 @@ gdk_clipboard_is_local (GdkClipboard *clipboard)
 
 /**
  * gdk_clipboard_get_content:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
+ *
+ * Returns the `GdkContentProvider` currently set on @clipboard.
  *
- * Returns the #GdkContentProvider currently set on @clipboard. If the
- * @clipboard is empty or its contents are not owned by the current process,
- * %NULL will be returned.
+ * If the @clipboard is empty or its contents are not owned by the
+ * current process, %NULL will be returned.
  *
  * Returns: (transfer none) (nullable): The content of a clipboard or %NULL
  *     if the clipboard does not maintain any content.
- **/
+ */
 GdkContentProvider *
 gdk_clipboard_get_content (GdkClipboard *clipboard)
 {
@@ -524,20 +519,26 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)
 
 /**
  * gdk_clipboard_store_async:
- * @clipboard: a #GdkClipboard
- * @io_priority: the [I/O priority][io-priority]
- *     of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @io_priority: the I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
- * Asynchronously instructs the @clipboard to store its contents remotely to
- * preserve them for later usage. If the clipboard is not local, this function
- * does nothing but report success.
+ * Asynchronously instructs the @clipboard to store its contents remotely.
+ *
+ * If the clipboard is not local, this function does nothing but report success.
+ *
+ * The @callback must call [method@Gdk.Clipboard.store_finish].
  *
- * This function is called automatically when gtk_main() or #GtkApplication
- * exit, so you likely don't need to call it.
- **/
+ * The purpose of this call is to preserve clipboard contents beyond the
+ * lifetime of an application, so this function is typically called on
+ * exit. Depending on the platform, the functionality may not be available
+ * unless a "clipboard manager" is running.
+ *
+ * This function is called automatically when a [class@Gtk.Application] is
+ * shut down, so you likely don't need to call it.
+ */
 void
 gdk_clipboard_store_async (GdkClipboard        *clipboard,
                            int                  io_priority,
@@ -571,15 +572,16 @@ gdk_clipboard_store_async (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_store_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous clipboard store.
  *
- * Finishes an asynchronous clipboard store started with gdk_clipboard_store_async().
+ * See [method@Gdk.Clipboard.store_async].
  *
  * Returns: %TRUE if storing was successful.
- **/
+ */
 gboolean
 gdk_clipboard_store_finish (GdkClipboard  *clipboard,
                             GAsyncResult  *result,
@@ -632,22 +634,22 @@ gdk_clipboard_read_internal (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_async:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  * @mime_types: a %NULL-terminated array of mime types to choose from
- * @io_priority: the [I/O priority][io-priority]
- * of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @io_priority: the I/O priority of the request
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
  * Asynchronously requests an input stream to read the @clipboard's
- * contents from. When the operation is finished @callback will be called. 
- * You can then call gdk_clipboard_read_finish() to get the result of the 
- * operation.
+ * contents from.
+ *
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_finish] to get the result of the operation.
  *
  * The clipboard will choose the most suitable mime type from the given list
- * to fulfill the request, preferring the ones listed first. 
- **/
+ * to fulfill the request, preferring the ones listed first.
+ */
 void
 gdk_clipboard_read_async (GdkClipboard        *clipboard,
                           const char         **mime_types,
@@ -672,17 +674,18 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
  * @out_mime_type: (out) (allow-none) (transfer none): pointer to store
  *     the chosen mime type in or %NULL
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous clipboard read.
  *
- * Finishes an asynchronous clipboard read started with gdk_clipboard_read_async().
+ * See [method@Gdk.Clipboard.read_async].
  *
- * Returns: (transfer full) (nullable): a #GInputStream or %NULL on error.
- **/
+ * Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error.
+ */
 GInputStream *
 gdk_clipboard_read_finish (GdkClipboard  *clipboard,
                            GAsyncResult  *result,
@@ -827,23 +830,23 @@ gdk_clipboard_read_value_internal (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_value_async:
- * @clipboard: a #GdkClipboard
- * @type: a #GType to read
- * @io_priority: the [I/O priority][io-priority]
- *     of the request. 
+ * @clipboard: a `GdkClipboard`
+ * @type: a `GType` to read
+ * @io_priority: the I/O priority of the request
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
  * Asynchronously request the @clipboard contents converted to the given
- * @type. When the operation is finished @callback will be called. 
- * You can then call gdk_clipboard_read_value_finish() to get the resulting
- * #GValue.
+ * @type.
  *
- * For local clipboard contents that are available in the given #GType, the
- * value will be copied directly. Otherwise, GDK will try to use
- * gdk_content_deserialize_async() to convert the clipboard's data.
- **/
+ * When the operation is finished @callback will be called. You must then call
+ * [method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`.
+ *
+ * For local clipboard contents that are available in the given `GType`,
+ * the value will be copied directly. Otherwise, GDK will try to use
+ * [func@content_deserialize_async] to convert the clipboard's data.
+ */
 void
 gdk_clipboard_read_value_async (GdkClipboard        *clipboard,
                                 GType                type,
@@ -867,16 +870,16 @@ gdk_clipboard_read_value_async (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_value_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a GError` location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous clipboard read.
  *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_value_async().
+ * See [method@Gdk.Clipboard.read_value_async].
  *
- * Returns: (transfer none): a #GValue containing the result.
- **/
+ * Returns: (transfer none): a `GValue` containing the result.
+ */
 const GValue *
 gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,
                                  GAsyncResult  *result,
@@ -891,19 +894,20 @@ gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,
 
 /**
  * gdk_clipboard_read_texture_async:
- * @clipboard: a #GdkClipboard
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
- * Asynchronously request the @clipboard contents converted to a #GdkPixbuf.
- * When the operation is finished @callback will be called. You can then
- * call gdk_clipboard_read_texture_finish() to get the result.
+ * Asynchronously request the @clipboard contents converted to a `GdkPixbuf`.
+ *
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_texture_finish] to get the result.
  *
- * This is a simple wrapper around gdk_clipboard_read_value_async(). Use
- * that function or gdk_clipboard_read_async() directly if you need more
- * control over the operation.
- **/
+ * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
+ * Use that function or [methos@Gdk.Clipboard.read_async] directly if you
+ * need more control over the operation.
+ */
 void
 gdk_clipboard_read_texture_async (GdkClipboard        *clipboard,
                                   GCancellable        *cancellable,
@@ -925,16 +929,16 @@ gdk_clipboard_read_texture_async (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_texture_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous clipboard read.
  *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_texture_async().
+ * See [method@Gdk.Clipboard.read_texture_async].
  *
- * Returns: (transfer full) (nullable): a new #GdkTexture or %NULL on error.
- **/
+ * Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
+ */
 GdkTexture *
 gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
                                    GAsyncResult  *result,
@@ -955,19 +959,20 @@ gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
 
 /**
  * gdk_clipboard_read_text_async:
- * @clipboard: a #GdkClipboard
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
  * Asynchronously request the @clipboard contents converted to a string.
- * When the operation is finished @callback will be called. You can then
- * call gdk_clipboard_read_text_finish() to get the result.
  *
- * This is a simple wrapper around gdk_clipboard_read_value_async(). Use
- * that function or gdk_clipboard_read_async() directly if you need more
- * control over the operation.
- **/
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_text_finish] to get the result.
+ *
+ * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
+ * Use that function or [method@Gdk.Clipboard.read_async] directly if you
+ * need more control over the operation.
+ */
 void
 gdk_clipboard_read_text_async (GdkClipboard        *clipboard,
                                GCancellable        *cancellable,
@@ -989,16 +994,16 @@ gdk_clipboard_read_text_async (GdkClipboard        *clipboard,
 
 /**
  * gdk_clipboard_read_text_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_text_async().
+ * Finishes an asynchronous clipboard read.
  *
- * Returns: (transfer full) (nullable): a new string or %NULL on error.
- **/
+ * See [method@Gdk.Clipboard.read_text_async].
+ *
+ * Returns: (transfer full) (nullable): a new string or %NULL on error
+ */
 char *
 gdk_clipboard_read_text_finish (GdkClipboard  *clipboard,
                                 GAsyncResult  *result,
@@ -1188,13 +1193,14 @@ gdk_clipboard_claim_remote (GdkClipboard      *clipboard,
 
 /**
  * gdk_clipboard_set_content:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  * @provider: (transfer none) (allow-none): the new contents of @clipboard or
  *     %NULL to clear the clipboard
  *
- * Sets a new content provider on @clipboard. The clipboard will claim the
- * #GdkDisplay's resources and advertise these new contents to other
- * applications.
+ * Sets a new content provider on @clipboard.
+ *
+ * The clipboard will claim the `GdkDisplay`'s resources and advertise
+ * these new contents to other applications.
  *
  * In the rare case of a failure, this function will return %FALSE. The
  * clipboard will then continue reporting its old contents and ignore
@@ -1205,7 +1211,7 @@ gdk_clipboard_claim_remote (GdkClipboard      *clipboard,
  * transfer the contents and then request that format from @provider.
  *
  * Returns: %TRUE if setting the clipboard succeeded
- **/
+ */
 gboolean
 gdk_clipboard_set_content (GdkClipboard       *clipboard,
                            GdkContentProvider *provider)
@@ -1242,16 +1248,19 @@ gdk_clipboard_set_content (GdkClipboard       *clipboard,
 
 /**
  * gdk_clipboard_set:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  * @type: type of value to set
  * @...: value contents conforming to @type
  *
- * Sets the clipboard to contain the value collected from the given
- * varargs.
- **/
+ * Sets the clipboard to contain the value collected from the given varargs.
+ *
+ * ```c
+ * gdk_clipboard_set (clipboard, GTK_TYPE_TEXT_BUFFER, buffer);
+ * ```
+ */
 void
-gdk_clipboard_set (GdkClipboard          *clipboard,
-                   GType                  type,
+gdk_clipboard_set (GdkClipboard *clipboard,
+                   GType         type,
                    ...)
 {
   va_list args;
@@ -1265,13 +1274,12 @@ gdk_clipboard_set (GdkClipboard          *clipboard,
 
 /**
  * gdk_clipboard_set_valist: (skip)
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  * @type: type of value to set
  * @args: varargs containing the value of @type
  *
- * Sets the clipboard to contain the value collected from the given
- * @args.
- **/
+ * Sets the clipboard to contain the value collected from the given @args.
+ */
 void
 gdk_clipboard_set_valist (GdkClipboard *clipboard,
                           GType         type,
@@ -1301,11 +1309,11 @@ gdk_clipboard_set_valist (GdkClipboard *clipboard,
 
 /**
  * gdk_clipboard_set_value: (rename-to gdk_clipboard_set)
- * @clipboard: a #GdkClipboard
- * @value: a #GValue to set
+ * @clipboard: a `GdkClipboard`
+ * @value: a `GValue` to set
  *
  * Sets the @clipboard to contain the given @value.
- **/
+ */
 void
 gdk_clipboard_set_value (GdkClipboard *clipboard,
                          const GValue *value)
@@ -1323,11 +1331,11 @@ gdk_clipboard_set_value (GdkClipboard *clipboard,
 
 /**
  * gdk_clipboard_set_text: (skip)
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
  * @text: Text to put into the clipboard
  *
  * Puts the given @text into the clipboard.
- **/
+ */
 void
 gdk_clipboard_set_text (GdkClipboard *clipboard,
                         const char   *text)
@@ -1339,11 +1347,11 @@ gdk_clipboard_set_text (GdkClipboard *clipboard,
 
 /**
  * gdk_clipboard_set_texture: (skip)
- * @clipboard: a #GdkClipboard
- * @texture: a #GdkTexture to put into the clipboard
+ * @clipboard: a `GdkClipboard`
+ * @texture: a `GdkTexture` to put into the clipboard
  *
  * Puts the given @texture into the clipboard.
- **/
+ */
 void
 gdk_clipboard_set_texture (GdkClipboard *clipboard,
                            GdkTexture   *texture)
@@ -1353,4 +1361,3 @@ gdk_clipboard_set_texture (GdkClipboard *clipboard,
 
   gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, texture);
 }
-
diff --git a/gdk/gdkcontentdeserializer.c b/gdk/gdkcontentdeserializer.c
index a61f933273..42f77c0078 100644
--- a/gdk/gdkcontentdeserializer.c
+++ b/gdk/gdkcontentdeserializer.c
@@ -30,13 +30,19 @@
 
 
 /**
- * SECTION:gdkcontentdeserializer
- * @Short_description: Deserialize content for transfer
- * @Title: GdkContentDeserializer
- * @See_also: #GdkContentSerializer
+ * GdkContentDeserializer:
  *
- * A GdkContentDeserializer is used to deserialize content received via
+ * A `GdkContentDeserializer` is used to deserialize content received via
  * inter-application data transfers.
+ *
+ * The `GdkContentDeserializer` transforms serialized content that is
+ * identified by a mime type into an object identified by a GType.
+ *
+ * GTK provides serializers and deserializers for common data types
+ * such as text, colors, images or file lists. To register your own
+ * deserialization functions, use [func@content_register_deserializer].
+ *
+ * Also see [class@Gdk.ContentSerializer].
  */
 
 typedef struct _Deserializer Deserializer;
@@ -166,7 +172,7 @@ gdk_content_deserializer_run (const char                *mime_type,
 
 /**
  * gdk_content_deserializer_get_mime_type:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
  * Gets the mime type to deserialize from.
  *
@@ -182,7 +188,7 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_gtype:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
  * Gets the GType to create an instance of.
  *
@@ -198,11 +204,11 @@ gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_value:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
- * Gets the #GValue to store the deserialized object in.
+ * Gets the `GValue` to store the deserialized object in.
  *
- * Returns: (transfer none): the #GValue for the current operation
+ * Returns: (transfer none): the `GValue` for the current operation
  */
 GValue *
 gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
@@ -214,9 +220,11 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_input_stream:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
- * Gets the input stream that was passed to gdk_content_deserialize_async().
+ * Gets the input stream for the current operation.
+ *
+ * This is the stream that was passed to [func@content_deserialize_async].
  *
  * Returns: (transfer none): the input stream for the current operation
  */
@@ -230,11 +238,13 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_priority:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
+ *
+ * Gets the I/O priority for the current operation.
  *
- * Gets the io priority that was passed to gdk_content_deserialize_async().
+ * This is the priority that was passed to [funccontent_deserialize_async].
  *
- * Returns: the io priority for the current operation
+ * Returns: the I/O priority for the current operation
  */
 int
 gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
@@ -246,9 +256,11 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_cancellable:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
+ *
+ * Gets the cancellable for the current operation.
  *
- * Gets the cancellable that was passed to gdk_content_deserialize_async().
+ * This is the `GCancellable` that was passed to [func@content_deserialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -262,7 +274,7 @@ gdk_content_deserializer_get_cancellable (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_get_user_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
  * Gets the user data that was passed when the deserializer was registered.
  *
@@ -278,7 +290,7 @@ gdk_content_deserializer_get_user_data (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_set_task_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  * @data: data to associate with this operation
  * @notify: destroy notify for @data
  *
@@ -300,9 +312,11 @@ gdk_content_deserializer_set_task_data (GdkContentDeserializer *deserializer,
 
 /**
  * gdk_content_deserializer_get_task_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
- * Gets the data that was associated with @deserializer via gdk_content_deserializer_set_task_data().
+ * Gets the data that was associated with the current operation.
+ *
+ * See [method@Gdk.ContentDeserializer.set_task_data].
  *
  * Returns: (transfer none): the task data for @deserializer
  */
@@ -329,7 +343,7 @@ gdk_content_deserializer_emit_callback (gpointer data)
 
 /**
  * gdk_content_deserializer_return_success:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
  * Indicate that the deserialization has been successfully completed.
  */
@@ -349,10 +363,11 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserializer_return_error:
- * @deserializer: a #GdkContentDeserializer
- * @error: a #GError
+ * @deserializer: a `GdkContentDeserializer`
+ * @error: a `GError`
  *
  * Indicate that the deserialization has ended with an error.
+ *
  * This function consumes @error.
  */
 void
@@ -376,8 +391,7 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,
  * @data: data that @deserialize can access
  * @notify: destroy notify for @data
  *
- * Registers a function to create objects of a given @type from
- * a serialized representation with the given mime type.
+ * Registers a function to deserialize object of a given type.
  */
 void
 gdk_content_register_deserializer (const char                *mime_type,
@@ -424,18 +438,18 @@ lookup_deserializer (const char *mime_type,
           deserializer->type == type)
         return deserializer;
     }
-  
+
   return NULL;
 }
 
 /**
  * gdk_content_formats_union_deserialize_gtypes:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
  *
  * Add GTypes for mime types in @formats for which deserializers are
  * registered.
  *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
  */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
@@ -465,12 +479,12 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
 
 /**
  * gdk_content_formats_union_deserialize_mime_types:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
  *
  * Add mime types for GTypes in @formats for which deserializers are
  * registered.
  *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
  */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats)
@@ -511,17 +525,21 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
 
 /**
  * gdk_content_deserialize_async:
- * @stream: a #GInputStream to read the serialized content from
+ * @stream: a `GInputStream` to read the serialized content from
  * @mime_type: the mime type to deserialize from
  * @type: the GType to deserialize from
- * @io_priority: the io priority of the operation
- * @cancellable: (nullable): optional #GCancellable object
+ * @io_priority: the I/O priority of the operation
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the operation is done
  * @user_data: (closure): data to pass to the callback function
  *
  * Read content from the given input stream and deserialize it, asynchronously.
- * When the operation is finished, @callback will be called. You can then
- * call gdk_content_deserialize_finish() to get the result of the operation.
+ *
+ * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
+ * indicate a higher priority.
+ *
+ * When the operation is finished, @callback will be called. You must then
+ * call [func@content_deserialize_finish] to get the result of the operation.
  */
 void
 gdk_content_deserialize_async (GInputStream        *stream,
@@ -553,14 +571,15 @@ gdk_content_deserialize_async (GInputStream        *stream,
 
 /**
  * gdk_content_deserialize_finish:
- * @result: the #GAsyncResult
+ * @result: the `GAsyncResult`
  * @value: return location for the result of the operation
  * @error: return location for an error
  *
  * Finishes a content deserialization operation.
  *
- * Returns: %TRUE if the operation was successful. In this case, @value is set.
- *          %FALSE if an error occurred. In this case, @error is set
+ * Returns: %TRUE if the operation was successful. In this case,
+ *   @value is set. %FALSE if an error occurred. In this case,
+ *   @error is set
  */
 gboolean
 gdk_content_deserialize_finish (GAsyncResult  *result,
diff --git a/gdk/gdkcontentdeserializer.h b/gdk/gdkcontentdeserializer.h
index 2b3fda4d81..4ff7028424 100644
--- a/gdk/gdkcontentdeserializer.h
+++ b/gdk/gdkcontentdeserializer.h
@@ -32,11 +32,6 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_DESERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), 
GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer))
 #define GDK_IS_CONTENT_DESERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), 
GDK_TYPE_CONTENT_DESERIALIZER))
 
-/**
- * GdkContentDeserializer:
- *
- * Should not be accessed directly.
- */
 typedef struct _GdkContentDeserializer GdkContentDeserializer;
 
 /**
@@ -44,6 +39,7 @@ typedef struct _GdkContentDeserializer GdkContentDeserializer;
  * @deserializer: a #GdkContentDeserializer
  *
  * The type of a function that can be registered with gdk_content_register_deserializer().
+ *
  * When the function gets called to operate on content, it can call functions on the
  * @deserializer object to obtain the mime type, input stream, user data, etc. for its
  * operation.
diff --git a/gdk/gdkcontentformats.c b/gdk/gdkcontentformats.c
index 005d387b7c..d8e590e14f 100644
--- a/gdk/gdkcontentformats.c
+++ b/gdk/gdkcontentformats.c
@@ -16,46 +16,40 @@
  */
 
 /**
- * SECTION:gdkcontentformats
- * @Title: Content Formats
- * @Short_description: Advertising and negotiating of content
- *     exchange formats
- * @See_also: #GdkDrag, #GdkDrop, #GdkClipboard, #GdkContentProvider
- *
- * This section describes the #GdkContentFormats structure that is used to
- * advertise and negotiate the format of content passed between different
- * widgets, windows or applications using for example the clipboard or
- * drag'n'drop.
- *
- * GDK supports content in 2 forms: #GType and mime type.
- * Using #GTypes is meant only for in-process content transfers. Mime types
+ * GdkContentFormats:
+ *
+ * The `GdkContentFormats` structure is used to advertise and negotiate the
+ * format of content.
+ *
+ * You will encounter `GdkContentFormats` when interacting with objects
+ * controlling operations that pass data between different widgets, window
+ * or application, like [class Gdk Drag], [class Gdk Drop],
+ * [class@Gdk.Clipboard] or [class@Gdk.ContentProvider].
+ *
+ * GDK supports content in 2 forms: `GType` and mime type.
+ * Using `GTypes` is meant only for in-process content transfers. Mime types
  * are meant to be used for data passing both in-process and out-of-process.
  * The details of how data is passed is described in the documentation of
- * the actual implementations.
+ * the actual implementations. To transform between the two forms,
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used.
  *
- * A #GdkContentFormats describes a set of possible formats content can be
- * exchanged in. It is assumed that this set is ordered. #GTypes are more
- * important than mime types. Order between different #GTypes or mime types
+ * A `GdkContentFormats` describes a set of possible formats content can be
+ * exchanged in. It is assumed that this set is ordered. `GTypes` are more
+ * important than mime types. Order between different `GTypes` or mime types
  * is the order they were added in, most important first. Functions that
- * care about order, such as gdk_content_formats_union() will describe in
- * their documentation how they interpret that order, though in general the
+ * care about order, such as [method@Gdk.ContentFormats.union], will describe
+ * in their documentation how they interpret that order, though in general the
  * order of the first argument is considered the primary order of the result,
  * followed by the order of further arguments.
  *
- * For debugging purposes, the function gdk_content_formats_to_string() exists.
- * It will print a comma-seperated formats of formats from most important to least
- * important.
- *
- * #GdkContentFormats is an immutable struct. After creation, you cannot change
- * the types it represents. Instead, new #GdkContentFormats have to be created.
- * The #GdkContentFormatsBuilder structure is meant to help in this endeavor.
- */
-
-/**
- * GdkContentFormats:
+ * For debugging purposes, the function [method@Gdk.ContentFormats.to_string]
+ * exists. It will print a comma-separated list of formats from most important
+ * to least important.
  *
- * A #GdkContentFormats struct is a reference counted struct
- * and should be treated as opaque.
+ * `GdkContentFormats` is an immutable struct. After creation, you cannot change
+ * the types it represents. Instead, new `GdkContentFormats` have to be created.
+ * The [struct@Gdk.ContentFormatsBuilder]` structure is meant to help in this
+ * endeavor.
  */
 
 #include "config.h"
@@ -92,7 +86,7 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
  *
  * Returns: An interned string for the canonicalized mime type
  *     or %NULL if the string wasn't a valid mime type
- **/
+ */
 const char *
 gdk_intern_mime_type (const char *string)
 {
@@ -134,15 +128,15 @@ gdk_content_formats_new_take (GType *      gtypes,
  * @mime_types: (array length=n_mime_types) (allow-none): Pointer to an
  *   array of mime types
  * @n_mime_types: number of entries in @mime_types.
- * 
- * Creates a new #GdkContentFormats from an array of mime types.
+ *
+ * Creates a new `GdkContentFormats` from an array of mime types.
  *
  * The mime types must be valid and different from each other or the
  * behavior of the return value is undefined. If you cannot guarantee
- * this, use #GdkContentFormatsBuilder instead.
- * 
- * Returns: (transfer full): the new #GdkContentFormats.
- **/
+ * this, use `GdkContentFormatsBuilder` instead.
+ *
+ * Returns: (transfer full): the new `GdkContentFormats`.
+ */
 GdkContentFormats *
 gdk_content_formats_new (const char **mime_types,
                          guint        n_mime_types)
@@ -165,12 +159,12 @@ gdk_content_formats_new (const char **mime_types,
 
 /**
  * gdk_content_formats_new_for_gtype:
- * @type: a $GType
+ * @type: a `GType`
  *
- * Creates a new #GdkContentFormats for a given #GType.
+ * Creates a new `GdkContentFormats` for a given `GType`.
  *
- * Returns: a new #GdkContentFormats
- **/
+ * Returns: a new `GdkContentFormats`
+ */
 GdkContentFormats *
 gdk_content_formats_new_for_gtype (GType type)
 {
@@ -187,12 +181,12 @@ gdk_content_formats_new_for_gtype (GType type)
 
 /**
  * gdk_content_formats_ref:
- * @formats:  a #GdkContentFormats
- * 
- * Increases the reference count of a #GdkContentFormats by one.
+ * @formats:  a `GdkContentFormats`
  *
- * Returns: the passed in #GdkContentFormats.
- **/
+ * Increases the reference count of a `GdkContentFormats` by one.
+ *
+ * Returns: the passed in `GdkContentFormats`.
+ */
 GdkContentFormats *
 gdk_content_formats_ref (GdkContentFormats *formats)
 {
@@ -205,12 +199,13 @@ gdk_content_formats_ref (GdkContentFormats *formats)
 
 /**
  * gdk_content_formats_unref:
- * @formats: a #GdkContentFormats
- * 
- * Decreases the reference count of a #GdkContentFormats by one.
+ * @formats: a `GdkContentFormats`
+ *
+ * Decreases the reference count of a `GdkContentFormats` by one.
+ *
  * If the resulting reference count is zero, frees the formats.
- **/
-void               
+ */
+void
 gdk_content_formats_unref (GdkContentFormats *formats)
 {
   g_return_if_fail (formats != NULL);
@@ -227,15 +222,16 @@ gdk_content_formats_unref (GdkContentFormats *formats)
 
 /**
  * gdk_content_formats_print:
- * @formats: a #GdkContentFormats
- * @string: a #GString to print into
+ * @formats: a `GdkContentFormats`
+ * @string: a `GString` to print into
  *
  * Prints the given @formats into a string for human consumption.
+ *
  * This is meant for debugging and logging.
  *
  * The form of the representation may change at any time and is
  * not guaranteed to stay identical.
- **/
+ */
 void
 gdk_content_formats_print (GdkContentFormats *formats,
                            GString           *string)
@@ -263,14 +259,15 @@ gdk_content_formats_print (GdkContentFormats *formats,
 
 /**
  * gdk_content_formats_to_string:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
  *
  * Prints the given @formats into a human-readable string.
- * This is a small wrapper around gdk_content_formats_print() to help
- * when debugging.
+ *
+ * This is a small wrapper around [method@Gdk.ContentFormats.print]
+ * to help when debugging.
  *
  * Returns: (transfer full): a new string
- **/
+ */
 char *
 gdk_content_formats_to_string (GdkContentFormats *formats)
 {
@@ -286,13 +283,13 @@ gdk_content_formats_to_string (GdkContentFormats *formats)
 
 /**
  * gdk_content_formats_union:
- * @first: (transfer full): the #GdkContentFormats to merge into
- * @second: (transfer none): the #GdkContentFormats to merge from
+ * @first: (transfer full): the `GdkContentFormats` to merge into
+ * @second: (transfer none): the `GdkContentFormats` to merge from
  *
  * Append all missing types from @second to @first, in the order
  * they had in @second.
  *
- * Returns: a new #GdkContentFormats
+ * Returns: a new `GdkContentFormats`
  */
 GdkContentFormats *
 gdk_content_formats_union (GdkContentFormats       *first,
@@ -329,8 +326,8 @@ gdk_content_formats_contain_interned_mime_type (const GdkContentFormats *formats
 
 /**
  * gdk_content_formats_match:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
  *
  * Checks if @first and @second have any matching formats.
  *
@@ -349,15 +346,16 @@ gdk_content_formats_match (const GdkContentFormats *first,
 
 /**
  * gdk_content_formats_match_gtype:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
  *
- * Finds the first #GType from @first that is also contained
- * in @second. If no matching #GType is found, %G_TYPE_INVALID
- * is returned.
+ * Finds the first `GType` from @first that is also contained
+ * in @second.
  *
- * Returns: The first common #GType or %G_TYPE_INVALID if none.
- **/
+ * If no matching `GType` is found, %G_TYPE_INVALID is returned.
+ *
+ * Returns: The first common `GType` or %G_TYPE_INVALID if none.
+ */
 GType
 gdk_content_formats_match_gtype (const GdkContentFormats *first,
                                  const GdkContentFormats *second)
@@ -378,15 +376,16 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first,
 
 /**
  * gdk_content_formats_match_mime_type:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
  *
  * Finds the first mime type from @first that is also contained
- * in @second. If no matching mime type is found, %NULL is
- * returned.
+ * in @second.
+ *
+ * If no matching mime type is found, %NULL is returned.
  *
  * Returns: (nullable): The first common mime type or %NULL if none.
- **/
+ */
 const char *
 gdk_content_formats_match_mime_type (const GdkContentFormats *first,
                                      const GdkContentFormats *second)
@@ -407,13 +406,13 @@ gdk_content_formats_match_mime_type (const GdkContentFormats *first,
 
 /**
  * gdk_content_formats_contain_gtype:
- * @formats: a #GdkContentFormats
- * @type: the #GType to search for
+ * @formats: a `GdkContentFormats`
+ * @type: the `GType` to search for
  *
- * Checks if a given #GType is part of the given @formats.
+ * Checks if a given `GType` is part of the given @formats.
  *
  * Returns: %TRUE if the #GType was found
- **/
+ */
 gboolean
 gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
                                    GType                    type)
@@ -433,13 +432,13 @@ gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
 
 /**
  * gdk_content_formats_contain_mime_type:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
  * @mime_type: the mime type to search for
  *
  * Checks if a given mime type is part of the given @formats.
  *
  * Returns: %TRUE if the mime_type was found
- **/
+ */
 gboolean
 gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
                                        const char              *mime_type)
@@ -453,18 +452,19 @@ gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
 
 /**
  * gdk_content_formats_get_gtypes:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
  * @n_gtypes: (out) (optional): optional pointer to take the
  *     number of #GTypes contained in the return value
  *
- * Gets the #GTypes included in @formats. Note that @formats may not
- * contain any #GTypes, in particular when they are empty. In that
- * case %NULL will be returned. 
+ * Gets the `GTypes` included in @formats.
+ *
+ * Note that @formats may not contain any #GTypes, in particular when
+ * they are empty. In that case %NULL will be returned.
  *
  * Returns: (transfer none) (nullable) (array length=n_gtypes):
  *      %G_TYPE_INVALID-terminated array of types included in @formats or
  *      %NULL if none.
- **/
+ */
 const GType *
 gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
                                 gsize                   *n_gtypes)
@@ -479,18 +479,19 @@ gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
 
 /**
  * gdk_content_formats_get_mime_types:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
  * @n_mime_types: (out) (allow-none): optional pointer to take the
  *     number of mime types contained in the return value
  *
- * Gets the mime types included in @formats. Note that @formats may not
- * contain any mime types, in particular when they are empty. In that
- * case %NULL will be returned. 
+ * Gets the mime types included in @formats.
+ *
+ * Note that @formats may not contain any mime types, in particular
+ * when they are empty. In that case %NULL will be returned.
  *
- * Returns: (transfer none) (nullable): %NULL-terminated array of 
+ * Returns: (transfer none) (nullable): %NULL-terminated array of
  *     interned strings of mime types included in @formats or %NULL
  *     if none.
- **/
+ */
 const char * const *
 gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
                                     gsize                   *n_mime_types)
@@ -506,9 +507,8 @@ gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
 /**
  * GdkContentFormatsBuilder:
  *
- * A #GdkContentFormatsBuilder struct is an opaque struct. It is meant to
- * not be kept around and only be used to create new #GdkContentFormats
- * objects.
+ * A `GdkContentFormatsBuilder` is an auxiliary struct used to create
+ * new `GdkContentFormats`, and should not be kept around.
  */
 
 struct _GdkContentFormatsBuilder
@@ -532,12 +532,13 @@ G_DEFINE_BOXED_TYPE (GdkContentFormatsBuilder,
 /**
  * gdk_content_formats_builder_new:
  *
- * Create a new #GdkContentFormatsBuilder object. The resulting builder
- * would create an empty #GdkContentFormats. Use addition functions to add
- * types to it.
+ * Create a new `GdkContentFormatsBuilder` object.
  *
- * Returns: a new #GdkContentFormatsBuilder
- **/
+ * The resulting builder would create an empty `GdkContentFormats`.
+ * Use addition functions to add types to it.
+ *
+ * Returns: a new `GdkContentFormatsBuilder`
+ */
 GdkContentFormatsBuilder *
 gdk_content_formats_builder_new (void)
 {
@@ -551,15 +552,15 @@ gdk_content_formats_builder_new (void)
 
 /**
  * gdk_content_formats_builder_ref:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
  *
  * Acquires a reference on the given @builder.
  *
- * This function is intended primarily for bindings. #GdkContentFormatsBuilder objects
- * should not be kept around.
+ * This function is intended primarily for bindings.
+ * `GdkContentFormatsBuilder` objects should not be kept around.
  *
- * Returns: (transfer none): the given #GdkContentFormatsBuilder with
- *   its reference count increased
+ * Returns: (transfer none): the given `GdkContentFormatsBuilder`
+ *   with its reference count increased
  */
 GdkContentFormatsBuilder *
 gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder)
@@ -581,7 +582,7 @@ gdk_content_formats_builder_clear (GdkContentFormatsBuilder *builder)
 
 /**
  * gdk_content_formats_builder_unref:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
  *
  * Releases a reference on the given @builder.
  */
@@ -602,12 +603,12 @@ gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder)
 
 /**
  * gdk_content_formats_builder_free_to_formats: (skip)
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
  *
- * Creates a new #GdkContentFormats from the current state of the
+ * Creates a new `GdkContentFormats` from the current state of the
  * given @builder, and frees the @builder instance.
  *
- * Returns: (transfer full): the newly created #GdkContentFormats
+ * Returns: (transfer full): the newly created `GdkContentFormats`
  *   with all the formats added to @builder
  */
 GdkContentFormats *
@@ -626,17 +627,17 @@ gdk_content_formats_builder_free_to_formats (GdkContentFormatsBuilder *builder)
 
 /**
  * gdk_content_formats_builder_to_formats:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormats`Builder
  *
- * Creates a new #GdkContentFormats from the given @builder.
+ * Creates a new `GdkContentFormats` from the given @builder.
  *
- * The given #GdkContentFormatsBuilder is reset once this function returns;
+ * The given `GdkContentFormatsBuilder` is reset once this function returns;
  * you cannot call this function multiple times on the same @builder instance.
  *
  * This function is intended primarily for bindings. C code should use
- * gdk_content_formats_builder_free_to_formats().
+ * [method@Gdk.ContentFormatsBuilder.free_to_formats].
  *
- * Returns: (transfer full): the newly created #GdkContentFormats
+ * Returns: (transfer full): the newly created `GdkContentFormats`
  *   with all the formats added to @builder
  */
 GdkContentFormats *
@@ -674,12 +675,12 @@ gdk_content_formats_builder_to_formats (GdkContentFormatsBuilder *builder)
 
 /**
  * gdk_content_formats_builder_add_formats:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
  * @formats: the formats to add
  *
  * Appends all formats from @formats to @builder, skipping those that
  * already exist.
- **/
+ */
 void
 gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,
                                          const GdkContentFormats  *formats)
@@ -698,10 +699,10 @@ gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,
 
 /**
  * gdk_content_formats_builder_add_gtype:
- * @builder: a #GdkContentFormatsBuilder
- * @type: a #GType
+ * @builder: a `GdkContentFormats`Builder
+ * @type: a `GType`
  *
- * Appends @gtype to @builder if it has not already been added.
+ * Appends @type to @builder if it has not already been added.
  **/
 void
 gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
@@ -719,11 +720,11 @@ gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
 
 /**
  * gdk_content_formats_builder_add_mime_type:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
  * @mime_type: a mime type
  *
  * Appends @mime_type to @builder if it has not already been added.
- **/
+ */
 void
 gdk_content_formats_builder_add_mime_type (GdkContentFormatsBuilder *builder,
                                            const char               *mime_type)
diff --git a/gdk/gdkcontentprovider.c b/gdk/gdkcontentprovider.c
index 4253ea4203..5e7b2f8818 100644
--- a/gdk/gdkcontentprovider.c
+++ b/gdk/gdkcontentprovider.c
@@ -25,20 +25,17 @@
 #include "gdkintl.h"
 
 /**
- * SECTION:gdkcontentprovider
- * @Short_description: Provides content for data transfer between applications
- * @Title: GdkContentProvider
- * @See_also: #GdkContentSerializer, #GdkContentDeserializer
+ * GdkContentProvider:
  *
- * A GdkContentProvider is used to provide content for the clipboard in
- * a number of formats.
+ * A `GdkContentProvider` is used to provide content for the clipboard or
+ * for drag-and-drop operations in a number of formats.
  *
- * To create a GdkContentProvider, use gdk_content_provider_new_for_value() or
- * gdk_content_provider_new_for_bytes().
+ * To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value]
+ * or [ctor@Gdk.ContentProvider.new_for_bytes].
  *
  * GDK knows how to handle common text and image formats out-of-the-box. See
- * #GdkContentSerializer and #GdkContentDeserializer if you want to add support
- * for application-specific data formats.
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want
+ * to add support for application-specific data formats.
  */
 
 typedef struct _GdkContentProviderPrivate GdkContentProviderPrivate;
@@ -226,7 +223,7 @@ gdk_content_provider_init (GdkContentProvider *provider)
  * Gets the formats that the provider can provide its current contents in.
  *
  * Returns: (transfer full): The formats of the provider
- **/
+ */
 GdkContentFormats *
 gdk_content_provider_ref_formats (GdkContentProvider *provider)
 {
@@ -240,13 +237,14 @@ gdk_content_provider_ref_formats (GdkContentProvider *provider)
  * @provider: a #GdkContentProvider
  *
  * Gets the formats that the provider suggests other applications to store
- * the data in.  
+ * the data in.
+ *
  * An example of such an application would be a clipboard manager.
  *
- * This can be assumed to be a subset of gdk_content_provider_ref_formats().
+ * This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].
  *
  * Returns: (transfer full): The storable formats of the provider
- **/
+ */
 GdkContentFormats *
 gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)
 {
@@ -257,9 +255,9 @@ gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)
 
 /**
  * gdk_content_provider_content_changed:
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
  *
- * Emits the #GdkContentProvider::content-changed signal.
+ * Emits the ::content-changed signal.
  */
 void
 gdk_content_provider_content_changed (GdkContentProvider *provider)
@@ -273,26 +271,27 @@ gdk_content_provider_content_changed (GdkContentProvider *provider)
 
 /**
  * gdk_content_provider_write_mime_type_async:
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
  * @mime_type: the mime type to provide the data in
- * @stream: the #GOutputStream to write to
- * @io_priority: the [I/O priority][io-priority]
- * of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @stream: the `GOutputStream` to write to
+ * @io_priority: I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
  * Asynchronously writes the contents of @provider to @stream in the given
- * @mime_type. When the operation is finished @callback will be called. You
- * can then call gdk_content_provider_write_mime_type_finish() to get the 
- * result of the operation.
+ * @mime_type.
+ *
+ * When the operation is finished @callback will be called. You must then call
+ * [method@Gdk.ContentProvider.write_mime_type_finish] to get the result
+ * of the operation.
  *
  * The given mime type does not need to be listed in the formats returned by
- * gdk_content_provider_ref_formats(). However, if the given #GType is not
- * supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
+ * [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is
+ * not supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
  *
  * The given @stream will not be closed.
- **/
+ */
 void
 gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,
                                             const char          *mime_type,
@@ -318,17 +317,17 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,
 
 /**
  * gdk_content_provider_write_mime_type_finish:
- * @provider: a #GdkContentProvider
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- *     ignore.
+ * @provider: a `GdkContentProvider`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous write operation.
  *
- * Finishes an asynchronous write operation started with
- * gdk_content_provider_write_mime_type_async().
+ * See [method@Gdk.ContentProvider.write_mime_type_async].
  *
  * Returns: %TRUE if the operation was completed successfully. Otherwise
  *     @error will be set to describe the failure.
- **/
+ */
 gboolean
 gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
                                              GAsyncResult        *result,
@@ -342,22 +341,21 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
 
 /**
  * gdk_content_provider_get_value:
- * @provider: a #GdkContentProvider
- * @value: the #GValue to fill
- * @error: a #GError location to store the error occurring, or %NULL to 
- *     ignore.
+ * @provider: a `GdkContentProvider`
+ * @value: the `GValue` to fill
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * Gets the contents of @provider stored in @value.
  *
- * The @value will have been initialized to the #GType the value should be
- * provided in. This given #GType does not need to be listed in the formats
- * returned by gdk_content_provider_ref_formats(). However, if the given
- * #GType is not supported, this operation can fail and
+ * The @value will have been initialized to the `GType` the value should be
+ * provided in. This given `GType` does not need to be listed in the formats
+ * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
+ * given `GType` is not supported, this operation can fail and
  * #G_IO_ERROR_NOT_SUPPORTED will be reported.
  *
  * Returns: %TRUE if the value was set successfully. Otherwise
  *     @error will be set to describe the failure.
- **/
+ */
 gboolean
 gdk_content_provider_get_value (GdkContentProvider  *provider,
                                 GValue              *value,
diff --git a/gdk/gdkcontentprovider.h b/gdk/gdkcontentprovider.h
index f1f558ab74..f4be04238e 100644
--- a/gdk/gdkcontentprovider.h
+++ b/gdk/gdkcontentprovider.h
@@ -38,12 +38,6 @@ G_BEGIN_DECLS
 
 typedef struct _GdkContentProviderClass GdkContentProviderClass;
 
-/**
- * GdkContentProvider:
- *
- * Should not be directly accessed.
- */
-
 struct _GdkContentProvider
 {
   GObject parent;
diff --git a/gdk/gdkcontentserializer.c b/gdk/gdkcontentserializer.c
index 7a3e4c3d22..cf8e7c88cf 100644
--- a/gdk/gdkcontentserializer.c
+++ b/gdk/gdkcontentserializer.c
@@ -32,13 +32,20 @@
 
 
 /**
- * SECTION:gdkcontentserializer
- * @Short_description: Serialize content for transfer
- * @Title: GdkContentSerializer
- * @See_also: #GdkContentDeserializer, #GdkContentProvider
+ * GdkContentSerializer:
  *
- * A GdkContentSerializer is used to serialize content for inter-application
- * data transfers.
+ * A `GdkContentSerializer` is used to serialize content for
+ * inter-application data transfers.
+ *
+ * The `GdkContentSerializer` transforms an object that is identified
+ * by a GType into a serialized form (i.e. a byte stream) that is
+ * identified by a mime type.
+ *
+ * GTK provides serializers and deserializers for common data types
+ * such as text, colors, images or file lists. To register your own
+ * serialization functions, use [func@content_register_serializer].
+ *
+ * Also see [class@Gdk.ContentDeserializer].
  */
 
 typedef struct _Serializer Serializer;
@@ -169,7 +176,7 @@ gdk_content_serializer_run (const char              *mime_type,
 
 /**
  * gdk_content_serializer_get_mime_type:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
  * Gets the mime type to serialize to.
  *
@@ -185,11 +192,11 @@ gdk_content_serializer_get_mime_type (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_gtype:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
- * Gets the GType to of the object to serialize.
+ * Gets the `GType` to of the object to serialize.
  *
- * Returns: the GType for the current operation
+ * Returns: the `GType` for the current operation
  */
 GType
 gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)
@@ -201,11 +208,11 @@ gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_value:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
- * Gets the #GValue to read the object to serialize from.
+ * Gets the `GValue` to read the object to serialize from.
  *
- * Returns: (transfer none): the #GValue for the current operation
+ * Returns: (transfer none): the `GValue` for the current operation
  */
 const GValue *
 gdk_content_serializer_get_value (GdkContentSerializer *serializer)
@@ -217,9 +224,11 @@ gdk_content_serializer_get_value (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_output_stream:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
- * Gets the output stream that was passed to gdk_content_serialize_async().
+ * Gets the output stream for the current operation.
+ *
+ * This is the stream that was passed to [func@content_serialize_async].
  *
  * Returns: (transfer none): the output stream for the current operation
  */
@@ -233,11 +242,13 @@ gdk_content_serializer_get_output_stream (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_priority:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
+ *
+ * Gets the I/O priority for the current operation.
  *
- * Gets the io priority that was passed to gdk_content_serialize_async().
+ * This is the priority that was passed to [func@content_serialize_async].
  *
- * Returns: the io priority for the current operation
+ * Returns: the I/O priority for the current operation
  */
 int
 gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
@@ -249,9 +260,11 @@ gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_cancellable:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
- * Gets the cancellable that was passed to gdk_content_serialize_async().
+ * Gets the cancellable for the current operation.
+ *
+ * This is the `GCancellable` that was passed to [content_serialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -265,7 +278,7 @@ gdk_content_serializer_get_cancellable (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_get_user_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
  * Gets the user data that was passed when the serializer was registered.
  *
@@ -281,7 +294,7 @@ gdk_content_serializer_get_user_data (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_set_task_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  * @data: data to associate with this operation
  * @notify: destroy notify for @data
  *
@@ -303,9 +316,11 @@ gdk_content_serializer_set_task_data (GdkContentSerializer   *serializer,
 
 /**
  * gdk_content_serializer_get_task_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
+ *
+ * Gets the data that was associated with the current operation.
  *
- * Gets the data that was associated with @serializer via gdk_content_serializer_set_task_data().
+ * See [method@Gdk.ContentSerializer.set_task_data].
  *
  * Returns: (transfer none): the task data for @serializer
  */
@@ -332,7 +347,7 @@ gdk_content_serializer_emit_callback (gpointer data)
 
 /**
  * gdk_content_serializer_return_success:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
  * Indicate that the serialization has been successfully completed.
  */
@@ -352,10 +367,11 @@ gdk_content_serializer_return_success (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serializer_return_error:
- * @serializer: a #GdkContentSerializer
- * @error: a #GError
+ * @serializer: a `GdkContentSerializer`
+ * @error: a `GError`
  *
  * Indicate that the serialization has ended with an error.
+ *
  * This function consumes @error.
  */
 void
@@ -379,8 +395,7 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer,
  * @data: data that @serialize can access
  * @notify: destroy notify for @data
  *
- * Registers a function to convert objects of the given @type to
- * a serialized representation with the given mime type.
+ * Registers a function to serialize objects of a given type.
  */
 void
 gdk_content_register_serializer (GType                    type,
@@ -433,12 +448,12 @@ lookup_serializer (const char *mime_type,
 
 /**
  * gdk_content_formats_union_serialize_gtypes:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
  *
  * Add GTypes for the mime types in @formats for which serializers are
  * registered.
  *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
  */
 GdkContentFormats *
 gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
@@ -468,12 +483,12 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
 
 /**
  * gdk_content_formats_union_serialize_mime_types:
- * @formats: (transfer full):  a #GdkContentFormats
+ * @formats: (transfer full):  a `GdkContentFormats`
  *
  * Add mime types for GTypes in @formats for which serializers are
  * registered.
  *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
  */
 GdkContentFormats *
 gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats)
@@ -514,17 +529,21 @@ serialize_not_found (GdkContentSerializer *serializer)
 
 /**
  * gdk_content_serialize_async:
- * @stream: a #GOutputStream to write the serialized content to
+ * @stream: a `GOutputStream` to write the serialized content to
  * @mime_type: the mime type to serialize to
  * @value: the content to serialize
- * @io_priority: the io priority of the operation
+ * @io_priority: the I/O priority of the operation
  * @cancellable: (nullable): optional #GCancellable object
  * @callback: (scope async): callback to call when the operation is done
  * @user_data: (closure): data to pass to the callback function
  *
  * Serialize content and write it to the given output stream, asynchronously.
- * When the operation is finished, @callback will be called. You can then
- * call gdk_content_serialize_finish() to get the result of the operation.
+ *
+ * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
+ * indicate a higher priority.
+ *
+ * When the operation is finished, @callback will be called. You must then
+ * call [func@content_serialize_finish] to get the result of the operation.
  */
 void
 gdk_content_serialize_async (GOutputStream       *stream,
@@ -556,7 +575,7 @@ gdk_content_serialize_async (GOutputStream       *stream,
 
 /**
  * gdk_content_serialize_finish:
- * @result: the #GAsyncResult
+ * @result: the `GAsyncResult`
  * @error: return location for an error
  *
  * Finishes a content serialization operation.
diff --git a/gdk/gdkcontentserializer.h b/gdk/gdkcontentserializer.h
index 82b4f909a7..17b5c7c36e 100644
--- a/gdk/gdkcontentserializer.h
+++ b/gdk/gdkcontentserializer.h
@@ -32,11 +32,6 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_SERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, 
GdkContentSerializer))
 #define GDK_IS_CONTENT_SERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER))
 
-/**
- * GdkContentSerializer:
- *
- * Should not be accessed directly.
- */
 typedef struct _GdkContentSerializer GdkContentSerializer;
 
 /**
@@ -44,6 +39,7 @@ typedef struct _GdkContentSerializer GdkContentSerializer;
  * @serializer: a #GdkContentSerializer
  *
  * The type of a function that can be registered with gdk_content_register_serializer().
+ *
  * When the function gets called to operate on content, it can call functions on the
  * @serializer object to obtain the mime type, output stream, user data, etc. for its
  * operation.
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index ebb87c5c7b..700f458573 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -37,19 +37,19 @@
 #include <errno.h>
 
 /**
- * SECTION:gdkcursor
- * @Short_description: Named and texture cursors
- * @Title: Cursors
+ * GdkCursor:
+ *
+ * `GdkCursor` is used to create and destroy cursors.
  *
- * `GdkCursor` is used to create and destroy cursors. Cursors are immutable
- * objects, so once you created them, there is no way to modify them later.
- * You should create a new cursor when you want to change something about
- * it.
+ * Cursors are immutable objects, so once you created them, there is no way
+ * to modify them later. You should create a new cursor when you want to change
+ * something about it.
  *
  * Cursors by themselves are not very interesting: they must be bound to a
  * window for users to see them. This is done with [method@Gdk.Surface.set_cursor]
  * or [method@Gdk.Surface.set_device_cursor]. Applications will typically
- * use higher-level GTK functions such as `gtk_widget_set_cursor()` instead.
+ * use higher-level GTK functions such as [method@Gtk.Widget.set_cursor]`
+ * instead.
  *
  * Cursors are not bound to a given [class@Gdk.Display], so they can be shared.
  * However, the appearance of cursors may vary when used on different
@@ -68,20 +68,11 @@
  * and provide an image to use for the cursor.
  *
  * To ease work with unsupported cursors, a fallback cursor can be provided.
- * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above,
- * it will try the fallback cursor. Fallback cursors can themselves have fallback
- * cursors again, so it is possible to provide a chain of progressively easier
- * to support cursors. If none of the provided cursors can be supported, the
- * default cursor will be the ultimate fallback.
- */
-
-/**
- * GdkCursor:
- *
- * A #GdkCursor represents a cursor. Its contents are private.
- *
- * Cursors are immutable objects, so they can not change after
- * they have been constructed.
+ * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned
+ * above, it will try the fallback cursor. Fallback cursors can themselves have
+ * fallback cursors again, so it is possible to provide a chain of progressively
+ * easier to support cursors. If none of the provided cursors can be supported,
+ * the default cursor will be the ultimate fallback.
  */
 
 enum {
@@ -178,6 +169,11 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
   object_class->set_property = gdk_cursor_set_property;
   object_class->finalize = gdk_cursor_finalize;
 
+  /**
+   * GdkCursor:fallback:
+   *
+   * Cursor to fall back to if this cursor cannot be displayed.
+   */
   g_object_class_install_property (object_class,
                                    PROP_FALLBACK,
                                    g_param_spec_object ("fallback",
@@ -186,6 +182,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                         GDK_TYPE_CURSOR,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                         G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:hotspot-x:
+   *
+   * X position of the cursor hotspot in the cursor image.
+   */
   g_object_class_install_property (object_class,
                                    PROP_HOTSPOT_X,
                                    g_param_spec_int ("hotspot-x",
@@ -194,6 +196,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                      0, G_MAXINT, 0,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                      G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:hotspot-y:
+   *
+   * Y position of the cursor hotspot in the cursor image.
+   */
   g_object_class_install_property (object_class,
                                    PROP_HOTSPOT_Y,
                                    g_param_spec_int ("hotspot-y",
@@ -202,6 +210,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                      0, G_MAXINT, 0,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                      G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:name:
+   *
+   * Name of this this cursor.
+   *
+   * The name will be %NULL if the cursor was created from a texture.
+   */
   g_object_class_install_property (object_class,
                                    PROP_NAME,
                                    g_param_spec_string ("name",
@@ -210,6 +226,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                         NULL,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                         G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:texture:
+   *
+   * The texture displayed by this cursor.
+   *
+   * The texture will be %NULL if the cursor was created from a name.
+   */
   g_object_class_install_property (object_class,
                                    PROP_TEXTURE,
                                    g_param_spec_object ("texture",
@@ -274,7 +298,7 @@ gdk_cursor_equal (gconstpointer a,
 /**
  * gdk_cursor_new_from_name:
  * @name: the name of the cursor
- * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
+ * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
  *     this one cannot be supported
  *
  * Creates a new cursor by looking up @name in the current cursor
@@ -282,6 +306,7 @@ gdk_cursor_equal (gconstpointer a,
  *
  * A recommended set of cursor names that will work across different
  * platforms can be found in the CSS specification:
+ *
  * - "none"
  * - ![](default_cursor.png) "default"
  * - ![](help_cursor.png) "help"
@@ -319,7 +344,7 @@ gdk_cursor_equal (gconstpointer a,
  * - ![](zoom_out_cursor.png) "zoom-out"
  *
  *
- * Returns: (nullable): a new #GdkCursor, or %NULL if there is no
+ * Returns: (nullable): a new `GdkCursor`, or %NULL if there is no
  *   cursor with the given name
  */
 GdkCursor *
@@ -340,12 +365,12 @@ gdk_cursor_new_from_name (const char *name,
  * @texture: the texture providing the pixel data
  * @hotspot_x: the horizontal offset of the “hotspot” of the cursor
  * @hotspot_y: the vertical offset of the “hotspot” of the cursor
- * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
+ * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
  *     this one cannot be supported
  *
- * Creates a new cursor from a #GdkTexture.
+ * Creates a new cursor from a `GdkTexture`.
  *
- * Returns: a new #GdkCursor.
+ * Returns: a new `GdkCursor`
  */
 GdkCursor *
 gdk_cursor_new_from_texture (GdkTexture *texture,
@@ -368,18 +393,18 @@ gdk_cursor_new_from_texture (GdkTexture *texture,
 
 /**
  * gdk_cursor_get_fallback:
- * @cursor: a #GdkCursor.
+ * @cursor: a `GdkCursor`
  *
- * Returns the fallback for this @cursor. The fallback will be used if this
- * cursor is not available on a given #GdkDisplay.
+ * Returns the fallback for this @cursor.
  *
- * For named cursors, this can happen when using nonstandard names or when
- * using an incomplete cursor theme.
- * For textured cursors, this can happen when the texture is too large or
- * when the #GdkDisplay it is used on does not support textured cursors.
+ * The fallback will be used if this cursor is not available on a given
+ * `GdkDisplay`. For named cursors, this can happen when using nonstandard
+ * names or when using an incomplete cursor theme. For textured cursors,
+ * this can happen when the texture is too large or when the `GdkDisplay`
+ * it is used on does not support textured cursors.
  *
- * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL to use
- *     the default cursor as fallback.
+ * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL
+ *  to use the default cursor as fallback.
  */
 GdkCursor *
 gdk_cursor_get_fallback (GdkCursor *cursor)
@@ -391,13 +416,14 @@ gdk_cursor_get_fallback (GdkCursor *cursor)
 
 /**
  * gdk_cursor_get_name:
- * @cursor: a #GdkCursor.
+ * @cursor: a `GdkCursor`
+ *
+ * Returns the name of the cursor.
  *
- * Returns the name of the cursor. If the cursor is not a named cursor, %NULL
- * will be returned.
+ * If the cursor is not a named cursor, %NULL will be returned.
  *
- * Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not
- *     a named cursor
+ * Returns: (transfer none) (nullable): the name of the cursor or %NULL
+ *   if it is not a named cursor
  */
 const char *
 gdk_cursor_get_name (GdkCursor *cursor)
@@ -411,11 +437,12 @@ gdk_cursor_get_name (GdkCursor *cursor)
  * gdk_cursor_get_texture:
  * @cursor: a #GdkCursor.
  *
- * Returns the texture for the cursor. If the cursor is a named cursor, %NULL
- * will be returned.
+ * Returns the texture for the cursor.
  *
- * Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a
- *     named cursor
+ * If the cursor is a named cursor, %NULL will be returned.
+ *
+ * Returns: (transfer none) (nullable): the texture for cursor or %NULL
+ *   if it is a named cursor
  */
 GdkTexture *
 gdk_cursor_get_texture (GdkCursor *cursor)
@@ -427,14 +454,15 @@ gdk_cursor_get_texture (GdkCursor *cursor)
 
 /**
  * gdk_cursor_get_hotspot_x:
- * @cursor: a #GdkCursor.
+ * @cursor: a `GdkCursor`
+ *
+ * Returns the horizontal offset of the hotspot.
  *
- * Returns the horizontal offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * The hotspot indicates the pixel that will be directly above the cursor.
  *
  * Note that named cursors may have a nonzero hotspot, but this function
  * will only return the hotspot position for cursors created with
- * gdk_cursor_new_from_texture().
+ * [ctor@Gdk.Cursor.new_from_texture].
  *
  * Returns: the horizontal offset of the hotspot or 0 for named cursors
  */
@@ -448,14 +476,15 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor)
 
 /**
  * gdk_cursor_get_hotspot_y:
- * @cursor: a #GdkCursor.
+ * @cursor: a `GdkCursor`
+ *
+ * Returns the vertical offset of the hotspot.
  *
- * Returns the vertical offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * The hotspot indicates the pixel that will be directly above the cursor.
  *
  * Note that named cursors may have a nonzero hotspot, but this function
  * will only return the hotspot position for cursors created with
- * gdk_cursor_new_from_texture().
+ * [ctor@Gdk.Cursor.new_from_texture].
  *
  * Returns: the vertical offset of the hotspot or 0 for named cursors
  */
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index f96dbc5e65..e4d24016fd 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -26,24 +26,14 @@
 #include "gdkintl.h"
 #include "gdkkeysprivate.h"
 
-/**
- * SECTION:gdkdevice
- * @Short_description: Object representing an input device
- * @Title: GdkDevice
- * @See_also: #GdkSeat
- *
- * The #GdkDevice object represents a single input device, such
- * as a keyboard, a mouse, a touchpad, etc.
- *
- * See the #GdkSeat documentation for more information about the
- * various kinds of devices, and their relationships.
- */
-
 /**
  * GdkDevice:
  *
- * The GdkDevice struct contains only private fields and
- * should not be accessed directly.
+ * The `GdkDevice` object represents an input device, such
+ * as a keyboard, a mouse, or a touchpad.
+ *
+ * See the [class Gdk Seat] documentation for more information
+ * about the various kinds of devices, and their relationships.
  */
 
 typedef struct _GdkAxisInfo GdkAxisInfo;
@@ -182,7 +172,9 @@ gdk_device_class_init (GdkDeviceClass *klass)
   /**
    * GdkDevice:vendor-id:
    *
-   * Vendor ID of this device, see gdk_device_get_vendor_id().
+   * Vendor ID of this device.
+   *
+   * See [method@Gdk.Device.get_vendor_id].
    */
   device_props[PROP_VENDOR_ID] =
       g_param_spec_string ("vendor-id",
@@ -195,7 +187,9 @@ gdk_device_class_init (GdkDeviceClass *klass)
   /**
    * GdkDevice:product-id:
    *
-   * Product ID of this device, see gdk_device_get_product_id().
+   * Product ID of this device.
+   *
+   * See [method@Gdk.Device.get_product_id].
    */
   device_props[PROP_PRODUCT_ID] =
       g_param_spec_string ("product-id",
@@ -208,7 +202,7 @@ gdk_device_class_init (GdkDeviceClass *klass)
   /**
    * GdkDevice:seat:
    *
-   * #GdkSeat of this device.
+   * `GdkSeat` of this device.
    */
   device_props[PROP_SEAT] =
       g_param_spec_object ("seat",
@@ -222,6 +216,7 @@ gdk_device_class_init (GdkDeviceClass *klass)
    * GdkDevice:num-touches:
    *
    * The maximal number of concurrent touches on a touch device.
+   *
    * Will be 0 if the device is not a touch device or if the number
    * of touches is unknown.
    */
@@ -234,6 +229,11 @@ gdk_device_class_init (GdkDeviceClass *klass)
                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                          G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:tool:
+   *
+   * The `GdkDeviceTool` that is currently used with this device.
+   */
   device_props[PROP_TOOL] =
     g_param_spec_object ("tool",
                          P_("Tool"),
@@ -241,6 +241,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                          GDK_TYPE_DEVICE_TOOL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:direction:
+   *
+   * The direction of the current layout.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_DIRECTION] =
       g_param_spec_enum ("direction",
                          P_("Direction"),
@@ -248,6 +255,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                          PANGO_TYPE_DIRECTION, PANGO_DIRECTION_NEUTRAL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:direction:
+   *
+   * Whether the device has both right-to-left and left-to-right layouts.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_HAS_BIDI_LAYOUTS] =
       g_param_spec_boolean ("has-bidi-layouts",
                             P_("Has bidi layouts"),
@@ -255,6 +269,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                             FALSE,
                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:caps-lock-state:
+   *
+   * Whether Caps Lock is on.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_CAPS_LOCK_STATE] =
       g_param_spec_boolean ("caps-lock-state",
                             P_("Caps lock state"),
@@ -262,6 +283,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                             FALSE,
                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:num-lock-state:
+   *
+   * Whether Num Lock is on.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_NUM_LOCK_STATE] =
       g_param_spec_boolean ("num-lock-state",
                             P_("Num lock state"),
@@ -269,6 +297,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                             FALSE,
                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:scroll-lock-state:
+   *
+   * Whether Scroll Lock is on.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_SCROLL_LOCK_STATE] =
       g_param_spec_boolean ("scroll-lock-state",
                             P_("Scroll lock state"),
@@ -276,6 +311,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
                             FALSE,
                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDevice:modifier-state:
+   *
+   * The current modifier state of the device.
+   *
+   * This is only relevant for keyboard devices.
+   */
   device_props[PROP_MODIFIER_STATE] =
       g_param_spec_flags ("modifier-state",
                           P_("Modifier state"),
@@ -287,11 +329,11 @@ gdk_device_class_init (GdkDeviceClass *klass)
 
   /**
    * GdkDevice::changed:
-   * @device: the #GdkDevice that changed.
+   * @device: the `GdkDevice`
+   *
+   * Emitted either when the the number of either axes or keys changes.
    *
-   * The ::changed signal is emitted either when the #GdkDevice
-   * has changed the number of either axes or keys. For example
-   * on X11 this will normally happen when the physical device
+   * On X11 this will normally happen when the physical device
    * routing events through the logical device changes (for
    * example, user switches from the USB mouse to a tablet); in
    * that case the logical device will change to reflect the axes
@@ -307,11 +349,10 @@ gdk_device_class_init (GdkDeviceClass *klass)
 
   /**
    * GdkDevice::tool-changed:
-   * @device: the #GdkDevice that changed.
+   * @device: the `GdkDevice`
    * @tool: The new current tool
    *
-   * The ::tool-changed signal is emitted on pen/eraser
-   * #GdkDevices whenever tools enter or leave proximity.
+   * Emitted on pen/eraser devices whenever tools enter or leave proximity.
    */
   signals[TOOL_CHANGED] =
     g_signal_new (g_intern_static_string ("tool-changed"),
@@ -478,19 +519,21 @@ gdk_device_get_property (GObject    *object,
 
 /**
  * gdk_device_get_surface_at_position:
- * @device: pointer #GdkDevice to query info to.
+ * @device: pointer `GdkDevice` to query info to
  * @win_x: (out) (allow-none): return location for the X coordinate of the device location,
  *         relative to the surface origin, or %NULL.
  * @win_y: (out) (allow-none): return location for the Y coordinate of the device location,
  *         relative to the surface origin, or %NULL.
  *
- * Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y in
- * double precision. Returns %NULL if the surface tree under @device is not known to GDK (for example,
- * belongs to another application).
+ * Obtains the surface underneath @device, returning the location of the
+ * device in @win_x and @win_y
  *
- * Returns: (nullable) (transfer none): the #GdkSurface under the
- *   device position, or %NULL.
- **/
+ * Returns %NULL if the surface tree under @device is not known to GDK
+ * (for example, belongs to another application).
+ *
+ * Returns: (nullable) (transfer none): the `GdkSurface` under the
+ *   device position, or %NULL
+ */
 GdkSurface *
 gdk_device_get_surface_at_position (GdkDevice *device,
                                     double    *win_x,
@@ -514,13 +557,12 @@ gdk_device_get_surface_at_position (GdkDevice *device,
 
 /**
  * gdk_device_get_name:
- * @device: a #GdkDevice
+ * @device: a GdkDevice`
  *
- * Determines the name of the device, suitable
- * for showing in a user interface.
+ * The name of the device, suitable for showing in a user interface.
  *
  * Returns: a name
- **/
+ */
 const char *
 gdk_device_get_name (GdkDevice *device)
 {
@@ -531,14 +573,15 @@ gdk_device_get_name (GdkDevice *device)
 
 /**
  * gdk_device_get_has_cursor:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
  * Determines whether the pointer follows device motion.
+ *
  * This is not meaningful for keyboard devices, which
  * don't have a pointer.
  *
  * Returns: %TRUE if the pointer follows device motion
- **/
+ */
 gboolean
 gdk_device_get_has_cursor (GdkDevice *device)
 {
@@ -549,12 +592,12 @@ gdk_device_get_has_cursor (GdkDevice *device)
 
 /**
  * gdk_device_get_source:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
  * Determines the type of the device.
  *
- * Returns: a #GdkInputSource
- **/
+ * Returns: a `GdkInputSource`
+ */
 GdkInputSource
 gdk_device_get_source (GdkDevice *device)
 {
@@ -565,13 +608,13 @@ gdk_device_get_source (GdkDevice *device)
 
 /**
  * gdk_device_get_axis_use:
- * @device: a pointer #GdkDevice.
- * @index_: the index of the axis.
+ * @device: a pointer `GdkDevice`
+ * @index_: the index of the axi.
  *
  * Returns the axis use for @index_.
  *
- * Returns: a #GdkAxisUse specifying how the axis is used.
- **/
+ * Returns: a `GdkAxisUse` specifying how the axis is used.
+ */
 GdkAxisUse
 gdk_device_get_axis_use (GdkDevice *device,
                          guint      index_)
@@ -589,13 +632,12 @@ gdk_device_get_axis_use (GdkDevice *device,
 
 /**
  * gdk_device_get_display:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
- * Returns the #GdkDisplay to which @device pertains.
+ * Returns the `GdkDisplay` to which @device pertains.
  *
- * Returns: (transfer none): a #GdkDisplay. This memory is owned
- *          by GTK, and must not be freed or unreffed.
- **/
+ * Returns: (transfer none): a `GdkDisplay`
+ */
 GdkDisplay *
 gdk_device_get_display (GdkDevice *device)
 {
@@ -616,13 +658,13 @@ _gdk_device_set_associated_device (GdkDevice *device,
 
 /*
  * gdk_device_list_physical_devices:
- * @device: a logical #GdkDevice
+ * @device: a logical `GdkDevice`
  *
  * Returns the list of physical devices attached to the given logical
- * #GdkDevice.
+ * `GdkDevice`.
  *
  * Returns: (nullable) (transfer container) (element-type GdkDevice):
- *   the list of physical devices attached to a logical #GdkDevice
+ *   the list of physical devices attached to a logical `GdkDevice`
  */
 GList *
 gdk_device_list_physical_devices (GdkDevice *device)
@@ -655,12 +697,12 @@ _gdk_device_remove_physical_device (GdkDevice *device,
 
 /*
  * gdk_device_get_n_axes:
- * @device: a pointer #GdkDevice
+ * @device: a pointer `GdkDevice`
  *
  * Returns the number of axes the device currently has.
  *
  * Returns: the number of axes.
- **/
+ */
 int
 gdk_device_get_n_axes (GdkDevice *device)
 {
@@ -672,16 +714,16 @@ gdk_device_get_n_axes (GdkDevice *device)
 
 /*
  * gdk_device_get_axis: (skip)
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  * @axes: (array): pointer to an array of axes
  * @use: the use to look for
- * @value: (out): location to store the found value.
+ * @value: (out): location to store the found value
  *
- * Interprets an array of double as axis values for a given device,
- * and locates the value in the array for a given axis use.
+ * Interprets an array of `double` as axis values and get the value
+ * for a given axis use.
  *
  * Returns: %TRUE if the given axis use was found, otherwise %FALSE
- **/
+ */
 gboolean
 gdk_device_get_axis (GdkDevice  *device,
                      double     *axes,
@@ -1073,16 +1115,17 @@ _gdk_device_surface_at_position (GdkDevice       *device,
 
 /**
  * gdk_device_get_vendor_id:
- * @device: a physical #GdkDevice
+ * @device: a physical `GdkDevice`
+ *
+ * Returns the vendor ID of this device.
  *
- * Returns the vendor ID of this device, or %NULL if this information couldn't
- * be obtained. This ID is retrieved from the device, and is thus constant for
- * it.
+ * This ID is retrieved from the device, and does not change.
  *
- * This function, together with gdk_device_get_product_id(), can be used to eg.
- * compose #GSettings paths to store settings for this device.
+ * This function, together with [method@Gdk.Device.get_product_id],
+ * can be used to eg. compose `GSettings` paths to store settings
+ * for this device.
  *
- * |[<!-- language="C" -->
+ * ```c
  *  static GSettings *
  *  get_device_settings (GdkDevice *device)
  *  {
@@ -1100,7 +1143,7 @@ _gdk_device_surface_at_position (GdkDevice       *device,
  *
  *    return settings;
  *  }
- * ]|
+ * ```
  *
  * Returns: (nullable): the vendor ID, or %NULL
  */
@@ -1114,11 +1157,12 @@ gdk_device_get_vendor_id (GdkDevice *device)
 
 /**
  * gdk_device_get_product_id:
- * @device: a physical #GdkDevice
+ * @device: a physical `GdkDevice`
+ *
+ * Returns the product ID of this device.
  *
- * Returns the product ID of this device, or %NULL if this information couldn't
- * be obtained. This ID is retrieved from the device, and is thus constant for
- * it. See gdk_device_get_vendor_id() for more information.
+ * This ID is retrieved from the device, and does not change.
+ * See [method@Gdk.Device.get_vendor_id] for more information.
  *
  * Returns: (nullable): the product ID, or %NULL
  */
@@ -1148,10 +1192,10 @@ gdk_device_set_seat (GdkDevice *device,
  * gdk_device_get_seat:
  * @device: A #GdkDevice
  *
- * Returns the #GdkSeat the device belongs to.
+ * Returns the `GdkSeat` the device belongs to.
  *
- * Returns: (transfer none): a #GdkSeat
- **/
+ * Returns: (transfer none): a `GdkSeat`
+ */
 GdkSeat *
 gdk_device_get_seat (GdkDevice *device)
 {
@@ -1175,7 +1219,7 @@ gdk_device_update_tool (GdkDevice     *device,
 
 /**
  * gdk_device_get_num_touches:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
  * Retrieves the number of touch points associated to @device.
  *
@@ -1191,11 +1235,11 @@ gdk_device_get_num_touches (GdkDevice *device)
 
 /**
  * gdk_device_get_device_tool:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
- * Retrieves the #GdkDeviceTool associated to @device.
+ * Retrieves the current tool for @device.
  *
- * Returns: (transfer none): the #GdkDeviceTool
+ * Returns: (transfer none): the `GdkDeviceTool`, or %NULL
  */
 GdkDeviceTool *
 gdk_device_get_device_tool (GdkDevice *device)
@@ -1207,10 +1251,11 @@ gdk_device_get_device_tool (GdkDevice *device)
 
 /**
  * gdk_device_get_caps_lock_state:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
+ *
+ * Retrieves whether the Caps Lock modifier of the keyboard is locked.
  *
- * Retrieves whether the Caps Lock modifier of the
- * keyboard is locked, if @device is a keyboard device.
+ * This is only relevant for keyboard devices.
  *
  * Returns: %TRUE if Caps Lock is on for @device
  */
@@ -1227,10 +1272,11 @@ gdk_device_get_caps_lock_state (GdkDevice *device)
 
 /**
  * gdk_device_get_num_lock_state:
- * @device: a #GdkDevice
+ * @device: a ``GdkDevice`
  *
- * Retrieves whether the Num Lock modifier of the
- * keyboard is locked, if @device is a keyboard device.
+ * Retrieves whether the Num Lock modifier of the keyboard is locked.
+ *
+ * This is only relevant for keyboard devices.
  *
  * Returns: %TRUE if Num Lock is on for @device
  */
@@ -1247,10 +1293,11 @@ gdk_device_get_num_lock_state (GdkDevice *device)
 
 /**
  * gdk_device_get_scroll_lock_state:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
+ *
+ * Retrieves whether the Scroll Lock modifier of the keyboard is locked.
  *
- * Retrieves whether the Scroll Lock modifier of the
- * keyboard is locked, if @device is a keyboard device.
+ * This is only relevant for keyboard devices.
  *
  * Returns: %TRUE if Scroll Lock is on for @device
  */
@@ -1267,10 +1314,11 @@ gdk_device_get_scroll_lock_state (GdkDevice *device)
 
 /**
  * gdk_device_get_modifier_state:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
  *
- * Retrieves the current modifier state of the keyboard,
- * if @device is a keyboard device.
+ * Retrieves the current modifier state of the keyboard.
+ *
+ * This is only relevant for keyboard devices.
  *
  * Returns: the current modifier state
  */
@@ -1287,13 +1335,14 @@ gdk_device_get_modifier_state (GdkDevice *device)
 
 /**
  * gdk_device_get_direction:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
+ *
+ * Returns the direction of effective layout of the keyboard.
  *
- * Returns the direction of effective layout of the keyboard,
- * if @device is a keyboard device.
+ * This is only relevant for keyboard devices.
  *
  * The direction of a layout is the direction of the majority
- * of its symbols. See pango_unichar_direction().
+ * of its symbols. See [func@Pango.unichar_direction].
  *
  * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
  *   if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
@@ -1312,11 +1361,12 @@ gdk_device_get_direction (GdkDevice *device)
 
 /**
  * gdk_device_has_bidi_layouts:
- * @device: a #GdkDevice
+ * @device: a `GdkDevice`
+ *
+ * Determines if layouts for both right-to-left and
+ * left-to-right languages are in use on the keyboard.
  *
- * Determines if keyboard layouts for both right-to-left and
- * left-to-right languages are in use on the keyboard, if
- * @device is a keyboard device.
+ * This is only relevant for keyboard devices.
  *
  * Returns: %TRUE if there are layouts with both directions,
  *     %FALSE otherwise
diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c
index 7e108e9c97..ac25d0a873 100644
--- a/gdk/gdkdevicepad.c
+++ b/gdk/gdkdevicepad.c
@@ -18,33 +18,24 @@
  */
 
 /**
- * SECTION:gdkdevicepad
- * @Short_description: Pad device interface
- * @Title: GtkDevicePad
+ * GdkDevicePad:
  *
- * #GdkDevicePad is an interface implemented by devices of type
+ * `GdkDevicePad` is an interface implemented by devices of type
  * %GDK_SOURCE_TABLET_PAD, it allows querying the features provided
  * by the pad device.
  *
  * Tablet pads may contain one or more groups, each containing a subset
- * of the buttons/rings/strips available. gdk_device_pad_get_n_groups()
- * can be used to obtain the number of groups, gdk_device_pad_get_n_features()
- * and gdk_device_pad_get_feature_group() can be combined to find out the
- * number of buttons/rings/strips the device has, and how are they grouped.
+ * of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups]
+ * can be used to obtain the number of groups, [method@Gdk.DevicePad.get_n_features]
+ * and [method@Gdk.DevicePad.get_feature_group] can be combined to find out
+ * the number of buttons/rings/strips the device has, and how are they grouped.
  *
  * Each of those groups have different modes, which may be used to map each
  * individual pad feature to multiple actions. Only one mode is effective
  * (current) for each given group, different groups may have different
  * current modes. The number of available modes in a group can be found
- * out through gdk_device_pad_get_group_n_modes(), and the current mode for
- * a given group will be notified through events of type #GDK_PAD_GROUP_MODE.
- */
-
-/**
- * GdkDevicePad:
- *
- * The GdkDevicePad struct contains only private fields and
- * should not be accessed directly.
+ * out through [method@Gdk.DevicePad.get_group_n_modes], and the current mode
+ * for a given group will be notified through events of type #GDK_PAD_GROUP_MODE.
  */
 
 #include "config.h"
@@ -62,15 +53,16 @@ gdk_device_pad_default_init (GdkDevicePadInterface *pad)
 
 /**
  * gdk_device_pad_get_n_groups:
- * @pad: a #GdkDevicePad
+ * @pad: a `GdkDevicePad`
  *
- * Returns the number of groups this pad device has. Pads have
- * at least one group. A pad group is a subcollection of
+ * Returns the number of groups this pad device has.
+ *
+ * Pads have at least one group. A pad group is a subcollection of
  * buttons/strip/rings that is affected collectively by a same
  * current mode.
  *
  * Returns: The number of button/ring/strip groups in the pad.
- **/
+ */
 int
 gdk_device_pad_get_n_groups (GdkDevicePad *pad)
 {
@@ -83,13 +75,13 @@ gdk_device_pad_get_n_groups (GdkDevicePad *pad)
 
 /**
  * gdk_device_pad_get_group_n_modes:
- * @pad: a #GdkDevicePad
+ * @pad: a `GdkDevicePad`
  * @group_idx: group to get the number of available modes from
  *
  * Returns the number of modes that @group may have.
  *
  * Returns: The number of modes available in @group.
- **/
+ */
 int
 gdk_device_pad_get_group_n_modes (GdkDevicePad *pad,
                                   int           group_idx)
@@ -104,13 +96,13 @@ gdk_device_pad_get_group_n_modes (GdkDevicePad *pad,
 
 /**
  * gdk_device_pad_get_n_features:
- * @pad: a #GdkDevicePad
+ * @pad: a `GdkDevicePad`
  * @feature: a pad feature
  *
  * Returns the number of features a tablet pad has.
  *
  * Returns: The amount of elements of type @feature that this pad has.
- **/
+ */
 int
 gdk_device_pad_get_n_features (GdkDevicePad        *pad,
                                GdkDevicePadFeature  feature)
@@ -124,15 +116,16 @@ gdk_device_pad_get_n_features (GdkDevicePad        *pad,
 
 /**
  * gdk_device_pad_get_feature_group:
- * @pad: a #GdkDevicePad
+ * @pad: a `GdkDevicePad`
  * @feature: the feature type to get the group from
  * @feature_idx: the index of the feature to get the group from
  *
- * Returns the group the given @feature and @idx belong to,
- * or -1 if feature/index do not exist in @pad.
+ * Returns the group the given @feature and @idx belong to.
+ *
+ * f the feature or index do not exist in @pad, -1 is returned.
  *
  * Returns: The group number of the queried pad feature.
- **/
+ */
 int
 gdk_device_pad_get_feature_group (GdkDevicePad        *pad,
                                   GdkDevicePadFeature  feature,
diff --git a/gdk/gdkdevicetool.c b/gdk/gdkdevicetool.c
index 0cfcf800bf..fba863bb7c 100644
--- a/gdk/gdkdevicetool.c
+++ b/gdk/gdkdevicetool.c
@@ -23,6 +23,11 @@
 #include "gdkinternals.h"
 #include "gdkintl.h"
 
+/**
+ * GdkDeviceTool:
+ *
+ * A physical tool associated to a `GdkDevice`.
+ */
 
 G_DEFINE_TYPE (GdkDeviceTool, gdk_device_tool, G_TYPE_OBJECT)
 
@@ -101,6 +106,11 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
   object_class->set_property = gdk_device_tool_set_property;
   object_class->get_property = gdk_device_tool_get_property;
 
+  /**
+   * GdkDeviceTool:serial:
+   *
+   * The serial number of the tool.
+   */
   tool_props[TOOL_PROP_SERIAL] = g_param_spec_uint64 ("serial",
                                                       "Serial",
                                                       "Serial number",
@@ -108,6 +118,12 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
                                                       G_PARAM_READWRITE |
                                                       G_PARAM_CONSTRUCT_ONLY |
                                                       G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkDeviceTool:tool-type:
+   *
+   * The type of the tool.
+   */
   tool_props[TOOL_PROP_TOOL_TYPE] = g_param_spec_enum ("tool-type",
                                                        "Tool type",
                                                        "Tool type",
@@ -116,12 +132,24 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
                                                        G_PARAM_READWRITE |
                                                        G_PARAM_CONSTRUCT_ONLY |
                                                        G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkDeviceTool:axes:
+   *
+   * The axes of the tool.
+   */
   tool_props[TOOL_PROP_AXES] = g_param_spec_flags ("axes",
                                                    "Axes",
                                                    "Tool axes",
                                                    GDK_TYPE_AXIS_FLAGS, 0,
                                                    G_PARAM_READWRITE |
                                                    G_PARAM_CONSTRUCT_ONLY);
+
+  /**
+   * GdkDeviceTool:hardware-id:
+   *
+   * The hardware ID of the tool.
+   */
   tool_props[TOOL_PROP_HARDWARE_ID] = g_param_spec_uint64 ("hardware-id",
                                                            "Hardware ID",
                                                            "Hardware ID",
@@ -154,13 +182,15 @@ gdk_device_tool_new (guint64           serial,
 
 /**
  * gdk_device_tool_get_serial:
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
  *
- * Gets the serial of this tool, this value can be used to identify a
- * physical tool (eg. a tablet pen) across program executions.
+ * Gets the serial number of this tool.
+ *
+ * This value can be used to identify a physical tool
+ * (eg. a tablet pen) across program executions.
  *
  * Returns: The serial ID for this tool
- **/
+ */
 guint64
 gdk_device_tool_get_serial (GdkDeviceTool *tool)
 {
@@ -171,20 +201,22 @@ gdk_device_tool_get_serial (GdkDeviceTool *tool)
 
 /**
  * gdk_device_tool_get_hardware_id:
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
+ *
+ * Gets the hardware ID of this tool, or 0 if it's not known.
  *
- * Gets the hardware ID of this tool, or 0 if it's not known. When
- * non-zero, the identificator is unique for the given tool model,
+ * When non-zero, the identificator is unique for the given tool model,
  * meaning that two identical tools will share the same @hardware_id,
- * but will have different serial numbers (see gdk_device_tool_get_serial()).
+ * but will have different serial numbers (see
+ * [method@Gdk.DeviceTool.get_serial]).
  *
  * This is a more concrete (and device specific) method to identify
- * a #GdkDeviceTool than gdk_device_tool_get_tool_type(), as a tablet
- * may support multiple devices with the same #GdkDeviceToolType,
- * but having different hardware identificators.
+ * a `GdkDeviceTool` than [method@Gdk.DeviceTool.get_tool_type],
+ * as a tablet may support multiple devices with the same
+ * `GdkDeviceToolType`, but different hardware identificators.
  *
  * Returns: The hardware identificator of this tool.
- **/
+ */
 guint64
 gdk_device_tool_get_hardware_id (GdkDeviceTool *tool)
 {
@@ -195,13 +227,14 @@ gdk_device_tool_get_hardware_id (GdkDeviceTool *tool)
 
 /**
  * gdk_device_tool_get_tool_type:
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
  *
- * Gets the #GdkDeviceToolType of the tool.
+ * Gets the `GdkDeviceToolType` of the tool.
  *
- * Returns: The physical type for this tool. This can be used to figure out what
- * sort of pen is being used, such as an airbrush or a pencil.
- **/
+ * Returns: The physical type for this tool. This can be used to
+ *   figure out what sort of pen is being used, such as an airbrush
+ *   or a pencil.
+ */
 GdkDeviceToolType
 gdk_device_tool_get_tool_type (GdkDeviceTool *tool)
 {
@@ -212,7 +245,7 @@ gdk_device_tool_get_tool_type (GdkDeviceTool *tool)
 
 /**
  * gdk_device_tool_get_axes:
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
  *
  * Gets the axes of the tool.
  *
diff --git a/gdk/gdkdevicetool.h b/gdk/gdkdevicetool.h
index 16f5b3b30b..1a6a90d756 100644
--- a/gdk/gdkdevicetool.h
+++ b/gdk/gdkdevicetool.h
@@ -32,11 +32,6 @@ G_BEGIN_DECLS
 #define GDK_DEVICE_TOOL(o)      (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE_TOOL, GdkDeviceTool))
 #define GDK_IS_DEVICE_TOOL(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE_TOOL))
 
-/**
- * GdkDeviceTool:
- *
- * A physical tool associated to a #GdkDevice.
- */
 typedef struct _GdkDeviceTool GdkDeviceTool;
 
 /**
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 41d9728288..217b690dc0 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -54,23 +54,26 @@
 #endif
 
 /**
- * SECTION:gdkdisplaymanager
- * @Short_description: Maintains a list of all open GdkDisplays
- * @Title: GdkDisplayManager
+ * GdkDisplayManager:
  *
- * The purpose of the #GdkDisplayManager singleton object is to offer
- * notification when displays appear or disappear or the default display
- * changes.
+ * A singleton object that offers notification when displays appear or
+ * disappear.
  *
- * You can use gdk_display_manager_get() to obtain the #GdkDisplayManager
+ * You can use [func@Gdk.display_manager_get] to obtain the `GdkDisplayManager`
  * singleton, but that should be rarely necessary. Typically, initializing
  * GTK opens a display that you can work with without ever accessing the
- * #GdkDisplayManager.
+ * `GdkDisplayManager`.
  *
  * The GDK library can be built with support for multiple backends.
- * The #GdkDisplayManager object determines which backend is used
+ * The `GdkDisplayManager` object determines which backend is used
  * at runtime.
  *
+ * In the rare case that you need to influence which of the backends
+ * is being used, you can use [func@Gdk.set_allowed_backends]. Note
+ * that you need to call this function before initializing GTK.
+ *
+ * ## Backend-specific code
+ *
  * When writing backend-specific code that is supposed to work with
  * multiple GDK backends, you have to consider both compile time and
  * runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32
@@ -78,9 +81,7 @@
  * you are building your application against. At runtime, use type-check
  * macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
  *
- * ## Backend-specific code ## {#backend-specific}
- *
- * |[<!-- language="C" -->
+ * ```c
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
  *     {
@@ -96,14 +97,7 @@
  *   else
  * #endif
  *   g_error ("Unsupported GDK backend");
- * ]|
- */
-
-/**
- * GdkDisplayManager:
- *
- * The GdkDisplayManager struct contains only private fields and
- * should not be accessed directly.
+ * ```
  */
 
 enum {
@@ -142,7 +136,7 @@ gdk_display_manager_class_init (GdkDisplayManagerClass *klass)
    * @manager: the object on which the signal is emitted
    * @display: the opened display
    *
-   * The ::display-opened signal is emitted when a display is opened.
+   * Emitted when a display is opened.
    */
   signals[DISPLAY_OPENED] =
     g_signal_new (g_intern_static_string ("display-opened"),
@@ -155,6 +149,11 @@ gdk_display_manager_class_init (GdkDisplayManagerClass *klass)
                   1,
                   GDK_TYPE_DISPLAY);
 
+  /**
+   * GdkDisplayManager:default-display:
+   *
+   * The default display.
+   */
   g_object_class_install_property (object_class,
                                    PROP_DEFAULT_DISPLAY,
                                    g_param_spec_object ("default-display",
@@ -219,24 +218,21 @@ static const char *allowed_backends;
  * By default, GDK tries all included backends.
  *
  * For example,
- * |[<!-- language="C" -->
- * gdk_set_allowed_backends ("wayland,quartz,*");
- * ]|
- * instructs GDK to try the Wayland backend first,
- * followed by the Quartz backend, and then all
- * others.
+ * ```c
+ * gdk_set_allowed_backends ("wayland,macos,*");
+ * ```
+ * instructs GDK to try the Wayland backend first, followed by the
+ * MacOs backend, and then all others.
  *
- * If the `GDK_BACKEND` environment variable
- * is set, it determines what backends are tried in what
- * order, while still respecting the set of allowed backends
- * that are specified by this function.
+ * If the `GDK_BACKEND` environment variable is set, it determines
+ * what backends are tried in what order, while still respecting the
+ * set of allowed backends that are specified by this function.
  *
- * The possible backend names are x11, win32, quartz,
- * broadway, wayland. You can also include a * in the
- * list to try all remaining backends.
+ * The possible backend names are x11, win32, macos, broadway, wayland.
+ * You can also include a * in the list to try all remaining backends.
  *
- * This call must happen prior to gdk_display_open(),
- * gtk_init(), or gtk_init_check()
+ * This call must happen prior to functions that open a display, such
+ * as [func@Gdk.display_open], [func Gtk init], or [func@Gtk.init_check]
  * in order to take effect.
  */
 void
@@ -275,16 +271,18 @@ static GdkBackend gdk_backends[] = {
 /**
  * gdk_display_manager_get:
  *
- * Gets the singleton #GdkDisplayManager object.
+ * Gets the singleton `GdkDisplayManager` object.
  *
  * When called for the first time, this function consults the
- * `GDK_BACKEND` environment variable to find out which
- * of the supported GDK backends to use (in case GDK has been compiled
- * with multiple backends). Applications can use gdk_set_allowed_backends()
- * to limit what backends can be used.
+ * `GDK_BACKEND` environment variable to find out which of the
+ * supported GDK backends to use (in case GDK has been compiled
+ * with multiple backends).
+ *
+ * Applications can use [func@set_allowed_backends] to limit what
+ * backends wil be used.
  *
- * Returns: (transfer none): The global #GdkDisplayManager singleton
- **/
+ * Returns: (transfer none): The global `GdkDisplayManager` singleton
+ */
 GdkDisplayManager*
 gdk_display_manager_get (void)
 {
@@ -298,11 +296,11 @@ gdk_display_manager_get (void)
 
 /**
  * gdk_display_manager_get_default_display:
- * @manager: a #GdkDisplayManager
+ * @manager: a `GdkDisplayManager`
  *
- * Gets the default #GdkDisplay.
+ * Gets the default `GdkDisplay`.
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
  *     there is no default display.
  */
 GdkDisplay *
@@ -314,12 +312,13 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager)
 /**
  * gdk_display_get_default:
  *
- * Gets the default #GdkDisplay. This is a convenience
- * function for:
+ * Gets the default `GdkDisplay`.
+ *
+ * This is a convenience function for:
  * `gdk_display_manager_get_default_display (gdk_display_manager_get ())`.
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
- *   there is no default display.
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
+ *   there is no default display
  */
 GdkDisplay *
 gdk_display_get_default (void)
@@ -329,11 +328,11 @@ gdk_display_get_default (void)
 
 /**
  * gdk_display_manager_set_default_display:
- * @manager: a #GdkDisplayManager
- * @display: a #GdkDisplay
+ * @manager: a `GdkDisplayManager`
+ * @display: a `GdkDisplay`
  *
  * Sets @display as the default display.
- **/
+ */
 void
 gdk_display_manager_set_default_display (GdkDisplayManager *manager,
                                          GdkDisplay        *display)
@@ -348,14 +347,14 @@ gdk_display_manager_set_default_display (GdkDisplayManager *manager,
 
 /**
  * gdk_display_manager_list_displays:
- * @manager: a #GdkDisplayManager
+ * @manager: a `GdkDisplayManager`
  *
  * List all currently open displays.
  *
  * Returns: (transfer container) (element-type GdkDisplay): a newly
- *     allocated #GSList of #GdkDisplay objects. Free with g_slist_free()
+ *     allocated `GSList` of `GdkDisplay` objects. Free with g_slist_free()
  *     when you are done with it.
- **/
+ */
 GSList *
 gdk_display_manager_list_displays (GdkDisplayManager *manager)
 {
@@ -364,13 +363,13 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager)
 
 /**
  * gdk_display_manager_open_display:
- * @manager: a #GdkDisplayManager
+ * @manager: a `GdkDisplayManager`
  * @name: the name of the display to open
  *
  * Opens a display.
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
- *     display could not be opened
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL
+ *   if the display could not be opened
  */
 GdkDisplay *
 gdk_display_manager_open_display (GdkDisplayManager *manager,
diff --git a/gdk/gdkdrag.c b/gdk/gdkdrag.c
index 9b54924c56..87c45515d1 100644
--- a/gdk/gdkdrag.c
+++ b/gdk/gdkdrag.c
@@ -23,14 +23,11 @@
  */
 
 /**
- * SECTION:gdkdrag
- * @Title: Drag And Drop
- * @Short_description: Functions for controlling drag and drop handling
+ * GdkDrag:
  *
- * These functions provide a low-level interface for drag and drop.
+ * The `GdkDrag` object represents the source of an ongoing DND operation.
  *
- * The `GdkDrag` object represents the source side of an ongoing DND operation.
- * It is created when a drag is started, and stays alive for duration of
+ * A `GdkDrag` is created when a drag is started, and stays alive for duration of
  * the DND operation. After a drag has been started with [method Gdk Drag.begin],
  * the caller gets informed about the status of the ongoing drag operation
  * with signals on the `GdkDrag` object.
@@ -106,21 +103,14 @@ static GList *drags = NULL;
 
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrag, gdk_drag, G_TYPE_OBJECT)
 
-/**
- * GdkDrag:
- *
- * The GdkDrag struct contains only private fields and
- * should not be accessed directly.
- */
-
 /**
  * gdk_drag_get_display:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
- * Gets the #GdkDisplay that the drag object was created for.
+ * Gets the `GdkDisplay` that the drag object was created for.
  *
- * Returns: (transfer none): a #GdkDisplay
- **/
+ * Returns: (transfer none): a `GdkDisplay`
+ */
 GdkDisplay *
 gdk_drag_get_display (GdkDrag *drag)
 {
@@ -133,12 +123,12 @@ gdk_drag_get_display (GdkDrag *drag)
 
 /**
  * gdk_drag_get_formats:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
- * Retrieves the formats supported by this GdkDrag object.
+ * Retrieves the formats supported by this `GdkDrag` object.
  *
- * Returns: (transfer none): a #GdkContentFormats
- **/
+ * Returns: (transfer none): a `GdkContentFormats`
+ */
 GdkContentFormats *
 gdk_drag_get_formats (GdkDrag *drag)
 {
@@ -151,12 +141,12 @@ gdk_drag_get_formats (GdkDrag *drag)
 
 /**
  * gdk_drag_get_actions:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
  * Determines the bitmask of possible actions proposed by the source.
  *
- * Returns: the #GdkDragAction flags
- **/
+ * Returns: the `GdkDragAction` flags
+ */
 GdkDragAction
 gdk_drag_get_actions (GdkDrag *drag)
 {
@@ -169,12 +159,12 @@ gdk_drag_get_actions (GdkDrag *drag)
 
 /**
  * gdk_drag_get_selected_action:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
  * Determines the action chosen by the drag destination.
  *
- * Returns: a #GdkDragAction value
- **/
+ * Returns: a `GdkDragAction` value
+ */
 GdkDragAction
 gdk_drag_get_selected_action (GdkDrag *drag)
 {
@@ -187,12 +177,12 @@ gdk_drag_get_selected_action (GdkDrag *drag)
 
 /**
  * gdk_drag_get_device:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
- * Returns the #GdkDevice associated to the GdkDrag object.
+ * Returns the `GdkDevice` associated to the `GdkDrag` object.
  *
- * Returns: (transfer none): The #GdkDevice associated to @drag.
- **/
+ * Returns: (transfer none): The `GdkDevice` associated to @drag.
+ */
 GdkDevice *
 gdk_drag_get_device (GdkDrag *drag)
 {
@@ -205,12 +195,12 @@ gdk_drag_get_device (GdkDrag *drag)
 
 /**
  * gdk_drag_get_content:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
- * Returns the #GdkContentProvider associated to the GdkDrag object.
+ * Returns the `GdkContentProvider` associated to the `GdkDrag` object.
  *
- * Returns: (transfer none): The #GdkContentProvider associated to @drag.
- **/
+ * Returns: (transfer none): The `GdkContentProvider` associated to @drag.
+ */
 GdkContentProvider *
 gdk_drag_get_content (GdkDrag *drag)
 {
@@ -223,12 +213,12 @@ gdk_drag_get_content (GdkDrag *drag)
 
 /**
  * gdk_drag_get_surface:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
- * Returns the #GdkSurface where the drag originates.
+ * Returns the `GdkSurface` where the drag originates.
  *
- * Returns: (transfer none): The #GdkSurface where the drag originates
- **/
+ * Returns: (transfer none): The `GdkSurface` where the drag originates
+ */
 GdkSurface *
 gdk_drag_get_surface (GdkDrag *drag)
 {
@@ -386,7 +376,7 @@ gdk_drag_class_init (GdkDragClass *klass)
   /**
    * GdkDrag:content:
    *
-   * The #GdkContentProvider.
+   * The `GdkContentProvider`.
    */
   properties[PROP_CONTENT] =
     g_param_spec_object ("content",
@@ -401,7 +391,7 @@ gdk_drag_class_init (GdkDragClass *klass)
   /**
    * GdkDrag:device:
    *
-   * The #GdkDevice that is performing the drag.
+   * The `GdkDevice` that is performing the drag.
    */
   properties[PROP_DEVICE] =
     g_param_spec_object ("device",
@@ -416,7 +406,7 @@ gdk_drag_class_init (GdkDragClass *klass)
   /**
    * GdkDrag:display:
    *
-   * The #GdkDisplay that the drag belongs to.
+   * The `GdkDisplay` that the drag belongs to.
    */
   properties[PROP_DISPLAY] =
     g_param_spec_object ("display",
@@ -442,6 +432,11 @@ gdk_drag_class_init (GdkDragClass *klass)
                         G_PARAM_STATIC_STRINGS |
                         G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GdkDrag:selected-action:
+   *
+   * The currently selected action of the drag.
+   */
   properties[PROP_SELECTED_ACTION] =
     g_param_spec_flags ("selected-action",
                         "Selected action",
@@ -452,6 +447,11 @@ gdk_drag_class_init (GdkDragClass *klass)
                         G_PARAM_STATIC_STRINGS |
                         G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GdkDrag:actions:
+   *
+   * The possible actions of this drag.
+   */
   properties[PROP_ACTIONS] =
     g_param_spec_flags ("actions",
                         "Actions",
@@ -462,6 +462,11 @@ gdk_drag_class_init (GdkDragClass *klass)
                         G_PARAM_STATIC_STRINGS |
                         G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GdkDrag:surface:
+   *
+   * The surface where the drag originates.
+   */
   properties[PROP_SURFACE] =
     g_param_spec_object ("surface",
                          "Surface",
@@ -477,7 +482,7 @@ gdk_drag_class_init (GdkDragClass *klass)
    * @drag: The object on which the signal is emitted
    * @reason: The reason the drag was cancelled
    *
-   * The drag operation was cancelled.
+   * Emitted when the drag operation is cancelled.
    */
   signals[CANCEL] =
     g_signal_new (g_intern_static_string ("cancel"),
@@ -492,7 +497,7 @@ gdk_drag_class_init (GdkDragClass *klass)
    * GdkDrag::drop-performed:
    * @drag: The object on which the signal is emitted
    *
-   * The drag operation was performed on an accepting client.
+   * Emitted when the drop operation is performed on an accepting client.
    */
   signals[DROP_PERFORMED] =
     g_signal_new (g_intern_static_string ("drop-performed"),
@@ -507,9 +512,9 @@ gdk_drag_class_init (GdkDragClass *klass)
    * GdkDrag::dnd-finished:
    * @drag: The object on which the signal is emitted
    *
-   * The drag operation was finished, the destination
-   * finished reading all data. The drag object can now
-   * free all miscellaneous data.
+   * Emitted when the destination side has finished reading all data.
+   *
+   * The drag object can now free all miscellaneous data.
    */
   signals[DND_FINISHED] =
     g_signal_new (g_intern_static_string ("dnd-finished"),
@@ -677,14 +682,15 @@ gdk_drag_set_selected_action (GdkDrag       *drag,
 
 /**
  * gdk_drag_get_drag_surface:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  *
  * Returns the surface on which the drag icon should be rendered
- * during the drag operation. Note that the surface may not be
- * available until the drag operation has begun. GDK will move
- * the surface in accordance with the ongoing drag operation.
- * The surface is owned by @drag and will be destroyed when
- * the drag operation is over.
+ * during the drag operation.
+ *
+ * Note that the surface may not be available until the drag operation
+ * has begun. GDK will move the surface in accordance with the ongoing
+ * drag operation. The surface is owned by @drag and will be destroyed
+ * when the drag operation is over.
  *
  * Returns: (nullable) (transfer none): the drag surface, or %NULL
  */
@@ -701,13 +707,14 @@ gdk_drag_get_drag_surface (GdkDrag *drag)
 
 /**
  * gdk_drag_set_hotspot:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  * @hot_x: x coordinate of the drag surface hotspot
  * @hot_y: y coordinate of the drag surface hotspot
  *
  * Sets the position of the drag surface that will be kept
- * under the cursor hotspot. Initially, the hotspot is at the
- * top left corner of the drag surface.
+ * under the cursor hotspot.
+ *
+ * Initially, the hotspot is at the top left corner of the drag surface.
  */
 void
 gdk_drag_set_hotspot (GdkDrag *drag,
@@ -722,17 +729,18 @@ gdk_drag_set_hotspot (GdkDrag *drag,
 
 /**
  * gdk_drag_drop_done:
- * @drag: a #GdkDrag
+ * @drag: a `GdkDrag`
  * @success: whether the drag was ultimatively successful
  *
- * Inform GDK if the drop ended successfully. Passing %FALSE
- * for @success may trigger a drag cancellation animation.
+ * Informs GDK that the drop ended.
  *
- * This function is called by the drag source, and should
- * be the last call before dropping the reference to the
- * @drag.
+ * Passing %FALSE for @success may trigger a drag cancellation
+ * animation.
  *
- * The #GdkDrag will only take the first gdk_drag_drop_done()
+ * This function is called by the drag source, and should be the
+ * last call before dropping the reference to the @drag.
+ *
+ * The `GdkDrag` will only take the first [method Gdk Drag.drop_done]
  * call as effective, if this function is called multiple times,
  * all subsequent calls will be ignored.
  */
@@ -804,22 +812,22 @@ gdk_drag_get_cursor (GdkDrag       *drag,
 
   if (drag_cursors[i].cursor == NULL)
     drag_cursors[i].cursor = gdk_cursor_new_from_name (drag_cursors[i].name, NULL);
-                                                       
+
   return drag_cursors[i].cursor;
 }
 
 /**
  * gdk_drag_action_is_unique:
- * @action: a #GdkDragAction
+ * @action: a `GdkDragAction`
  *
- * Checks if @action represents a single action or if it
- * includes multiple flags that can be selected from.
+ * Checks if @action represents a single action or includes
+ * multiple actions.
  *
  * When @action is 0 - ie no action was given, %TRUE
  * is returned.
  *
  * Returns: %TRUE if exactly one action was given
- **/
+ */
 gboolean
 gdk_drag_action_is_unique (GdkDragAction action)
 {
diff --git a/gdk/gdkdrag.h b/gdk/gdkdrag.h
index 070b0f812d..9133e0793b 100644
--- a/gdk/gdkdrag.h
+++ b/gdk/gdkdrag.h
@@ -45,7 +45,7 @@ G_BEGIN_DECLS
  * @GDK_DRAG_CANCEL_USER_CANCELLED: Drag cancelled by the user
  * @GDK_DRAG_CANCEL_ERROR: Unspecified error.
  *
- * Used in #GdkDrag to the reason of a cancelled DND operation.
+ * Used in `GdkDrag` to the reason of a cancelled DND operation.
  */
 typedef enum {
   GDK_DRAG_CANCEL_NO_TARGET,
diff --git a/gdk/gdkdragsurface.c b/gdk/gdkdragsurface.c
index 5e41b4bbe7..7000337551 100644
--- a/gdk/gdkdragsurface.c
+++ b/gdk/gdkdragsurface.c
@@ -26,14 +26,13 @@
 /**
  * GdkDragSurface:
  *
- * A #GdkDragSurface is an interface implemented by #GdkSurfaces used
- * during a DND operation.
+ * A #GdkDragSurface is an interface for surfaces used during DND.
  */
 
 /**
  * GdkDragSurfaceInterface:
  *
- * The #GdkDragSurfaceInterface implementation is private to GDK.
+ * The `GdkDragSurfaceInterface` implementation is private to GDK.
  */
 
 G_DEFINE_INTERFACE (GdkDragSurface, gdk_drag_surface, GDK_TYPE_SURFACE)
@@ -54,7 +53,7 @@ gdk_drag_surface_default_init (GdkDragSurfaceInterface *iface)
 
 /**
  * gdk_drag_surface_present:
- * @drag_surface: the #GdkDragSurface to show
+ * @drag_surface: the `GdkDragSurface` to show
  * @width: the unconstrained drag_surface width to layout
  * @height: the unconstrained drag_surface height to layout
  *
diff --git a/gdk/gdkdrawcontext.c b/gdk/gdkdrawcontext.c
index d0ea519e18..451b7499ab 100644
--- a/gdk/gdkdrawcontext.c
+++ b/gdk/gdkdrawcontext.c
@@ -27,24 +27,17 @@
 #include "gdkprofilerprivate.h"
 
 /**
- * SECTION:gdkdrawcontext
- * @Title: GdkDrawContext
- * @Short_description: Base class for draw contexts
+ * GdkDrawContext:
  *
- * #GdkDrawContext is the base object used by contexts implementing different
- * rendering methods, such as #GdkGLContext or #GdkVulkanContext. It provides
- * shared functionality between those contexts.
+ * Base class for objects implementing different rendering methods.
  *
- * You will always interact with one of those subclasses.
+ * `GdkDrawContext` is the base object used by contexts implementing different
+ * rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext].
+ * It provides shared functionality between those contexts.
  *
- * A GdkDrawContext is always associated with a single toplevel surface.
- */
-
-/**
- * GdkDrawContext:
+ * You will always interact with one of those subclasses.
  *
- * The GdkDrawContext struct contains only private fields and should not
- * be accessed directly.
+ * A `GdkDrawContext` is always associated with a single toplevel surface.
  */
 
 typedef struct _GdkDrawContextPrivate GdkDrawContextPrivate;
@@ -148,7 +141,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass)
   /**
    * GdkDrawContext:display:
    *
-   * The #GdkDisplay used to create the #GdkDrawContext.
+   * The `GdkDisplay` used to create the `GdkDrawContext`.
    */
   pspecs[PROP_DISPLAY] =
     g_param_spec_object ("display",
@@ -161,7 +154,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass)
   /**
    * GdkDrawContext:surface:
    *
-   * The #GdkSurface the context is bound to.
+   * The `GdkSurface` the context is bound to.
    */
   pspecs[PROP_SURFACE] =
     g_param_spec_object ("surface",
@@ -186,16 +179,16 @@ gdk_draw_context_init (GdkDrawContext *self)
 
 /**
  * gdk_draw_context_is_in_frame:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
+ *
+ * Returns %TRUE if @context is in the process of drawing to its surface.
  *
- * Returns %TRUE if @context is in the process of drawing to its surface
- * after a call to gdk_draw_context_begin_frame() and not yet having called
- * gdk_draw_context_end_frame().
- * In this situation, drawing commands may be effecting the contents of a
- * @context's surface.
+ * This is the case between calls to [method@Gdk.DrawContext.begin_frame]
+ * and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands
+ * may be effecting the contents of the @context's surface.
  *
- * Returns: %TRUE if the context is between gdk_draw_context_begin_frame() 
- *     and gdk_draw_context_end_frame() calls.
+ * Returns: %TRUE if the context is between [method@Gdk.DrawContext.begin_frame]
+ *     and [method@Gdk.DrawContext.end_frame] calls.
  */
 gboolean
 gdk_draw_context_is_in_frame (GdkDrawContext *context)
@@ -209,9 +202,9 @@ gdk_draw_context_is_in_frame (GdkDrawContext *context)
 
 /*< private >
  * gdk_draw_context_surface_resized:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
  *
- * Called by the #GdkSurface the @context belongs to when the size of the surface
+ * Called by the surface the @context belongs to when the size of the surface
  * changes.
  */
 void
@@ -222,11 +215,11 @@ gdk_draw_context_surface_resized (GdkDrawContext *context)
 
 /**
  * gdk_draw_context_get_display:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
  *
- * Retrieves the #GdkDisplay the @context is created for
+ * Retrieves the `GdkDisplay` the @context is created for
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay or %NULL
+ * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
  */
 GdkDisplay *
 gdk_draw_context_get_display (GdkDrawContext *context)
@@ -240,9 +233,9 @@ gdk_draw_context_get_display (GdkDrawContext *context)
 
 /**
  * gdk_draw_context_get_surface:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
  *
- * Retrieves the #GdkSurface used by the @context.
+ * Retrieves the surface that @context is bound to.
  *
  * Returns: (nullable) (transfer none): a #GdkSurface or %NULL
  */
@@ -258,7 +251,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
 
 /**
  * gdk_draw_context_begin_frame:
- * @context: the context used to draw the frame
+ * @context: the `GdkDrawContext` used to draw the frame
  * @region: minimum region that should be drawn
  *
  * Indicates that you are beginning the process of redrawing @region
@@ -267,23 +260,24 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
  * Calling this function begins a drawing operation using @context on the
  * surface that @context was created from. The actual requirements and
  * guarantees for the drawing operation vary for different implementations
- * of drawing, so a #GdkCairoContext and a #GdkGLContext need to be treated
- * differently.
+ * of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext]
+ * need to be treated differently.
  *
- * A call to this function is a requirement for drawing and must be followed
- * by a call to gdk_draw_context_end_frame(), which will complete the
- * drawing operation and ensure the contents become visible on screen.
+ * A call to this function is a requirement for drawing and must be
+ * followed by a call to [method@Gdk.DrawContext.end_frame], which will
+ * complete the drawing operation and ensure the contents become visible
+ * on screen.
  *
  * Note that the @region passed to this function is the minimum region that
  * needs to be drawn and depending on implementation, windowing system and
  * hardware in use, it might be necessary to draw a larger region. Drawing
- * implementation must use gdk_draw_context_get_frame_region() to query the
- * region that must be drawn.
+ * implementation must use [method@Gdk.DrawContext.get_frame_region() to
+ * query the region that must be drawn.
  *
  * When using GTK, the widget system automatically places calls to
  * gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
- * use of #GskRenderers, so application code does not need to call these
- * functions explicitly.
+ * use of [class@Gsk.Renderer]s, so application code does not need to call
+ * these functions explicitly.
  */
 void
 gdk_draw_context_begin_frame (GdkDrawContext       *context,
@@ -342,13 +336,14 @@ region_get_pixels (cairo_region_t *region)
 
 /**
  * gdk_draw_context_end_frame:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
+ *
+ * Ends a drawing operation started with gdk_draw_context_begin_frame().
  *
- * Ends a drawing operation started with gdk_draw_context_begin_frame()
- * and makes the drawing available on screen. See that function for more
- * details about drawing.
+ * This makes the drawing available on screen.
+ * See [method@Gdk.DrawContext.begin_frame] for more details about drawing.
  *
- * When using a #GdkGLContext, this function may call `glFlush()`
+ * When using a [class@Gdk.GLContext], this function may call `glFlush()`
  * implicitly before returning; it is not recommended to call `glFlush()`
  * explicitly before calling this function.
  */
@@ -389,14 +384,14 @@ gdk_draw_context_end_frame (GdkDrawContext *context)
  * gdk_draw_context_get_frame_region:
  * @context: a #GdkDrawContext
  *
- * Retrieves the region that is currently in the process of being repainted.
+ * Retrieves the region that is currently being repainted.
  *
- * After a call to gdk_draw_context_begin_frame() this function will return
- * a union of the region passed to that function and the area of the surface
- * that the @context determined needs to be repainted.
+ * After a call to [method@Gdk.DrawContext.begin_frame] this function will
+ * return a union of the region passed to that function and the area of the
+ * surface that the @context determined needs to be repainted.
  *
- * If @context is not in between calls to gdk_draw_context_begin_frame() and
- * gdk_draw_context_end_frame(), %NULL will be returned.
+ * If @context is not in between calls to [method@Gdk.DrawContext.begin_frame]
+ * and [method@Gdk.DrawContext.end_frame], %NULL will be returned.
  *
  * Returns: (transfer none) (nullable): a Cairo region or %NULL if not drawing
  *     a frame.
diff --git a/gdk/gdkdrop.c b/gdk/gdkdrop.c
index 289c30ee5d..14c5d267f3 100644
--- a/gdk/gdkdrop.c
+++ b/gdk/gdkdrop.c
@@ -18,17 +18,14 @@
  */
 
 /**
- * SECTION:gdkdrop
- * @Title: Drag And Drop
- * @Short_description: Functions for controlling drag and drop handling
+ * GdkDrop:
  *
- * These functions provide a low-level interface for drag and drop.
+ * The `GdkDrop` object represents the target of an ongoing DND operation.
  *
- * The `GdkDrop` object represents the target side of an ongoing DND operation.
- * Possible drop sites get informed about the status of the ongoing drag operation
- * with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, %GDK_DRAG_MOTION and
- * %GDK_DROP_START. The `GdkDrop` object can be obtained from these
- * [class@Gdk.Event] types using [method@Gdk.DndEvent.get_drop].
+ * Possible drop sites get informed about the status of the ongoing drag
+ * operation with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
+ * %GDK_DRAG_MOTION and %GDK_DROP_START. The `GdkDrop` object can be obtained
+ * from these [class@Gdk.Event] types using [method@Gdk.DndEvent.get_drop].
  *
  * The actual data transfer is initiated from the target side via an async
  * read, using one of the `GdkDrop` methods for this purpose:
@@ -88,13 +85,6 @@ static GParamSpec *properties[N_PROPERTIES] = { NULL, };
 
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrop, gdk_drop, G_TYPE_OBJECT)
 
-/**
- * GdkDrop:
- *
- * The GdkDrop struct contains only private fields and
- * should not be accessed directly.
- */
-
 static void
 gdk_drop_default_status (GdkDrop       *self,
                          GdkDragAction  actions,
@@ -345,7 +335,7 @@ gdk_drop_class_init (GdkDropClass *klass)
   /**
    * GdkDrop:device:
    *
-   * The #GdkDevice performing the drop
+   * The `GdkDevice` performing the drop
    */
   properties[PROP_DEVICE] =
     g_param_spec_object ("device",
@@ -360,7 +350,7 @@ gdk_drop_class_init (GdkDropClass *klass)
   /**
    * GdkDrop:display:
    *
-   * The #GdkDisplay that the drop belongs to.
+   * The `GdkDisplay` that the drop belongs to.
    */
   properties[PROP_DISPLAY] =
     g_param_spec_object ("display",
@@ -374,7 +364,7 @@ gdk_drop_class_init (GdkDropClass *klass)
   /**
    * GdkDrop:drag:
    *
-   * The #GdkDrag that initiated this drop
+   * The `GdkDrag` that initiated this drop
    */
   properties[PROP_DRAG] =
     g_param_spec_object ("drag",
@@ -404,7 +394,7 @@ gdk_drop_class_init (GdkDropClass *klass)
   /**
    * GdkDrop:surface:
    *
-   * The #GdkSurface the drop happens on
+   * The `GdkSurface` the drop happens on
    */
   properties[PROP_SURFACE] =
     g_param_spec_object ("surface",
@@ -426,12 +416,12 @@ gdk_drop_init (GdkDrop *self)
 
 /**
  * gdk_drop_get_display:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  *
- * Gets the #GdkDisplay that @self was created for.
+ * Gets the `GdkDisplay` that @self was created for.
  *
- * Returns: (transfer none): a #GdkDisplay
- **/
+ * Returns: (transfer none): a `GdkDisplay`
+ */
 GdkDisplay *
 gdk_drop_get_display (GdkDrop *self)
 {
@@ -444,12 +434,12 @@ gdk_drop_get_display (GdkDrop *self)
 
 /**
  * gdk_drop_get_device:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  *
- * Returns the #GdkDevice performing the drop.
+ * Returns the `GdkDevice` performing the drop.
  *
- * Returns: (transfer none): The #GdkDevice performing the drop.
- **/
+ * Returns: (transfer none): The `GdkDevice` performing the drop.
+ */
 GdkDevice *
 gdk_drop_get_device (GdkDrop *self)
 {
@@ -462,13 +452,13 @@ gdk_drop_get_device (GdkDrop *self)
 
 /**
  * gdk_drop_get_formats:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  *
- * Returns the #GdkContentFormats that the drop offers the data
+ * Returns the `GdkContentFormats` that the drop offers the data
  * to be read in.
  *
- * Returns: (transfer none): The possible #GdkContentFormats
- **/
+ * Returns: (transfer none): The possible `GdkContentFormats`
+ */
 GdkContentFormats *
 gdk_drop_get_formats (GdkDrop *self)
 {
@@ -481,12 +471,12 @@ gdk_drop_get_formats (GdkDrop *self)
 
 /**
  * gdk_drop_get_surface:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  *
- * Returns the #GdkSurface performing the drop.
+ * Returns the `GdkSurface` performing the drop.
  *
- * Returns: (transfer none): The #GdkSurface performing the drop.
- **/
+ * Returns: (transfer none): The `GdkSurface` performing the drop.
+ */
 GdkSurface *
 gdk_drop_get_surface (GdkDrop *self)
 {
@@ -499,23 +489,25 @@ gdk_drop_get_surface (GdkDrop *self)
 
 /**
  * gdk_drop_get_actions:
- * @self: a #GdkDrop
- *
- * Returns the possible actions for this #GdkDrop. If this value
- * contains multiple actions - ie gdk_drag_action_is_unique()
- * returns %FALSE for the result - gdk_drop_finish() must choose
- * the action to use when accepting the drop. This will only
- * happen if you passed %GDK_ACTION_ASK as one of the possible
- * actions in gdk_drop_status(). %GDK_ACTION_ASK itself will not
+ * @self: a `GdkDrop`
+ *
+ * Returns the possible actions for this `GdkDrop`.
+ *
+ * If this value contains multiple actions - i.e.
+ * [func@Gdk.drag_action_is_unique] returns %FALSE for the result -
+ * [method Gdk Drop.finish] must choose the action to use when
+ * accepting the drop. This will only happen if you passed
+ * %GDK_ACTION_ASK as one of the possible actions in
+ * [method Gdk Drop.status]. %GDK_ACTION_ASK itself will not
  * be included in the actions returned by this function.
  *
- * This value may change over the lifetime of the #GdkDrop both
- * as a response to source side actions as well as to calls to
- * gdk_drop_status() or gdk_drop_finish(). The source side will
- * not change this value anymore once a drop has started.
+ * This value may change over the lifetime of the [class Gdk Drop]
+ * both as a response to source side actions as well as to calls to
+ * [method Gdk Drop.status] or [method Gdk Drop.finish]. The source
+ * side will not change this value anymore once a drop has started.
  *
- * Returns: The possible #GdkDragActions
- **/
+ * Returns: The possible `GdkDragActions`
+ */
 GdkDragAction
 gdk_drop_get_actions (GdkDrop *self)
 {
@@ -546,15 +538,15 @@ gdk_drop_set_actions (GdkDrop       *self,
 
 /**
  * gdk_drop_get_drag:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  *
- * If this is an in-app drag-and-drop operation, returns the #GdkDrag
+ * If this is an in-app drag-and-drop operation, returns the `GdkDrag`
  * that corresponds to this drop.
  *
  * If it is not, %NULL is returned.
  *
- * Returns: (transfer none) (nullable): the corresponding #GdkDrag
- **/
+ * Returns: (transfer none) (nullable): the corresponding `GdkDrag`
+ */
 GdkDrag *
 gdk_drop_get_drag (GdkDrop *self)
 {
@@ -567,16 +559,16 @@ gdk_drop_get_drag (GdkDrop *self)
 
 /**
  * gdk_drop_status:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  * @actions: Supported actions of the destination, or 0 to indicate
  *    that a drop will not be accepted
  * @preferred: A unique action that's a member of @actions indicating the
- *    preferred action.
+ *    preferred action
  *
  * Selects all actions that are potentially supported by the destination.
  *
  * When calling this function, do not restrict the passed in actions to
- * the ones provided by gdk_drop_get_actions(). Those actions may
+ * the ones provided by [method Gdk Drop.get_actions]. Those actions may
  * change in the future, even depending on the actions you provide here.
  *
  * The @preferred action is a hint to the drag'n'drop mechanism about which
@@ -606,15 +598,14 @@ gdk_drop_status (GdkDrop       *self,
 
 /**
  * gdk_drop_finish:
- * @self: a #GdkDrop
- * @action: the action performed by the destination or 0 if the drop
- *     failed
+ * @self: a `GdkDrop`
+ * @action: the action performed by the destination or 0 if the drop failed
  *
  * Ends the drag operation after a drop.
- * 
+ *
  * The @action must be a single action selected from the actions
- * available via gdk_drop_get_actions().
- **/
+ * available via [method Gdk Drop.get_actions].
+ */
 void
 gdk_drop_finish (GdkDrop       *self,
                  GdkDragAction  action)
@@ -664,17 +655,17 @@ gdk_drop_read_internal (GdkDrop             *self,
 
 /**
  * gdk_drop_read_async:
- * @self: a #GdkDrop
+ * @self: a `GdkDrop`
  * @mime_types: (array zero-terminated=1) (element-type utf8):
  *     pointer to an array of mime types
- * @io_priority: the io priority for the read operation
- * @cancellable: (allow-none): optional #GCancellable object,
+ * @io_priority: the I/O priority for the read operation
+ * @cancellable: (allow-none): optional `GCancellable` object,
  *     %NULL to ignore
- * @callback: (scope async): a #GAsyncReadyCallback to call when
+ * @callback: (scope async): a `GAsyncReadyCallback` to call when
  *     the request is satisfied
  * @user_data: (closure): the data to pass to @callback
  *
- * Asynchronously read the dropped data from a #GdkDrop
+ * Asynchronously read the dropped data from a `GdkDrop`
  * in a format that complies with one of the mime types.
  */
 void
@@ -701,14 +692,16 @@ gdk_drop_read_async (GdkDrop             *self,
 
 /**
  * gdk_drop_read_finish:
- * @self: a #GdkDrop
- * @result: a #GAsyncResult
+ * @self: a `GdkDrop`
+ * @result: a `GAsyncResult`
  * @out_mime_type: (out) (type utf8): return location for the used mime type
  * @error: (allow-none): location to store error information on failure, or %NULL
  *
- * Finishes an async drop read operation, see gdk_drop_read_async().
+ * Finishes an async drop read operation.
+ *
+ * See [method Gdk Drop.read_async].
  *
- * Returns: (nullable) (transfer full): the #GInputStream, or %NULL
+ * Returns: (nullable) (transfer full): the `GInputStream`, or %NULL
  */
 GInputStream *
 gdk_drop_read_finish (GdkDrop       *self,
@@ -851,23 +844,24 @@ gdk_drop_read_value_internal (GdkDrop             *self,
 
 /**
  * gdk_drop_read_value_async:
- * @self: a #GdkDrop
- * @type: a #GType to read
- * @io_priority: the [I/O priority][io-priority]
- *     of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @self: a `GdkDrop`
+ * @type: a `GType` to read
+ * @io_priority: the I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
- * Asynchronously request the drag operation's contents converted to the given
- * @type. When the operation is finished @callback will be called. 
- * You can then call gdk_drop_read_value_finish() to get the resulting
- * #GValue.
+ * Asynchronously request the drag operation's contents converted
+ * to the given @type.
  *
- * For local drag'n'drop operations that are available in the given #GType, the
- * value will be copied directly. Otherwise, GDK will try to use
- * gdk_content_deserialize_async() to convert the data.
- **/
+ * When the operation is finished @callback will be called. You must
+ * then call [method Gdk Drop.read_value_finish] to get the resulting
+ * `GValue`.
+ *
+ * For local drag'n'drop operations that are available in the given
+ * `GType`, the value will be copied directly. Otherwise, GDK will
+ * try to use [func@Gdk.content_deserialize_async] to convert the data.
+ */
 void
 gdk_drop_read_value_async (GdkDrop             *self,
                            GType                type,
@@ -891,16 +885,16 @@ gdk_drop_read_value_async (GdkDrop             *self,
 
 /**
  * gdk_drop_read_value_finish:
- * @self: a #GdkDrop
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @self: a `GdkDrop`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an async drop read.
  *
- * Finishes an async drop read started with
- * gdk_drop_read_value_async().
+ * See [method Gdk Drop.read_value_async].
  *
- * Returns: (transfer none): a #GValue containing the result.
- **/
+ * Returns: (transfer none): a `GValue` containing the result.
+ */
 const GValue *
 gdk_drop_read_value_finish (GdkDrop       *self,
                             GAsyncResult  *result,
@@ -1019,4 +1013,3 @@ gdk_drop_emit_drop_event (GdkDrop  *self,
 
   gdk_drop_do_emit_event (event, dont_queue);
 }
-
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index c4548aa227..eb39c95976 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -41,8 +41,8 @@
 /**
  * GdkEvent: (ref-func gdk_event_ref) (unref-func gdk_event_unref)
  *
- * `GdkEvent` and its derived types are immutable data structures,
- * created by GTK itself to represent windowing system events.
+ * `GdkEvent`s are immutable data structures, created by GDK to
+ * represent windowing system events.
  *
  * In GTK applications the events are handled automatically by toplevel
  * widgets and passed on to the event controllers of appropriate widgets,
@@ -52,7 +52,7 @@
 /**
  * GdkEventSequence:
  *
- * GdkEventSequence is an opaque type representing a sequence
+ * `GdkEventSequence` is an opaque type representing a sequence
  * of related touch events.
  */
 
@@ -338,9 +338,9 @@ static GType gdk_event_types[GDK_EVENT_LAST];
 
 /*< private >
  * GDK_EVENT_TYPE_SLOT:
- * @ETYPE: a #GdkEventType
+ * @ETYPE: a `GdkEvent`Type
  *
- * Associates a #GdkEvent type with the given #GdkEventType enumeration.
+ * Associates a `GdkEvent` type with the given `GdkEvent`Type enumeration.
  *
  * This macro can only be used with %GDK_DEFINE_EVENT_TYPE.
  */
@@ -350,10 +350,10 @@ static GType gdk_event_types[GDK_EVENT_LAST];
  * GDK_DEFINE_EVENT_TYPE:
  * @TypeName: the type name, in camel case
  * @type_name: the type name, in snake case
- * @type_info: the address of the #GdkEventTypeInfo for the event type
+ * @type_info: the address of the `GdkEvent`TypeInfo for the event type
  * @_C_: custom code to call after registering the event type
  *
- * Registers a new #GdkEvent subclass with the given @TypeName and @type_info.
+ * Registers a new `GdkEvent` subclass with the given @TypeName and @type_info.
  *
  * Similarly to %G_DEFINE_TYPE_WITH_CODE, this macro will generate a `get_type()`
  * function that registers the event type.
@@ -381,15 +381,15 @@ type_name ## _get_type (void) \
 
 /*< private >
  * gdk_event_alloc:
- * @event_type: the #GdkEventType to allocate
+ * @event_type: the `GdkEvent`Type to allocate
  * @surface: (nullable): the #GdkSurface of the event
  * @device: (nullable): the #GdkDevice of the event
  * @time_: the event serial
  *
- * Allocates a #GdkEvent for the given @event_type, and sets its
+ * Allocates a `GdkEvent` for the given @event_type, and sets its
  * common fields with the given parameters.
  *
- * Returns: (transfer full): the newly allocated #GdkEvent instance
+ * Returns: (transfer full): the newly allocated `GdkEvent` instance
  */
 static gpointer
 gdk_event_alloc (GdkEventType event_type,
@@ -820,7 +820,7 @@ _gdk_event_queue_flush (GdkDisplay *display)
 
 /**
  * gdk_event_ref:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
  * Increase the ref count of @event.
  *
@@ -838,10 +838,11 @@ gdk_event_ref (GdkEvent *event)
 
 /**
  * gdk_event_unref:
- * @event: (transfer full): a #GdkEvent
+ * @event: (transfer full): a `GdkEvent`
  *
- * Decrease the ref count of @event, and free it
- * if the last reference is dropped.
+ * Decrease the ref count of @event.
+ *
+ * If the last reference is dropped, the structure is freed.
  */
 void
 gdk_event_unref (GdkEvent *event)
@@ -854,10 +855,11 @@ gdk_event_unref (GdkEvent *event)
 
 /**
  * gdk_event_get_pointer_emulated:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
+ *
+ * Returns whether this event is an 'emulated' pointer event.
  *
- * Returns whether this event is an 'emulated' pointer event (typically
- * from a touch event), as opposed to a real one.
+ * Emulated pointer events typically originate from a touch events.
  *
  * Returns: %TRUE if this event is emulated
  */
@@ -893,7 +895,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event)
 
 /**
  * gdk_event_get_axis:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  * @axis_use: the axis use to look for
  * @value: (out): location to store the value found
  *
@@ -901,7 +903,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event)
  * an event structure.
  *
  * Returns: %TRUE if the specified axis was found, otherwise %FALSE
- **/
+ */
 gboolean
 gdk_event_get_axis (GdkEvent   *event,
                    GdkAxisUse  axis_use,
@@ -936,17 +938,18 @@ gdk_event_get_axis (GdkEvent   *event,
 
 /**
  * gdk_event_triggers_context_menu:
- * @event: a #GdkEvent, currently only button events are meaningful values
+ * @event: a `GdkEvent`, currently only button events are meaningful values
+ *
+ * Returns whether a `GdkEvent` should trigger a context menu,
+ * according to platform conventions.
  *
- * This function returns whether a #GdkEvent should trigger a
- * context menu, according to platform conventions. The right
- * mouse button always triggers context menus.
+ * The right mouse button typically triggers context menus.
  *
  * This function should always be used instead of simply checking for
  * event->button == %GDK_BUTTON_SECONDARY.
  *
  * Returns: %TRUE if the event should trigger a context menu.
- **/
+ */
 gboolean
 gdk_event_triggers_context_menu (GdkEvent *event)
 {
@@ -997,12 +1000,14 @@ gdk_events_get_axis_distances (GdkEvent *event1,
 
 /**
  * gdk_events_get_distance:
- * @event1: first #GdkEvent
- * @event2: second #GdkEvent
+ * @event1: first `GdkEvent`
+ * @event2: second `GdkEvent`
  * @distance: (out): return location for the distance
  *
- * If both events have X/Y information, the distance between both coordinates
- * (as in a straight line going from @event1 to @event2) will be returned.
+ * Returns the distance between the event locations.
+ *
+ * This assumes that both events have X/Y information.
+ * If not, this function returns %FALSE.
  *
  * Returns: %TRUE if the distance could be calculated.
  **/
@@ -1018,17 +1023,21 @@ gdk_events_get_distance (GdkEvent *event1,
 
 /**
  * gdk_events_get_angle:
- * @event1: first #GdkEvent
- * @event2: second #GdkEvent
+ * @event1: first `GdkEvent`
+ * @event2: second `GdkEvent`
  * @angle: (out): return location for the relative angle between both events
  *
- * If both events contain X/Y information, this function will return %TRUE
- * and return in @angle the relative angle from @event1 to @event2. The rotation
- * direction for positive angles is from the positive X axis towards the positive
- * Y axis.
+ * Returns the relative angle from @event1 to @event2.
+ *
+ * The relative angle is the angle between the X axis and the line
+ * through both events' positions. The rotation direction for positive
+ * angles is from the positive X axis towards the positive Y axis.
+ *
+ * This assumes that both events have X/Y information.
+ * If not, this function returns %FALSE.
  *
  * Returns: %TRUE if the angle could be calculated.
- **/
+ */
 gboolean
 gdk_events_get_angle (GdkEvent *event1,
                       GdkEvent *event2,
@@ -1060,16 +1069,18 @@ gdk_events_get_angle (GdkEvent *event1,
 
 /**
  * gdk_events_get_center:
- * @event1: first #GdkEvent
- * @event2: second #GdkEvent
+ * @event1: first `GdkEvent`
+ * @event2: second `GdkEvent`
  * @x: (out): return location for the X coordinate of the center
  * @y: (out): return location for the Y coordinate of the center
  *
- * If both events contain X/Y information, the center of both coordinates
- * will be returned in @x and @y.
+ * Returns the point halfway between the events' positions.
+ *
+ * This assumes that both events have X/Y information.
+ * If not, this function returns %FALSE.
  *
  * Returns: %TRUE if the center could be calculated.
- **/
+ */
 gboolean
 gdk_events_get_center (GdkEvent *event1,
                        GdkEvent *event2,
@@ -1111,14 +1122,14 @@ G_DEFINE_BOXED_TYPE (GdkEventSequence, gdk_event_sequence,
 
 /**
  * gdk_event_get_axes:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  * @axes: (transfer none) (out) (array length=n_axes): the array of values for all axes
  * @n_axes: (out): the length of array
  *
  * Extracts all axis values from an event.
  *
  * Returns: %TRUE on success, otherwise %FALSE
- **/
+ */
 gboolean
 gdk_event_get_axes (GdkEvent  *event,
                     double   **axes,
@@ -1147,11 +1158,11 @@ gdk_event_dup_axes (GdkEvent *event)
 
 /**
  * gdk_event_get_event_type:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
  * Retrieves the type of the event.
  *
- * Returns: a #GdkEventType
+ * Returns: a `GdkEvent`Type
  */
 GdkEventType
 gdk_event_get_event_type (GdkEvent *event)
@@ -1163,9 +1174,9 @@ gdk_event_get_event_type (GdkEvent *event)
 
 /**
  * gdk_event_get_surface:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
- * Extracts the #GdkSurface associated with an event.
+ * Extracts the surface associated with an event.
  *
  * Returns: (transfer none): The #GdkSurface associated with the event
  */
@@ -1179,7 +1190,7 @@ gdk_event_get_surface (GdkEvent *event)
 
 /**
  * gdk_event_get_seat:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
  * Returns the seat that originated the event.
  *
@@ -1195,7 +1206,7 @@ gdk_event_get_seat (GdkEvent *event)
 
 /**
  * gdk_event_get_device:
- * @event: a #GdkEvent.
+ * @event: a `GdkEvent`.
  *
  * Returns the device of an event.
  *
@@ -1211,16 +1222,18 @@ gdk_event_get_device (GdkEvent *event)
 
 /**
  * gdk_event_get_device_tool:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
+ *
+ * Returns a `GdkDeviceTool` representing the tool that
+ * caused the event.
  *
- * If the event was generated by a device that supports
- * different tools (eg. a tablet), this function will
- * return a #GdkDeviceTool representing the tool that
- * caused the event. Otherwise, %NULL will be returned.
+ * If the was not generated by a device that supports
+ * different tools (such as a tablet), this function will
+ * return %NULL.
  *
- * Note: the #GdkDeviceTools will be constant during
+ * Note: the `GdkDeviceTool` will be constant during
  * the application lifetime, if settings must be stored
- * persistently across runs, see gdk_device_tool_get_serial()
+ * persistently across runs, see [method@Gdk.DeviceTool.get_serial].
  *
  * Returns: (transfer none) (nullable): The current device tool, or %NULL
  **/
@@ -1234,13 +1247,15 @@ gdk_event_get_device_tool (GdkEvent *event)
 
 /**
  * gdk_event_get_time:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
- * Returns the time stamp from @event, if there is one; otherwise
- * returns #GDK_CURRENT_TIME.
+ * Returns the timestamp of @event.
  *
- * Returns: time stamp field from @event
- **/
+ * Not all events have timestamps. In that case, this function
+ * returns %GDK_CURRENT_TIME.
+ *
+ * Returns: timestamp field from @event
+ */
 guint32
 gdk_event_get_time (GdkEvent *event)
 {
@@ -1251,9 +1266,9 @@ gdk_event_get_time (GdkEvent *event)
 
 /**
  * gdk_event_get_display:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
- * Retrieves the #GdkDisplay associated to the @event.
+ * Retrieves the display associated to the @event.
  *
  * Returns: (transfer none) (nullable): a #GdkDisplay
  */
@@ -1270,10 +1285,12 @@ gdk_event_get_display (GdkEvent *event)
 
 /**
  * gdk_event_get_event_sequence:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
+ *
+ * Retuns the event sequence to which the event belongs.
  *
- * If @event is a touch event, returns the #GdkEventSequence
- * to which the event belongs. Otherwise, return %NULL.
+ * Related touch events are connected in a sequence. Other
+ * events typically don't have event sequence information.
  *
  * Returns: (transfer none): the event sequence that the event belongs to
  */
@@ -1287,12 +1304,12 @@ gdk_event_get_event_sequence (GdkEvent *event)
 
 /**
  * gdk_event_get_modifier_state:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  *
  * Returns the modifier state field of an event.
  *
  * Returns: the modifier state of @event
- **/
+ */
 GdkModifierType
 gdk_event_get_modifier_state (GdkEvent *event)
 {
@@ -1303,12 +1320,12 @@ gdk_event_get_modifier_state (GdkEvent *event)
 
 /**
  * gdk_event_get_position:
- * @event: a #GdkEvent
+ * @event: a `GdkEvent`
  * @x: (out): location to put event surface x coordinate
  * @y: (out): location to put event surface y coordinate
  *
  * Extract the event surface relative x/y coordinates from an event.
- **/
+ */
 gboolean
 gdk_event_get_position (GdkEvent *event,
                         double   *x,
@@ -1324,7 +1341,7 @@ gdk_event_get_position (GdkEvent *event,
 /**
  * GdkButtonEvent:
  *
- * An event related to a button on a pointer device/
+ * An event related to a button on a pointer device.
  */
 
 static void
@@ -1484,8 +1501,8 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event,
 /*< private >
  * gdk_key_event_new:
  * @type: the event type, either %GDK_KEY_PRESS or %GDK_KEY_RELEASE
- * @surface: the #GdkSurface of the event
- * @device: the #GdkDevice related to the event
+ * @surface: the surface of the event
+ * @device: the device related to the event
  * @time: the event's timestamp
  * @keycode: the keycode of the event
  * @state: the modifiers state
@@ -1493,9 +1510,9 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event,
  * @translated: the translated key data for the given @state
  * @no_lock: the translated key data without the given @state
  *
- * Creates a new #GdkKeyEvent.
+ * Creates a new `GdkKeyEvent`.
  *
- * Returns: (transfer full) (type GdkKeyEvent): the newly created #GdkEvent
+ * Returns: (transfer full) (type GdkKeyEvent): the newly created `GdkEvent`
  */
 GdkEvent *
 gdk_key_event_new (GdkEventType      type,
@@ -1671,17 +1688,20 @@ gdk_key_event_is_modifier (GdkEvent *event)
 
 /**
  * gdk_key_event_matches:
- * @event: (type GdkKeyEvent): a key #GdkEvent
+ * @event: (type GdkKeyEvent): a key `GdkEvent`
  * @keyval: the keyval to match
  * @modifiers: the modifiers to match
  *
- * Matches a key event against a keyboard shortcut that is specified
- * as a keyval and modifiers. Partial matches are possible where the
- * combination matches if the currently active group is ignored.
+ * Matches a key event against a keyval and modifiers.
+ *
+ * This is typically used to trigger keyboard shortcuts such as Ctrl-C.
+ *
+ * Partial matches are possible where the combination matches
+ * if the currently active group is ignored.
  *
  * Note that we ignore Caps Lock for matching.
  *
- * Returns: a GdkKeyMatch value describing whether @event matches
+ * Returns: a `GdkKeyMatch` value describing whether @event matches
  */
 GdkKeyMatch
 gdk_key_event_matches (GdkEvent        *event,
@@ -1773,12 +1793,14 @@ gdk_key_event_matches (GdkEvent        *event,
 
 /**
  * gdk_key_event_get_match:
- * @event: (type GdkKeyEvent): a key #GdkEvent
+ * @event: (type GdkKeyEvent): a key `GdkEvent`
  * @keyval: (out): return location for a keyval
  * @modifiers: (out): return location for modifiers
  *
- * Gets a keyval and modifier combination that will cause
- * gdk_key_event_matches() to successfully match the given event.
+ * Gets a keyval and modifier combination that will match
+ * the event.
+ *
+ * See [method@Gdk.KeyEvent.matches].
  *
  * Returns: %TRUE on success
  */
@@ -2153,7 +2175,7 @@ gdk_delete_event_new (GdkSurface *surface)
 /**
  * GdkFocusEvent:
  *
- * An event related to a focus change.
+ * An event related to a keyboard focus change.
  */
 
 static const GdkEventTypeInfo gdk_focus_event_info = {
@@ -2345,11 +2367,13 @@ gdk_scroll_event_get_deltas (GdkEvent *event,
  * gdk_scroll_event_is_stop:
  * @event: (type GdkScrollEvent): a scroll event
  *
- * Check whether a scroll event is a stop scroll event. Scroll sequences
- * with smooth scroll information may provide a stop scroll event once the
- * interaction with the device finishes, e.g. by lifting a finger. This
- * stop scroll event is the signal that a widget may trigger kinetic
- * scrolling based on the current velocity.
+ * Check whether a scroll event is a stop scroll event.
+ *
+ * Scroll sequences with smooth scroll information may provide
+ * a stop scroll event once the interaction with the device finishes,
+ * e.g. by lifting a finger. This stop scroll event is the signal
+ * that a widget may trigger kinetic scrolling based on the current
+ * velocity.
  *
  * Stop scroll events always have a delta of 0/0.
  *
@@ -2373,7 +2397,12 @@ gdk_scroll_event_is_stop (GdkEvent *event)
 /**
  * GdkTouchpadEvent:
  *
- * An event related to a touchpad device.
+ * An event related to a gesture on a touchpad device.
+ *
+ * Unlike touchscreens, where the windowing system sends basic
+ * sequences of begin, update, end events, and leaves gesture
+ * recognition to the clients, touchpad gestures are typically
+ * processed by the system, resulting in these events.
  */
 
 static GdkModifierType
@@ -2469,7 +2498,7 @@ gdk_touchpad_event_new_pinch (GdkSurface *surface,
 
 /**
  * gdk_touchpad_event_get_gesture_phase:
- * @event: (type GdkTouchpadEvent): a touchpad #GdkEvent
+ * @event: (type GdkTouchpadEvent): a touchpad event
  *
  * Extracts the touchpad gesture phase from a touchpad event.
  *
@@ -2514,7 +2543,7 @@ gdk_touchpad_event_get_n_fingers (GdkEvent *event)
  * @dy: (out): return location for y
  *
  * Extracts delta information from a touchpad event.
- **/
+ */
 void
 gdk_touchpad_event_get_deltas (GdkEvent *event,
                                double   *dx,
@@ -2680,7 +2709,7 @@ gdk_pad_event_new_group_mode (GdkSurface *surface,
  * a pad event.
  *
  * Returns: the button of @event
- **/
+ */
 guint
 gdk_pad_event_get_button (GdkEvent *event)
 {
@@ -2700,7 +2729,7 @@ gdk_pad_event_get_button (GdkEvent *event)
  * @value: (out): Return location for the axis value
  *
  * Extracts the information from a pad strip or ring event.
- **/
+ */
 void
 gdk_pad_event_get_axis_value (GdkEvent *event,
                               guint    *index,
@@ -2723,7 +2752,7 @@ gdk_pad_event_get_axis_value (GdkEvent *event,
  * @mode: (out): return location for the mode
  *
  * Extracts group and mode information from a pad event.
- **/
+ */
 void
 gdk_pad_event_get_group_mode (GdkEvent *event,
                               guint    *group,
@@ -2850,16 +2879,17 @@ gdk_motion_event_new (GdkSurface      *surface,
 
 /**
  * gdk_event_get_history:
- * @event: a motion or scroll #GdkEvent
+ * @event: a motion or scroll event
  * @out_n_coords: (out): Return location for the length of the returned array
  *
- * Retrieves the history of the @event, as a list of time and coordinates.
+ * Retrieves the history of the device that @event is for, as a list of
+ * time and coordinates.
  *
- * The history includes events that are not delivered to the application
- * because they occurred in the same frame as @event.
+ * The history includes positions that are not delivered as separate events
+ * to the application because they occurred in the same frame as @event.
  *
  * Note that only motion and scroll events record history, and motion
- * events only if one of the mouse buttons is down.
+ * events do it only if one of the mouse buttons is down.
  *
  * Returns: (transfer container) (array length=out_n_coords) (nullable): an
  *   array of time and coordinates
@@ -3053,7 +3083,7 @@ gdk_dnd_event_new (GdkEventType  type,
  * gdk_dnd_event_get_drop:
  * @event: (type GdkDNDEvent): a DND event
  *
- * Gets the #GdkDrop from a DND event.
+ * Gets the `GdkDrop` object from a DND event.
  *
  * Returns: (transfer none) (nullable): the drop
  **/
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 2b87754eec..e038501cd2 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -47,10 +47,9 @@ G_BEGIN_DECLS
 #define GDK_IS_EVENT_TYPE(event, type)  (gdk_event_get_event_type ((event)) == (type))
 
 /**
- * GDK_PRIORITY_EVENTS:
+ * GDK_PRIORITY_EVENTS: (value: 0)
  *
- * This is the priority that events from the X server are given in the
- * [GLib Main Loop][glib-The-Main-Event-Loop].
+ * This is the priority that events from the X server are given in the main loop.
  */
 #define GDK_PRIORITY_EVENTS    (G_PRIORITY_DEFAULT)
 
@@ -58,8 +57,7 @@ G_BEGIN_DECLS
  * GDK_PRIORITY_REDRAW: (value 120)
  *
  * This is the priority that the idle handler processing surface updates
- * is given in the
- * [GLib Main Loop][glib-The-Main-Event-Loop].
+ * is given in the main loop.
  */
 #define GDK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)
 
@@ -216,9 +214,11 @@ typedef enum
  * @GDK_TOUCHPAD_GESTURE_PHASE_CANCEL: The gesture was cancelled, all
  *   changes should be undone.
  *
- * Specifies the current state of a touchpad gesture. All gestures are
- * guaranteed to begin with an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN,
- * followed by 0 or several events with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE.
+ * Specifies the current state of a touchpad gesture.
+ *
+ * All gestures are guaranteed to begin with an event with phase
+ * %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by 0 or several events
+ * with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE.
  *
  * A finished gesture may have 2 possible outcomes, an event with phase
  * %GDK_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is
@@ -494,8 +494,9 @@ gboolean                gdk_events_get_center           (GdkEvent *event1,
  *     (specifically, the currently active group) is ignored
  * @GDK_KEY_MATCH_EXACT: The key event matches
  *
- * The possible return values from gdk_key_event_matches()
- * describe how well an event matches a given keyval and modifiers.
+ * Describes how well an event matches a given keyval and modifiers.
+ *
+ * `GdkKeyMatch` values are returned by [method@Gdk.KeyEvent.matches].
  */
 typedef enum {
   GDK_KEY_MATCH_NONE,
diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c
index 5e4492744c..0a4e915b2a 100644
--- a/gdk/gdkframeclock.c
+++ b/gdk/gdkframeclock.c
@@ -28,52 +28,43 @@
 #include "gdkinternals.h"
 
 /**
- * SECTION:gdkframeclock
- * @Title: GdkFrameClock
- * @Short_description: Synchronizes painting to a surface
- *
- * A #GdkFrameClock tells the application when to update and repaint
- * a surface. This may be synced to the vertical refresh rate of the
- * monitor, for example. Even when the frame clock uses a simple timer
- * rather than a hardware-based vertical sync, the frame clock helps
- * because it ensures everything paints at the same time (reducing the
- * total number of frames). The frame clock can also automatically
- * stop painting when it knows the frames will not be visible, or
- * scale back animation framerates.
- *
- * #GdkFrameClock is designed to be compatible with an OpenGL-based
- * implementation or with mozRequestAnimationFrame in Firefox,
- * for example.
+ * GdkFrameClock:
+ *
+ * A `GdkFrameClock` tells the application when to update and repaint
+ * a surface.
+ *
+ * This may be synced to the vertical refresh rate of the monitor, for example.
+ * Even when the frame clock uses a simple timer rather than a hardware-based
+ * vertical sync, the frame clock helps because it ensures everything paints at
+ * the same time (reducing the total number of frames).
+ *
+ * The frame clock can also automatically stop painting when it knows the frames
+ * will not be visible, or scale back animation framerates.
+ *
+ * `GdkFrameClock` is designed to be compatible with an OpenGL-based implementation
+ * or with mozRequestAnimationFrame in Firefox, for example.
  *
  * A frame clock is idle until someone requests a frame with
- * gdk_frame_clock_request_phase(). At some later point that makes
- * sense for the synchronization being implemented, the clock will
- * process a frame and emit signals for each phase that has been
- * requested. (See the signals of the #GdkFrameClock class for
- * documentation of the phases. %GDK_FRAME_CLOCK_PHASE_UPDATE and the
- * #GdkFrameClock::update signal are most interesting for application
- * writers, and are used to update the animations, using the frame time
- * given by gdk_frame_clock_get_frame_time().
+ * [method@Gdk.FrameClock.request_phase]. At some later point that makes sense
+ * for the synchronization being implemented, the clock will process a frame and
+ * emit signals for each phase that has been requested. (See the signals of the
+ * `GdkFrameClock` class for documentation of the phases.
+ * %GDK_FRAME_CLOCK_PHASE_UPDATE and the [signal@GdkFrameClock::update] signal
+ * are most interesting for application writers, and are used to update the
+ * animations, using the frame time given by [metohd@Gdk.FrameClock.get_frame_time].
  *
  * The frame time is reported in microseconds and generally in the same
  * timescale as g_get_monotonic_time(), however, it is not the same
  * as g_get_monotonic_time(). The frame time does not advance during
  * the time a frame is being painted, and outside of a frame, an attempt
- * is made so that all calls to gdk_frame_clock_get_frame_time() that
+ * is made so that all calls to [method@Gdk.FrameClock.get_frame_time] that
  * are called at a “similar” time get the same value. This means that
  * if different animations are timed by looking at the difference in
- * time between an initial value from gdk_frame_clock_get_frame_time()
- * and the value inside the #GdkFrameClock::update signal of the clock,
+ * time between an initial value from [method@Gdk.FrameClock.get_frame_time]
+ * and the value inside the [signal@GdkFrameClock::update] signal of the clock,
  * they will stay exactly synchronized.
  */
 
-/**
- * GdkFrameClock:
- *
- * The GdkFrameClock struct contains only private fields and
- * should not be accessed directly.
- */
-
 enum {
   FLUSH_EVENTS,
   BEFORE_PAINT,
@@ -138,9 +129,10 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::flush-events:
    * @clock: the frame clock emitting the signal
    *
-   * This signal is used to flush pending motion events that
-   * are being batched up and compressed together. Applications
-   * should not handle this signal.
+   * Used to flush pending motion events that are being batched up and
+   * compressed together.
+   *
+   * Applications should not handle this signal.
    */
   signals[FLUSH_EVENTS] =
     g_signal_new (g_intern_static_string ("flush-events"),
@@ -154,8 +146,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::before-paint:
    * @clock: the frame clock emitting the signal
    *
-   * This signal begins processing of the frame. Applications
-   * should generally not handle this signal.
+   * Begins processing of the frame.
+   *
+   * Applications should generally not handle this signal.
    */
   signals[BEFORE_PAINT] =
     g_signal_new (g_intern_static_string ("before-paint"),
@@ -169,12 +162,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::update:
    * @clock: the frame clock emitting the signal
    *
-   * This signal is emitted as the first step of toolkit and
-   * application processing of the frame. Animations should
-   * be updated using gdk_frame_clock_get_frame_time().
-   * Applications can connect directly to this signal, or
-   * use gtk_widget_add_tick_callback() as a more convenient
-   * interface.
+   * Emitted as the first step of toolkit and application processing
+   * of the frame.
+   *
+   * Animations should be updated using [method@Gdk.FrameClock.get_frame_time].
+   * Applications can connect directly to this signal, or use
+   * [method@Gtk.Widget.add_tick_callback] as a more convenient interface.
    */
   signals[UPDATE] =
     g_signal_new (g_intern_static_string ("update"),
@@ -188,10 +181,11 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::layout:
    * @clock: the frame clock emitting the signal
    *
-   * This signal is emitted as the second step of toolkit and
-   * application processing of the frame. Any work to update
-   * sizes and positions of application elements should be
-   * performed. GTK normally handles this internally.
+   * Emitted as the second step of toolkit and application processing
+   * of the frame.
+   *
+   * Any work to update sizes and positions of application elements
+   * should be performed. GTK normally handles this internally.
    */
   signals[LAYOUT] =
     g_signal_new (g_intern_static_string ("layout"),
@@ -205,11 +199,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::paint:
    * @clock: the frame clock emitting the signal
    *
-   * This signal is emitted as the third step of toolkit and
-   * application processing of the frame. The frame is
-   * repainted. GDK normally handles this internally and
-   * emits #GdkSurface::render which are turned into
-   * #GtkWidget::snapshot signals by GTK.
+   * Emitted as the third step of toolkit and application processing
+   * of the frame.
+   *
+   * The frame is repainted. GDK normally handles this internally and
+   * emits [signal@GdkSurface::render] signals which are turned into
+   * [signal@GtkWidget::snapshot] signals by GTK.
    */
   signals[PAINT] =
     g_signal_new (g_intern_static_string ("paint"),
@@ -223,8 +218,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::after-paint:
    * @clock: the frame clock emitting the signal
    *
-   * This signal ends processing of the frame. Applications
-   * should generally not handle this signal.
+   * This signal ends processing of the frame.
+   *
+   * Applications should generally not handle this signal.
    */
   signals[AFTER_PAINT] =
     g_signal_new (g_intern_static_string ("after-paint"),
@@ -238,8 +234,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * GdkFrameClock::resume-events:
    * @clock: the frame clock emitting the signal
    *
-   * This signal is emitted after processing of the frame is
-   * finished, and is handled internally by GTK to resume normal
+   * Emitted after processing of the frame is finished.
+   *
+   * This signal is handled internally by GTK to resume normal
    * event processing. Applications should not handle this signal.
    */
   signals[RESUME_EVENTS] =
@@ -267,10 +264,11 @@ gdk_frame_clock_init (GdkFrameClock *clock)
 
 /**
  * gdk_frame_clock_get_frame_time:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
+ *
+ * Gets the time that should currently be used for animations.
  *
- * Gets the time that should currently be used for animations.  Inside
- * the processing of a frame, it’s the time used to compute the
+ * Inside the processing of a frame, it’s the time used to compute the
  * animation position of everything in a frame. Outside of a frame, it's
  * the time of the conceptual “previous frame,” which may be either
  * the actual previous frame time, or if that’s too old, an updated
@@ -289,18 +287,19 @@ gdk_frame_clock_get_frame_time (GdkFrameClock *frame_clock)
 
 /**
  * gdk_frame_clock_request_phase:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  * @phase: the phase that is requested
  *
- * Asks the frame clock to run a particular phase. The signal
- * corresponding the requested phase will be emitted the next
+ * Asks the frame clock to run a particular phase.
+ *
+ * The signal corresponding the requested phase will be emitted the next
  * time the frame clock processes. Multiple calls to
  * gdk_frame_clock_request_phase() will be combined together
  * and only one frame processed. If you are displaying animated
  * content and want to continually request the
  * %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time,
- * you should use gdk_frame_clock_begin_updating() instead, since
- * this allows GTK to adjust system parameters to get maximally
+ * you should use [method@Gdk.FrameClock.begin_updating] instead,
+ * since this allows GTK to adjust system parameters to get maximally
  * smooth animations.
  */
 void
@@ -314,14 +313,15 @@ gdk_frame_clock_request_phase (GdkFrameClock      *frame_clock,
 
 /**
  * gdk_frame_clock_begin_updating:
- * @frame_clock: a #GdkFrameClock
- *
- * Starts updates for an animation. Until a matching call to
- * gdk_frame_clock_end_updating() is made, the frame clock will continually
- * request a new frame with the %GDK_FRAME_CLOCK_PHASE_UPDATE phase.
- * This function may be called multiple times and frames will be
- * requested until gdk_frame_clock_end_updating() is called the same
- * number of times.
+ * @frame_clock: a `GdkFrameClock`
+ *
+ * Starts updates for an animation.
+ *
+ * Until a matching call to [method@Gdk.FrameClock.end_updating] is made,
+ * the frame clock will continually request a new frame with the
+ * %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple
+ * times and frames will be requested until gdk_frame_clock_end_updating()
+ * is called the same number of times.
  */
 void
 gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock)
@@ -333,10 +333,11 @@ gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock)
 
 /**
  * gdk_frame_clock_end_updating:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  *
- * Stops updates for an animation. See the documentation for
- * gdk_frame_clock_begin_updating().
+ * Stops updates for an animation.
+ *
+ * See the documentation for [method@Gdk.FrameClock.begin_updating].
  */
 void
 gdk_frame_clock_end_updating (GdkFrameClock *frame_clock)
@@ -354,7 +355,6 @@ _gdk_frame_clock_freeze (GdkFrameClock *clock)
   GDK_FRAME_CLOCK_GET_CLASS (clock)->freeze (clock);
 }
 
-
 static void
 _gdk_frame_clock_thaw (GdkFrameClock *clock)
 {
@@ -377,7 +377,6 @@ _gdk_frame_clock_inhibit_freeze (GdkFrameClock *clock)
     _gdk_frame_clock_thaw (clock);
 }
 
-
 void
 _gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock)
 {
@@ -394,13 +393,13 @@ _gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock)
 
 /**
  * gdk_frame_clock_get_frame_counter:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  *
- * A #GdkFrameClock maintains a 64-bit counter that increments for
+ * `GdkFrameClock` maintains a 64-bit counter that increments for
  * each frame drawn.
  *
  * Returns: inside frame processing, the value of the frame counter
- *  for the current frame. Outside of frame processing, the frame
+ *   for the current frame. Outside of frame processing, the frame
  *   counter for the last frame.
  */
 gint64
@@ -417,18 +416,20 @@ gdk_frame_clock_get_frame_counter (GdkFrameClock *frame_clock)
 
 /**
  * gdk_frame_clock_get_history_start:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  *
- * #GdkFrameClock internally keeps a history of #GdkFrameTimings
+ * Returns the frame counter for the oldest frame available in history.
+ *
+ * `GdkFrameClock` internally keeps a history of `GdkFrameTimings`
  * objects for recent frames that can be retrieved with
- * gdk_frame_clock_get_timings(). The set of stored frames
+ * [method@Gdk.FrameClock.get_timings]. The set of stored frames
  * is the set from the counter values given by
- * gdk_frame_clock_get_history_start() and
- * gdk_frame_clock_get_frame_counter(), inclusive.
+ * [method@Gdk.FrameClock.get_history_start] and
+ * [method@Gdk.FrameClock.get_frame_counter], inclusive.
  *
  * Returns: the frame counter value for the oldest frame
  *  that is available in the internal frame history of the
- *  #GdkFrameClock.
+ *  `GdkFrameClock`
  */
 gint64
 gdk_frame_clock_get_history_start (GdkFrameClock *frame_clock)
@@ -472,17 +473,19 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock)
 
 /**
  * gdk_frame_clock_get_timings:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  * @frame_counter: the frame counter value identifying the frame to
- *  be received.
+ *  be received
+ *
+ * Retrieves a `GdkFrameTimings` object holding timing information
+ * for the current frame or a recent frame.
  *
- * Retrieves a #GdkFrameTimings object holding timing information
- * for the current frame or a recent frame. The #GdkFrameTimings
- * object may not yet be complete: see gdk_frame_timings_get_complete().
+ * The `GdkFrameTimings` object may not yet be complete: see
+ * [method@Gdk.FrameTimings.get_complete].
  *
- * Returns: (nullable) (transfer none): the #GdkFrameTimings object for
- *  the specified frame, or %NULL if it is not available. See
- *  gdk_frame_clock_get_history_start().
+ * Returns: (nullable) (transfer none): the `GdkFrameTimings` object
+ *   for the specified frame, or %NULL if it is not available. See
+ *   [method@Gdk.FrameClock.get_history_start].
  */
 GdkFrameTimings *
 gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
@@ -508,14 +511,14 @@ gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
 
 /**
  * gdk_frame_clock_get_current_timings:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  *
  * Gets the frame timings for the current frame.
  *
- * Returns: (nullable) (transfer none): the #GdkFrameTimings for the
- *  frame currently being processed, or even no frame is being
- *  processed, for the previous frame. Before any frames have been
- *  processed, returns %NULL.
+ * Returns: (nullable) (transfer none): the `GdkFrameTimings` for the
+ *   frame currently being processed, or even no frame is being
+ *   processed, for the previous frame. Before any frames have been
+ *   processed, returns %NULL.
  */
 GdkFrameTimings *
 gdk_frame_clock_get_current_timings (GdkFrameClock *frame_clock)
@@ -584,14 +587,16 @@ _gdk_frame_clock_debug_print_timings (GdkFrameClock   *clock,
 
 /**
  * gdk_frame_clock_get_refresh_info:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  * @base_time: base time for determining a presentaton time
  * @refresh_interval_return: (out) (optional): a location to store the
- * determined refresh interval, or %NULL. A default refresh interval of
- * 1/60th of a second will be stored if no history is present.
+ *   determined refresh interval, or %NULL. A default refresh interval of
+ *   1/60th of a second will be stored if no history is present.
  * @presentation_time_return: (out): a location to store the next
- *  candidate presentation time after the given base time.
- *  0 will be will be stored if no history is present.
+ *   candidate presentation time after the given base time.
+ *   0 will be will be stored if no history is present.
+ *
+ * Predicts a presentation time, based on history.
  *
  * Using the frame history stored in the frame clock, finds the last
  * known presentation time and refresh interval, and assuming that
@@ -754,12 +759,12 @@ guess_refresh_interval (GdkFrameClock *frame_clock)
 
 /**
  * gdk_frame_clock_get_fps:
- * @frame_clock: a #GdkFrameClock
+ * @frame_clock: a `GdkFrameClock`
  *
  * Calculates the current frames-per-second, based on the
  * frame timings of @frame_clock.
  *
- * Returns: the current fps, as a double
+ * Returns: the current fps, as a `double`
  */
 double
 gdk_frame_clock_get_fps (GdkFrameClock *frame_clock)
diff --git a/gdk/gdkframeclock.h b/gdk/gdkframeclock.h
index f50512c150..0fd6bca1f4 100644
--- a/gdk/gdkframeclock.h
+++ b/gdk/gdkframeclock.h
@@ -55,10 +55,10 @@ typedef struct _GdkFrameClockClass         GdkFrameClockClass;
  * @GDK_FRAME_CLOCK_PHASE_RESUME_EVENTS: corresponds to GdkFrameClock::resume-events. Should not be handled 
by applications.
  * @GDK_FRAME_CLOCK_PHASE_AFTER_PAINT: corresponds to GdkFrameClock::after-paint. Should not be handled by 
applications.
  *
- * #GdkFrameClockPhase is used to represent the different paint clock
- * phases that can be requested. The elements of the enumeration
- * correspond to the signals of #GdkFrameClock.
- **/
+ * Used to represent the different paint clock phases that can be requested.
+ *
+ * The elements of the enumeration correspond to the signals of `GdkFrameClock`.
+ */
 typedef enum {
   GDK_FRAME_CLOCK_PHASE_NONE          = 0,
   GDK_FRAME_CLOCK_PHASE_FLUSH_EVENTS  = 1 << 0,
diff --git a/gdk/gdkframetimings.c b/gdk/gdkframetimings.c
index 797638d844..22d9623746 100644
--- a/gdk/gdkframetimings.c
+++ b/gdk/gdkframetimings.c
@@ -21,24 +21,17 @@
 
 #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)
diff --git a/gdk/gdkglcontext.c b/gdk/gdkglcontext.c
index 3bc52b74fb..b9d802acf9 100644
--- a/gdk/gdkglcontext.c
+++ b/gdk/gdkglcontext.c
@@ -19,68 +19,57 @@
  */
 
 /**
- * SECTION:gdkglcontext
- * @Title: GdkGLContext
- * @Short_description: OpenGL draw context
+ * GdkGLContext:
  *
- * #GdkGLContext is an object representing the platform-specific
+ * `GdkGLContext` is an object representing a platform-specific
  * OpenGL draw context.
  *
- * #GdkGLContexts are created for a #GdkSurface using
- * gdk_surface_create_gl_context(), and the context will match the
- * the characteristics of the surface.
+ * `GdkGLContext`s are created for a surface using
+ * [method@Gdk.Surface.create_gl_context], and the context will match
+ * the the characteristics of the surface.
  *
- * A #GdkGLContext is not tied to any particular normal framebuffer.
- * For instance, it cannot draw to the #GdkSurface back buffer. The GDK
+ * A `GdkGLContext` is not tied to any particular normal framebuffer.
+ * For instance, it cannot draw to the surface back buffer. The GDK
  * repaint system is in full control of the painting to that. Instead,
- * you can create render buffers or textures and use gdk_cairo_draw_from_gl()
+ * you can create render buffers or textures and use [func@cairo_draw_from_gl]
  * in the draw function of your widget to draw them. Then GDK will handle
  * the integration of your rendering with that of other widgets.
  *
- * Support for #GdkGLContext is platform-specific, context creation
+ * Support for `GdkGLContext` is platform-specific and context creation
  * can fail, returning %NULL context.
  *
- * A #GdkGLContext has to be made "current" in order to start using
+ * A `GdkGLContext` has to be made "current" in order to start using
  * it, otherwise any OpenGL call will be ignored.
  *
- * ## Creating a new OpenGL context ##
+ * ## Creating a new OpenGL context
  *
- * In order to create a new #GdkGLContext instance you need a
- * #GdkSurface, which you typically get during the realize call
- * of a widget.
+ * In order to create a new `GdkGLContext` instance you need a `GdkSurface`,
+ * which you typically get during the realize call of a widget.
  *
- * A #GdkGLContext is not realized until either gdk_gl_context_make_current(),
- * or until it is realized using gdk_gl_context_realize(). It is possible to
- * specify details of the GL context like the OpenGL version to be used, or
- * whether the GL context should have extra state validation enabled after
- * calling gdk_surface_create_gl_context() by calling gdk_gl_context_realize().
- * If the realization fails you have the option to change the settings of the
- * #GdkGLContext and try again.
+ * A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current]
+ * or [method@Gdk.GLContext.realize] is called. It is possible to specify
+ * details of the GL context like the OpenGL version to be used, or whether
+ * the GL context should have extra state validation enabled after calling
+ * [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize].
+ * If the realization fails you have the option to change the settings of
+ * the `GdkGLContext` and try again.
  *
- * ## Using a GdkGLContext ##
+ * ## Using a GdkGLContext
  *
- * You will need to make the #GdkGLContext the current context
- * before issuing OpenGL calls; the system sends OpenGL commands to
- * whichever context is current. It is possible to have multiple
- * contexts, so you always need to ensure that the one which you
- * want to draw with is the current one before issuing commands:
+ * You will need to make the `GdkGLContext` the current context before issuing
+ * OpenGL calls; the system sends OpenGL commands to whichever context is current.
+ * It is possible to have multiple contexts, so you always need to ensure that
+ * the one which you want to draw with is the current one before issuing commands:
  *
- * |[<!-- language="C" -->
- *   gdk_gl_context_make_current (context);
- * ]|
+ * ```c
+ * gdk_gl_context_make_current (context);
+ * ```
  *
  * You can now perform your drawing using OpenGL commands.
  *
- * You can check which #GdkGLContext is the current one by using
- * gdk_gl_context_get_current(); you can also unset any #GdkGLContext
- * that is currently set by calling gdk_gl_context_clear_current().
- */
-
-/**
- * GdkGLContext:
- *
- * The GdkGLContext struct contains only private fields and
- * should not be accessed directly.
+ * You can check which `GdkGLContext` is the current one by using
+ * [method@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext`
+ * that is currently set by calling [method@Gdk.GLContext.clear_current].
  */
 
 #include "config.h"
@@ -425,7 +414,7 @@ gdk_gl_context_class_init (GdkGLContextClass *klass)
   /**
    * GdkGLContext:shared-context:
    *
-   * The #GdkGLContext that this context is sharing data with, or %NULL
+   * The `GdkGLContext` that this context is sharing data with, or %NULL
    */
   obj_pspecs[PROP_SHARED_CONTEXT] =
     g_param_spec_object ("shared-context",
@@ -566,14 +555,15 @@ gdk_gl_context_has_unpack_subimage (GdkGLContext *context)
 
 /**
  * gdk_gl_context_set_debug_enabled:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  * @enabled: whether to enable debugging in the context
  *
- * Sets whether the #GdkGLContext should perform extra validations and
- * run time checking. This is useful during development, but has
- * additional overhead.
+ * Sets whether the `GdkGLContext` should perform extra validations and
+ * runtime checking.
  *
- * The #GdkGLContext must not be realized or made current prior to
+ * This is useful during development, but has additional overhead.
+ *
+ * The `GdkGLContext` must not be realized or made current prior to
  * calling this function.
  */
 void
@@ -592,9 +582,11 @@ gdk_gl_context_set_debug_enabled (GdkGLContext *context,
 
 /**
  * gdk_gl_context_get_debug_enabled:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
+ *
+ * Retrieves whether the context is doing extra validations and runtime checking.
  *
- * Retrieves the value set using gdk_gl_context_set_debug_enabled().
+ * See [method@Gdk.GLContext.set_debug_enabled].
  *
  * Returns: %TRUE if debugging is enabled
  */
@@ -610,17 +602,17 @@ gdk_gl_context_get_debug_enabled (GdkGLContext *context)
 
 /**
  * gdk_gl_context_set_forward_compatible:
- * @context: a #GdkGLContext
- * @compatible: whether the context should be forward compatible
+ * @context: a `GdkGLContext`
+ * @compatible: whether the context should be forward-compatible
  *
- * Sets whether the #GdkGLContext should be forward compatible.
+ * Sets whether the `GdkGLContext` should be forward-compatible.
  *
- * Forward compatible contexts must not support OpenGL functionality that
+ * Forward-compatible contexts must not support OpenGL functionality that
  * has been marked as deprecated in the requested version; non-forward
  * compatible contexts, on the other hand, must support both deprecated and
  * non deprecated functionality.
  *
- * The #GdkGLContext must not be realized or made current prior to calling
+ * The `GdkGLContext` must not be realized or made current prior to calling
  * this function.
  */
 void
@@ -639,11 +631,13 @@ gdk_gl_context_set_forward_compatible (GdkGLContext *context,
 
 /**
  * gdk_gl_context_get_forward_compatible:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
+ *
+ * Retrieves whether the context is forward-compatible.
  *
- * Retrieves the value set using gdk_gl_context_set_forward_compatible().
+ * See [method@Gdk.GLContext.set_forward_compatible].
  *
- * Returns: %TRUE if the context should be forward compatible
+ * Returns: %TRUE if the context should be forward-compatible
  */
 gboolean
 gdk_gl_context_get_forward_compatible (GdkGLContext *context)
@@ -657,7 +651,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context)
 
 /**
  * gdk_gl_context_set_required_version:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  * @major: the major version to request
  * @minor: the minor version to request
  *
@@ -665,7 +659,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context)
  *
  * Setting @major and @minor to zero will use the default values.
  *
- * The #GdkGLContext must not be realized or made current prior to calling
+ * The `GdkGLContext` must not be realized or made current prior to calling
  * this function.
  */
 void
@@ -716,12 +710,13 @@ gdk_gl_context_set_required_version (GdkGLContext *context,
 
 /**
  * gdk_gl_context_get_required_version:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  * @major: (out) (nullable): return location for the major version to request
  * @minor: (out) (nullable): return location for the minor version to request
  *
- * Retrieves the major and minor version requested by calling
- * gdk_gl_context_set_required_version().
+ * Retrieves required OpenGL version.
+ *
+ * See [method@Gdk.GLContext.set_required_version].
  */
 void
 gdk_gl_context_get_required_version (GdkGLContext *context,
@@ -776,11 +771,11 @@ gdk_gl_context_get_required_version (GdkGLContext *context,
 
 /**
  * gdk_gl_context_is_legacy:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
- * Whether the #GdkGLContext is in legacy mode or not.
+ * Whether the `GdkGLContext` is in legacy mode or not.
  *
- * The #GdkGLContext must be realized before calling this function.
+ * The `GdkGLContext` must be realized before calling this function.
  *
  * When realizing a GL context, GDK will try to use the OpenGL 3.2 core
  * profile; this profile removes all the OpenGL API that was deprecated
@@ -819,12 +814,13 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context,
 
 /**
  * gdk_gl_context_set_use_es:
- * @context: a #GdkGLContext:
+ * @context: a `GdkGLContext`
  * @use_es: whether the context should use OpenGL ES instead of OpenGL,
  *   or -1 to allow auto-detection
  *
- * Requests that GDK create an OpenGL ES context instead of an OpenGL one,
- * if the platform and windowing system allows it.
+ * Requests that GDK create an OpenGL ES context instead of an OpenGL one.
+ *
+ * Not all platforms support OpenGL ES.
  *
  * The @context must not have been realized.
  *
@@ -832,9 +828,9 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context,
  * underlying GL implementation is OpenGL or OpenGL ES once the @context
  * is realized.
  *
- * You should check the return value of gdk_gl_context_get_use_es() after
- * calling gdk_gl_context_realize() to decide whether to use the OpenGL or
- * OpenGL ES API, extensions, or shaders.
+ * You should check the return value of [method@Gdk.GLContext.get_use_es]
+ * after calling [method@Gdk.GLContext.realize] to decide whether to use
+ * the OpenGL or OpenGL ES API, extensions, or shaders.
  */
 void
 gdk_gl_context_set_use_es (GdkGLContext *context,
@@ -851,11 +847,11 @@ gdk_gl_context_set_use_es (GdkGLContext *context,
 
 /**
  * gdk_gl_context_get_use_es:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
  * Checks whether the @context is using an OpenGL or OpenGL ES profile.
  *
- * Returns: %TRUE if the #GdkGLContext is using an OpenGL ES profile
+ * Returns: %TRUE if the `GdkGLContext` is using an OpenGL ES profile
  */
 gboolean
 gdk_gl_context_get_use_es (GdkGLContext *context)
@@ -963,12 +959,12 @@ gl_debug_message_callback (GLenum        source,
 
 /**
  * gdk_gl_context_realize:
- * @context: a #GdkGLContext
- * @error: return location for a #GError
+ * @context: a `GdkGLContext`
+ * @error: return location for a `GError`
  *
- * Realizes the given #GdkGLContext.
+ * Realizes the given `GdkGLContext`.
  *
- * It is safe to call this function on a realized #GdkGLContext.
+ * It is safe to call this function on a realized `GdkGLContext`.
  *
  * Returns: %TRUE if the context is realized
  */
@@ -1088,7 +1084,7 @@ gdk_gl_context_check_extensions (GdkGLContext *context)
 
 /**
  * gdk_gl_context_make_current:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
  * Makes the @context the current one.
  */
@@ -1127,11 +1123,11 @@ gdk_gl_context_make_current (GdkGLContext *context)
 
 /**
  * gdk_gl_context_get_display:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
- * Retrieves the #GdkDisplay the @context is created for
+ * Retrieves the display the @context is created for
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay or %NULL
+ * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
  */
 GdkDisplay *
 gdk_gl_context_get_display (GdkGLContext *context)
@@ -1143,11 +1139,11 @@ gdk_gl_context_get_display (GdkGLContext *context)
 
 /**
  * gdk_gl_context_get_surface:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
- * Retrieves the #GdkSurface used by the @context.
+ * Retrieves the surface used by the @context.
  *
- * Returns: (nullable) (transfer none): a #GdkSurface or %NULL
+ * Returns: (nullable) (transfer none): a `GdkSurface` or %NULL
  */
 GdkSurface *
 gdk_gl_context_get_surface (GdkGLContext *context)
@@ -1159,11 +1155,11 @@ gdk_gl_context_get_surface (GdkGLContext *context)
 
 /**
  * gdk_gl_context_get_shared_context:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  *
- * Retrieves the #GdkGLContext that this @context share data with.
+ * Retrieves the `GdkGLContext` that this @context share data with.
  *
- * Returns: (nullable) (transfer none): a #GdkGLContext or %NULL
+ * Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL
  */
 GdkGLContext *
 gdk_gl_context_get_shared_context (GdkGLContext *context)
@@ -1177,7 +1173,7 @@ gdk_gl_context_get_shared_context (GdkGLContext *context)
 
 /**
  * gdk_gl_context_get_version:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  * @major: (out): return location for the major version
  * @minor: (out): return location for the minor version
  *
@@ -1204,10 +1200,10 @@ gdk_gl_context_get_version (GdkGLContext *context,
 /**
  * gdk_gl_context_clear_current:
  *
- * Clears the current #GdkGLContext.
+ * Clears the current `GdkGLContext`.
  *
  * Any OpenGL call after this function returns will be ignored
- * until gdk_gl_context_make_current() is called.
+ * until [method@Gdk.GLContext.make_current] is called.
  */
 void
 gdk_gl_context_clear_current (void)
@@ -1225,9 +1221,9 @@ gdk_gl_context_clear_current (void)
 /**
  * gdk_gl_context_get_current:
  *
- * Retrieves the current #GdkGLContext.
+ * Retrieves the current `GdkGLContext`.
  *
- * Returns: (nullable) (transfer none): the current #GdkGLContext, or %NULL
+ * Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL
  */
 GdkGLContext *
 gdk_gl_context_get_current (void)
diff --git a/gdk/gdkgltexture.c b/gdk/gdkgltexture.c
index 5688513528..caf3e7ab6b 100644
--- a/gdk/gdkgltexture.c
+++ b/gdk/gdkgltexture.c
@@ -25,6 +25,12 @@
 
 #include <epoxy/gl.h>
 
+/**
+ * GdkGLTexture:
+ *
+ * A GdkTexture representing a GL texture object.
+ */
+
 struct _GdkGLTexture {
   GdkTexture parent_instance;
 
@@ -133,14 +139,13 @@ gdk_gl_texture_get_id (GdkGLTexture *self)
 
 /**
  * gdk_gl_texture_release:
- * @self: a #GdkTexture wrapping a GL texture
+ * @self: a `GdkTexture` wrapping a GL texture
  *
- * Releases the GL resources held by a #GdkGLTexture that
- * was created with gdk_gl_texture_new().
+ * Releases the GL resources held by a `GdkGLTexture`.
  *
  * The texture contents are still available via the
- * gdk_texture_download() function, after this function
- * has been called.
+ * [method@Gdk.Texture.download] function, after this
+ * function has been called.
  */
 void
 gdk_gl_texture_release (GdkGLTexture *self)
@@ -177,21 +182,21 @@ gdk_gl_texture_release (GdkGLTexture *self)
 
 /**
  * gdk_gl_texture_new:
- * @context: a #GdkGLContext
+ * @context: a `GdkGLContext`
  * @id: the ID of a texture that was created with @context
  * @width: the nominal width of the texture
  * @height: the nominal height of the texture
  * @destroy: a destroy notify that will be called when the GL resources
- *           are released
+ *   are released
  * @data: data that gets passed to @destroy
  *
  * Creates a new texture for an existing GL texture.
  *
  * Note that the GL texture must not be modified until @destroy is called,
  * which will happen when the GdkTexture object is finalized, or due to
- * an explicit call of gdk_gl_texture_release().
+ * an explicit call of [method@Gdk.GLTexture.release].
  *
- * Return value: (transfer full): A newly-created #GdkTexture
+ * Return value: (transfer full): A newly-created `GdkTexture`
  */
 GdkTexture *
 gdk_gl_texture_new (GdkGLContext   *context,
diff --git a/gdk/gdkgltexture.h b/gdk/gdkgltexture.h
index bdc70a0cad..54e4fee7e7 100644
--- a/gdk/gdkgltexture.h
+++ b/gdk/gdkgltexture.h
@@ -33,11 +33,6 @@ G_BEGIN_DECLS
 #define GDK_GL_TEXTURE(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_GL_TEXTURE, 
GdkGLTexture))
 #define GDK_IS_GL_TEXTURE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_GL_TEXTURE))
 
-/**
- * GdkGLTexture:
- *
- * A #GdkTexture representing a GL texture object.
- */
 typedef struct _GdkGLTexture            GdkGLTexture;
 typedef struct _GdkGLTextureClass       GdkGLTextureClass;
 
diff --git a/gdk/gdkmemorytexture.c b/gdk/gdkmemorytexture.c
index 663d0409f9..06fa3d6619 100644
--- a/gdk/gdkmemorytexture.c
+++ b/gdk/gdkmemorytexture.c
@@ -21,6 +21,12 @@
 
 #include "gdkmemorytextureprivate.h"
 
+/**
+ * GdkMemoryTexture:
+ *
+ * A `GdkTexture` representing image data in memory.
+ */
+
 struct _GdkMemoryTexture
 {
   GdkTexture parent_instance;
@@ -111,14 +117,15 @@ gdk_memory_texture_init (GdkMemoryTexture *self)
  * @width: the width of the texture
  * @height: the height of the texture
  * @format: the format of the data
- * @bytes: the #GBytes containing the pixel data
+ * @bytes: the `GBytes` containing the pixel data
  * @stride: rowstride for the data
  *
  * Creates a new texture for a blob of image data.
- * The #GBytes must contain @stride x @height pixels
+ *
+ * The `GBytes` must contain @stride x @height pixels
  * in the given format.
  *
- * Returns: A newly-created #GdkTexture
+ * Returns: A newly-created `GdkTexture`
  */
 GdkTexture *
 gdk_memory_texture_new (int              width,
diff --git a/gdk/gdkmemorytexture.h b/gdk/gdkmemorytexture.h
index d4161d60de..090b5c6275 100644
--- a/gdk/gdkmemorytexture.h
+++ b/gdk/gdkmemorytexture.h
@@ -45,14 +45,14 @@ G_BEGIN_DECLS
  * @GDK_MEMORY_N_FORMATS: The number of formats. This value will change as
  *     more formats get added, so do not rely on its concrete integer.
  *
- * #GdkMemoryFormat describes a format that bytes can have in memory.
+ * `GdkMemoryFormat` describes a format that bytes can have in memory.
  *
  * It describes formats by listing the contents of the memory passed to it.
  * So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a
  * byte each of red, green and blue. It is not endian-dependent, so
- * CAIRO_FORMAT_ARGB32 is represented by different #GdkMemoryFormats on
- * architectures with different endiannesses.
- * 
+ * CAIRO_FORMAT_ARGB32 is represented by different `GdkMemoryFormats`
+ * on architectures with different endiannesses.
+ *
  * Its naming is modelled after VkFormat (see
  * https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat
  * for details).
@@ -74,12 +74,13 @@ typedef enum {
 /**
  * GDK_MEMORY_DEFAULT:
  *
- * This is the default memory format used by GTK and is the format
- * provided by gdk_texture_download(). It is equal to
- * %CAIRO_FORMAT_ARGB32.
+ * The default memory format used by GTK.
+ *
+ * This is the format provided by [method@Gdk.Texture.download].
+ * It is equal to %CAIRO_FORMAT_ARGB32.
  *
- * Be aware that unlike the #GdkMemoryFormat values, this format is
- * different for different endianness.
+ * Be aware that unlike the #GdkMemoryFormat values, this format
+ * is different for different endianness.
  */
 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 #define GDK_MEMORY_DEFAULT GDK_MEMORY_B8G8R8A8_PREMULTIPLIED
@@ -94,11 +95,6 @@ typedef enum {
 #define GDK_MEMORY_TEXTURE(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_MEMORY_TEXTURE, 
GdkMemoryTexture))
 #define GDK_IS_MEMORY_TEXTURE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_MEMORY_TEXTURE))
 
-/**
- * GdkMemoryTexture:
- *
- * A #GdkTexture representing image data in memory.
- */
 typedef struct _GdkMemoryTexture        GdkMemoryTexture;
 typedef struct _GdkMemoryTextureClass   GdkMemoryTextureClass;
 
diff --git a/gdk/gdkmonitor.c b/gdk/gdkmonitor.c
index 46edc8a5c4..0e9bd5064d 100644
--- a/gdk/gdkmonitor.c
+++ b/gdk/gdkmonitor.c
@@ -25,22 +25,16 @@
 #include "gdkdisplay.h"
 #include "gdkenumtypes.h"
 
-/**
- * SECTION:gdkmonitor
- * @Title: GdkMonitor
- * @Short_description: Object representing an output
- *
- * GdkMonitor objects represent the individual outputs that are
- * associated with a #GdkDisplay. GdkDisplay keeps a #GListModel to enumerate
- * and monitor monitors with gdk_display_get_monitors().  
- * You can use gdk_display_get_monitor_at_surface() to find a particular monitor.
- */
-
 /**
  * GdkMonitor:
  *
- * The GdkMonitor struct contains only private fields and should not
- * be accessed directly.
+ * `GdkMonitor` objects represent the individual outputs that are
+ * associated with a `GdkDisplay`.
+ *
+ * `GdkDisplay` keeps a `GListModel` to enumerate and monitor
+ * monitors with [method@Gdk.Display.get_monitors]. You can use
+ * [method@Gdk.Display.get_monitor_at_surface] to find a particular
+ * monitor.
  */
 
 enum {
@@ -176,30 +170,59 @@ gdk_monitor_class_init (GdkMonitorClass *class)
   object_class->get_property = gdk_monitor_get_property;
   object_class->set_property = gdk_monitor_set_property;
 
+  /**
+   * GdkMonitor:display:
+   *
+   * The `GdkDisplay` of the monitor.
+   */
   props[PROP_DISPLAY] =
     g_param_spec_object ("display",
                          "Display",
                          "The display of the monitor",
                          GDK_TYPE_DISPLAY,
                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:manufacturer:
+   *
+   * The manufacturer name.
+   */
   props[PROP_MANUFACTURER] =
     g_param_spec_string ("manufacturer",
                          "Manufacturer",
                          "The manufacturer name",
                          NULL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:model:
+   *
+   * The model name.
+   */
   props[PROP_MODEL] =
     g_param_spec_string ("model",
                          "Model",
                          "The model name",
                          NULL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:connector:
+   *
+   * The connector name.
+   */
   props[PROP_CONNECTOR] =
     g_param_spec_string ("connector",
                          "Connector",
                          "The connector name",
                          NULL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:scale-factor:
+   *
+   * The scale factor.
+   */
   props[PROP_SCALE_FACTOR] =
     g_param_spec_int ("scale-factor",
                       "Scale factor",
@@ -207,12 +230,24 @@ gdk_monitor_class_init (GdkMonitorClass *class)
                       0, G_MAXINT,
                       1,
                       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:geometry:
+   *
+   * The geometry of the monitor.
+   */
   props[PROP_GEOMETRY] =
     g_param_spec_boxed ("geometry",
                         "Geometry",
                         "The geometry of the monitor",
                         GDK_TYPE_RECTANGLE,
                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:width-mm:
+   *
+   * The width of the monitor, in millimeters.
+   */
   props[PROP_WIDTH_MM] =
     g_param_spec_int ("width-mm",
                       "Physical width",
@@ -220,6 +255,12 @@ gdk_monitor_class_init (GdkMonitorClass *class)
                       0, G_MAXINT,
                       0,
                       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:height-mm:
+   *
+   * The height of the monitor, in millimeters.
+   */
   props[PROP_HEIGHT_MM] =
     g_param_spec_int ("height-mm",
                       "Physical height",
@@ -227,6 +268,12 @@ gdk_monitor_class_init (GdkMonitorClass *class)
                       0, G_MAXINT,
                       0,
                       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:refresh-rate:
+   *
+   * The refresh rate, in milli-Hertz.
+   */
   props[PROP_REFRESH_RATE] =
     g_param_spec_int ("refresh-rate",
                       "Refresh rate",
@@ -234,6 +281,12 @@ gdk_monitor_class_init (GdkMonitorClass *class)
                       0, G_MAXINT,
                       0,
                       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:subpixel-layout:
+   *
+   * The subpixel layout.
+   */
   props[PROP_SUBPIXEL_LAYOUT] =
     g_param_spec_enum ("subpixel-layout",
                        "Subpixel layout",
@@ -241,6 +294,12 @@ gdk_monitor_class_init (GdkMonitorClass *class)
                        GDK_TYPE_SUBPIXEL_LAYOUT,
                        GDK_SUBPIXEL_LAYOUT_UNKNOWN,
                        G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+
+  /**
+   * GdkMonitor:valid:
+   *
+   * Whether the object is still valid.
+   */ 
   props[PROP_VALID] =
     g_param_spec_boolean ("valid",
                           "Valid",
@@ -254,8 +313,7 @@ gdk_monitor_class_init (GdkMonitorClass *class)
    * GdkMonitor::invalidate:
    * @monitor: the object on which this signal was emitted
    *
-   * The ::invalidate signal gets emitted when the output represented
-   * by @monitor gets disconnected.
+   * Emitted when the output represented by @monitor gets disconnected.
    */
   signals[INVALIDATE] = g_signal_new (g_intern_static_string ("invalidate"),
                                       G_TYPE_FROM_CLASS (object_class),
@@ -268,7 +326,7 @@ gdk_monitor_class_init (GdkMonitorClass *class)
 
 /**
  * gdk_monitor_get_display:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the display that this monitor belongs to.
  *
@@ -284,12 +342,14 @@ gdk_monitor_get_display (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_geometry:
- * @monitor: a #GdkMonitor
- * @geometry: (out): a #GdkRectangle to be filled with the monitor geometry
+ * @monitor: a `GdkMonitor`
+ * @geometry: (out): a `GdkRectangle` to be filled with the monitor geometry
  *
- * Retrieves the size and position of an individual monitor within the
- * display coordinate space. The returned geometry is in  ”application pixels”,
- * not in ”device pixels” (see gdk_monitor_get_scale_factor()).
+ * Retrieves the size and position of the monitor within the
+ * display coordinate space.
+ *
+ * The returned geometry is in  ”application pixels”, not in
+ * ”device pixels” (see [method@Gdk.Monitor.get_scale_factor]).
  */
 void
 gdk_monitor_get_geometry (GdkMonitor   *monitor,
@@ -303,7 +363,7 @@ gdk_monitor_get_geometry (GdkMonitor   *monitor,
 
 /**
  * gdk_monitor_get_width_mm:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the width in millimeters of the monitor.
  *
@@ -319,7 +379,7 @@ gdk_monitor_get_width_mm (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_height_mm:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the height in millimeters of the monitor.
  *
@@ -335,7 +395,7 @@ gdk_monitor_get_height_mm (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_connector:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the name of the monitor's connector, if available.
  *
@@ -351,16 +411,18 @@ gdk_monitor_get_connector (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_manufacturer:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
- * Gets the name or PNP ID of the monitor's manufacturer, if available.
+ * Gets the name or PNP ID of the monitor's manufacturer.
  *
  * Note that this value might also vary depending on actual
  * display backend.
  *
- * PNP ID registry is located at https://uefi.org/pnp_id_list
+ * The PNP ID registry is located at
+ * [https://uefi.org/pnp_id_list](https://uefi.org/pnp_id_list).
  *
- * Returns: (transfer none) (nullable): the name of the manufacturer, or %NULL
+ * Returns: (transfer none) (nullable): the name of the manufacturer,
+ *   or %NULL
  */
 const char *
 gdk_monitor_get_manufacturer (GdkMonitor *monitor)
@@ -372,7 +434,7 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_model:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the string identifying the monitor model, if available.
  *
@@ -388,15 +450,17 @@ gdk_monitor_get_model (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_scale_factor:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the internal scale factor that maps from monitor coordinates
- * to the actual device pixels. On traditional systems this is 1, but
- * on very high density outputs this can be a higher value (often 2).
+ * to device pixels.
+ *
+ * On traditional systems this is 1, but on very high density outputs
+ * it can be a higher value (often 2).
  *
  * This can be used if you want to create pixel based data for a
  * particular monitor, but most of the time you’re drawing to a surface
- * where it is better to use gdk_surface_get_scale_factor() instead.
+ * where it is better to use [method@Gdk.Surface.get_scale_factor] instead.
  *
  * Returns: the scale factor
  */
@@ -410,7 +474,7 @@ gdk_monitor_get_scale_factor (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_refresh_rate:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets the refresh rate of the monitor, if available.
  *
@@ -429,10 +493,10 @@ gdk_monitor_get_refresh_rate (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_get_subpixel_layout:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Gets information about the layout of red, green and blue
- * primaries for each pixel in this monitor, if available.
+ * primaries for pixels.
  *
  * Returns: the subpixel layout
  */
@@ -561,11 +625,13 @@ gdk_monitor_invalidate (GdkMonitor *monitor)
 
 /**
  * gdk_monitor_is_valid:
- * @monitor: a #GdkMonitor
+ * @monitor: a `GdkMonitor`
  *
  * Returns %TRUE if the @monitor object corresponds to a
- * physical monitor. The @monitor becomes invalid when the
- * physical monitor is unplugged or removed.
+ * physical monitor.
+ *
+ * The @monitor becomes invalid when the physical monitor
+ * is unplugged or removed.
  *
  * Returns: %TRUE if the object corresponds to a physical monitor
  */
diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c
index a1726401b0..b58a90947f 100644
--- a/gdk/gdkpaintable.c
+++ b/gdk/gdkpaintable.c
@@ -30,52 +30,53 @@ void            gtk_snapshot_push_debug                 (GdkSnapshot
 void            gtk_snapshot_pop                        (GdkSnapshot            *snapshot);
 
 /**
- * SECTION:gdkpaintable
- * @Title: GdkPaintable
- * @Short_description: An interface for a paintable region
- * @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot
- *
- * #GdkPaintable is a simple interface used by GDK and GTK to represent
- * objects that can be painted anywhere at any size without requiring any
- * sort of layout. The interface is inspired by similar concepts elsewhere,
- * such as [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
+ * GdkPaintable:
+ *
+ * `GdkPaintable` is a simple interface used by GTK to represent content that
+ * can be painted.
+ *
+ * The content of a `GdkPaintable` can be painted anywhere at any size
+ * without requiring any sort of layout. The interface is inspired by
+ * similar concepts elsewhere, such as
+ * [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
  * [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source),
  * or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html).
  *
- * A #GdkPaintable can be snapshot at any time and size using
- * gdk_paintable_snapshot(). How the paintable interprets that size and if it
- * scales or centers itself into the given rectangle is implementation defined,
- * though if you are implementing a #GdkPaintable and don't know what to do, it
- * is suggested that you scale your paintable ignoring any potential aspect ratio.
- *
- * The contents that a #GdkPaintable produces may depend on the #GdkSnapshot passed
- * to it. For example, paintables may decide to use more detailed images on higher
- * resolution screens or when OpenGL is available. A #GdkPaintable will however
- * always produce the same output for the same snapshot.
- *
- * A #GdkPaintable may change its contents, meaning that it will now produce a
- * different output with the same snapshot. Once that happens, it will call
- * gdk_paintable_invalidate_contents() which will emit the
- * #GdkPaintable::invalidate-contents signal. If a paintable is known to never
- * change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS flag.
- * If a consumer cannot deal with changing contents, it may call
- * gdk_paintable_get_current_image() which will return a static paintable and
- * use that.
+ * A `GdkPaintable` can be snapshot at any time and size using
+ * [method@Gdk.Paintable.snapshot]. How the paintable interprets that size and
+ * if it scales or centers itself into the given rectangle is implementation
+ * defined, though if you are implementing a `GdkPaintable` and don't know what
+ * to do, it is suggested that you scale your paintable ignoring any potential
+ * aspect ratio.
+ *
+ * The contents that a `GdkPaintable` produces may depend on the [class@GdkSnapshot]
+ * passed to it. For example, paintables may decide to use more detailed images
+ * on higher resolution screens or when OpenGL is available. A `GdkPaintable`
+ * will however always produce the same output for the same snapshot.
+ *
+ * A `GdkPaintable` may change its contents, meaning that it will now produce
+ * a different output with the same snapshot. Once that happens, it will call
+ * [method@Gdk.Paintable.invalidate_contents] which will emit the
+ * [signal@GdkPaintable::invalidate-contents] signal. If a paintable is known
+ * to never change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS
+ * flag. If a consumer cannot deal with changing contents, it may call
+ * [method@Gdk.Paintable.get_current_image] which will return a static
+ * paintable and use that.
  *
  * A paintable can report an intrinsic (or preferred) size or aspect ratio it
  * wishes to be rendered at, though it doesn't have to. Consumers of the interface
- * can use this information to layout thepaintable appropriately.
- * Just like the contents, the size of a paintable can change. A paintable will
- * indicate this by calling gdk_paintable_invalidate_size() which will emit the
- * #GdkPaintable::invalidate-size signal.
- * And just like for contents, if a paintable is known to never change its size,
- * it will set the %GDK_PAINTABLE_STATIC_SIZE flag.
+ * can use this information to layout thepaintable appropriately. Just like the
+ * contents, the size of a paintable can change. A paintable will indicate this
+ * by calling [method@Gdk.Paintable.invalidate_size] which will emit the
+ * [signal@GdkPaintable::invalidate-size] signal. And just like for contents,
+ * if a paintable is known to never change its size, it will set the
+ * %GDK_PAINTABLE_STATIC_SIZE flag.
  *
  * Besides API for applications, there are some functions that are only
  * useful for implementing subclasses and should not be used by applications:
- * gdk_paintable_invalidate_contents(),
- * gdk_paintable_invalidate_size(),
- * gdk_paintable_new_empty().
+ * [method@Gdk.Paintable.invalidate_contents],
+ * [method@Gdk.Paintable.invalidate_size],
+ * [method@Gdk.Paintable.new_empty].
  */
 
 G_DEFINE_INTERFACE (GdkPaintable, gdk_paintable, G_TYPE_OBJECT)
@@ -161,7 +162,7 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
 
   /**
    * GdkPaintable::invalidate-contents
-   * @paintable: a #GdkPaintable
+   * @paintable: a `GdkPaintable`
    *
    * Emitted when the contents of the @paintable change.
    *
@@ -179,15 +180,18 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
 
   /**
    * GdkPaintable::invalidate-size
-   * @paintable: a #GdkPaintable
+   * @paintable: a `GdkPaintable`
    *
-   * Emitted when the intrinsic size of the @paintable changes. This means the values
-   * reported by at least one of gdk_paintable_get_intrinsic_width(),
-   * gdk_paintable_get_intrinsic_height() or gdk_paintable_get_intrinsic_aspect_ratio()
+   * Emitted when the intrinsic size of the @paintable changes.
+   *
+   * This means the values reported by at least one of
+   * [method@Gdk.Paintable.get_intrinsic_width],
+   * [method@Gdk.Paintable.get_intrinsic_height] or
+   * [method@Gdk.Paintable.get_intrinsic_aspect_ratio]
    * has changed.
    *
-   * Examples for such an event would be a paintable displaying the contents of a toplevel
-   * surface being resized.
+   * Examples for such an event would be a paintable displaying
+   * the contents of a toplevel surface being resized.
    */
   signals[INVALIDATE_SIZE] =
     g_signal_new ("invalidate-size",
@@ -201,14 +205,16 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
 
 /**
  * gdk_paintable_snapshot:
- * @paintable: a #GdkPaintable
- * @snapshot: a #GdkSnapshot to snapshot to
+ * @paintable: a `GdkPaintable`
+ * @snapshot: a `GdkSnapshot` to snapshot to
  * @width: width to snapshot in
  * @height: height to snapshot in
  *
- * Snapshots the given paintable with the given @width and @height at the
- * current (0,0) offset of the @snapshot. If @width and @height are not larger
- * than zero, this function will do nothing.
+ * Snapshots the given paintable with the given @width and @height.
+ *
+ * The paintable is drawn at the current (0,0) offset of the @snapshot.
+ * If @width and @height are not larger than zero, this function will
+ * do nothing.
  */
 void
 gdk_paintable_snapshot (GdkPaintable *paintable,
@@ -241,12 +247,12 @@ gdk_paintable_is_immutable (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_get_current_image:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  *
  * Gets an immutable paintable for the current contents displayed by @paintable.
  *
- * This is useful when you want to retain the current state of an animation, for
- * example to take a screenshot of a running animation.
+ * This is useful when you want to retain the current state of an animation,
+ * for example to take a screenshot of a running animation.
  *
  * If the @paintable is already immutable, it will return itself.
  *
@@ -269,13 +275,15 @@ gdk_paintable_get_current_image (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_get_flags:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  *
- * Get flags for the paintable. This is oftentimes useful for optimizations.
+ * Get flags for the paintable.
  *
- * See #GdkPaintableFlags for the flags and what they mean.
+ * This is oftentimes useful for optimizations.
  *
- * Returns: The #GdkPaintableFlags for this paintable.
+ * See [flags@Gdk.PaintableFlags] for the flags and what they mean.
+ *
+ * Returns: The `GdkPaintableFlags` for this paintable
  */
 GdkPaintableFlags
 gdk_paintable_get_flags (GdkPaintable *paintable)
@@ -290,17 +298,18 @@ gdk_paintable_get_flags (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_get_intrinsic_width:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  *
  * Gets the preferred width the @paintable would like to be displayed at.
+ *
  * Consumers of this interface can use this to reserve enough space to draw
  * the paintable.
  *
- * This is a purely informational value and does not in any way limit the values
- * that may be passed to gdk_paintable_snapshot().
+ * This is a purely informational value and does not in any way limit the
+ * values that may be passed to [method@Gdk.Paintable.snapshot].
  *
- * If the @paintable does not have a preferred width, it returns 0. Negative
- * values are never returned.
+ * If the @paintable does not have a preferred width, it returns 0.
+ * Negative values are never returned.
  *
  * Returns: the intrinsic width of @paintable or 0 if none.
  */
@@ -317,17 +326,18 @@ gdk_paintable_get_intrinsic_width (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_get_intrinsic_height:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  *
  * Gets the preferred height the @paintable would like to be displayed at.
+ *
  * Consumers of this interface can use this to reserve enough space to draw
  * the paintable.
  *
- * This is a purely informational value and does not in any way limit the values
- * that may be passed to gdk_paintable_snapshot().
+ * This is a purely informational value and does not in any way limit the
+ * values that may be passed to [method@Gdk.Paintable.snapshot].
  *
- * If the @paintable does not have a preferred height, it returns 0. Negative
- * values are never returned.
+ * If the @paintable does not have a preferred height, it returns 0.
+ * Negative values are never returned.
  *
  * Returns: the intrinsic height of @paintable or 0 if none.
  */
@@ -344,23 +354,25 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_get_intrinsic_aspect_ratio:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  *
  * Gets the preferred aspect ratio the @paintable would like to be displayed at.
- * The aspect ratio is the width divided by the height, so a value of 0.5 means
- * that the @paintable prefers to be displayed twice as high as it is wide.
- * Consumers of this interface can use this to preserve aspect ratio when displaying
- * the paintable.
  *
- * This is a purely informational value and does not in any way limit the values
- * that may be passed to gdk_paintable_snapshot().
+ * The aspect ratio is the width divided by the height, so a value of 0.5
+ * means that the @paintable prefers to be displayed twice as high as it
+ * is wide. Consumers of this interface can use this to preserve aspect
+ * ratio when displaying the paintable.
+ *
+ * This is a purely informational value and does not in any way limit the
+ * values that may be passed to [method@Gdk.Paintable.snapshot].
  *
  * Usually when a @paintable returns nonzero values from
- * gdk_paintable_get_intrinsic_width() and gdk_paintable_get_intrinsic_height()
- * the aspect ratio should conform to those values, though that is not required.
+ * [method@Gdk.Paintable.get_intrinsic_width] and
+ * [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio
+ * should conform to those values, though that is not required.
  *
- * If the @paintable does not have a preferred aspect ratio, it returns 0.
- * Negative values are never returned.
+ * If the @paintable does not have a preferred aspect ratio,
+ * it returns 0. Negative values are never returned.
  *
  * Returns: the intrinsic aspect ratio of @paintable or 0 if none.
  */
@@ -377,13 +389,15 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_invalidate_contents:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
+ *
+ * Called by implementations of `GdkPaintable` to invalidate their contents.
  *
- * Called by implementations of #GdkPaintable to invalidate their contents.
  * Unless the contents are invalidated, implementations must guarantee that
- * multiple calls of gdk_paintable_snapshot() produce the same output.
+ * multiple calls of [method@Gdk.Paintable.snapshot] produce the same output.
  *
- * This function will emit the #GdkPaintable::invalidate-contents signal.
+ * This function will emit the [signal@Gdk.Paintable::invalidate-contents]
+ * signal.
  *
  * If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag,
  * it must not call this function.
@@ -399,13 +413,15 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_invalidate_size:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
+ *
+ * Called by implementations of `GdkPaintable` to invalidate their size.
  *
- * Called by implementations of #GdkPaintable to invalidate their size.
  * As long as the size is not invalidated, @paintable must return the same
  * values for its intrinsic width, height and aspect ratio.
  *
- * This function will emit the #GdkPaintable::invalidate-size signal.
+ * This function will emit the [signal@Gdk.Paintable::invalidate-size]
+ * signal.
  *
  * If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag,
  * it must not call this function.
@@ -421,7 +437,7 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
 
 /**
  * gdk_paintable_compute_concrete_size:
- * @paintable: a #GdkPaintable
+ * @paintable: a `GdkPaintable`
  * @specified_width: the width @paintable could be drawn into or
  *     0.0 if unknown
  * @specified_height: the height @paintable could be drawn into or
@@ -435,8 +451,10 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
  * @concrete_height: (out): will be set to the concrete height
  *     computed.
  *
- * Applies the sizing algorithm outlined in
- * https://drafts.csswg.org/css-images-3/#default-sizing
+ * Compute a concrete size for the `GdkPaintable`.
+ *
+ * Applies the sizing algorithm outlined in the
+ * [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing)
  * to the given @paintable. See that link for more details.
  *
  * It is not necessary to call this function when both @specified_width
@@ -643,11 +661,13 @@ gdk_empty_paintable_init (GdkEmptyPaintable *self)
  * @intrinsic_height: The intrinsic height to report. Can be 0 for no height.
  *
  * Returns a paintable that has the given intrinsic size and draws nothing.
- * This is often useful for implementing the #GdkPaintableInterface.get_current_image()
- * virtual function when the paintable is in an incomplete state (like a
- * #GtkMediaStream before receiving the first frame).
  *
- * Returns: (transfer full): a #GdkPaintable
+ * This is often useful for implementing the
+ * #GdkPaintableInterface.get_current_image() virtual function
+ * when the paintable is in an incomplete state (like a
+ * [class@Gtk.MediaStream] before receiving the first frame).
+ *
+ * Returns: (transfer full): a `GdkPaintable`
  */
 GdkPaintable *
 gdk_paintable_new_empty (int intrinsic_width,
diff --git a/gdk/gdkpaintable.h b/gdk/gdkpaintable.h
index 2936a75b7a..938aa2bf59 100644
--- a/gdk/gdkpaintable.h
+++ b/gdk/gdkpaintable.h
@@ -31,25 +31,21 @@ G_BEGIN_DECLS
 
 #define GDK_TYPE_PAINTABLE               (gdk_paintable_get_type ())
 
-/**
- * GdkPaintable:
- *
- * Interface for paintable objects.
- */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkPaintable, gdk_paintable, GDK, PAINTABLE, GObject)
 
 /**
  * GdkPaintableFlags:
  * @GDK_PAINTABLE_STATIC_SIZE: The size is immutable.
- *     The #GdkPaintable::invalidate-size signal will never be
+ *     The [signal@GdkPaintable::invalidate-size] signal will never be
  *     emitted.
  * @GDK_PAINTABLE_STATIC_CONTENTS: The content is immutable.
- *     The #GdkPaintable::invalidate-contents signal will never be
+ *     The [signal@GdkPaintable::invalidate-contents] signal will never be
  *     emitted.
  *
- * Flags about this object. Implementations use these for optimizations
- * such as caching.
+ * Flags about a paintable object.
+ *
+ * Implementations use these for optimizations such as caching.
  */
 typedef enum {
   GDK_PAINTABLE_STATIC_SIZE = 1 << 0,
@@ -78,14 +74,15 @@ typedef enum {
  *     #GdkPaintableInterface.get_intrinsic_height() return non-zero values,
  *     this function should return the aspect ratio computed from those.
  *
- * The list of functions that can be implemented for the #GdkPaintable interface.
+ * The list of functions that can be implemented for the `GdkPaintable`
+ * interface.
  *
- * Note that apart from the #GdkPaintableInterface.snapshot() function, no virtual
- * function of this interface is mandatory to implement, though it is a good idea
- * to implement #GdkPaintableInterface.get_current_image() for non-static paintables
- * and #GdkPaintableInterface.get_flags() if the image is not dynamic as the default
- * implementation returns no flags and that will make the implementation likely
- * quite slow.
+ * Note that apart from the #GdkPaintableInterface.snapshot() function, no
+ * virtual function of this interface is mandatory to implement, though it
+ * is a good idea to implement #GdkPaintableInterface.get_current_image()
+ * for non-static paintables and #GdkPaintableInterface.get_flags() if the
+ * image is not dynamic as the default implementation returns no flags and
+ * that will make the implementation likely quite slow.
  */
 struct _GdkPaintableInterface
 {
diff --git a/gdk/gdkpopup.c b/gdk/gdkpopup.c
index 26b8fe55dd..20f7ca23bd 100644
--- a/gdk/gdkpopup.c
+++ b/gdk/gdkpopup.c
@@ -24,16 +24,15 @@
 #include "gdkpopupprivate.h"
 
 /**
- * SECTION:gdkpopup
- * @Short_description: Interface for popup surfaces
- * @Title: Popups
- * @See_also: #GdkToplevel, #GdkSurface
+ * GdkPopup:
  *
- * A #GdkPopup is a surface that is attached to another surface,
- * called its #GdkPopup:parent, and is positioned relative to it.
+ * A `GdkPopup` is a surface that is attached to another surface.
  *
- * #GdkPopups are typically used to implement menus and similar popups.
- * They can be modal, which is indicated by the #GdkPopup:autohide property.
+ * The `GdkPopup` is positioned relative to its parent surface.
+ *
+ * `GdkPopup`s are typically used to implement menus and similar popups.
+ * They can be modal, which is indicated by the [property@GdkPopup:autohide]
+ * property.
  */
 
 G_DEFINE_INTERFACE (GdkPopup, gdk_popup, GDK_TYPE_SURFACE)
@@ -96,25 +95,26 @@ gdk_popup_default_init (GdkPopupInterface *iface)
 
 /**
  * gdk_popup_present:
- * @popup: the #GdkPopup to show
+ * @popup: the `GdkPopup` to show
  * @width: the unconstrained popup width to layout
  * @height: the unconstrained popup height to layout
- * @layout: the #GdkPopupLayout object used to layout
+ * @layout: the `GdkPopupLayout` object used to layout
  *
  * Present @popup after having processed the #GdkPopupLayout rules.
+ *
  * If the popup was previously now showing, it will be showed,
  * otherwise it will change position according to @layout.
  *
  * After calling this function, the result should be handled in response
- * to the #GdkSurface::layout signal being emitted. The resulting popup
- * position can be queried using gdk_popup_get_position_x(),
- * gdk_popup_get_position_y(), and the resulting size will be sent as
- * parameters in the layout signal. Use gdk_popup_get_rect_anchor() and
- * gdk_popup_get_surface_anchor() to get the resulting anchors.
+ * to the [signal@GdkSurface::layout] signal being emitted. The resulting
+ * popup position can be queried using [method@Gdk.Popup.get_position_x],
+ * [method@Gdk.Popup.get_position_y], and the resulting size will be sent as
+ * parameters in the layout signal. Use [method@Gdk.Popup.get_rect_anchor]
+ * and [method@Gdk.Popup.get_surface_anchor] to get the resulting anchors.
  *
  * Presenting may fail, for example if the @popup is set to autohide
  * and is immediately hidden upon being presented. If presenting failed,
- * the #GdkSurface::layout signal will not me emitted.
+ * the [signal@Gdk.Surface::layout] signal will not me emitted.
  *
  * Returns: %FALSE if it failed to be presented, otherwise %TRUE.
  */
@@ -134,12 +134,12 @@ gdk_popup_present (GdkPopup       *popup,
 
 /**
  * gdk_popup_get_surface_anchor:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Gets the current popup surface anchor.
  *
- * The value returned may change after calling gdk_popup_present(),
- * or after the #GdkSurface::layout signal is emitted.
+ * The value returned may change after calling [method@Gdk.Popup.present],
+ * or after the [signal@Gdk.Surface::layout] signal is emitted.
  *
  * Returns: the current surface anchor value of @popup
  */
@@ -153,12 +153,12 @@ gdk_popup_get_surface_anchor (GdkPopup *popup)
 
 /**
  * gdk_popup_get_rect_anchor:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Gets the current popup rectangle anchor.
  *
- * The value returned may change after calling gdk_popup_present(),
- * or after the #GdkSurface::layout signal is emitted.
+ * The value returned may change after calling [method@Gdk.Popup.present],
+ * or after the [signal@Gdk.Surface::layout] signal is emitted.
  *
  * Returns: the current rectangle anchor value of @popup
  */
@@ -172,7 +172,7 @@ gdk_popup_get_rect_anchor (GdkPopup *popup)
 
 /**
  * gdk_popup_get_parent:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Returns the parent surface of a popup.
  *
@@ -195,7 +195,7 @@ gdk_popup_get_parent (GdkPopup *popup)
 
 /**
  * gdk_popup_get_position_x:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Obtains the position of the popup relative to its parent.
  *
@@ -211,7 +211,7 @@ gdk_popup_get_position_x (GdkPopup *popup)
 
 /**
  * gdk_popup_get_position_y:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Obtains the position of the popup relative to its parent.
  *
@@ -227,7 +227,7 @@ gdk_popup_get_position_y (GdkPopup *popup)
 
 /**
  * gdk_popup_get_autohide:
- * @popup: a #GdkPopup
+ * @popup: a `GdkPopup`
  *
  * Returns whether this popup is set to hide on outside clicks.
  *
@@ -249,7 +249,18 @@ guint
 gdk_popup_install_properties (GObjectClass *object_class,
                               guint         first_prop)
 {
+  /**
+   * GdkToplevel:parent:
+   *
+   * The parent surface of the toplevel.
+   */
   g_object_class_override_property (object_class, first_prop + GDK_POPUP_PROP_PARENT, "parent");
+
+  /**
+   * GdkToplevel:autohide:
+   *
+   * Whether the toplevel should be modal with respect to its parent.
+   */
   g_object_class_override_property (object_class, first_prop + GDK_POPUP_PROP_AUTOHIDE, "autohide");
 
   return GDK_POPUP_NUM_PROPERTIES;
diff --git a/gdk/gdkpopup.h b/gdk/gdkpopup.h
index 361d4bac03..ba8a2782a7 100644
--- a/gdk/gdkpopup.h
+++ b/gdk/gdkpopup.h
@@ -31,11 +31,6 @@ G_BEGIN_DECLS
 
 #define GDK_TYPE_POPUP (gdk_popup_get_type ())
 
-/**
- * GdkPopup:
- *
- * Interface for popup surfaces.
- */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkPopup, gdk_popup, GDK, POPUP, GObject)
 
diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c
index 686a2cbafe..ccf815d0f1 100644
--- a/gdk/gdkpopuplayout.c
+++ b/gdk/gdkpopuplayout.c
@@ -23,13 +23,10 @@
 #include "gdksurface.h"
 
 /**
- * SECTION:gdkpopuplayout
- * @Title: GdkPopupLayout
- * @Short_description: Information for presenting popups
+ * GdkPopupLayout:
  *
- * Popups are positioned relative to their parent surface.
- * The GdkPopupLayout struct contains information that is
- * necessary to do so.
+ * The `GdkPopupLayout` struct contains information that is
+ * necessary position a `GdkPopup` relaive to its parent.
  *
  * The positioning requires a negotiation with the windowing system,
  * since it depends on external constraints, such as the position of
@@ -55,12 +52,12 @@
  *
  * Ultimatively, it is up to the windowing system to determine the position
  * and size of the popup. You can learn about the result by calling
- * gdk_popup_get_position_x(), gdk_popup_get_position_y(),
- * gdk_popup_get_rect_anchor() and gdk_popup_get_surface_anchor() after the
- * popup has been presented. This can be used to adjust the rendering. For
- * example, GtkPopover changes its arrow position accordingly. But you have
- * to be careful avoid changing the size of the popover, or it has to be
- * presented again.
+ * [method@Gdk.Popup.get_position_x], [method@Gdk.Popup.get_position_y],
+ * [method@Gdk.Popup.get_rect_anchor] and [method@Gdk.Popup.get_surface_anchor]
+ * after the popup has been presented. This can be used to adjust the rendering.
+ * For example, [class@Gtk.Popover] changes its arrow position accordingly.
+ * But you have to be careful avoid changing the size of the popover, or it
+ * has to be presented again.
  */
 
 struct _GdkPopupLayout
@@ -86,22 +83,24 @@ G_DEFINE_BOXED_TYPE (GdkPopupLayout, gdk_popup_layout,
 
 /**
  * gdk_popup_layout_new: (constructor)
- * @anchor_rect:  (not nullable): the anchor #GdkRectangle to align @surface with
+ * @anchor_rect:  (not nullable): the anchor `GdkRectangle` to align @surface with
  * @rect_anchor: the point on @anchor_rect to align with @surface's anchor point
  * @surface_anchor: the point on @surface to align with @rect's anchor point
  *
- * Create a popup layout description. Used together with gdk_popup_present()
- * to describe how a popup surface should be placed and behave on-screen.
+ * Create a popup layout description.
+ *
+ * Used together with [method@Gdk.Popup.present] to describe how a popup
+ * surface should be placed and behave on-screen.
  *
  * @anchor_rect is relative to the top-left corner of the surface's parent.
  * @rect_anchor and @surface_anchor determine anchor points on @anchor_rect
  * and surface to pin together.
  *
  * The position of @anchor_rect's anchor point can optionally be offset using
- * gdk_popup_layout_set_offset(), which is equivalent to offsetting the
+ * [method@Gdk.PopupLayout.set_offset], which is equivalent to offsetting the
  * position of surface.
  *
- * Returns: (transfer full): newly created instance of #GdkPopupLayout
+ * Returns: (transfer full): newly created instance of `GdkPopupLayout`
  */
 GdkPopupLayout *
 gdk_popup_layout_new (const GdkRectangle *anchor_rect,
@@ -121,7 +120,7 @@ gdk_popup_layout_new (const GdkRectangle *anchor_rect,
 
 /**
  * gdk_popup_layout_ref:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
  * Increases the reference count of @value.
  *
@@ -136,7 +135,7 @@ gdk_popup_layout_ref (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_unref:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
  * Decreases the reference count of @value.
  */
@@ -149,9 +148,9 @@ gdk_popup_layout_unref (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_copy:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
- * Create a new #GdkPopupLayout and copy the contents of @layout into it.
+ * Makes a copy of @layout.
  *
  * Returns: (transfer full): a copy of @layout.
  */
@@ -179,13 +178,13 @@ gdk_popup_layout_copy (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_equal:
- * @layout: a #GdkPopupLayout
- * @other: another #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
+ * @other: another `GdkPopupLayout`
  *
  * Check whether @layout and @other has identical layout properties.
  *
  * Returns: %TRUE if @layout and @other have identical layout properties,
- * otherwise %FALSE.
+ *   otherwise %FALSE.
  */
 gboolean
 gdk_popup_layout_equal (GdkPopupLayout *layout,
@@ -208,7 +207,7 @@ gdk_popup_layout_equal (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_set_anchor_rect:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @anchor_rect: the new anchor rectangle
  *
  * Set the anchor rectangle.
@@ -222,11 +221,11 @@ gdk_popup_layout_set_anchor_rect (GdkPopupLayout     *layout,
 
 /**
  * gdk_popup_layout_get_anchor_rect:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
  * Get the anchor rectangle.
  *
- * Returns: The anchor rectangle.
+ * Returns: The anchor rectangle
  */
 const GdkRectangle *
 gdk_popup_layout_get_anchor_rect (GdkPopupLayout *layout)
@@ -236,7 +235,7 @@ gdk_popup_layout_get_anchor_rect (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_set_rect_anchor:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @anchor: the new rect anchor
  *
  * Set the anchor on the anchor rectangle.
@@ -250,7 +249,7 @@ gdk_popup_layout_set_rect_anchor (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_get_rect_anchor:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
  * Returns the anchor position on the anchor rectangle.
  *
@@ -264,7 +263,7 @@ gdk_popup_layout_get_rect_anchor (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_set_surface_anchor:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @anchor: the new popup surface anchor
  *
  * Set the anchor on the popup surface.
@@ -278,7 +277,7 @@ gdk_popup_layout_set_surface_anchor (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_get_surface_anchor:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
  * Returns the anchor position on the popup surface.
  *
@@ -292,15 +291,16 @@ gdk_popup_layout_get_surface_anchor (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_set_anchor_hints:
- * @layout: a #GdkPopupLayout
- * @anchor_hints: the new #GdkAnchorHints
+ * @layout: a `GdkPopupLayout`
+ * @anchor_hints: the new `GdkAnchorHints`
  *
  * Set new anchor hints.
  *
- * The set @anchor_hints determines how @surface will be moved if the anchor
- * points cause it to move off-screen. For example, %GDK_ANCHOR_FLIP_X will
- * replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_NORTH_EAST and vice versa
- * if @surface extends beyond the left or right edges of the monitor.
+ * The set @anchor_hints determines how @surface will be moved
+ * if the anchor points cause it to move off-screen. For example,
+ * %GDK_ANCHOR_FLIP_X will replace %GDK_GRAVITY_NORTH_WEST with
+ * %GDK_GRAVITY_NORTH_EAST and vice versa if @surface extends
+ * beyond the left or right edges of the monitor.
  */
 void
 gdk_popup_layout_set_anchor_hints (GdkPopupLayout *layout,
@@ -311,11 +311,11 @@ gdk_popup_layout_set_anchor_hints (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_get_anchor_hints:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  *
- * Get the #GdkAnchorHints.
+ * Get the `GdkAnchorHints`.
  *
- * Returns: the #GdkAnchorHints.
+ * Returns: the `GdkAnchorHints`
  */
 GdkAnchorHints
 gdk_popup_layout_get_anchor_hints (GdkPopupLayout *layout)
@@ -325,7 +325,7 @@ gdk_popup_layout_get_anchor_hints (GdkPopupLayout *layout)
 
 /**
  * gdk_popup_layout_set_offset:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @dx: x delta to offset the anchor rectangle with
  * @dy: y delta to offset the anchor rectangle with
  *
@@ -342,7 +342,7 @@ gdk_popup_layout_set_offset (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_get_offset:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @dx: (out): return location for the delta X coordinate
  * @dy: (out): return location for the delta Y coordinate
  *
@@ -361,15 +361,17 @@ gdk_popup_layout_get_offset (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_set_shadow_width:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @left: width of the left part of the shadow
  * @right: width of the right part of the shadow
  * @top: height of the top part of the shadow
  * @bottom: height of the bottom part of the shadow
  *
- * The shadow width corresponds to the part of the computed surface size
- * that would consist of the shadow margin surrounding the window, would
- * there be any.
+ * Sets the shadow width of the popup.
+ *
+ * The shadow width corresponds to the part of the computed
+ * surface size that would consist of the shadow margin
+ * surrounding the window, would there be any.
  *
  * Since: 4.2
  */
@@ -388,7 +390,7 @@ gdk_popup_layout_set_shadow_width (GdkPopupLayout *layout,
 
 /**
  * gdk_popup_layout_get_shadow_width:
- * @layout: a #GdkPopupLayout
+ * @layout: a `GdkPopupLayout`
  * @left: (out): return location for the left shadow width
  * @right: (out): return location for the right shadow width
  * @top: (out): return location for the top shadow width
diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c
index 83b77429cf..3db6292bfe 100644
--- a/gdk/gdkrectangle.c
+++ b/gdk/gdkrectangle.c
@@ -29,15 +29,17 @@
 
 
 /**
- * SECTION:gdkregion
- * @Short_description: Simple graphical data type
- * @Title: GdkRectangle
+ * GdkRectangle:
+ * @x: the x coordinate of the top left corner
+ * @y: the y coordinate of the top left corner
+ * @width: the width of the rectangle
+ * @height: the height of the rectangle
  *
- * GDK provides a `GdkRectangle` data type for representing rectangles.
- * Together with Cairo’s `cairo_region_t` data type, these are the central
- * types for representing sets of pixels.
+ * A `GdkRectangle` data type for representing rectangles.
  *
- * A #GdkRectangle represents the position and size of a rectangle.
+ * `GdkRectangle` is identical to `cairo_rectangle_t`. Together with Cairo’s
+ * `cairo_region_t` data type, these are the central types for representing
+ * sets of pixels.
  *
  * The intersection of two rectangles can be computed with
  * [method@Gdk.Rectangle.intersect]; to find the union of two rectangles use
@@ -53,14 +55,15 @@
 
 /**
  * gdk_rectangle_union:
- * @src1: a #GdkRectangle
- * @src2: a #GdkRectangle
+ * @src1: a `GdkRectangle`
+ * @src2: a `GdkRectangle`
  * @dest: (out): return location for the union of @src1 and @src2
  *
  * Calculates the union of two rectangles.
+ *
  * The union of rectangles @src1 and @src2 is the smallest rectangle which
- * includes both @src1 and @src2 within it.
- * It is allowed for @dest to be the same as either @src1 or @src2.
+ * includes both @src1 and @src2 within it. It is allowed for @dest to be
+ * the same as either @src1 or @src2.
  *
  * Note that this function does not ignore 'empty' rectangles (ie. with
  * zero width or height).
@@ -86,17 +89,18 @@ gdk_rectangle_union (const GdkRectangle *src1,
 
 /**
  * gdk_rectangle_intersect:
- * @src1: a #GdkRectangle
- * @src2: a #GdkRectangle
+ * @src1: a `GdkRectangle`
+ * @src2: a `GdkRectangle`
  * @dest: (out caller-allocates) (allow-none): return location for the
- * intersection of @src1 and @src2, or %NULL
+ *   intersection of @src1 and @src2, or %NULL
  *
- * Calculates the intersection of two rectangles. It is allowed for
- * @dest to be the same as either @src1 or @src2. If the rectangles 
- * do not intersect, @dest’s width and height is set to 0 and its x 
- * and y values are undefined. If you are only interested in whether
- * the rectangles intersect, but not in the intersecting area itself,
- * pass %NULL for @dest.
+ * Calculates the intersection of two rectangles.
+ *
+ * It is allowed for @dest to be the same as either @src1 or @src2.
+ * If the rectangles do not intersect, @dest’s width and height is set
+ * to 0 and its x and y values are undefined. If you are only interested
+ * in whether the rectangles intersect, but not in the intersecting area
+ * itself, pass %NULL for @dest.
  *
  * Returns: %TRUE if the rectangles intersect.
  */
@@ -141,7 +145,7 @@ gdk_rectangle_intersect (const GdkRectangle *src1,
 
 /**
  * gdk_rectangle_contains_point:
- * @rect: a #GdkRectangle
+ * @rect: a `GdkRectangle`
  * @x: X coordinate
  * @y: Y coordinate
  *
@@ -164,8 +168,8 @@ gdk_rectangle_contains_point (const GdkRectangle *rect,
 
 /**
  * gdk_rectangle_equal:
- * @rect1: a #GdkRectangle
- * @rect2: a #GdkRectangle
+ * @rect1: a `GdkRectangle`
+ * @rect2: a `GdkRectangle`
  *
  * Checks if the two given rectangles are equal.
  *
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index a2525591c9..926990b095 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -30,18 +30,6 @@
 #include <errno.h>
 #include <math.h>
 
-/**
- * SECTION:gdkrgba
- * @Title: GdkRGBA
- * @Short_description: RGBA colors
- *
- * #GdkRGBA is a convenient way to pass colors around.
- * It’s based on cairo’s way to deal with colors and mirrors its behavior.
- * All values are in the range from 0.0 to 1.0 inclusive. So the color
- * (0.0, 0.0, 0.0, 0.0) represents transparent black and
- * (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped
- * to this range when drawing.
- */
 
 G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba,
                      gdk_rgba_copy, gdk_rgba_free)
@@ -54,19 +42,26 @@ G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba,
  * @alpha: The opacity of the color from 0.0 for completely translucent to
  *   1.0 for opaque
  *
- * A #GdkRGBA is used to represent a (possibly translucent)
- * color, in a way that is compatible with cairo’s notion of color.
+ * A `GdkRGBA` is used to represent a color, in a way that is compatible
+ * with cairo’s notion of color.
+ *
+ * `GdkRGBA` is a convenient way to pass colors around. It’s based on
+ * cairo’s way to deal with colors and mirrors its behavior. All values
+ * are in the range from 0.0 to 1.0 inclusive. So the color
+ * (0.0, 0.0, 0.0, 0.0) represents transparent black and
+ * (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will
+ * be clamped to this range when drawing.
  */
 
 /**
  * gdk_rgba_copy:
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
  *
- * Makes a copy of a #GdkRGBA.
+ * Makes a copy of a `GdkRGBA`.
  *
- * The result must be freed through gdk_rgba_free().
+ * The result must be freed through [method Gdk Rgba free].
  *
- * Returns: A newly allocated #GdkRGBA, with the same contents as @rgba
+ * Returns: A newly allocated `GdkRGBA`, with the same contents as @rgba
  */
 GdkRGBA *
 gdk_rgba_copy (const GdkRGBA *rgba)
@@ -76,9 +71,9 @@ gdk_rgba_copy (const GdkRGBA *rgba)
 
 /**
  * gdk_rgba_free:
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
  *
- * Frees a #GdkRGBA created with gdk_rgba_copy()
+ * Frees a `GdkRGBA`.
  */
 void
 gdk_rgba_free (GdkRGBA *rgba)
@@ -88,10 +83,11 @@ gdk_rgba_free (GdkRGBA *rgba)
 
 /**
  * gdk_rgba_is_clear:
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
+ *
+ * Checks if an @rgba value is transparent.
  *
- * Checks if an @rgba value is transparent. That is, drawing with the value
- * would not produce any change.
+ * That is, drawing with the value would not produce any change.
  *
  * Returns: %TRUE if the @rgba is clear
  */
@@ -103,10 +99,12 @@ gdk_rgba_is_clear (const GdkRGBA *rgba)
 
 /**
  * gdk_rgba_is_opaque:
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
+ *
+ * Checks if an @rgba value is opaque.
  *
- * Checks if an @rgba value is opaque. That is, drawing with the value
- * will not retain any results from previous contents.
+ * That is, drawing with the value will not retain any results
+ * from previous contents.
  *
  * Returns: %TRUE if the @rgba is opaque
  */
@@ -160,26 +158,27 @@ parse_rgb_value (const char   *str,
 
 /**
  * gdk_rgba_parse:
- * @rgba: the #GdkRGBA to fill in
+ * @rgba: the `GdkRGBA` to fill in
  * @spec: the string specifying the color
  *
- * Parses a textual representation of a color, filling in
- * the @red, @green, @blue and @alpha fields of the @rgba #GdkRGBA.
+ * Parses a textual representation of a color.
  *
  * The string can be either one of:
+ *
  * - A standard name (Taken from the X11 rgb.txt file).
  * - A hexadecimal value in the form “\#rgb”, “\#rrggbb”,
  *   “\#rrrgggbbb” or ”\#rrrrggggbbbb”
  * - A hexadecimal value in the form “\#rgba”, “\#rrggbbaa”,
  *   or ”\#rrrrggggbbbbaaaa”
- * - A RGB color in the form “rgb(r,g,b)” (In this case the color will
- *   have full opacity)
+ * - A RGB color in the form “rgb(r,g,b)” (In this case the color
+ *   will have full opacity)
  * - A RGBA color in the form “rgba(r,g,b,a)”
  *
- * Where “r”, “g”, “b” and “a” are respectively the red, green, blue and
- * alpha color values. In the last two cases, “r”, “g”, and “b” are either
- * integers in the range 0 to 255 or percentage values in the range 0% to
- * 100%, and a is a floating point value in the range 0 to 1.
+ * Where “r”, “g”, “b” and “a” are respectively the red, green,
+ * blue and alpha color values. In the last two cases, “r”, “g”,
+ * and “b” are either integers in the range 0 to 255 or percentage
+ * values in the range 0% to 100%, and a is a floating point value
+ * in the range 0 to 1.
  *
  * Returns: %TRUE if the parsing succeeded
  */
@@ -306,10 +305,10 @@ gdk_rgba_parse (GdkRGBA    *rgba,
 
 /**
  * gdk_rgba_hash:
- * @p: (type GdkRGBA): a #GdkRGBA pointer
+ * @p: (type GdkRGBA): a `GdkRGBA`
  *
  * A hash function suitable for using for a hash
- * table that stores #GdkRGBAs.
+ * table that stores `GdkRGBA`s.
  *
  * Returns: The hash value for @p
  */
@@ -326,10 +325,10 @@ gdk_rgba_hash (gconstpointer p)
 
 /**
  * gdk_rgba_equal:
- * @p1: (type GdkRGBA): a #GdkRGBA pointer
- * @p2: (type GdkRGBA): another #GdkRGBA pointer
+ * @p1: (type GdkRGBA): a `GdkRGBA`
+ * @p2: (type GdkRGBA): another `GdkRGBA`
  *
- * Compares two RGBA colors.
+ * Compares two `GdkRGBA` colors.
  *
  * Returns: %TRUE if the two colors compare equal
  */
@@ -353,23 +352,21 @@ gdk_rgba_equal (gconstpointer p1,
 
 /**
  * gdk_rgba_to_string:
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
  *
  * Returns a textual specification of @rgba in the form
- * `rgb(r,g,b)` or
- * `rgba(r,g,b,a)`,
- * where “r”, “g”, “b” and “a” represent the red, green,
- * blue and alpha values respectively. “r”, “g”, and “b” are
- * represented as integers in the range 0 to 255, and “a”
- * is represented as a floating point value in the range 0 to 1.
+ * `rgb(r,g,b)` or `rgba(r,g,b,a)`, where “r”, “g”, “b” and
+ * “a” represent the red, green, blue and alpha values
+ * respectively. “r”, “g”, and “b” are represented as integers
+ * in the range 0 to 255, and “a” is represented as a floating
+ * point value in the range 0 to 1.
  *
  * These string forms are string forms that are supported by
- * the CSS3 colors module, and can be parsed by gdk_rgba_parse().
+ * the CSS3 colors module, and can be parsed by [method Gdk RGBA.parse].
  *
- * Note that this string representation may lose some
- * precision, since “r”, “g” and “b” are represented as 8-bit
- * integers. If this is a concern, you should use a
- * different representation.
+ * Note that this string representation may lose some precision,
+ * since “r”, “g” and “b” are represented as 8-bit integers. If
+ * this is a concern, you should use a different representation.
  *
  * Returns: A newly allocated text string
  */
@@ -578,4 +575,3 @@ gdk_rgba_parser_parse (GtkCssParser *parser,
       return FALSE;
     }
 }
-
diff --git a/gdk/gdkseat.c b/gdk/gdkseat.c
index 83af3b88a4..397dc9ff4b 100644
--- a/gdk/gdkseat.c
+++ b/gdk/gdkseat.c
@@ -28,21 +28,11 @@
 #include "gdkintl.h"
 #include "gdkinternals.h"
 
-/**
- * SECTION:gdkseat
- * @Short_description: Object representing a user seat
- * @Title: GdkSeat
- * @See_also: #GdkDisplay, #GdkDevice
- *
- * The #GdkSeat object represents a collection of input devices
- * that belong to a user.
- */
-
 /**
  * GdkSeat:
  *
- * The GdkSeat struct contains only private fields and
- * should not be accessed directly.
+ * The `GdkSeat` object represents a collection of input devices
+ * that belong to a user.
  */
 
 typedef struct _GdkSeatPrivate GdkSeatPrivate;
@@ -120,10 +110,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
   /**
    * GdkSeat::device-added:
    * @seat: the object on which the signal is emitted
-   * @device: the newly added #GdkDevice.
+   * @device: the newly added `GdkDevice`.
    *
-   * The ::device-added signal is emitted when a new input
-   * device is related to this seat.
+   * Emitted when a new input device is related to this seat.
    */
   signals [DEVICE_ADDED] =
     g_signal_new (g_intern_static_string ("device-added"),
@@ -138,10 +127,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
   /**
    * GdkSeat::device-removed:
    * @seat: the object on which the signal is emitted
-   * @device: the just removed #GdkDevice.
+   * @device: the just removed `GdkDevice`.
    *
-   * The ::device-removed signal is emitted when an
-   * input device is removed (e.g. unplugged).
+   * Emitted when an input device is removed (e.g. unplugged).
    */
   signals [DEVICE_REMOVED] =
     g_signal_new (g_intern_static_string ("device-removed"),
@@ -156,12 +144,13 @@ gdk_seat_class_init (GdkSeatClass *klass)
   /**
    * GdkSeat::tool-added:
    * @seat: the object on which the signal is emitted
-   * @tool: the new #GdkDeviceTool known to the seat
+   * @tool: the new `GdkDeviceTool` known to the seat
    *
-   * The ::tool-added signal is emitted whenever a new tool
-   * is made known to the seat. The tool may later be assigned
-   * to a device (i.e. on proximity with a tablet). The device
-   * will emit the #GdkDevice::tool-changed signal accordingly.
+   * Emitted whenever a new tool is made known to the seat.
+   *
+   * The tool may later be assigned to a device (i.e. on
+   * proximity with a tablet). The device will emit the
+   * [signalGdkDevice::tool-changed] signal accordingly.
    *
    * A same tool may be used by several devices.
    */
@@ -177,10 +166,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
   /**
    * GdkSeat::tool-removed:
    * @seat: the object on which the signal is emitted
-   * @tool: the just removed #GdkDeviceTool
+   * @tool: the just removed `GdkDeviceTool`
    *
-   * This signal is emitted whenever a tool is no longer known
-   * to this @seat.
+   * Emitted whenever a tool is no longer known to this @seat.
    */
   signals [TOOL_REMOVED] =
     g_signal_new (g_intern_static_string ("tool-removed"),
@@ -194,7 +182,7 @@ gdk_seat_class_init (GdkSeatClass *klass)
   /**
    * GdkSeat:display:
    *
-   * #GdkDisplay of this seat.
+   * `GdkDisplay` of this seat.
    */
   props[PROP_DISPLAY] =
     g_param_spec_object ("display",
@@ -215,12 +203,12 @@ gdk_seat_init (GdkSeat *seat)
 
 /**
  * gdk_seat_get_capabilities:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
  *
- * Returns the capabilities this #GdkSeat currently has.
+ * Returns the capabilities this `GdkSeat` currently has.
  *
  * Returns: the seat capabilities
- **/
+ */
 GdkSeatCapabilities
 gdk_seat_get_capabilities (GdkSeat *seat)
 {
@@ -234,30 +222,30 @@ gdk_seat_get_capabilities (GdkSeat *seat)
 
 /*
  * gdk_seat_grab:
- * @seat: a #GdkSeat
- * @surface: the #GdkSurface which will own the grab
+ * @seat: a `GdkSeat`
+ * @surface: the `GdkSurface` which will own the grab
  * @capabilities: capabilities that will be grabbed
  * @owner_events: if %FALSE then all device events are reported with respect to
- *                @surface and are only reported if selected by @event_mask. If
- *                %TRUE then pointer events for this application are reported
- *                as normal, but pointer events outside this application are
- *                reported with respect to @surface and only if selected by
- *                @event_mask. In either mode, unreported events are discarded.
- * @cursor: (nullable): the cursor to display while the grab is active. If
- *          this is %NULL then the normal cursors are used for
- *          @surface and its descendants, and the cursor for @surface is used
- *          elsewhere.
+ *   @surface and are only reported if selected by @event_mask. If %TRUE then
+ *   pointer events for this application are reported as normal, but pointer
+ *   events outside this application are reported with respect to @surface and
+ *   only if selected by @event_mask. In either mode, unreported events are
+ *   discarded.
+ * @cursor: (nullable): the cursor to display while the grab is active.
+ *   If this is %NULL then the normal cursors are used for @surface and
+ *   its descendants, and the cursor for @surface is used elsewhere.
  * @event: (nullable): the event that is triggering the grab, or %NULL if none
- *         is available.
- * @prepare_func: (nullable) (scope call): function to
- *                prepare the surface to be grabbed, it can be %NULL if @surface is
- *                visible before this call.
+ *   is available.
+ * @prepare_func: (nullable) (scope call): function to prepare the surface
+ *   to be grabbed, it can be %NULL if @surface is visible before this call.
  * @prepare_func_data: (closure): user data to pass to @prepare_func
  *
  * Grabs the seat so that all events corresponding to the given @capabilities
- * are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(),
- * or the surface becomes hidden. This overrides any previous grab on the
- * seat by this client.
+ * are passed to this application.
+ *
+ * The grab remains in place until the seat is ungrabbed with
+ * [method Gdk Seat.ungrab], or the surface becomes hidden. This overrides
+ * any previous grab on the seat by this client.
  *
  * As a rule of thumb, if a grab is desired over %GDK_SEAT_CAPABILITY_POINTER,
  * all other "pointing" capabilities (eg. %GDK_SEAT_CAPABILITY_TOUCH) should
@@ -269,18 +257,18 @@ gdk_seat_get_capabilities (GdkSeat *seat)
  * events corresponding to the given capabilities. For example in GTK this
  * is used for Drag and Drop operations, popup menus and such.
  *
- * Note that if the event mask of a #GdkSurface has selected both button press
+ * Note that if the event mask of a `GdkSurface` has selected both button press
  * and button release events, or touch begin and touch end, then a press event
  * will cause an automatic grab until the button is released, equivalent to a
- * grab on the surface with @owner_events set to %TRUE. This is done because most
- * applications expect to receive paired press and release events.
+ * grab on the surface with @owner_events set to %TRUE. This is done because
+ * most applications expect to receive paired press and release events.
  *
  * If you set up anything at the time you take the grab that needs to be
- * cleaned up when the grab ends, you should handle the #GdkEventGrabBroken
+ * cleaned up when the grab ends, you should handle the `GdkEventGrabBroken`
  * events that are emitted when the grab ends unvoluntarily.
  *
  * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
- **/
+ */
 GdkGrabStatus
 gdk_seat_grab (GdkSeat                *seat,
                GdkSurface              *surface,
@@ -308,10 +296,12 @@ gdk_seat_grab (GdkSeat                *seat,
 
 /*
  * gdk_seat_ungrab:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
+ *
+ * Releases a grab.
  *
- * Releases a grab added through gdk_seat_grab().
- **/
+ * See [method Gdk Seat grab] for more information.
+ */
 void
 gdk_seat_ungrab (GdkSeat *seat)
 {
@@ -330,10 +320,10 @@ gdk_seat_ungrab (GdkSeat *seat)
  *
  * Returns the devices that match the given capabilities.
  *
- * Returns: (transfer container) (element-type GdkDevice): A list of #GdkDevices.
- *          The list must be freed with g_list_free(), the elements are owned
- *          by GTK and must not be freed.
- **/
+ * Returns: (transfer container) (element-type GdkDevice): A list
+ *   of `GdkDevices`. The list must be freed with g_list_free(),
+ *   the elements are owned by GTK and must not be freed.
+ */
 GList *
 gdk_seat_get_devices (GdkSeat             *seat,
                       GdkSeatCapabilities  capabilities)
@@ -348,13 +338,13 @@ gdk_seat_get_devices (GdkSeat             *seat,
 
 /**
  * gdk_seat_get_pointer:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
  *
  * Returns the device that routes pointer events.
  *
- * Returns: (transfer none) (nullable): a #GdkDevice with pointer
- *          capabilities. This object is owned by GTK and must not be freed.
- **/
+ * Returns: (transfer none) (nullable): a `GdkDevice` with pointer
+ *   capabilities. This object is owned by GTK and must not be freed.
+ */
 GdkDevice *
 gdk_seat_get_pointer (GdkSeat *seat)
 {
@@ -368,13 +358,13 @@ gdk_seat_get_pointer (GdkSeat *seat)
 
 /**
  * gdk_seat_get_keyboard:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
  *
  * Returns the device that routes keyboard events.
  *
- * Returns: (transfer none) (nullable): a #GdkDevice with keyboard
- *          capabilities. This object is owned by GTK and must not be freed.
- **/
+ * Returns: (transfer none) (nullable): a `GdkDevice` with keyboard
+ *   capabilities. This object is owned by GTK and must not be freed.
+ */
 GdkDevice *
 gdk_seat_get_keyboard (GdkSeat *seat)
 {
@@ -404,13 +394,13 @@ gdk_seat_device_removed (GdkSeat   *seat,
 
 /**
  * gdk_seat_get_display:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
  *
- * Returns the #GdkDisplay this seat belongs to.
+ * Returns the `GdkDisplay` this seat belongs to.
  *
- * Returns: (transfer none): a #GdkDisplay. This object is owned by GTK
- *          and must not be freed.
- **/
+ * Returns: (transfer none): a `GdkDisplay`. This object
+ *   is owned by GTK and must not be freed.
+ */
 GdkDisplay *
 gdk_seat_get_display (GdkSeat *seat)
 {
@@ -464,14 +454,13 @@ gdk_seat_get_tool (GdkSeat          *seat,
 
 /**
  * gdk_seat_get_tools:
- * @seat: A #GdkSeat
+ * @seat: a `GdkSeat`
  *
- * Returns all #GdkDeviceTools that are known to the
- * application.
+ * Returns all `GdkDeviceTools` that are known to the application.
  *
  * Returns: (transfer container) (element-type Gdk.DeviceTool):
- *     A list of tools. Free with g_list_free().
- **/
+ *   A list of tools. Free with g_list_free().
+ */
 GList *
 gdk_seat_get_tools (GdkSeat *seat)
 {
diff --git a/gdk/gdksnapshot.c b/gdk/gdksnapshot.c
index 1589428e5e..ae6b9fbc4c 100644
--- a/gdk/gdksnapshot.c
+++ b/gdk/gdksnapshot.c
@@ -21,6 +21,14 @@
 
 #include "gdksnapshotprivate.h"
 
+/**
+ * GdkSnapshot:
+ *
+ * Base type for snapshot operations.
+ *
+ * The subclass of `GdkSnapshot` used by GTK is [class@Gtk.Snapshot].
+ */
+
 G_DEFINE_ABSTRACT_TYPE (GdkSnapshot, gdk_snapshot, G_TYPE_OBJECT)
 
 static void
diff --git a/gdk/gdksnapshot.h b/gdk/gdksnapshot.h
index c2b4ce2e1c..e609ea3807 100644
--- a/gdk/gdksnapshot.h
+++ b/gdk/gdksnapshot.h
@@ -29,11 +29,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * GdkSnapshot:
- *
- * Base type for snapshot operations.
- */
 
 typedef struct _GdkSnapshotClass        GdkSnapshotClass;
 
diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 31c5b44b73..c04a2e7eef 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -52,27 +52,17 @@
 #endif
 
 /**
- * SECTION:gdksurface
- * @Short_description: Onscreen display areas in the target window system
- * @Title: Surfaces
- * @See_also: #GdkToplevel, #GdkPopup
+ * GdkSurface:
  *
- * A #GdkSurface is a (usually) rectangular region on the screen.
- * It’s a low-level object, used to implement high-level objects
- * such as #GtkWindow or #GtkDialog in GTK.
+ * A `GdkSurface` is a rectangular region on the screen.
  *
- * The surfaces you see in practice are either #GdkToplevel or
- * #GdkPopup, and those interfaces provide much of the required
- * API to interact with these surfaces. Other, more specialized
- * surface types exist, but you will rarely interact with them
- * directly.
- */
-
-/**
- * GdkSurface:
+ * It’s a low-level object, used to implement high-level objects
+ * such as [class@Gtk.Window] or [class@Gtk.Dialog] in GTK.
  *
- * The GdkSurface struct contains only private fields and
- * should not be accessed directly.
+ * The surfaces you see in practice are either [class@Gdk.Toplevel] or
+ * [class@Gdk.Popup], and those interfaces provide much of the required
+ * API to interact with these surfaces. Other, more specialized surface
+ * types exist, but you will rarely interact with them directly.
  */
 
 enum {
@@ -501,8 +491,10 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
   /**
    * GdkSurface:cursor:
    *
-   * The mouse pointer for a #GdkSurface. See gdk_surface_set_cursor() and
-   * gdk_surface_get_cursor() for details.
+   * The mouse pointer for the `GdkSurface`.
+   *
+   * See [method@Gdk.Surface.set_cursor] and
+   * [method@Gdk.Surface.get_cursor] for details.
    */
   properties[PROP_CURSOR] =
       g_param_spec_object ("cursor",
@@ -514,8 +506,9 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
   /**
    * GdkSurface:display:
    *
-   * The #GdkDisplay connection of the surface. See gdk_surface_get_display()
-   * for details.
+   * The `GdkDisplay` connection of the surface.
+   *
+   * See [method@Gdk.Surface.get_display] for details.
    */
   properties[PROP_DISPLAY] =
       g_param_spec_object ("display",
@@ -524,6 +517,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
                            GDK_TYPE_DISPLAY,
                            G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkSurface:frame-clock:
+   *
+   * The `GdkFrameClock` of the surface.
+   */
   properties[PROP_FRAME_CLOCK] =
       g_param_spec_object ("frame-clock",
                            P_("Frame Clock"),
@@ -531,6 +529,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
                            GDK_TYPE_FRAME_CLOCK,
                            G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkSurface:mapped:
+   *
+   * Whether the surface is mapped.
+   */
   properties[PROP_MAPPED] =
       g_param_spec_boolean ("mapped",
                             P_("Mapped"),
@@ -538,6 +541,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
                             FALSE,
                             G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkSurface:width:
+   *
+   * The width of the surface in pixels.
+   */
   properties[PROP_WIDTH] =
       g_param_spec_int ("width",
                         P_("Width"),
@@ -545,6 +553,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
                         0, G_MAXINT, 0,
                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkSurface:height:
+   *
+   * The height of the surface, in pixels.
+   */
   properties[PROP_HEIGHT] =
       g_param_spec_int ("height",
                         P_("Height"),
@@ -552,6 +565,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
                         0, G_MAXINT, 0,
                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkSurface:scale-factor:
+   *
+   * The scale factor of the surface.
+   */
   properties[PROP_SCALE_FACTOR] =
       g_param_spec_int ("scale-factor",
                         P_("Scale factor"),
@@ -563,7 +581,7 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
 
   /**
    * GdkSurface::layout:
-   * @surface: the #GdkSurface
+   * @surface: the `GdkSurface`
    * @width: the current width
    * @height: the current height
    *
@@ -588,13 +606,13 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
 
   /**
    * GdkSurface::render:
-   * @surface: the #GdkSurface
+   * @surface: the `GdkSurface`
    * @region: the region that needs to be redrawn
    *
    * Emitted when part of the surface needs to be redrawn.
    *
    * Returns: %TRUE to indicate that the signal has been handled
-   */ 
+   */
   signals[RENDER] =
     g_signal_new (g_intern_static_string ("render"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -612,13 +630,13 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
 
   /**
    * GdkSurface::event:
-   * @surface: the #GdkSurface
+   * @surface: the `GdkSurface`
    * @event: (type Gdk.Event): an input event
    *
    * Emitted when GDK receives an input event for @surface.
    *
    * Returns: %TRUE to indicate that the event has been handled
-   */ 
+   */
   signals[EVENT] =
     g_signal_new (g_intern_static_string ("event"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -636,11 +654,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
 
   /**
    * GdkSurface::enter-monitor:
-   * @surface: the #GdkSurface
+   * @surface: the `GdkSurface`
    * @monitor: the monitor
    *
    * Emitted when @surface starts being present on the monitor.
-   */ 
+   */
   signals[ENTER_MONITOR] =
     g_signal_new (g_intern_static_string ("enter-monitor"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -655,11 +673,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
 
   /**
    * GdkSurface::leave-monitor:
-   * @surface: the #GdkSurface
+   * @surface: the `GdkSurface`
    * @monitor: the monitor
    *
    * Emitted when @surface stops being present on the monitor.
-   */ 
+   */
   signals[LEAVE_MONITOR] =
     g_signal_new (g_intern_static_string ("leave-monitor"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -833,8 +851,8 @@ gdk_surface_new (GdkDisplay     *display,
  *
  * Creates a new toplevel surface.
  *
- * Returns: (transfer full): the new #GdkSurface
- **/
+ * Returns: (transfer full): the new `GdkSurface`
+ */
 GdkSurface *
 gdk_surface_new_toplevel (GdkDisplay *display)
 {
@@ -852,9 +870,9 @@ gdk_surface_new_toplevel (GdkDisplay *display)
  * Create a new popup surface.
  *
  * The surface will be attached to @parent and can be positioned
- * relative to it using gdk_popup_present().
+ * relative to it using [method@Gdk.Popup.present].
  *
- * Returns: (transfer full): a new #GdkSurface
+ * Returns: (transfer full): a new `GdkSurface`
  */
 GdkSurface *
 gdk_surface_new_popup (GdkSurface *parent,
@@ -898,20 +916,19 @@ surface_remove_from_pointer_info (GdkSurface  *surface,
 
 /**
  * _gdk_surface_destroy_hierarchy:
- * @surface: a #GdkSurface
- * @recursing_native: If %TRUE, then this is being called because a native parent
- *            was destroyed. This generally means that the call to the
- *            windowing system to destroy the surface can be omitted, since
- *            it will be destroyed as a result of the parent being destroyed.
- *            Unless @foreign_destroy.
+ * @surface: a `GdkSurface`
+ * @recursing_native: If %TRUE, then this is being called because a native
+ *   parent was destroyed. This generally means that the call to the windowing
+ *   system to destroy the surface can be omitted, since it will be destroyed
+ *   as a result of the parent being destroyed. Unless @foreign_destroy.
  * @foreign_destroy: If %TRUE, the surface or a parent was destroyed by some
- *            external agency. The surface has already been destroyed and no
- *            windowing system calls should be made. (This may never happen
- *            for some windowing systems.)
+ *   external agency. The surface has already been destroyed and no windowing
+ *   system calls should be made. (This may never happen for some windowing
+ *   systems.)
  *
  * Internal function to destroy a surface. Like gdk_surface_destroy(),
  * but does not drop the reference count created by gdk_surface_new().
- **/
+ */
 static void
 _gdk_surface_destroy_hierarchy (GdkSurface *surface,
                                 gboolean   foreign_destroy)
@@ -955,15 +972,15 @@ _gdk_surface_destroy_hierarchy (GdkSurface *surface,
 
 /**
  * _gdk_surface_destroy:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @foreign_destroy: If %TRUE, the surface or a parent was destroyed by some
- *            external agency. The surface has already been destroyed and no
- *            windowing system calls should be made. (This may never happen
- *            for some windowing systems.)
+ *   external agency. The surface has already been destroyed and no windowing
+ *   system calls should be made. (This may never happen for some windowing
+ *   systems.)
  *
  * Internal function to destroy a surface. Like gdk_surface_destroy(),
  * but does not drop the reference count created by gdk_surface_new().
- **/
+ */
 void
 _gdk_surface_destroy (GdkSurface *surface,
                       gboolean   foreign_destroy)
@@ -973,16 +990,18 @@ _gdk_surface_destroy (GdkSurface *surface,
 
 /**
  * gdk_surface_destroy:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
- * Destroys the window system resources associated with @surface and decrements @surface's
- * reference count. The window system resources for all children of @surface are also
- * destroyed, but the children’s reference counts are not decremented.
+ * Destroys the window system resources associated with @surface and
+ * decrements @surface's reference count.
  *
- * Note that a surface will not be destroyed automatically when its reference count
- * reaches zero. You must call this function yourself before that happens.
+ * The window system resources for all children of @surface are also
+ * destroyed, but the children’s reference counts are not decremented.
  *
- **/
+ * Note that a surface will not be destroyed automatically when its
+ * reference count reaches zero. You must call this function yourself
+ * before that happens.
+ */
 void
 gdk_surface_destroy (GdkSurface *surface)
 {
@@ -1005,12 +1024,12 @@ gdk_surface_get_widget (GdkSurface *surface)
 
 /**
  * gdk_surface_get_display:
- * @surface: a #GdkSurface
- * 
- * Gets the #GdkDisplay associated with a #GdkSurface.
- * 
- * Returns: (transfer none): the #GdkDisplay associated with @surface
- **/
+ * @surface: a `GdkSurface`
+ *
+ * Gets the `GdkDisplay` associated with a `GdkSurface`.
+ *
+ * Returns: (transfer none): the `GdkDisplay` associated with @surface
+ */
 GdkDisplay *
 gdk_surface_get_display (GdkSurface *surface)
 {
@@ -1020,12 +1039,12 @@ gdk_surface_get_display (GdkSurface *surface)
 }
 /**
  * gdk_surface_is_destroyed:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
- * Check to see if a surface is destroyed..
+ * Check to see if a surface is destroyed.
  *
  * Returns: %TRUE if the surface is destroyed
- **/
+ */
 gboolean
 gdk_surface_is_destroyed (GdkSurface *surface)
 {
@@ -1034,13 +1053,15 @@ gdk_surface_is_destroyed (GdkSurface *surface)
 
 /**
  * gdk_surface_get_mapped:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
+ *
+ * Checks whether the surface has been mapped.
  *
- * Checks whether the surface has been mapped (with gdk_toplevel_present()
- * or gdk_popup_present()).
+ * A surface is mapped with [method@Gdk.Toplevel.present]
+ * or [method@Gdk.Popup.present].
  *
  * Returns: %TRUE if the surface is mapped
- **/
+ */
 gboolean
 gdk_surface_get_mapped (GdkSurface *surface)
 {
@@ -1138,21 +1159,19 @@ gdk_surface_get_paint_gl_context (GdkSurface  *surface,
 
 /**
  * gdk_surface_create_gl_context:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @error: return location for an error
  *
- * Creates a new #GdkGLContext matching the
- * framebuffer format to the visual of the #GdkSurface. The context
- * is disconnected from any particular surface or surface.
+ * Creates a new `GdkGLContext` for the `GdkSurface`.
  *
- * If the creation of the #GdkGLContext failed, @error will be set.
+ * The context is disconnected from any particular surface or surface.
+ * If the creation of the `GdkGLContext` failed, @error will be set.
+ * Before using the returned `GdkGLContext`, you will need to
+ * call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize].
  *
- * Before using the returned #GdkGLContext, you will need to
- * call gdk_gl_context_make_current() or gdk_gl_context_realize().
- *
- * Returns: (transfer full): the newly created #GdkGLContext, or
- * %NULL on error
- **/
+ * Returns: (transfer full): the newly created `GdkGLContext`,
+ *   or %NULL on error
+ */
 GdkGLContext *
 gdk_surface_create_gl_context (GdkSurface   *surface,
                                GError      **error)
@@ -1174,12 +1193,12 @@ gdk_surface_create_gl_context (GdkSurface   *surface,
 
 /**
  * gdk_surface_create_cairo_context:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
- * Creates a new #GdkCairoContext for rendering on @surface.
+ * Creates a new `GdkCairoContext` for rendering on @surface.
  *
- * Returns: (transfer full): the newly created #GdkCairoContext
- **/
+ * Returns: (transfer full): the newly created `GdkCairoContext`
+ */
 GdkCairoContext *
 gdk_surface_create_cairo_context (GdkSurface *surface)
 {
@@ -1196,16 +1215,16 @@ gdk_surface_create_cairo_context (GdkSurface *surface)
 
 /**
  * gdk_surface_create_vulkan_context:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @error: return location for an error
  *
- * Creates a new #GdkVulkanContext for rendering on @surface.
+ * Creates a new `GdkVulkanContext` for rendering on @surface.
  *
- * If the creation of the #GdkVulkanContext failed, @error will be set.
+ * If the creation of the `GdkVulkanContext` failed, @error will be set.
  *
- * Returns: (transfer full): the newly created #GdkVulkanContext, or
- * %NULL on error
- **/
+ * Returns: (transfer full): the newly created `GdkVulkanContext`, or
+ *   %NULL on error
+ */
 GdkVulkanContext *
 gdk_surface_create_vulkan_context (GdkSurface  *surface,
                                    GError    **error)
@@ -1370,10 +1389,11 @@ gdk_surface_layout_on_clock (GdkFrameClock *clock,
 
 /**
  * gdk_surface_request_layout:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
+ *
+ * Request a layout phase from the surface's frame clock.
  *
- * Request a %GDK_FRAME_CLOCK_PHASE_LAYOUT from the surface's
- * frame clock. See gdk_frame_clock_request_phase().
+ * See [method@Gdk.FrameClock.request_phase].
  */
 void
 gdk_surface_request_layout (GdkSurface *surface)
@@ -1423,14 +1443,15 @@ gdk_surface_paint_on_clock (GdkFrameClock *clock,
 
 /*
  * gdk_surface_invalidate_rect:
- * @surface: a #GdkSurface
- * @rect: (allow-none): rectangle to invalidate or %NULL to invalidate the whole
- *      surface
- *
- * A convenience wrapper around gdk_surface_invalidate_region()
- * which invalidates a rectangular region.
- * See gdk_surface_invalidate_region() for details.
- **/
+ * @surface: a `GdkSurface`
+ * @rect: (allow-none): rectangle to invalidate or %NULL to
+ *   invalidate the whole surface
+ *
+ * Invalidate a rectangular region of @surface.
+ *
+ * This is a convenience wrapper around
+ * [method@Gdk.Surface.invalidate_region].
+ */
 void
 gdk_surface_invalidate_rect (GdkSurface        *surface,
                              const GdkRectangle *rect)
@@ -1473,14 +1494,14 @@ impl_surface_add_update_area (GdkSurface     *impl_surface,
 
 /**
  * gdk_surface_queue_render:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
- * Forces a #GdkSurface::render signal emission for @surface
+ * Forces a [signal@Gdk.Surface::render] signal emission for @surface
  * to be scheduled.
  *
  * This function is useful for implementations that track invalid
  * regions on their own.
- **/
+ */
 void
 gdk_surface_queue_render (GdkSurface *surface)
 {
@@ -1495,16 +1516,18 @@ gdk_surface_queue_render (GdkSurface *surface)
 
 /*
  * gdk_surface_invalidate_region:
- * @surface: a #GdkSurface
- * @region: a #cairo_region_t
+ * @surface: a `GdkSurface`
+ * @region: a `cairo_region_t`
+ *
+ * Adds @region to the update area for @surface.
  *
- * Adds @region to the update area for @surface. The update area is
- * the region that needs to be redrawn, or “dirty region.”
+ * The update area is the region that needs to be redrawn,
+ * or “dirty region.”
  *
- * GDK will process all updates whenever the frame clock schedules a
- * redraw, so there’s no need to do forces redraws manually, you just
- * need to invalidate regions that you know should be redrawn.
- **/
+ * GDK will process all updates whenever the frame clock schedules
+ * a redraw, so there’s no need to do forces redraws manually, you
+ * just need to invalidate regions that you know should be redrawn.
+ */
 void
 gdk_surface_invalidate_region (GdkSurface          *surface,
                                const cairo_region_t *region)
@@ -1535,11 +1558,11 @@ gdk_surface_invalidate_region (GdkSurface          *surface,
 
 /*
  * _gdk_surface_clear_update_area:
- * @surface: a #GdkSurface.
+ * @surface: a `GdkSurface`
  *
  * Internal function to clear the update area for a surface.
  * This is called when the surface is hidden or destroyed.
- **/
+ */
 void
 _gdk_surface_clear_update_area (GdkSurface *surface)
 {
@@ -1556,14 +1579,14 @@ _gdk_surface_clear_update_area (GdkSurface *surface)
 
 /*
  * gdk_surface_freeze_updates:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
  * Temporarily freezes a surface such that it won’t receive expose
  * events.  The surface will begin receiving expose events again when
  * gdk_surface_thaw_updates() is called. If gdk_surface_freeze_updates()
  * has been called more than once, gdk_surface_thaw_updates() must be
  * called an equal number of times to begin processing exposes.
- **/
+ */
 void
 gdk_surface_freeze_updates (GdkSurface *surface)
 {
@@ -1590,12 +1613,12 @@ request_motion_cb (void *data)
 
 /*
  * gdk_surface_thaw_updates:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
  * Thaws a surface frozen with gdk_surface_freeze_updates(). Note that this
  * will not necessarily schedule updates if the surface freeze count reaches
  * zero.
- **/
+ */
 void
 gdk_surface_thaw_updates (GdkSurface *surface)
 {
@@ -1623,7 +1646,7 @@ gdk_surface_thaw_updates (GdkSurface *surface)
 
 /*
  * gdk_surface_constrain_size:
- * @geometry: a #GdkGeometry structure
+ * @geometry: a `GdkGeometry` structure
  * @flags: a mask indicating what portions of @geometry are set
  * @width: desired width of surface
  * @height: desired height of the surface
@@ -1677,18 +1700,19 @@ gdk_surface_constrain_size (GdkGeometry    *geometry,
 
 /**
  * gdk_surface_get_device_position:
- * @surface: a #GdkSurface.
- * @device: pointer #GdkDevice to query to.
- * @x: (out) (allow-none): return location for the X coordinate of @device, or %NULL.
- * @y: (out) (allow-none): return location for the Y coordinate of @device, or %NULL.
- * @mask: (out) (allow-none): return location for the modifier mask, or %NULL.
+ * @surface: a `GdkSurface`
+ * @device: pointer `GdkDevice` to query to
+ * @x: (out) (allow-none): return locatio for the X coordinate of @device, or %NULL
+ * @y: (out) (allow-none): return location for the Y coordinate of @device, or %NULL
+ * @mask: (out) (allow-none): return location for the modifier mask, or %NULL
+ *
+ * Obtains the current device position and modifier state.
  *
- * Obtains the current device position in doubles and modifier state.
- * The position is given in coordinates relative to the upper left
- * corner of @surface.
+ * The position is given in coordinates relative to the upper
+ * left corner of @surface.
  *
  * Return: %TRUE if the device is over the surface
- **/
+ */
 gboolean
 gdk_surface_get_device_position (GdkSurface       *surface,
                                  GdkDevice       *device,
@@ -1725,12 +1749,14 @@ gdk_surface_get_device_position (GdkSurface       *surface,
 
 /**
  * gdk_surface_hide:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
+ *
+ * Hide the surface.
  *
  * For toplevel surfaces, withdraws them, so they will no longer be
  * known to the window manager; for all surfaces, unmaps them, so
  * they won’t be displayed. Normally done automatically as
- * part of gtk_widget_hide().
+ * part of [method Gtk Widget hide].
  */
 void
 gdk_surface_hide (GdkSurface *surface)
@@ -1811,17 +1837,18 @@ gdk_surface_set_cursor_internal (GdkSurface *surface,
 
 /**
  * gdk_surface_get_cursor:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
+ *
+ * Retrieves a `GdkCursor` pointer for the cursor currently set on the
+ * `GdkSurface`.
  *
- * Retrieves a #GdkCursor pointer for the cursor currently set on the
- * specified #GdkSurface, or %NULL.  If the return value is %NULL then
- * there is no custom cursor set on the specified surface, and it is
- * using the cursor for its parent surface.
+ * If the return value is %NULL then there is no custom cursor set on
+ * the surface, and it is using the cursor for its parent surface.
  *
- * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
- *   returned object is owned by the #GdkSurface and should not be
- *   unreferenced directly. Use gdk_surface_set_cursor() to unset the
- *   cursor of the surface
+ * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
+ *   returned object is owned by the `GdkSurface` and should not be
+ *   unreferenced directly. Use [method@Gdk.Surface.set_cursor] to
+ *   unset the cursor of the surface
  */
 GdkCursor *
 gdk_surface_get_cursor (GdkSurface *surface)
@@ -1833,22 +1860,21 @@ gdk_surface_get_cursor (GdkSurface *surface)
 
 /**
  * gdk_surface_set_cursor:
- * @surface: a #GdkSurface
- * @cursor: (allow-none): a cursor
+ * @surface: a `GdkSurface`
+ * @cursor: (allow-none): a `GdkCursor`
  *
- * Sets the default mouse pointer for a #GdkSurface.
+ * Sets the default mouse pointer for a `GdkSurface`.
  *
+ * Passing %NULL for the @cursor argument means that @surface will use
+ * the cursor of its parent surface. Most surfaces should use this default.
  * Note that @cursor must be for the same display as @surface.
  *
- * Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to
- * create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.
- * Passing %NULL for the @cursor argument to gdk_surface_set_cursor() means
- * that @surface will use the cursor of its parent surface. Most surfaces
- * should use this default.
+ * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture]
+ * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.
  */
 void
 gdk_surface_set_cursor (GdkSurface *surface,
-                        GdkCursor *cursor)
+                        GdkCursor  *cursor)
 {
   g_return_if_fail (GDK_IS_SURFACE (surface));
 
@@ -1891,22 +1917,23 @@ gdk_surface_set_cursor (GdkSurface *surface,
 
 /**
  * gdk_surface_get_device_cursor:
- * @surface: a #GdkSurface.
- * @device: a logical, pointer #GdkDevice.
- *
- * Retrieves a #GdkCursor pointer for the @device currently set on the
- * specified #GdkSurface, or %NULL.  If the return value is %NULL then
- * there is no custom cursor set on the specified surface, and it is
- * using the cursor for its parent surface.
- *
- * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
- *   returned object is owned by the #GdkSurface and should not be
- *   unreferenced directly. Use gdk_surface_set_cursor() to unset the
- *   cursor of the surface
- **/
+ * @surface: a `GdkSurface`
+ * @device: a pointer `GdkDevice`
+ *
+ * Retrieves a `GdkCursor` pointer for the @device currently set on the
+ * specified `GdkSurface`.
+ *
+ * If the return value is %NULL then there is no custom cursor set on the
+ * specified surface, and it is using the cursor for its parent surface.
+ *
+ * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
+ *   returned object is owned by the `GdkSurface` and should not be
+ *   unreferenced directly. Use [method@Gdk.Surface.set_cursor] to unset
+ *   the cursor of the surface
+ */
 GdkCursor *
 gdk_surface_get_device_cursor (GdkSurface *surface,
-                               GdkDevice *device)
+                               GdkDevice  *device)
 {
   g_return_val_if_fail (GDK_IS_SURFACE (surface), NULL);
   g_return_val_if_fail (GDK_IS_DEVICE (device), NULL);
@@ -1917,21 +1944,22 @@ gdk_surface_get_device_cursor (GdkSurface *surface,
 
 /**
  * gdk_surface_set_device_cursor:
- * @surface: a #GdkSurface
- * @device: a logical, pointer #GdkDevice
- * @cursor: a #GdkCursor
- *
- * Sets a specific #GdkCursor for a given device when it gets inside @surface.
- * Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to create
- * the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing
- * %NULL for the @cursor argument to gdk_surface_set_cursor() means that
- * @surface will use the cursor of its parent surface. Most surfaces should
- * use this default.
- **/
+ * @surface: a `GdkSurface`
+ * @device: a pointer `GdkDevice`
+ * @cursor: a `GdkCursor`
+ *
+ * Sets a specific `GdkCursor` for a given device when it gets inside @surface.
+ *
+ * Passing %NULL for the @cursor argument means that @surface will use the
+ * cursor of its parent surface. Most surfaces should use this default.
+ *
+ * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture]
+ * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.
+ */
 void
 gdk_surface_set_device_cursor (GdkSurface *surface,
-                               GdkDevice *device,
-                               GdkCursor *cursor)
+                               GdkDevice  *device,
+                               GdkCursor  *cursor)
 {
   g_return_if_fail (GDK_IS_SURFACE (surface));
   g_return_if_fail (GDK_IS_DEVICE (device));
@@ -1947,39 +1975,41 @@ gdk_surface_set_device_cursor (GdkSurface *surface,
 
 /*
  * gdk_surface_get_geometry:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @x: (out) (allow-none): return location for X coordinate of surface (relative to its parent)
  * @y: (out) (allow-none): return location for Y coordinate of surface (relative to its parent)
  * @width: (out) (allow-none): return location for width of surface
  * @height: (out) (allow-none): return location for height of surface
  *
- * Any of the return location arguments to this function may be %NULL,
- * if you aren’t interested in getting the value of that field.
+ * Get the geometry of the surface.
  *
  * The X and Y coordinates returned are relative to the parent surface
  * of @surface, which for toplevels usually means relative to the
  * surface decorations (titlebar, etc.) rather than relative to the
  * root window (screen-size background window).
  *
- * On the X11 platform, the geometry is obtained from the X server,
- * so reflects the latest position of @surface; this may be out-of-sync
- * with the position of @surface delivered in the most-recently-processed
- * #GdkEventConfigure. gdk_surface_get_position() in contrast gets the
- * position from the most recent configure event.
+ * On the X11 platform, the geometry is obtained from the X server, so
+ * reflects the latest position of @surface; this may be out-of-sync with
+ * the position of @surface delivered in the most-recently-processed
+ * `GdkEventConfigure`. [method@Gdk.Surface.get_position] in contrast gets
+ * the position from the most recent configure event.
  *
- * Note: If @surface is not a toplevel, it is much better
- * to call gdk_surface_get_position(), gdk_surface_get_width() and
- * gdk_surface_get_height() instead, because it avoids the roundtrip to
- * the X server and because these functions support the full 32-bit
+ * Any of the return location arguments to this function may be %NULL,
+ * if you aren’t interested in getting the value of that field.
+ *
+ * Note: If @surface is not a toplevel, it is much better to call
+ * [method@Gdk.Surface.get_position], [method@Gdk.Surface.get_width] and
+ * [method@Gdk.Surface.get_height] instead, because it avoids the roundtrip
+ * to the X server and because these functions support the full 32-bit
  * coordinate space, whereas gdk_surface_get_geometry() is restricted to
  * the 16-bit coordinates of X11.
  */
 void
 gdk_surface_get_geometry (GdkSurface *surface,
-                          int       *x,
-                          int       *y,
-                          int       *width,
-                          int       *height)
+                          int        *x,
+                          int        *y,
+                          int        *width,
+                          int        *height)
 {
   g_return_if_fail (GDK_IS_SURFACE (surface));
 
@@ -1991,12 +2021,12 @@ gdk_surface_get_geometry (GdkSurface *surface,
 
 /**
  * gdk_surface_get_width:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
  * Returns the width of the given @surface.
  *
  * Surface size is reported in ”application pixels”, not
- * ”device pixels” (see gdk_surface_get_scale_factor()).
+ * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
  *
  * Returns: The width of @surface
  */
@@ -2010,12 +2040,12 @@ gdk_surface_get_width (GdkSurface *surface)
 
 /**
  * gdk_surface_get_height:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
  * Returns the height of the given @surface.
  *
  * Surface size is reported in ”application pixels”, not
- * ”device pixels” (see gdk_surface_get_scale_factor()).
+ * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
  *
  * Returns: The height of @surface
  */
@@ -2029,11 +2059,12 @@ gdk_surface_get_height (GdkSurface *surface)
 
 /*
  * gdk_surface_get_origin:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @x: (out): return location for X coordinate
  * @y: (out): return location for Y coordinate
  *
  * Obtains the position of a surface in root window coordinates.
+ *
  * (Compare with gdk_surface_get_position() and
  * gdk_surface_get_geometry() which return the position
  * of a surface relative to its parent surface.)
@@ -2050,7 +2081,7 @@ gdk_surface_get_origin (GdkSurface *surface,
 
 /*
  * gdk_surface_get_root_coords:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @x: X coordinate in surface
  * @y: Y coordinate in surface
  * @root_x: (out): return location for X coordinate
@@ -2082,21 +2113,22 @@ gdk_surface_get_root_coords (GdkSurface *surface,
 
 /**
  * gdk_surface_set_input_region:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  * @region: region of surface to be reactive
  *
  * Apply the region to the surface for the purpose of event
- * handling. Mouse events which happen while the pointer position
- * corresponds to an unset bit in the mask will be passed on the
- * surface below @surface.
+ * handling.
  *
- * An input region is typically used with RGBA surfaces.
- * The alpha channel of the surface defines which pixels are
- * invisible and allows for nicely antialiased borders,
- * and the input region controls where the surface is
- * “clickable”.
+ * Mouse events which happen while the pointer position corresponds
+ * to an unset bit in the mask will be passed on the surface below
+ * @surface.
  *
- * Use gdk_display_supports_input_shapes() to find out if
+ * An input region is typically used with RGBA surfaces. The alpha
+ * channel of the surface defines which pixels are invisible and
+ * allows for nicely antialiased borders, and the input region
+ * controls where the surface is “clickable”.
+ *
+ * Use [method@Gdk.Display.supports_input_shapes] to find out if
  * a particular backend supports input regions.
  */
 void
@@ -2162,12 +2194,13 @@ update_cursor (GdkDisplay *display,
 
 /**
  * gdk_surface_beep:
- * @surface: a toplevel #GdkSurface
+ * @surface: a toplevel `GdkSurface`
+ *
+ * Emits a short beep associated to @surface.
  *
- * Emits a short beep associated to @surface in the appropriate
- * display, if supported. Otherwise, emits a short beep on
- * the display just as gdk_display_beep().
- **/
+ * If the display of @surface does not support per-surface beeps,
+ * emits a short beep on the display just as [method Gdk Display beep].
+ */
 void
 gdk_surface_beep (GdkSurface *surface)
 {
@@ -2310,24 +2343,26 @@ _gdk_windowing_got_event (GdkDisplay *display,
  * @width: width of the new surface
  * @height: height of the new surface
  *
- * Create a new surface that is as compatible as possible with the
- * given @surface. For example the new surface will have the same
- * fallback resolution and font options as @surface. Generally, the new
- * surface will also use the same backend as @surface, unless that is
- * not possible for some reason. The type of the returned surface may
- * be examined with cairo_surface_get_type().
+ * Create a new Cairo surface that is as compatible as possible with the
+ * given @surface.
+ *
+ * For example the new surface will have the same fallback resolution
+ * and font options as @surface. Generally, the new surface will also
+ * use the same backend as @surface, unless that is not possible for
+ * some reason. The type of the returned surface may be examined with
+ * cairo_surface_get_type().
  *
  * Initially the surface contents are all 0 (transparent if contents
  * have transparency, black otherwise.)
  *
- * Returns: a pointer to the newly allocated surface. The caller
- * owns the surface and should call cairo_surface_destroy() when done
- * with it.
- *
  * This function always returns a valid pointer, but it will return a
  * pointer to a “nil” surface if @other is already in an error state
  * or any other error occurs.
- **/
+ *
+ * Returns: a pointer to the newly allocated surface. The caller
+ *   owns the surface and should call cairo_surface_destroy() when done
+ *   with it.
+ */
 cairo_surface_t *
 gdk_surface_create_similar_surface (GdkSurface *     surface,
                                     cairo_content_t content,
@@ -2370,18 +2405,19 @@ gdk_surface_destroy_notify (GdkSurface *surface)
  *
  * This function is called by the drag source. After this call, you
  * probably want to set up the drag icon using the surface returned
- * by gdk_drag_get_drag_surface().
+ * by [method Gdk Drag.get_drag_surface].
  *
- * This function returns a reference to the GdkDrag object, but GTK
- * keeps its own reference as well, as long as the DND operation is
- * going on.
+ * This function returns a reference to the [class Gdk Drag] object,
+ * but GTK keeps its own reference as well, as long as the DND operation
+ * is going on.
  *
  * Note: if @actions include %GDK_ACTION_MOVE, you need to listen for
- * the #GdkDrag::dnd-finished signal and delete the data at the source
- * if gdk_drag_get_selected_action() returns %GDK_ACTION_MOVE.
+ * the [signal Gdk Drag::dnd-finished] signal and delete the data at
+ * the source if [method Gdk Drag.get_selected_action] returns
+ * %GDK_ACTION_MOVE.
  *
- * Returns: (transfer full) (nullable): a newly created #GdkDrag or
- *     %NULL on error.
+ * Returns: (transfer full) (nullable): a newly created [class Gdk Drag]
+ *   or %NULL on error
  */
 GdkDrag *
 gdk_drag_begin (GdkSurface          *surface,
@@ -2529,13 +2565,14 @@ gdk_surface_set_frame_clock (GdkSurface     *surface,
  * gdk_surface_get_frame_clock:
  * @surface: surface to get frame clock for
  *
- * Gets the frame clock for the surface. The frame clock for a surface
- * never changes unless the surface is reparented to a new toplevel
- * surface.
+ * Gets the frame clock for the surface.
+ *
+ * The frame clock for a surface never changes unless the surface is
+ * reparented to a new toplevel surface.
  *
  * Returns: (transfer none): the frame clock
  */
-GdkFrameClock*
+GdkFrameClock *
 gdk_surface_get_frame_clock (GdkSurface *surface)
 {
   g_return_val_if_fail (GDK_IS_SURFACE (surface), NULL);
@@ -2548,14 +2585,14 @@ gdk_surface_get_frame_clock (GdkSurface *surface)
  * @surface: surface to get scale factor for
  *
  * Returns the internal scale factor that maps from surface coordinates
- * to the actual device pixels. On traditional systems this is 1, but
- * on very high density outputs this can be a higher value (often 2).
+ * to the actual device pixels.
  *
- * A higher value means that drawing is automatically scaled up to
- * a higher resolution, so any code doing drawing will automatically look
- * nicer. However, if you are supplying pixel-based data the scale
- * value can be used to determine whether to use a pixel resource
- * with higher resolution data.
+ * On traditional systems this is 1, but on very high density outputs
+ * this can be a higher value (often 2). A higher value means that drawing
+ * is automatically scaled up to a higher resolution, so any code doing
+ * drawing will automatically look nicer. However, if you are supplying
+ * pixel-based data the scale value can be used to determine whether to
+ * use a pixel resource with higher resolution data.
  *
  * The scale of a surface may change during runtime.
  *
@@ -2611,9 +2648,11 @@ gdk_surface_get_unscaled_size (GdkSurface *surface,
 
 /**
  * gdk_surface_set_opaque_region:
- * @surface: a top-level or non-native #GdkSurface
+ * @surface: a top-level `GdkSurface`
  * @region: (allow-none):  a region, or %NULL
  *
+ * Marks a region of the `GdkSurface` as opaque.
+ *
  * For optimisation purposes, compositing window managers may
  * like to not draw obscured regions of surfaces, or turn off blending
  * during for these regions. With RGB windows with no transparency,
@@ -2623,10 +2662,10 @@ gdk_surface_get_unscaled_size (GdkSurface *surface,
  *
  * This function only works for toplevel surfaces.
  *
- * GTK will update this property automatically if
- * the @surface background is opaque, as we know where the opaque regions
- * are. If your surface background is not opaque, please update this
- * property in your #GtkWidgetClass.css_changed() handler.
+ * GTK will update this property automatically if the @surface background
+ * is opaque, as we know where the opaque regions are. If your surface
+ * background is not opaque, please update this property in your
+ * #GtkWidgetClass.css_changed() handler.
  */
 void
 gdk_surface_set_opaque_region (GdkSurface      *surface,
@@ -2943,12 +2982,14 @@ gdk_surface_handle_event (GdkEvent *event)
 
 /*
  * gdk_surface_request_motion:
- * @surface: a #GdkSurface
+ * @surface: a `GdkSurface`
  *
  * Request that the next frame cycle should deliver a motion
- * event for @surface if the pointer is over it, regardless
- * whether the pointer has moved or not. This is used by GTK
- * after moving widgets around.
+ * event for @surface.
+ *
+ * The motion event will be delivered if the pointer is over the
+ * surface, regardless whether the pointer has moved or not. This
+ * is used by GTK after moving widgets around.
  */
 void
 gdk_surface_request_motion (GdkSurface *surface)
@@ -2963,16 +3004,12 @@ gdk_surface_request_motion (GdkSurface *surface)
  * @x: (inout): coordinates to translate
  * @y: (inout): coordinates to translate
  *
- * Translates the given coordinates from being
- * relative to the @from surface to being relative
- * to the @to surface.
+ * Translates coordinates between two surfaces.
  *
- * Note that this only works if @to and @from are
- * popups or transient-for to the same toplevel
- * (directly or indirectly).
+ * Note that this only works if @to and @from are popups or
+ * transient-for to the same toplevel (directly or indirectly).
  *
- * Returns: %TRUE if the coordinates were successfully
- *     translated
+ * Returns: %TRUE if the coordinates were successfully translated
  */
 gboolean
 gdk_surface_translate_coordinates (GdkSurface *from,
diff --git a/gdk/gdktexture.c b/gdk/gdktexture.c
index 621274c84f..6e3bc73380 100644
--- a/gdk/gdktexture.c
+++ b/gdk/gdktexture.c
@@ -17,21 +17,21 @@
  */
 
 /**
- * SECTION:gdktexture
- * @Title: GdkTexture
- * @Short_description: Pixel data
+ * GdkTexture:
+ *
+ * `GdkTexture` is the basic element used to refer to pixel data.
  *
- * #GdkTexture is the basic element used to refer to pixel data.
- * It is primarily mean for pixel data that will not change over
+ * It is primarily meant for pixel data that will not change over
  * multiple frames, and will be used for a long time.
  *
- * There are various ways to create #GdkTexture objects from a
- * #GdkPixbuf, or a Cairo surface, or other pixel data.
+ * There are various ways to create `GdkTexture` objects from a
+ * `GdkPixbuf`, or a Cairo surface, or other pixel data.
  *
- * The ownership of the pixel data is transferred to the #GdkTexture
- * instance; you can only make a copy of it, via gdk_texture_download().
+ * The ownership of the pixel data is transferred to the `GdkTexture`
+ * instance; you can only make a copy of it, via
+ * [method@Gdk.Texture.download].
  *
- * #GdkTexture is an immutable object: That means you cannot change
+ * `GdkTexture` is an immutable object: That means you cannot change
  * anything about it other than increasing the reference count via
  * g_object_ref().
  */
@@ -53,12 +53,6 @@ gtk_snapshot_append_texture (GdkSnapshot            *snapshot,
                              GdkTexture             *texture,
                              const graphene_rect_t  *bounds);
 
-/**
- * GdkTexture:
- *
- * The `GdkTexture` structure contains only private data.
- */
-
 enum {
   PROP_0,
   PROP_WIDTH,
@@ -246,9 +240,10 @@ gdk_texture_init (GdkTexture *self)
  * @surface: a cairo image surface
  *
  * Creates a new texture object representing the surface.
+ *
  * @surface must be an image surface with format CAIRO_FORMAT_ARGB32.
  *
- * Returns: a new #GdkTexture
+ * Returns: a new `GdkTexture`
  */
 GdkTexture *
 gdk_texture_new_for_surface (cairo_surface_t *surface)
@@ -279,11 +274,11 @@ gdk_texture_new_for_surface (cairo_surface_t *surface)
 
 /**
  * gdk_texture_new_for_pixbuf:
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  *
- * Creates a new texture object representing the #GdkPixbuf.
+ * Creates a new texture object representing the `GdkPixbuf`.
  *
- * Returns: a new #GdkTexture
+ * Returns: a new `GdkTexture`
  */
 GdkTexture *
 gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
@@ -316,16 +311,16 @@ gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
  * @resource_path: the path of the resource file
  *
  * Creates a new texture by loading an image from a resource.
- * The file format is detected automatically.
- * The supported formats are PNG and JPEG, though more formats might be
- * available.
+ *
+ * The file format is detected automatically. The supported formats
+ * are PNG and JPEG, though more formats might be available.
  *
  * It is a fatal error if @resource_path does not specify a valid
  * image resource and the program will abort if that happens.
  * If you are unsure about the validity of a resource, use
- * gdk_texture_new_from_file() to load it.
+ * [ctor@Gdk.Texture.new_from_file] to load it.
  *
- * Return value: A newly-created texture
+ * Return value: A newly-created `GdkTexture`
  */
 GdkTexture *
 gdk_texture_new_from_resource (const char *resource_path)
@@ -348,18 +343,18 @@ gdk_texture_new_from_resource (const char *resource_path)
 
 /**
  * gdk_texture_new_from_file:
- * @file: #GFile to load
+ * @file: `GFile` to load
  * @error: Return location for an error
  *
  * Creates a new texture by loading an image from a file.
- * The file format is detected automatically.
- * The supported formats are PNG and JPEG, though more formats might be
- * available.
+ *
+ * The file format is detected automatically. The supported formats
+ * are PNG and JPEG, though more formats might be available.
  *
  * If %NULL is returned, then @error will be set.
  *
- * Return value: A newly-created #GdkTexture or %NULL if an error occurred.
- **/
+ * Return value: A newly-created `GdkTexture` or %NULL if an error occurred.
+ */
 GdkTexture *
 gdk_texture_new_from_file (GFile   *file,
                            GError **error)
@@ -388,11 +383,11 @@ gdk_texture_new_from_file (GFile   *file,
 
 /**
  * gdk_texture_get_width:
- * @texture: a #GdkTexture
+ * @texture: a `GdkTexture`
  *
  * Returns the width of @texture, in pixels.
  *
- * Returns: the width of the #GdkTexture
+ * Returns: the width of the `GdkTexture`
  */
 int
 gdk_texture_get_width (GdkTexture *texture)
@@ -404,11 +399,11 @@ gdk_texture_get_width (GdkTexture *texture)
 
 /**
  * gdk_texture_get_height:
- * @texture: a #GdkTexture
+ * @texture: a `GdkTexture`
  *
  * Returns the height of the @texture, in pixels.
  *
- * Returns: the height of the #GdkTexture
+ * Returns: the height of the `GdkTexture`
  */
 int
 gdk_texture_get_height (GdkTexture *texture)
@@ -456,21 +451,22 @@ gdk_texture_download_area (GdkTexture         *texture,
 
 /**
  * gdk_texture_download:
- * @texture: a #GdkTexture
+ * @texture: a `GdkTexture`
  * @data: (array): pointer to enough memory to be filled with the
  *     downloaded data of @texture
  * @stride: rowstride in bytes
  *
- * Downloads the @texture into local memory. This may be
- * an expensive operation, as the actual texture data may
- * reside on a GPU or on a remote display server.
+ * Downloads the @texture into local memory.
+ *
+ * This may be an expensive operation, as the actual texture data
+ * may reside on a GPU or on a remote display server.
  *
  * The data format of the downloaded data is equivalent to
  * %CAIRO_FORMAT_ARGB32, so every downloaded pixel requires
  * 4 bytes of memory.
  *
  * Downloading a texture into a Cairo image surface:
- * |[<!-- language="C" -->
+ * ```c
  * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
  *                                       gdk_texture_get_width (texture),
  *                                       gdk_texture_get_height (texture));
@@ -478,7 +474,7 @@ gdk_texture_download_area (GdkTexture         *texture,
  *                       cairo_image_surface_get_data (surface),
  *                       cairo_image_surface_get_stride (surface));
  * cairo_surface_mark_dirty (surface);
- * ]|
+ * ```
  */
 void
 gdk_texture_download (GdkTexture *texture,
@@ -536,18 +532,18 @@ gdk_texture_get_render_data (GdkTexture  *self,
 
 /**
  * gdk_texture_save_to_png:
- * @texture: a #GdkTexture
+ * @texture: a `GdkTexture`
  * @filename: the filename to store to
  *
  * Store the given @texture to the @filename as a PNG file.
  *
  * This is a utility function intended for debugging and testing.
  * If you want more control over formats, proper error handling or
- * want to store to a #GFile or other location, you might want to
+ * want to store to a `GFile` or other location, you might want to
  * look into using the gdk-pixbuf library.
  *
  * Returns: %TRUE if saving succeeded, %FALSE on failure.
- **/
+ */
 gboolean
 gdk_texture_save_to_png (GdkTexture *texture,
                          const char *filename)
diff --git a/gdk/gdktoplevel.c b/gdk/gdktoplevel.c
index 13eb38cda1..80b1a4285d 100644
--- a/gdk/gdktoplevel.c
+++ b/gdk/gdktoplevel.c
@@ -27,17 +27,13 @@
 #include <math.h>
 
 /**
- * SECTION:gdktoplevel
- * @Short_description: Interface for toplevel surfaces
- * @Title: Toplevels
- * @See_also: #GdkSurface, #GdkPopup
+ * GdkToplevel:
  *
- * A #GdkToplevel is a freestanding toplevel surface.
+ * A `GdkToplevel` is a freestanding toplevel surface.
  *
- * The #GdkToplevel interface provides useful APIs for
- * interacting with the windowing system, such as controlling
- * maximization and size of the surface, setting icons and
- * transient parents for dialogs.
+ * The `GdkToplevel` interface provides useful APIs for interacting with
+ * the windowing system, such as controlling maximization and size of the
+ * surface, setting icons and transient parents for dialogs.
  */
 
 G_DEFINE_INTERFACE (GdkToplevel, gdk_toplevel, GDK_TYPE_SURFACE)
@@ -119,53 +115,109 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface)
   iface->inhibit_system_shortcuts = gdk_toplevel_default_inhibit_system_shortcuts;
   iface->restore_system_shortcuts = gdk_toplevel_default_restore_system_shortcuts;
 
+  /**
+   * GdkToplevel:state:
+   *
+   * The state of the toplevel.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_flags ("state",
                           P_("State"),
                           P_("State"),
                           GDK_TYPE_TOPLEVEL_STATE, 0,
                           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkToplevel:title:
+   *
+   * The title of the surface.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_string ("title",
                            "Title",
                            "The title of the surface",
                            NULL,
                            G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:startup-id:
+   *
+   * The startup ID of the surface.
+   *
+   * See [class@Gdk.AppLaunchContext] for more information about
+   * startup feedback.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_string ("startup-id",
                            "Startup ID",
                            "The startup ID of the surface",
                            NULL,
                            G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:transient-for:
+   *
+   * The transient parent of the surface.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_object ("transient-for",
                            "Transient For",
                            "The transient parent of the surface",
                            GDK_TYPE_SURFACE,
                            G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:modal:
+   *
+   * Whether the surface is modal.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boolean ("modal",
                             "Modal",
                             "Whether the surface is modal",
                             FALSE,
                             G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:icon-list:
+   *
+   * A list of textures to use as icon.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_pointer ("icon-list",
                             "Icon List",
                             "The list of icon textures",
                             G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:decorated:
+   *
+   * Whether the window manager should add decorations.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boolean ("decorated",
                             "Decorated",
                             "Decorated",
                             FALSE,
                             G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:deletable:
+   *
+   * Whether the window manager should allow to close the surface.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boolean ("deletable",
                             "Deletable",
                             "Deletable",
                             FALSE,
                             G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:fullscreen-mode:
+   *
+   * The fullscreen mode of the surface.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_enum ("fullscreen-mode",
                          "Fullscreen mode",
@@ -173,6 +225,12 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface)
                          GDK_TYPE_FULLSCREEN_MODE,
                          GDK_FULLSCREEN_ON_CURRENT_MONITOR,
                          G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GdkToplevel:shortcuts-inhibited:
+   *
+   * Whether the surface should inhibit keyboard shortcuts.
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boolean ("shortcuts-inhibited",
                             "Shortcuts inhibited",
@@ -182,19 +240,21 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface)
 
   /**
    * GdkToplevel::compute-size:
-   * @toplevel: a #GdkToplevel
-   * @size: (type Gdk.ToplevelSize) (out caller-allocates): a #GdkToplevelSize
+   * @toplevel: a `GdkToplevel`
+   * @size: (type Gdk.ToplevelSize) (out caller-allocates): a `GdkToplevelSize`
    *
-   * Compute the desired size of the toplevel, given the information passed via
-   * the #GdkToplevelSize object.
+   * Emitted when the size for the surface needs to be computed, when
+   * it is present.
    *
-   * It will normally be emitted during or after gdk_toplevel_present(),
-   * depending on the configuration received by the windowing system. It may
-   * also be emitted at any other point in time, in response to the windowing
-   * system spontaneously changing the configuration.
+   * It will normally be emitted during or after [method@Gdk.Toplevel.present],
+   * depending on the configuration received by the windowing system.
+   * It may also be emitted at any other point in time, in response
+   * to the windowing system spontaneously changing the configuration.
    *
-   * It is the responsibility of the GdkToplevel user to handle this signal;
-   * failing to do so will result in an arbitrary size being used as a result.
+   * It is the responsibility of the toplevel user to handle this signal
+   * and compute the desired size of the toplevel, given the information
+   * passed via the [struct@Gdk.ToplevelSize] object. Failing to do so
+   * will result in an arbitrary size being used as a result.
    */
   signals[COMPUTE_SIZE] =
     g_signal_new ("compute-size",
@@ -227,16 +287,17 @@ gdk_toplevel_install_properties (GObjectClass *object_class,
 
 /**
  * gdk_toplevel_present:
- * @toplevel: the #GdkToplevel to show
- * @layout: the #GdkToplevelLayout object used to layout
+ * @toplevel: the `GdkToplevel` to show
+ * @layout: the `GdkToplevelLayout` object used to layout
+ *
+ * Present @toplevel after having processed the `GdkToplevelLayout` rules.
  *
- * Present @toplevel after having processed the #GdkToplevelLayout rules.
  * If the toplevel was previously not showing, it will be showed,
  * otherwise it will change layout according to @layout.
  *
- * GDK may emit the 'compute-size' signal to let the user of this toplevel
- * compute the preferred size of the toplevel surface. See
- * #GdkToplevel::compute-size for details.
+ * GDK may emit the [signal@Gdk.Toplevel::compute-size] signal to let
+ * the user of this toplevel compute the preferred size of the toplevel
+ * surface.
  *
  * Presenting is asynchronous and the specified layout parameters are not
  * guaranteed to be respected.
@@ -253,7 +314,7 @@ gdk_toplevel_present (GdkToplevel       *toplevel,
 
 /**
  * gdk_toplevel_minimize:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  *
  * Asks to minimize the @toplevel.
  *
@@ -271,7 +332,7 @@ gdk_toplevel_minimize (GdkToplevel *toplevel)
 
 /**
  * gdk_toplevel_lower:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  *
  * Asks to lower the @toplevel below other windows.
  *
@@ -289,13 +350,13 @@ gdk_toplevel_lower (GdkToplevel *toplevel)
 
 /**
  * gdk_toplevel_focus:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @timestamp: timestamp of the event triggering the surface focus
  *
  * Sets keyboard focus to @surface.
  *
- * In most cases, gtk_window_present_with_time() should be used
- * on a #GtkWindow, rather than calling this function.
+ * In most cases, [method@Gtk.Window.present_with_time] should be
+ * used on a [class@Gtk.Window], rather than calling this function.
  */
 void
 gdk_toplevel_focus (GdkToplevel *toplevel,
@@ -308,10 +369,10 @@ gdk_toplevel_focus (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_get_state:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  *
- * Gets the bitwise OR of the currently active surface state flags,
- * from the #GdkToplevelState enumeration.
+ * Gets the bitwise or of the currently active surface state flags,
+ * from the `GdkToplevelState` enumeration.
  *
  * Returns: surface state bitfield
  */
@@ -329,10 +390,12 @@ gdk_toplevel_get_state (GdkToplevel *toplevel)
 
 /**
  * gdk_toplevel_set_title:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @title: title of @surface
  *
- * Sets the title of a toplevel surface, to be displayed in the titlebar,
+ * Sets the title of a toplevel surface.
+ *
+ * The title maybe be displayed in the titlebar,
  * in lists of windows, etc.
  */
 void
@@ -346,11 +409,14 @@ gdk_toplevel_set_title (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_startup_id:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @startup_id: a string with startup-notification identifier
  *
- * When using GTK, typically you should use gtk_window_set_startup_id()
- * instead of this low-level function.
+ * Sets the startup notification ID.
+ *
+ * When using GTK, typically you should use
+ * [method@Gtk.Window.set_startup_id] instead of this
+ * low-level function.
  */
 void
 gdk_toplevel_set_startup_id (GdkToplevel *toplevel,
@@ -363,16 +429,18 @@ gdk_toplevel_set_startup_id (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_transient_for:
- * @toplevel: a #GdkToplevel
- * @parent: another toplevel #GdkSurface
+ * @toplevel: a `GdkToplevel`
+ * @parent: another toplevel `GdkSurface`
  *
- * Indicates to the window manager that @surface is a transient dialog
- * associated with the application surface @parent. This allows the
- * window manager to do things like center @surface on @parent and
- * keep @surface above @parent.
+ * Sets a transient-for parent.
  *
- * See gtk_window_set_transient_for() if you’re using #GtkWindow or
- * #GtkDialog.
+ * Indicates to the window manager that @surface is a transient
+ * dialog associated with the application surface @parent. This
+ * allows the window manager to do things like center @surface
+ * on @parent and keep @surface above @parent.
+ *
+ * See [method@Gtk.Window.set_transient_for] if you’re using
+ * [class@Gtk.Window] or [class@Gtk.Dialog].
  */
 void
 gdk_toplevel_set_transient_for (GdkToplevel *toplevel,
@@ -385,16 +453,18 @@ gdk_toplevel_set_transient_for (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_modal:
- * @toplevel: A toplevel surface
+ * @toplevel: a `GdkToplevel`
  * @modal: %TRUE if the surface is modal, %FALSE otherwise.
  *
+ * Sets the toplevel to be modal.
+ *
  * The application can use this hint to tell the
  * window manager that a certain surface has modal
  * behaviour. The window manager can use this information
  * to handle modal surfaces in a special way.
  *
  * You should only use this on surfaces for which you have
- * previously called gdk_toplevel_set_transient_for().
+ * previously called [method@Gdk.Toplevel.set_transient_for].
  */
 void
 gdk_toplevel_set_modal (GdkToplevel *toplevel,
@@ -407,9 +477,9 @@ gdk_toplevel_set_modal (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_icon_list:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @surfaces: (transfer none) (element-type GdkTexture):
- *     A list of textures to use as icon, of different sizes
+ *   A list of textures to use as icon, of different sizes
  *
  * Sets a list of icons for the surface.
  *
@@ -432,8 +502,8 @@ gdk_toplevel_set_icon_list (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_show_window_menu:
- * @toplevel: a #GdkToplevel
- * @event: a #GdkEvent to show the menu for
+ * @toplevel: a `GdkToplevel`
+ * @event: a `GdkEvent` to show the menu for
  *
  * Asks the windowing system to show the window menu.
  *
@@ -455,9 +525,11 @@ gdk_toplevel_show_window_menu (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_decorated:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @decorated: %TRUE to request decorations
  *
+ * Sets the toplevel to be decorated.
+ *
  * Setting @decorated to %FALSE hints the desktop environment
  * that the surface has its own, client-side decorations and
  * does not need to have window decorations added.
@@ -473,9 +545,11 @@ gdk_toplevel_set_decorated (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_set_deletable:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @deletable: %TRUE to request a delete button
  *
+ * Sets the toplevel to be deletable.
+ *
  * Setting @deletable to %TRUE hints the desktop environment
  * that it should offer the user a way to close the surface.
  */
@@ -490,7 +564,7 @@ gdk_toplevel_set_deletable (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_supports_edge_constraints:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  *
  * Returns whether the desktop environment supports
  * tiled window states.
@@ -508,17 +582,18 @@ gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel)
 
 /**
  * gdk_toplevel_inhibit_system_shortcuts:
- * @toplevel: the #GdkToplevel requesting system keyboard shortcuts
- * @event: (nullable): the #GdkEvent that is triggering the inhibit
- *         request, or %NULL if none is available.
+ * @toplevel: a `GdkToplevel`
+ * @event: (nullable): the `GdkEvent` that is triggering the inhibit
+ *   request, or %NULL if none is available
+ *
+ * Requests that the @toplevel inhibit the system shortcuts.
  *
- * Requests that the @toplevel inhibit the system shortcuts, asking the
- * desktop environment/windowing system to let all keyboard events reach
- * the surface, as long as it is focused, instead of triggering system
- * actions.
+ * This is asking the desktop environment/windowing system to let all
+ * keyboard events reach the surface, as long as it is focused, instead
+ * of triggering system actions.
  *
  * If granted, the rerouting remains active until the default shortcuts
- * processing is restored with gdk_toplevel_restore_system_shortcuts(),
+ * processing is restored with [method@Gdk.Toplevel.restore_system_shortcuts],
  * or the request is revoked by the desktop environment, windowing system
  * or the user.
  *
@@ -531,8 +606,7 @@ gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel)
  * or deny the request or even choose to ignore the request entirely.
  *
  * The caller can be notified whenever the request is granted or revoked
- * by listening to the GdkToplevel::shortcuts-inhibited property.
- *
+ * by listening to the [property@Gdk.Toplevel:shortcuts-inhibited] property.
  */
 void
 gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel,
@@ -546,10 +620,12 @@ gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel,
 
 /**
  * gdk_toplevel_restore_system_shortcuts:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  *
  * Restore default system keyboard shortcuts which were previously
- * requested to be inhibited by gdk_toplevel_inhibit_system_shortcuts().
+ * inhibited.
+ *
+ * This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts].
  */
 void
 gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel)
@@ -561,15 +637,17 @@ gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel)
 
 /**
  * gdk_toplevel_begin_resize:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @edge: the edge or corner from which the drag is started
  * @device: (nullable): the device used for the operation
  * @button: the button being used to drag, or 0 for a keyboard-initiated drag
  * @x: surface X coordinate of mouse click that began the drag
  * @y: surface Y coordinate of mouse click that began the drag
- * @timestamp: timestamp of mouse click that began the drag (use gdk_event_get_time())
+ * @timestamp: timestamp of mouse click that began the drag (use
+ *   [method@Gdk.Event.get_time])
+ *
+ * Begins an interactive resize operation.
  *
- * Begins an interactive resize operation (for a toplevel surface).
  * You might use this function to implement a “window resize grip.”
  */
 void
@@ -607,9 +685,11 @@ gdk_toplevel_begin_resize (GdkToplevel    *toplevel,
  * @button: the button being used to drag, or 0 for a keyboard-initiated drag
  * @x: surface X coordinate of mouse click that began the drag
  * @y: surface Y coordinate of mouse click that began the drag
- * @timestamp: timestamp of mouse click that began the drag
+ * @timestamp: timestamp of mouse click that began the drag (use
+ *   [method@Gdk.Event.get_time])
+ *
+ * Begins an interactive move operation.
  *
- * Begins an interactive move operation (for a toplevel surface).
  * You might use this function to implement draggable titlebars.
  */
 void
diff --git a/gdk/gdktoplevel.h b/gdk/gdktoplevel.h
index fb29315710..1d3f9c627d 100644
--- a/gdk/gdktoplevel.h
+++ b/gdk/gdktoplevel.h
@@ -60,9 +60,8 @@ typedef enum
  * @GDK_FULLSCREEN_ON_CURRENT_MONITOR: Fullscreen on current monitor only.
  * @GDK_FULLSCREEN_ON_ALL_MONITORS: Span across all monitors when fullscreen.
  *
- * Indicates which monitor (in a multi-head setup) a surface should span over
- * when in fullscreen mode.
- **/
+ * Indicates which monitor a surface should span over when in fullscreen mode.
+ */
 typedef enum
 {
   GDK_FULLSCREEN_ON_CURRENT_MONITOR,
@@ -90,10 +89,11 @@ typedef enum
  *
  * Specifies the state of a toplevel surface.
  *
- * On platforms that support information about individual edges, the %GDK_TOPLEVEL_STATE_TILED
- * state will be set whenever any of the individual tiled states is set. On platforms
- * that lack that support, the tiled state will give an indication of tiledness without
- * any of the per-edge states being set.
+ * On platforms that support information about individual edges, the
+ * %GDK_TOPLEVEL_STATE_TILED state will be set whenever any of the individual
+ * tiled states is set. On platforms that lack that support, the tiled state
+ * will give an indication of tiledness without any of the per-edge states
+ * being set.
  */
 typedef enum
 {
@@ -118,11 +118,6 @@ typedef enum
 
 #define GDK_TYPE_TOPLEVEL (gdk_toplevel_get_type ())
 
-/**
- * GdkToplevel:
- *
- * An interface for top level surfaces.
- */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkToplevel, gdk_toplevel, GDK, TOPLEVEL, GObject)
 
diff --git a/gdk/gdktoplevellayout.c b/gdk/gdktoplevellayout.c
index 0de2720b00..a950710dd4 100644
--- a/gdk/gdktoplevellayout.c
+++ b/gdk/gdktoplevellayout.c
@@ -23,16 +23,16 @@
 #include "gdkmonitor.h"
 
 /**
- * SECTION:gdktoplevellayout
- * @Title: GdkToplevelLayout
- * @Short_description: Information for presenting toplevels
+ * GdkToplevelLayout:
+ *
+ * The `GdkToplevelLayout` struct contains information that
+ * is necessary to present a sovereign window on screen.
+ *
+ * The `GdkToplevelLayout` gdk_toplevel_present().
  *
  * Toplevel surfaces are sovereign windows that can be presented
  * to the user in various states (maximized, on all workspaces,
  * etc).
- *
- * The GdkToplevelLayout struct contains information that
- * is necessary to do so, and is passed to gdk_toplevel_present().
  */
 struct _GdkToplevelLayout
 {
diff --git a/gdk/gdktoplevelsize.c b/gdk/gdktoplevelsize.c
index 66a4ddeadb..895b54033f 100644
--- a/gdk/gdktoplevelsize.c
+++ b/gdk/gdktoplevelsize.c
@@ -21,13 +21,10 @@
 #include "gdktoplevelsizeprivate.h"
 
 /**
- * SECTION:gdktoplevelsize
- * @Title: GdkToplevelSize
- * @Short_description: Information for computing toplevel size
+ * GdkToplevelSize:
  *
- * The GdkToplevelSIze struct contains information that may be useful
- * for users of GdkToplevel to compute a surface size. It also carries
- * information back with the computational result.
+ * The `GdkToplevelSize` struct contains information that is useful
+ * to compute the size of a toplevel size.
  */
 
 G_DEFINE_POINTER_TYPE (GdkToplevelSize, gdk_toplevel_size)
@@ -51,7 +48,7 @@ gdk_toplevel_size_init (GdkToplevelSize *size,
 
 /**
  * gdk_toplevel_size_get_bounds:
- * @size: a #GdkToplevelSize
+ * @size: a `GdkToplevelSize`
  * @bounds_width: (out): return location for width
  * @bounds_height: (out): return location for height
  *
@@ -77,14 +74,16 @@ gdk_toplevel_size_get_bounds (GdkToplevelSize *size,
 
 /**
  * gdk_toplevel_size_set_size:
- * @size: a #GdkToplevelSize
+ * @size: a `GdkToplevelSize`
  * @width: the width
  * @height: the height
  *
- * Sets the size the toplevel prefers to be resized to. The size should be
- * within the bounds (see gdk_toplevel_size_get_bounds()). The set size should
- * be considered as a hint, and should not be assumed to be respected by the
- * windowing system, or backend.
+ * Sets the size the toplevel prefers to be resized to.
+ *
+ * The size should be within the bounds (see
+ * [method@Gdk.ToplevelSize.get_bounds]). The set size should
+ * be considered as a hint, and should not be assumed to be
+ * respected by the windowing system, or backend.
  */
 void
 gdk_toplevel_size_set_size (GdkToplevelSize *size,
@@ -97,17 +96,19 @@ gdk_toplevel_size_set_size (GdkToplevelSize *size,
 
 /**
  * gdk_toplevel_size_set_min_size:
- * @size: a #GdkToplevelSize
+ * @size: a `GdkToplevelSize`
  * @min_width: the minimum width
  * @min_height: the minimum height
  *
+ * Sets the minimum size of the toplevel.
+ *
  * The minimum size corresponds to the limitations the toplevel can be shrunk
- * to, without resulting in incorrect painting. A user of a #GdkToplevel should
+ * to, without resulting in incorrect painting. A user of a `GdkToplevel` should
  * calculate these given both the existing size, and the bounds retrieved from
- * the #GdkToplevelSize object.
+ * the `GdkToplevelSize` object.
  *
  * The minimum size should be within the bounds (see
- * gdk_toplevel_size_get_bounds()).
+ * [method@Gdk.ToplevelSize.get_bounds]).
  */
 void
 gdk_toplevel_size_set_min_size (GdkToplevelSize *size,
@@ -120,12 +121,14 @@ gdk_toplevel_size_set_min_size (GdkToplevelSize *size,
 
 /**
  * gdk_toplevel_size_set_shadow_width:
- * @size: a #GdkToplevelSize
+ * @size: a `GdkToplevelSize`
  * @left: width of the left part of the shadow
  * @right: width of the right part of the shadow
  * @top: height of the top part of the shadow
  * @bottom: height of the bottom part of the shadow
  *
+ * Sets the shadows size of the toplevel.
+ *
  * The shadow width corresponds to the part of the computed surface size
  * that would consist of the shadow margin surrounding the window, would
  * there be any.
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index e35a9d9c6f..1c72061a61 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -53,16 +53,6 @@ G_BEGIN_DECLS
  */
 #define GDK_CURRENT_TIME     0L
 
-/**
- * GdkRectangle:
- * @x: the x coordinate of the top left corner
- * @y: the y coordinate of the top left corner
- * @width: the width of the rectangle
- * @height: the height of the rectangle
- *
- * Defines the position and size of a rectangle. It is identical to
- * #cairo_rectangle_int_t.
- */
 #ifdef __GI_SCANNER__
 /* The introspection scanner is currently unable to lookup how
  * cairo_rectangle_int_t is actually defined. This prevents
@@ -243,9 +233,7 @@ typedef enum {
  * @GDK_AXIS_SLIDER: the axis is used for pen slider information
  * @GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
  *
- * An enumeration describing the way in which a device
- * axis (valuator) maps onto the predefined valuator
- * types that GTK understands.
+ * Defines how device axes are interpreted by GTK.
  *
  * Note that the X and Y axes are not really needed; pointer devices
  * report their location via the x/y members of events regardless. Whether
@@ -303,13 +291,13 @@ typedef enum
  * GdkDragAction:
  * @GDK_ACTION_COPY: Copy the data.
  * @GDK_ACTION_MOVE: Move the data, i.e. first copy it, then delete
- *  it from the source using the DELETE target of the X selection protocol.
+ *   it from the source using the DELETE target of the X selection protocol.
  * @GDK_ACTION_LINK: Add a link to the data. Note that this is only
- *  useful if source and destination agree on what it means, and is not
- *  supported on all platforms.
+ *   useful if source and destination agree on what it means, and is not
+ *   supported on all platforms.
  * @GDK_ACTION_ASK: Ask the user what to do with the data.
  *
- * Used in #GdkDrop and #GdkDrag to indicate the actions that the
+ * Used in `GdkDrop` and `GdkDrag` to indicate the actions that the
  * destination can and should do with the dropped data.
  */
 typedef enum
@@ -323,9 +311,10 @@ typedef enum
 /**
  * GDK_ACTION_ALL:
  *
- * Defines all possible DND actions. This can be used in gdk_drop_status()
- * messages when any drop can be accepted or a more specific drop method
- * is not yet known.
+ * Defines all possible DND actions.
+ *
+ * This can be used in [method Gdk Drop.status] messages when any drop
+ * can be accepted or a more specific drop method is not yet known.
  */
 #define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK)
 
@@ -385,7 +374,7 @@ typedef struct _GdkKeymapKey GdkKeymapKey;
  *   letter at level 0, and an uppercase letter at level 1, though only the
  *   uppercase letter is printed.
  *
- * A #GdkKeymapKey is a hardware key that can be mapped to a keyval.
+ * A `GdkKeymapKey` is a hardware key that can be mapped to a keyval.
  */
 struct _GdkKeymapKey
 {
diff --git a/gdk/gdkvulkancontext.c b/gdk/gdkvulkancontext.c
index 13ba8dae8b..5fe6ad6512 100644
--- a/gdk/gdkvulkancontext.c
+++ b/gdk/gdkvulkancontext.c
@@ -29,28 +29,19 @@
 #include "gdkintl.h"
 
 /**
- * SECTION:gdkvulkancontext
- * @Title: GdkVulkanContext
- * @Short_description: Vulkan draw context
+ * GdkVulkanContext:
  *
- * #GdkVulkanContext is an object representing the platform-specific
+ * `GdkVulkanContext` is an object representing the platform-specific
  * Vulkan draw context.
  *
- * #GdkVulkanContexts are created for a #GdkSurface using
- * gdk_surface_create_vulkan_context(), and the context will match the
- * the characteristics of the surface.
+ * `GdkVulkanContext`s are created for a surface using
+ * [method@Gdk.Surface.create_vulkan_context], and the context will match
+ * the the characteristics of the surface.
  *
- * Support for #GdkVulkanContext is platform-specific, context creation
+ * Support for `GdkVulkanContext` is platform-specific and context creation
  * can fail, returning %NULL context.
  */
 
-/**
- * GdkVulkanContext:
- *
- * The GdkVulkanContext struct contains only private fields and should not
- * be accessed directly.
- */
-
 typedef struct _GdkVulkanContextPrivate GdkVulkanContextPrivate;
 
 struct _GdkVulkanContextPrivate {
@@ -540,8 +531,9 @@ gdk_vulkan_context_class_init (GdkVulkanContextClass *klass)
    * GdkVulkanContext::images-updated:
    * @context: the object on which the signal is emitted
    *
-   * This signal is emitted when the images managed by this context have
-   * changed. Usually this means that the swapchain had to be recreated,
+   * Emitted when the images managed by this context have changed.
+   *
+   * Usually this means that the swapchain had to be recreated,
    * for example in response to a change of the surface size.
    */
   signals[IMAGES_UPDATED] =
@@ -650,7 +642,7 @@ gdk_vulkan_context_initable_init (GInitableIface *iface)
 
 /**
  * gdk_vulkan_context_get_instance:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the Vulkan instance that is associated with @context.
  *
@@ -666,7 +658,7 @@ gdk_vulkan_context_get_instance (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_physical_device:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the Vulkan physical device that this context is using.
  *
@@ -698,7 +690,7 @@ gdk_vulkan_context_get_device (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_queue:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the Vulkan queue that this context is using.
  *
@@ -714,9 +706,10 @@ gdk_vulkan_context_get_queue (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_queue_family_index:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the family index for the queue that this context is using.
+ *
  * See vkGetPhysicalDeviceQueueFamilyProperties().
  *
  * Returns: the index
@@ -731,7 +724,7 @@ gdk_vulkan_context_get_queue_family_index (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_image_format:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the image format that this context is using.
  *
@@ -749,7 +742,7 @@ gdk_vulkan_context_get_image_format (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_n_images:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the number of images that this context is using in its swap chain.
  *
@@ -767,7 +760,7 @@ gdk_vulkan_context_get_n_images (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_image:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  * @id: the index of the image to return
  *
  * Gets the image with index @id that this context is using.
@@ -788,12 +781,12 @@ gdk_vulkan_context_get_image (GdkVulkanContext *context,
 
 /**
  * gdk_vulkan_context_get_draw_index:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the index of the image that is currently being drawn.
  *
- * This function can only be used between gdk_draw_context_begin_frame() and
- * gdk_draw_context_end_frame() calls.
+ * This function can only be used between [method@Gdk.DrawContext.begin_frame]
+ * and [method@Gdk.DrawContext.end_frame] calls.
  *
  * Returns: the index of the images that is being drawn
  */
@@ -810,13 +803,13 @@ gdk_vulkan_context_get_draw_index (GdkVulkanContext *context)
 
 /**
  * gdk_vulkan_context_get_draw_semaphore:
- * @context: a #GdkVulkanContext
+ * @context: a `GdkVulkanContext`
  *
  * Gets the Vulkan semaphore that protects access to the image that is
  * currently being drawn.
  *
- * This function can only be used between gdk_draw_context_begin_frame() and
- * gdk_draw_context_end_frame() calls.
+ * This function can only be used between [method@Gdk.DrawContext.begin_frame]
+ * and [method@Gdk.DrawContext.end_frame] calls.
  *
  * Returns: (transfer none): the VkSemaphore
  */


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]