Documentation fixes

Mostly fixing up indentation of continuation lines,
and other small cleanups.

36 files changed, 184 insertions, 201 deletions

diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c
index c3a4759c79..0be31e9ab0 100644
--- a/gdk/gdkclipboard.c
+++ b/gdk/gdkclipboard.c
@@ -504,8 +504,8 @@ gdk_clipboard_is_local (GdkClipboard *clipboard)
  * 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.
+ * Returns: (transfer none) (nullable): The content of a clipboard
+ *   if the clipboard does not maintain any content
  */
 GdkContentProvider *
 gdk_clipboard_get_content (GdkClipboard *clipboard)
@@ -677,14 +677,14 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,
  * @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.
+ *   the chosen mime type
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an asynchronous clipboard read.
  *
  * 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,
@@ -1194,8 +1194,8 @@ gdk_clipboard_claim_remote (GdkClipboard      *clipboard,
 /**
  * gdk_clipboard_set_content:
  * @clipboard: a `GdkClipboard`
- * @provider: (transfer none) (allow-none): the new contents of @clipboard or
- *     %NULL to clear the clipboard
+ * @provider: (transfer none) (allow-none): the new contents of @clipboard
+ *   or %NULL to clear the clipboard
  *
  * Sets a new content provider on @clipboard.
  *
diff --git a/gdk/gdkcontentformats.c b/gdk/gdkcontentformats.c
index 9bfaca1f8b..350b8ff2f5 100644
--- a/gdk/gdkcontentformats.c
+++ b/gdk/gdkcontentformats.c
@@ -85,7 +85,7 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
  * See RFC 2048 for the syntax if mime types.
  *
  * Returns: An interned string for the canonicalized mime type
- *     or %NULL if the string wasn't a valid mime type
+ *   or %NULL if the string wasn't a valid mime type
  */
 const char *
 gdk_intern_mime_type (const char *string)
@@ -454,16 +454,15 @@ gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
  * gdk_content_formats_get_gtypes:
  * @formats: a `GdkContentFormats`
  * @n_gtypes: (out) (optional): optional pointer to take the
- *     number of #GTypes contained in the return value
+ *   number of `GType`s contained in the return value
  *
- * Gets the `GTypes` included in @formats.
+ * Gets the `GType`s 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 zero-terminated=1):
- *      %G_TYPE_INVALID-terminated array of types included in @formats or
- *      %NULL if none.
+ *   %G_TYPE_INVALID-terminated array of types included in @formats
  */
 const GType *
 gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
@@ -481,16 +480,16 @@ gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
  * gdk_content_formats_get_mime_types:
  * @formats: a `GdkContentFormats`
  * @n_mime_types: (out) (optional): optional pointer to take the
- *     number of mime types contained in the return value
+ *   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.
  *
- * Returns: (transfer none) (nullable) (array length=n_mime_types zero-terminated=1): %NULL-terminated array of
- *     interned strings of mime types included in @formats or %NULL
- *     if none.
+ * Returns: (transfer none) (nullable) (array length=n_mime_types zero-terminated=1):
+ *   %NULL-terminated array of interned strings of mime types included
+ *   in @formats
  */
 const char * const *
 gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
diff --git a/gdk/gdkcontentprovider.c b/gdk/gdkcontentprovider.c
index 15e183a178..73e0951b2e 100644
--- a/gdk/gdkcontentprovider.c
+++ b/gdk/gdkcontentprovider.c
@@ -326,7 +326,7 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,
  * 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.
+ *   @error will be set to describe the failure.
  */
 gboolean
 gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
@@ -354,7 +354,7 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
  * #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.
+ *   @error will be set to describe the failure.
  */
 gboolean
 gdk_content_provider_get_value (GdkContentProvider  *provider,
diff --git a/gdk/gdkcontentproviderimpl.c b/gdk/gdkcontentproviderimpl.c
index 9c337c7b77..25c5404a17 100644
--- a/gdk/gdkcontentproviderimpl.c
+++ b/gdk/gdkcontentproviderimpl.c
@@ -394,7 +394,7 @@ gdk_content_provider_union_init (GdkContentProviderUnion *self)
 /**
  * gdk_content_provider_new_union:
  * @providers: (nullable) (array length=n_providers) (transfer full):
- *     The #GdkContentProviders to present the union of
+ *   The #GdkContentProviders to present the union of
  * @n_providers: the number of providers
  *
  * Creates a content provider that represents all the given @providers.
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index 57beb73a63..ed3afc019e 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -299,7 +299,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
- *     this one cannot be supported
+ *   this one cannot be supported
  *
  * Creates a new cursor by looking up @name in the current cursor
  * theme.
@@ -341,7 +341,7 @@ gdk_cursor_new_from_name (const char *name,
  * @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
- *     this one cannot be supported
+ *   this one cannot be supported
  *
  * Creates a new cursor from a `GdkTexture`.
  *
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index b36ce7f708..61b5bb22da 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -520,19 +520,19 @@ gdk_device_get_property (GObject    *object,
 /**
  * gdk_device_get_surface_at_position:
  * @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.
+ * @win_x: (out) (allow-none): return location for the X coordinate
+ *   of the device location relative to the surface origin
+ * @win_y: (out) (allow-none): return location for the Y coordinate
+ *   of the device location relative to the surface origin
  *
  * Obtains the surface underneath @device, returning the location of the
- * device in @win_x and @win_y
+ * device in @win_x and @win_y.
  *
  * 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
+ *   device position
  */
 GdkSurface *
 gdk_device_get_surface_at_position (GdkDevice *device,
@@ -1368,8 +1368,7 @@ gdk_device_get_direction (GdkDevice *device)
  *
  * This is only relevant for keyboard devices.
  *
- * Returns: %TRUE if there are layouts with both directions,
- *     %FALSE otherwise
+ * Returns: %TRUE if there are layouts with both directions, %FALSE otherwise
  */
 gboolean
 gdk_device_has_bidi_layouts (GdkDevice *device)
diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 720347e95f..156d5d6eba 100644
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -38,16 +38,16 @@ typedef struct _GdkTimeCoord GdkTimeCoord;
 /**
  * GdkInputSource:
  * @GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
- *                    pointer, even if it is something else, such as a trackball.)
+ *   pointer, even if it is something else, such as a trackball.)
  * @GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
  * @GDK_SOURCE_KEYBOARD: the device is a keyboard.
  * @GDK_SOURCE_TOUCHSCREEN: the device is a direct-input touch device, such
- *     as a touchscreen or tablet
+ *   as a touchscreen or tablet
  * @GDK_SOURCE_TOUCHPAD: the device is an indirect touch device, such
- *     as a touchpad
+ *   as a touchpad
  * @GDK_SOURCE_TRACKPOINT: the device is a trackpoint
  * @GDK_SOURCE_TABLET_PAD: the device is a "pad", a collection of buttons,
- *     rings and strips found in drawing tablets
+ *   rings and strips found in drawing tablets
  *
  * An enumeration describing the type of an input device in general terms.
  */
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index b86ad959f2..a88e9437be 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -1036,8 +1036,7 @@ gdk_display_real_get_app_launch_context (GdkDisplay *display)
  * Returns a `GdkAppLaunchContext` suitable for launching
  * applications on the given display.
  *
- * Returns: (transfer full): a new `GdkAppLaunchContext` for @display.
- *     Free with g_object_unref() when done
+ * Returns: (transfer full): a new `GdkAppLaunchContext` for @display
  */
 GdkAppLaunchContext *
 gdk_display_get_app_launch_context (GdkDisplay *display)
@@ -1053,8 +1052,9 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
  *
  * Opens a display.
  *
- * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if the
- *     display could not be opened
+ * If opening the display fails, `NULL` is returned.
+ *
+ * Returns: (nullable) (transfer none): a `GdkDisplay`
  */
 GdkDisplay *
 gdk_display_open (const char *display_name)
@@ -1073,7 +1073,7 @@ _gdk_display_get_next_serial (GdkDisplay *display)
  * gdk_display_notify_startup_complete:
  * @display: a `GdkDisplay`
  * @startup_id: a startup-notification identifier, for which
- *     notification process should be completed
+ *   notification process should be completed
  *
  * Indicates to the GUI environment that the application has
  * finished loading, using a given identifier.
@@ -1099,7 +1099,7 @@ gdk_display_notify_startup_complete (GdkDisplay  *display,
  * Gets the startup notification ID for a Wayland display, or %NULL
  * if no ID has been defined.
  *
- * Returns: (nullable): the startup notification ID for @display, or %NULL
+ * Returns: (nullable): the startup notification ID for @display
  */
 const char *
 gdk_display_get_startup_notification_id (GdkDisplay *display)
@@ -1160,7 +1160,7 @@ gdk_display_get_keymap (GdkDisplay *display)
 /*< private >
  * gdk_display_make_gl_context_current:
  * @display: a #GdkDisplay
- * @context: (optional): a #GdkGLContext, or %NULL
+ * @context: (optional): a #GdkGLContext
  *
  * Makes the given @context the current GL context, or unsets
  * the current GL context if @context is %NULL.
@@ -1243,7 +1243,7 @@ gdk_display_set_composited (GdkDisplay *display,
  * On modern displays, this value is always %TRUE.
  *
  * Returns: %TRUE if surfaces are created with an alpha channel or
- *     %FALSE if the display does not support this functionality.
+ *   %FALSE if the display does not support this functionality.
  */
 gboolean
 gdk_display_is_rgba (GdkDisplay *display)
@@ -1343,8 +1343,8 @@ gdk_display_get_default_seat (GdkDisplay *display)
  * Returns the list of seats known to @display.
  *
  * Returns: (transfer container) (element-type GdkSeat): the
- *          list of seats known to the `GdkDisplay`
- **/
+ *   list of seats known to the `GdkDisplay`
+ */
 GList *
 gdk_display_list_seats (GdkDisplay *display)
 {
@@ -1502,7 +1502,7 @@ gdk_display_set_cursor_theme (GdkDisplay *display,
  * @display: a `GdkDisplay`
  * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
  * @keys: (out) (array length=n_keys) (transfer full): return location
- *     for an array of `GdkKeymapKey`
+ *   for an array of `GdkKeymapKey`
  * @n_keys: return location for number of elements in returned array
  *
  * Obtains a list of keycode/group/level combinations that will
@@ -1540,9 +1540,9 @@ gdk_display_map_keyval (GdkDisplay    *display,
  * @display: a `GdkDisplay`
  * @keycode: a keycode
  * @keys: (out) (array length=n_entries) (transfer full) (optional): return
- *     location for array of `GdkKeymapKey`, or %NULL
+ *   location for array of `GdkKeymapKey`
  * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
- *     location for array of keyvals, or %NULL
+ *   location for array of keyvals
  * @n_entries: length of @keys and @keyvals
  *
  * Returns the keyvals bound to @keycode.
@@ -1577,12 +1577,11 @@ gdk_display_map_keycode (GdkDisplay    *display,
  * @keycode: a keycode
  * @state: a modifier state
  * @group: active keyboard group
- * @keyval: (out) (optional): return location for keyval, or %NULL
- * @effective_group: (out) (optional): return location for effective
- *     group, or %NULL
- * @level: (out) (optional): return location for level, or %NULL
- * @consumed: (out) (optional): return location for modifiers
- *     that were used to determine the group or level, or %NULL
+ * @keyval: (out) (optional): return location for keyval
+ * @effective_group: (out) (optional): return location for effective group
+ * @level: (out) (optional): return location for level
+ * @consumed: (out) (optional): return location for modifiers that were used
+ *   to determine the group or level
  *
  * Translates the contents of a `GdkEventKey` into a keyval, effective group,
  * and level.
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index c7e2a31f63..c7e3769e92 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -309,8 +309,7 @@ gdk_display_manager_get (void)
  *
  * Gets the default `GdkDisplay`.
  *
- * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
- *     there is no default display.
+ * Returns: (nullable) (transfer none): a `GdkDisplay`
  */
 GdkDisplay *
 gdk_display_manager_get_default_display (GdkDisplayManager *manager)
@@ -361,8 +360,7 @@ gdk_display_manager_set_default_display (GdkDisplayManager *manager,
  * List all currently open displays.
  *
  * Returns: (transfer container) (element-type GdkDisplay): a newly
- *     allocated `GSList` of `GdkDisplay` objects. Free with g_slist_free()
- *     when you are done with it.
+ *   allocated `GSList` of `GdkDisplay` objects
  */
 GSList *
 gdk_display_manager_list_displays (GdkDisplayManager *manager)
diff --git a/gdk/gdkdrawcontext.c b/gdk/gdkdrawcontext.c
index 4135ed4e4e..60cc894f75 100644
--- a/gdk/gdkdrawcontext.c
+++ b/gdk/gdkdrawcontext.c
@@ -188,7 +188,7 @@ gdk_draw_context_init (GdkDrawContext *self)
  * may be effecting the contents of the @context's surface.
  *
  * Returns: %TRUE if the context is between [method@Gdk.DrawContext.begin_frame]
- *     and [method@Gdk.DrawContext.end_frame] calls.
+ *   and [method@Gdk.DrawContext.end_frame] calls.
  */
 gboolean
 gdk_draw_context_is_in_frame (GdkDrawContext *context)
@@ -393,8 +393,7 @@ gdk_draw_context_end_frame (GdkDrawContext *context)
  * 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.
+ * Returns: (transfer none) (nullable): a Cairo region
  */
 const cairo_region_t *
 gdk_draw_context_get_frame_region (GdkDrawContext *context)
diff --git a/gdk/gdkdrop.c b/gdk/gdkdrop.c
index cb1cdb1bf6..90152d8105 100644
--- a/gdk/gdkdrop.c
+++ b/gdk/gdkdrop.c
@@ -657,12 +657,11 @@ gdk_drop_read_internal (GdkDrop             *self,
  * gdk_drop_read_async:
  * @self: a `GdkDrop`
  * @mime_types: (array zero-terminated=1) (element-type utf8):
- *     pointer to an array of mime types
+ *   pointer to an array of mime types
  * @io_priority: the I/O priority for the read operation
- * @cancellable: (allow-none): optional `GCancellable` object,
- *     %NULL to ignore
+ * @cancellable: (allow-none): optional `GCancellable` object
  * @callback: (scope async): a `GAsyncReadyCallback` to call when
- *     the request is satisfied
+ *   the request is satisfied
  * @user_data: (closure): the data to pass to @callback
  *
  * Asynchronously read the dropped data from a `GdkDrop`
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 70a7cbf2eb..0c2b403b59 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -491,7 +491,7 @@ gboolean                gdk_events_get_center           (GdkEvent *event1,
  * GdkKeyMatch:
  * @GDK_KEY_MATCH_NONE: The key event does not match
  * @GDK_KEY_MATCH_PARTIAL: The key event matches if keyboard state
- *     (specifically, the currently active group) is ignored
+ *   (specifically, the currently active group) is ignored
  * @GDK_KEY_MATCH_EXACT: The key event matches
  *
  * Describes how well an event matches a given keyval and modifiers.
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 90f42c5472..34afcd280e 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -412,7 +412,7 @@ gdk_keymap_get_modifier_state (GdkKeymap *keymap)
  * @keymap: a #GdkKeymap
  * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
  * @keys: (out) (array length=n_keys) (transfer full): return location
- *     for an array of #GdkKeymapKey
+ *   for an array of #GdkKeymapKey
  * @n_keys: return location for number of elements in returned array
  *
  * Obtains a list of keycode/group/level combinations that will
@@ -494,9 +494,9 @@ gdk_keymap_get_cached_entries_for_keyval (GdkKeymap     *keymap,
  * @keymap: a #GdkKeymap
  * @hardware_keycode: a keycode
  * @keys: (out) (array length=n_entries) (transfer full) (optional): return
- *     location for array of #GdkKeymapKey, or %NULL
+ *   location for array of #GdkKeymapKey
  * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
- *     location for array of keyvals, or %NULL
+ *   location for array of keyvals
  * @n_entries: length of @keys and @keyvals
  *
  * Returns the keyvals bound to @hardware_keycode.
@@ -551,12 +551,11 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * @hardware_keycode: a keycode
  * @state: a modifier state
  * @group: active keyboard group
- * @keyval: (out) (allow-none): return location for keyval, or %NULL
- * @effective_group: (out) (allow-none): return location for effective
- *     group, or %NULL
- * @level: (out) (allow-none): return location for level, or %NULL
+ * @keyval: (out) (allow-none): return location for keyval
+ * @effective_group: (out) (allow-none): return location for effective group
+ * @level: (out) (allow-none): return location for level
  * @consumed_modifiers: (out) (allow-none): return location for modifiers
- *     that were used to determine the group or level, or %NULL
+ *   that were used to determine the group or level
  *
  * Translates the contents of a #GdkEventKey into a keyval, effective
  * group, and level. Modifiers that affected the translation and
@@ -646,8 +645,7 @@ gdk_keymap_translate_keyboard_state (GdkKeymap       *keymap,
  * but without the leading “GDK_KEY_”.
  *
  * Returns: (nullable) (transfer none): a string containing the name
- *     of the key, or %NULL if @keyval is not a valid key. The string
- *     should not be modified.
+ *   of the key
  */
 const char *
 gdk_keyval_name (guint keyval)
@@ -666,7 +664,7 @@ gdk_keyval_name (guint keyval)
  * but without the leading “GDK_KEY_”.
  *
  * Returns: the corresponding key value, or %GDK_KEY_VoidSymbol
- *     if the key name is not a valid key
+ *   if the key name is not a valid key
  */
 guint
 gdk_keyval_from_name (const char *keyval_name)
diff --git a/gdk/gdkmemorytexture.h b/gdk/gdkmemorytexture.h
index 090b5c6275..598b2f2c3a 100644
--- a/gdk/gdkmemorytexture.h
+++ b/gdk/gdkmemorytexture.h
@@ -31,11 +31,11 @@ G_BEGIN_DECLS
 /**
  * GdkMemoryFormat:
  * @GDK_MEMORY_B8G8R8A8_PREMULTIPLIED: 4 bytes; for blue, green, red, alpha.
- *     The color values are premultiplied with the alpha value.
+ *   The color values are premultiplied with the alpha value.
  * @GDK_MEMORY_A8R8G8B8_PREMULTIPLIED: 4 bytes; for alpha, red, green, blue.
- *     The color values are premultiplied with the alpha value.
+ *   The color values are premultiplied with the alpha value.
  * @GDK_MEMORY_R8G8B8A8_PREMULTIPLIED: 4 bytes; for red, green, blue, alpha
- *     The color values are premultiplied with the alpha value.
+ *   The color values are premultiplied with the alpha value.
  * @GDK_MEMORY_B8G8R8A8: 4 bytes; for blue, green, red, alpha.
  * @GDK_MEMORY_A8R8G8B8: 4 bytes; for alpha, red, green, blue.
  * @GDK_MEMORY_R8G8B8A8: 4 bytes; for red, green, blue, alpha.
@@ -43,7 +43,7 @@ G_BEGIN_DECLS
  * @GDK_MEMORY_R8G8B8: 3 bytes; for red, green, blue. The data is opaque.
  * @GDK_MEMORY_B8G8R8: 3 bytes; for blue, green, red. The data is opaque.
  * @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.
+ *   more formats get added, so do not rely on its concrete integer.
  *
  * `GdkMemoryFormat` describes a format that bytes can have in memory.
  *
diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c
index 0c0c5dea14..b86aaaf19d 100644
--- a/gdk/gdkpaintable.c
+++ b/gdk/gdkpaintable.c
@@ -257,7 +257,7 @@ gdk_paintable_is_immutable (GdkPaintable *paintable)
  * If the @paintable is already immutable, it will return itself.
  *
  * Returns: (transfer full): An immutable paintable for the current
- *     contents of @paintable.
+ *   contents of @paintable
  */
 GdkPaintable *
 gdk_paintable_get_current_image (GdkPaintable *paintable)
@@ -439,17 +439,15 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
  * gdk_paintable_compute_concrete_size:
  * @paintable: a `GdkPaintable`
  * @specified_width: the width @paintable could be drawn into or
- *     0.0 if unknown
+ *   0.0 if unknown
  * @specified_height: the height @paintable could be drawn into or
- *     0.0 if unknown
+ *   0.0 if unknown
  * @default_width: the width @paintable would be drawn into if
- *     no other constraints were given
+ *   no other constraints were given
  * @default_height: the height @paintable would be drawn into if
- *     no other constraints were given
- * @concrete_width: (out): will be set to the concrete width
- *     computed.
- * @concrete_height: (out): will be set to the concrete height
- *     computed.
+ *   no other constraints were given
+ * @concrete_width: (out): will be set to the concrete width computed
+ * @concrete_height: (out): will be set to the concrete height computed
  *
  * Compute a concrete size for the `GdkPaintable`.
  *
diff --git a/gdk/gdkpaintable.h b/gdk/gdkpaintable.h
index 938aa2bf59..897f1d814f 100644
--- a/gdk/gdkpaintable.h
+++ b/gdk/gdkpaintable.h
@@ -37,11 +37,11 @@ G_DECLARE_INTERFACE (GdkPaintable, gdk_paintable, GDK, PAINTABLE, GObject)
 /**
  * GdkPaintableFlags:
  * @GDK_PAINTABLE_STATIC_SIZE: The size is immutable.
- *     The [signal@GdkPaintable::invalidate-size] signal will never be
- *     emitted.
+ *   The [signal@GdkPaintable::invalidate-size] signal will never be
+ *   emitted.
  * @GDK_PAINTABLE_STATIC_CONTENTS: The content is immutable.
- *     The [signal@GdkPaintable::invalidate-contents] signal will never be
- *     emitted.
+ *   The [signal@GdkPaintable::invalidate-contents] signal will never be
+ *   emitted.
  *
  * Flags about a paintable object.
  *
@@ -55,31 +55,31 @@ typedef enum {
 /**
  * GdkPaintableInterface:
  * @snapshot: Snapshot the paintable. The given @width and @height are
- *     guaranteed to be larger than 0.0. The resulting snapshot must modify
- *     only the area in the rectangle from (0,0) to (width, height).
- *     This is the only function that must be implemented for this interface.
- * @get_current_image: return a #GdkPaintable that does not change over
- *     time. This means the GDK_PAINTABLE_STATIC_SIZE and
- *     %GDK_PAINTABLE_STATIC_CONTENTS flag are set.
- * @get_flags: Get the flags for this instance. See #GdkPaintableFlags
- *     for details.
+ *   guaranteed to be larger than 0.0. The resulting snapshot must modify
+ *   only the area in the rectangle from (0,0) to (width, height).
+ *   This is the only function that must be implemented for this interface.
+ * @get_current_image: return a `GdkPaintable` that does not change over
+ *   time. This means the `GDK_PAINTABLE_STATIC_SIZE` and
+ *   `GDK_PAINTABLE_STATIC_CONTENTS` flag are set.
+ * @get_flags: Get the flags for this instance. See [enum@Gdk.PaintableFlags]
+ *   for details.
  * @get_intrinsic_width: The preferred width for this object to be
- *     snapshot at or 0 if none. This is purely a hint. The object must still
- *     be able to render at any size.
+ *   snapshot at or 0 if none. This is purely a hint. The object must still
+ *   be able to render at any size.
  * @get_intrinsic_height: The preferred height for this object to be
- *     snapshot at or 0 if none. This is purely a hint. The object must still
- *     be able to render at any size.
+ *   snapshot at or 0 if none. This is purely a hint. The object must still
+ *   be able to render at any size.
  * @get_intrinsic_aspect_ratio: The preferred aspect ratio for this object
- *     or 0 if none. If both #GdkPaintableInterface.get_intrinsic_width() and
- *     #GdkPaintableInterface.get_intrinsic_height() return non-zero values,
- *     this function should return the aspect ratio computed from those.
+ *   or 0 if none. If both [vfunc@Gdk.PaintableInterface.get_intrinsic_width]
+ *   and [vfunc@Gdk.PaintableInterface.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.
  *
- * 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()
+ * Note that apart from the [vfunc@Gdk.PaintableInterface.snapshot] function,
+ * no virtual function of this interface is mandatory to implement, though it
+ * is a good idea to implement [vfunc@Gdk.PaintableInterface.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.
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index 759296511f..1bf972b0ff 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -93,9 +93,8 @@ layout_iter_get_line_clip_region (PangoLayoutIter *iter,
  * @line: a `PangoLayoutLine`
  * @x_origin: X pixel where you intend to draw the layout line with this clip
  * @y_origin: baseline pixel where you intend to draw the layout line with this clip
- * @index_ranges: (array): array of byte indexes into the layout,
- *     where even members of array are start indexes and odd elements
- *     are end indexes
+ * @index_ranges: (array): array of byte indexes into the layout, where even
+ *   members of array are start indexes and odd elements are end indexes
  * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
  *
  * Obtains a clip region which contains the areas where the given
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index f3636226d1..ca016c1228 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -155,14 +155,14 @@ convert_no_alpha (guchar *dest_data,
  * The pixbuf will contain an alpha channel if the @surface contains one.
  *
  * Returns: (nullable) (transfer full): A newly-created pixbuf with a
- *     reference count of 1, or %NULL on error
+ *   reference count of 1
  */
 GdkPixbuf *
-gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
-                              int              src_x,
-                              int              src_y,
-                              int              width,
-                              int              height)
+gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
+                             int              src_x,
+                             int              src_y,
+                             int              width,
+                             int              height)
 {
   cairo_content_t content;
   GdkPixbuf *dest;
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index 3632147b7f..18b7790ba1 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -122,8 +122,7 @@ gdk_rgba_is_opaque (const GdkRGBA *rgba)
  *
  *  - For non-percentage values, we accept floats in the range 0-255
  *    not just [0-9]+ integers
- *  - For percentage values we accept any float, not just
- *     [ 0-9]+ | [0-9]* “.” [0-9]+
+ *  - For percentage values we accept any float, not just [ 0-9]+ | [0-9]* “.” [0-9]+
  *  - We accept mixed percentages and non-percentages in a single
  *    rgb() or rgba() specification.
  */
diff --git a/gdk/gdktexture.c b/gdk/gdktexture.c
index 3a22d2133e..c7da7d66dd 100644
--- a/gdk/gdktexture.c
+++ b/gdk/gdktexture.c
@@ -453,7 +453,7 @@ gdk_texture_download_area (GdkTexture         *texture,
  * gdk_texture_download:
  * @texture: a `GdkTexture`
  * @data: (array): pointer to enough memory to be filled with the
- *     downloaded data of @texture
+ *   downloaded data of @texture
  * @stride: rowstride in bytes
  *
  * Downloads the @texture into local memory.
diff --git a/gdk/gdktoplevel.c b/gdk/gdktoplevel.c
index ac89e61671..1d16438c0d 100644
--- a/gdk/gdktoplevel.c
+++ b/gdk/gdktoplevel.c
@@ -569,8 +569,7 @@ gdk_toplevel_set_deletable (GdkToplevel *toplevel,
  * Returns whether the desktop environment supports
  * tiled window states.
  *
- * Returns: %TRUE if the desktop environment supports
- *     tiled window states
+ * Returns: %TRUE if the desktop environment supports tiled window states
  */
 gboolean
 gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel)
diff --git a/gdk/gdktoplevellayout.c b/gdk/gdktoplevellayout.c
index 3cc027bd61..d2bc716d90 100644
--- a/gdk/gdktoplevellayout.c
+++ b/gdk/gdktoplevellayout.c
@@ -149,7 +149,7 @@ gdk_toplevel_layout_copy (GdkToplevelLayout *layout)
  * 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_toplevel_layout_equal (GdkToplevelLayout *layout,
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 14f1107da4..faff38f212 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -209,7 +209,7 @@ typedef enum {
 /**
  * GdkVulkanError:
  * @GDK_VULKAN_ERROR_UNSUPPORTED: Vulkan is not supported on this backend or has not been
- *     compiled in.
+ *   compiled in.
  * @GDK_VULKAN_ERROR_NOT_AVAILABLE: Vulkan support is not available on this Surface
  *
  * Error enumeration for #GdkVulkanContext.
diff --git a/gdk/macos/gdkmacosmonitor.c b/gdk/macos/gdkmacosmonitor.c
index ad124a9e64..a68668ced9 100644
--- a/gdk/macos/gdkmacosmonitor.c
+++ b/gdk/macos/gdkmacosmonitor.c
@@ -43,14 +43,14 @@ G_DEFINE_TYPE (GdkMacosMonitor, gdk_macos_monitor, GDK_TYPE_MONITOR)
 
 /**
  * gdk_macos_monitor_get_workarea:
- * @monitor: a #GdkMonitor
- * @workarea: (out): a #GdkRectangle to be filled with
- *     the monitor workarea
+ * @monitor: a `GdkMonitor`
+ * @workarea: (out): a `GdkRectangle` to be filled with the monitor workarea
  *
  * Retrieves the size and position of the “work area” on a monitor
- * within the display coordinate space. The returned geometry is in
- * ”application pixels”, not in ”device pixels” (see
- * gdk_monitor_get_scale_factor()).
+ * 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_macos_monitor_get_workarea (GdkMonitor   *monitor,
diff --git a/gdk/wayland/gdksurface-wayland.c b/gdk/wayland/gdksurface-wayland.c
index 66a8001bcd..a7265677df 100644
--- a/gdk/wayland/gdksurface-wayland.c
+++ b/gdk/wayland/gdksurface-wayland.c
@@ -4493,7 +4493,7 @@ gdk_wayland_surface_is_exported (GdkWaylandSurface *impl)
  * and thus may require changes in the future.
  *
  * Return value: %TRUE if the handle has been requested, %FALSE if
- *     an error occurred.
+ *   an error occurred.
  */
 gboolean
 gdk_wayland_toplevel_export_handle (GdkToplevel                *toplevel,
@@ -4601,7 +4601,7 @@ static const struct zxdg_imported_v1_listener xdg_imported_listener = {
  * and thus may require changes in the future.
  *
  * Return value: %TRUE if the surface has been marked as transient,
- *     %FALSE if an error occurred.
+ *   %FALSE if an error occurred.
  */
 gboolean
 gdk_wayland_toplevel_set_transient_for_exported (GdkToplevel *toplevel,
diff --git a/gdk/win32/gdkdisplay-win32.c b/gdk/win32/gdkdisplay-win32.c
index 223f1b47c5..ec147eade9 100644
--- a/gdk/win32/gdkdisplay-win32.c
+++ b/gdk/win32/gdkdisplay-win32.c
@@ -327,17 +327,17 @@ _gdk_win32_display_init_monitors (GdkWin32Display *win32_display)
 
 /**
  * gdk_win32_display_set_cursor_theme:
- * @display: (type GdkWin32Display): a #GdkDisplay
- * @name: (allow-none): the name of the cursor theme to use, or %NULL to unset
- *         a previously set value
+ * @display: (type GdkWin32Display): a `GdkDisplay`
+ * @name: (allow-none): the name of the cursor theme to use, or %NULL
+ *   to unset a previously set value
  * @size: the cursor size to use, or 0 to keep the previous size
  *
  * Sets the cursor theme from which the images for cursor
  * should be taken.
  *
  * If the windowing system supports it, existing cursors created
- * with gdk_cursor_new_from_name() are updated to reflect the theme
- * change. Custom cursors constructed with gdk_cursor_new_from_texture()
+ * with [ctor@Gdk.Cursor.new_from_name] are updated to reflect the theme
+ * change. Custom cursors constructed with [ctor@Gdk.Cursor.new_from_texture]
  * will have to be handled by the application (GTK applications can
  * learn about cursor theme changes by listening for change notification
  * for the corresponding #GtkSetting).
diff --git a/gdk/win32/gdkmonitor-win32.c b/gdk/win32/gdkmonitor-win32.c
index b149a33b63..19289fb6a0 100644
--- a/gdk/win32/gdkmonitor-win32.c
+++ b/gdk/win32/gdkmonitor-win32.c
@@ -853,14 +853,14 @@ _gdk_win32_monitor_compare (GdkWin32Monitor *a,
 
 /**
  * gdk_win32_monitor_get_workarea:
- * @monitor: a #GdkMonitor
- * @workarea: (out): a #GdkRectangle to be filled with
- *     the monitor workarea
+ * @monitor: a `GdkMonitor`
+ * @workarea: (out): a `GdkRectangle` to be filled with the monitor workarea
  *
  * Retrieves the size and position of the “work area” on a monitor
- * within the display coordinate space. The returned geometry is in
- * ”application pixels”, not in ”device pixels” (see
- * gdk_monitor_get_scale_factor()).
+ * 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_win32_monitor_get_workarea (GdkMonitor   *monitor,
diff --git a/gdk/win32/gdkwin32keys.h b/gdk/win32/gdkwin32keys.h
index a35cd74f33..c0dc85a80c 100644
--- a/gdk/win32/gdkwin32keys.h
+++ b/gdk/win32/gdkwin32keys.h
@@ -32,7 +32,7 @@ G_BEGIN_DECLS
  * @GDK_WIN32_KEYMAP_MATCH_NONE: no matches found. Output is not valid.
  * @GDK_WIN32_KEYMAP_MATCH_INCOMPLETE: the sequence matches so far, but is incomplete. Output is not valid.
  * @GDK_WIN32_KEYMAP_MATCH_PARTIAL: the sequence matches up to the last key,
- *     which does not match. Output is valid.
+ *   which does not match. Output is valid.
  * @GDK_WIN32_KEYMAP_MATCH_EXACT: the sequence matches exactly. Output is valid.
  *
  * An enumeration describing the result of a deadkey combination matching.
diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c
index cdf304a393..24b27ba9e9 100644
--- a/gdk/x11/gdkcursor-x11.c
+++ b/gdk/x11/gdkcursor-x11.c
@@ -260,17 +260,17 @@ gdk_x11_cursor_create_for_name (GdkDisplay  *display,
 
 /**
  * gdk_x11_display_set_cursor_theme:
- * @display: (type GdkX11Display): a #GdkDisplay
- * @theme: (nullable): the name of the cursor theme to use, or %NULL to unset
- *         a previously set value
+ * @display: (type GdkX11Display): a `GdkDisplay`
+ * @theme: (nullable): the name of the cursor theme to use, or %NULL
+ *   to unset a previously set value
  * @size: the cursor size to use, or 0 to keep the previous size
  *
  * Sets the cursor theme from which the images for cursor
  * should be taken.
  *
  * If the windowing system supports it, existing cursors created
- * with gdk_cursor_new_from_name() are updated to reflect the theme
- * change. Custom cursors constructed with gdk_cursor_new_from_texture()
+ * with [ctor@Gdk.Cursor.new_from_name] are updated to reflect the theme
+ * change. Custom cursors constructed with [ctor@Gdk.Cursor.new_from_texture]
  * will have to be handled by the application (GTK applications can learn
  * about cursor theme changes by listening for change notification
  * for the corresponding #GtkSetting).
diff --git a/gdk/x11/gdkdevicemanager-x11.c b/gdk/x11/gdkdevicemanager-x11.c
index 5be86397e7..683518f743 100644
--- a/gdk/x11/gdkdevicemanager-x11.c
+++ b/gdk/x11/gdkdevicemanager-x11.c
@@ -64,15 +64,16 @@ _gdk_x11_device_manager_new (GdkDisplay *display)
   g_error ("XInput2 support not found on display");
 }
 
-/**
+/*
  * gdk_x11_device_manager_lookup:
  * @device_manager: (type GdkX11DeviceManagerXI2): a #GdkDeviceManager
  * @device_id: a device ID, as understood by the XInput2 protocol
  *
  * Returns the #GdkDevice that wraps the given device ID.
  *
- * Returns: (transfer none) (allow-none) (type GdkX11DeviceXI2): The #GdkDevice wrapping the device ID,
- *          or %NULL if the given ID doesn’t currently represent a device.
+ * Returns: (transfer none) (allow-none) (type GdkX11DeviceXI2): The
+ *   `GdkDevice` wrapping the device ID,
+ *   or %NULL if the given ID doesn’t currently represent a device.
  **/
 GdkDevice *
 gdk_x11_device_manager_lookup (GdkX11DeviceManagerXI2 *device_manager,
@@ -86,12 +87,12 @@ gdk_x11_device_manager_lookup (GdkX11DeviceManagerXI2 *device_manager,
 
 /**
  * gdk_x11_device_get_id:
- * @device: (type GdkX11DeviceXI2): a #GdkDevice
+ * @device: (type GdkX11DeviceXI2): a `GdkDevice`
  *
  * Returns the device ID as seen by XInput2.
  *
- * Returns: the XInput2 device ID.
- **/
+ * Returns: the XInput2 device ID
+ */
 int
 gdk_x11_device_get_id (GdkDevice *device)
 {
diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index 828889e977..67675e83a7 100644
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/gdk/x11/gdkdisplay-x11.c
@@ -1358,15 +1358,14 @@ gdk_display_setup_window_visual (GdkDisplay *display,
 /**
  * gdk_x11_display_open:
  * @display_name: (allow-none): name of the X display.
- *     See the XOpenDisplay() for details.
+ *   See the XOpenDisplay() for details.
  *
  * Tries to open a new display to the X server given by
  * @display_name. If opening the display fails, %NULL is
  * returned.
  *
- * Returns: (nullable) (transfer full): The new display or
- *     %NULL on error.
- **/
+ * Returns: (nullable) (transfer full): The new display
+ */
 GdkDisplay *
 gdk_x11_display_open (const char *display_name)
 {
@@ -1994,16 +1993,16 @@ gdk_x11_lookup_xdisplay (Display *xdisplay)
   return display;
 }
 
-/**
+/*
  * _gdk_x11_display_screen_for_xrootwin:
  * @display: a #GdkDisplay
  * @xrootwin: window ID for one of the screen’s of the display.
- * 
+ *
  * Given the root window ID of one of the screen’s of a #GdkDisplay,
  * finds the screen.
- * 
+ *
  * Returns: (transfer none): the #GdkX11Screen corresponding to
- *     @xrootwin, or %NULL.
+ *   @xrootwin, or %NULL.
  **/
 GdkX11Screen *
 _gdk_x11_display_screen_for_xrootwin (GdkDisplay *display,
@@ -2832,7 +2831,7 @@ gdk_x11_display_get_monitors (GdkDisplay *display)
 
 /**
  * gdk_x11_display_get_primary_monitor:
- * @display: (type GdkX11Display): a #GdkDisplay
+ * @display: (type GdkX11Display): a `GdkDisplay`
  *
  * Gets the primary monitor for the display.
  *
@@ -2845,7 +2844,7 @@ gdk_x11_display_get_monitors (GdkDisplay *display)
  * (usually the first) may be returned.
  *
  * Returns: (transfer none): the primary monitor, or any monitor if no
- *     primary monitor is configured by the user
+ *   primary monitor is configured by the user
  */
 GdkMonitor *
 gdk_x11_display_get_primary_monitor (GdkDisplay *display)
diff --git a/gdk/x11/gdkmonitor-x11.c b/gdk/x11/gdkmonitor-x11.c
index 6e85beea58..9c6929b1b9 100644
--- a/gdk/x11/gdkmonitor-x11.c
+++ b/gdk/x11/gdkmonitor-x11.c
@@ -63,14 +63,14 @@ gdk_monitor_has_fullscreen_window (GdkMonitor *monitor)
 
 /**
  * gdk_x11_monitor_get_workarea:
- * @monitor: (type GdkX11Monitor): a #GdkMonitor
- * @workarea: (out): a #GdkRectangle to be filled with
- *     the monitor workarea
+ * @monitor: (type GdkX11Monitor): a `GdkMonitor`
+ * @workarea: (out): a `GdkRectangle` to be filled with the monitor workarea
  *
  * Retrieves the size and position of the “work area” on a monitor
- * within the display coordinate space. The returned geometry is in
- * ”application pixels”, not in ”device pixels” (see
- * gdk_monitor_get_scale_factor()).
+ * 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_x11_monitor_get_workarea (GdkMonitor   *monitor,
diff --git a/gdk/x11/gdkscreen-x11.c b/gdk/x11/gdkscreen-x11.c
index 9cb8be6746..9f6af3d1ec 100644
--- a/gdk/x11/gdkscreen-x11.c
+++ b/gdk/x11/gdkscreen-x11.c
@@ -372,12 +372,12 @@ gdk_x11_screen_get_xscreen (GdkX11Screen *screen)
 
 /**
  * gdk_x11_screen_get_screen_number:
- * @screen: a #GdkX11Screen
+ * @screen: a `GdkX11Screen`
  *
- * Returns the index of a #GdkX11Screen.
+ * Returns the index of a `GdkX11Screen`.
  *
  * Returns: the position of @screen among the screens
- *     of its display
+ *   of its display
  */
 int
 gdk_x11_screen_get_screen_number (GdkX11Screen *screen)
diff --git a/gdk/x11/gdkselection-x11.c b/gdk/x11/gdkselection-x11.c
index 606901ac61..4b9d150a6d 100644
--- a/gdk/x11/gdkselection-x11.c
+++ b/gdk/x11/gdkselection-x11.c
@@ -36,14 +36,14 @@
  * gdk_x11_display_text_property_to_text_list:
  * @display: (type GdkX11Display): The #GdkDisplay where the encoding is defined
  * @encoding: a string representing the encoding. The most
- *    common values for this are "STRING", or "COMPOUND_TEXT".
- *    This is value used as the type for the property
+ *   common values for this are "STRING", or "COMPOUND_TEXT".
+ *   This is value used as the type for the property
  * @format: the format of the property
  * @text: The text data
  * @length: The number of items to transform
  * @list: location to store an  array of strings in
- *    the encoding of the current locale. This array should be
- *    freed using gdk_x11_free_text_list().
+ *   the encoding of the current locale. This array should be
+ *   freed using gdk_x11_free_text_list().
  *
  * Convert a text string from the encoding as it is stored
  * in a property into an array of strings in the encoding of
@@ -51,7 +51,7 @@
  * nul-separated elements of the original text string.)
  *
  * Returns: the number of strings stored in list, or 0,
- *     if the conversion failed
+ *   if the conversion failed
  */
 int
 gdk_x11_display_text_property_to_text_list (GdkDisplay   *display,
@@ -274,10 +274,10 @@ _gdk_x11_display_text_property_to_utf8_list (GdkDisplay    *display,
  * @display: (type GdkX11Display): the #GdkDisplay where the encoding is defined
  * @str: a nul-terminated string
  * @encoding: (out) (transfer none): location to store the encoding
- *     (to be used as the type for the property)
+ *   (to be used as the type for the property)
  * @format: (out): location to store the format of the property
  * @ctext: (out) (array length=length): location to store newly
- *     allocated data for the property
+ *   allocated data for the property
  * @length: the length of @ctext, in bytes
  *
  * Convert a string from the encoding of the current
@@ -331,13 +331,11 @@ gdk_x11_display_string_to_compound_text (GdkDisplay  *display,
  * @encoding: (out) (transfer none): location to store resulting encoding
  * @format: (out): location to store format of the result
  * @ctext: (out) (array length=length): location to store the data of the result
- * @length: location to store the length of the data
- *     stored in @ctext
+ * @length: location to store the length of the data stored in @ctext
  *
  * Converts from UTF-8 to compound text.
  *
- * Returns: %TRUE if the conversion succeeded,
- *     otherwise %FALSE
+ * Returns: %TRUE if the conversion succeeded, otherwise %FALSE
  */
 gboolean
 gdk_x11_display_utf8_to_compound_text (GdkDisplay  *display,
diff --git a/gdk/x11/gdksurface-x11.c b/gdk/x11/gdksurface-x11.c
index 6fb6c96616..8d963a5b3a 100644
--- a/gdk/x11/gdksurface-x11.c
+++ b/gdk/x11/gdksurface-x11.c
@@ -183,13 +183,13 @@ _gdk_x11_surface_get_toplevel (GdkSurface *surface)
  * @width: the new width of the surface
  * @height: the new height of the surface
  * @scale: the new scale of the surface
- * 
+ *
  * Updates the state of the surface (in particular the drawable's
  * cairo surface) when its size has changed.
  *
  * Returns: %TRUE if the surface was updated, %FALSE if no updates
- *     where necessary
- **/
+ *   where necessary
+ */
 static gboolean
 gdk_x11_surface_update_size (GdkX11Surface *self,
                              int            width,
@@ -4622,15 +4622,14 @@ timestamp_predicate (Display *display,
 
 /**
  * gdk_x11_get_server_time:
- * @surface: (type GdkX11Surface): a #GdkSurface, used for communication
- *          with the server.  The surface must have
- *          GDK_PROPERTY_CHANGE_MASK in its events mask or a hang will
- *          result.
+ * @surface: (type GdkX11Surface): a `GdkSurface`, used for communication
+ *   with the server. The surface must have `GDK_PROPERTY_CHANGE_MASK` in
+ *   its events mask or a hang will result.
  *
  * Routine to get the current X server time stamp.
  *
- * Returns: the time stamp.
- **/
+ * Returns: the time stamp
+ */
 guint32
 gdk_x11_get_server_time (GdkSurface *surface)
 {
diff --git a/gdk/x11/gdkxid.c b/gdk/x11/gdkxid.c
index b08ffce7bf..76815528ea 100644
--- a/gdk/x11/gdkxid.c
+++ b/gdk/x11/gdkxid.c
@@ -88,14 +88,14 @@ _gdk_x11_display_remove_window (GdkDisplay *display,
 
 /**
  * gdk_x11_surface_lookup_for_display:
- * @display: (type GdkX11Display): the #GdkDisplay corresponding to the
- *           window handle
+ * @display: (type GdkX11Display): the `GdkDisplay` corresponding to the
+ *   window handle
  * @window: an Xlib Window
  *
- * Looks up the #GdkSurface that wraps the given native window handle.
+ * Looks up the `GdkSurface` that wraps the given native window handle.
  *
- * Returns: (transfer none) (type GdkX11Surface): the #GdkSurface wrapper for the native
- *    window, or %NULL if there is none.
+ * Returns: (transfer none) (type GdkX11Surface): the `GdkSurface` wrapper
+ *   for the native  window
  */
 GdkSurface *
 gdk_x11_surface_lookup_for_display (GdkDisplay *display,