Documentation fixes

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

171 files changed, 987 insertions, 1076 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,
diff --git a/gsk/gskenums.h b/gsk/gskenums.h
index fdea6d74a5..bb4518d948 100644
--- a/gsk/gskenums.h
+++ b/gsk/gskenums.h
@@ -169,12 +169,11 @@ typedef enum {
 
 /**
  * GskSerializationError:
- * @GSK_SERIALIZATION_UNSUPPORTED_FORMAT: The format can not be
- *     identified
- * @GSK_SERIALIZATION_UNSUPPORTED_VERSION: The version of the data
- *     is not understood
+ * @GSK_SERIALIZATION_UNSUPPORTED_FORMAT: The format can not be identified
+ * @GSK_SERIALIZATION_UNSUPPORTED_VERSION: The version of the data is not
+ *   understood
  * @GSK_SERIALIZATION_INVALID_DATA: The given data may not exist in
- *     a proper serialization
+ *   a proper serialization
  *
  * Errors that can happen during (de)serialization.
  */
@@ -187,17 +186,17 @@ typedef enum {
 /**
  * GskTransformCategory:
  * @GSK_TRANSFORM_CATEGORY_UNKNOWN: The category of the matrix has not been
- *     determined.
+ *   determined.
  * @GSK_TRANSFORM_CATEGORY_ANY: Analyzing the matrix concluded that it does
- *     not fit in any other category.
+ *   not fit in any other category.
  * @GSK_TRANSFORM_CATEGORY_3D: The matrix is a 3D matrix. This means that
- *     the w column (the last column) has the values (0, 0, 0, 1).
+ *   the w column (the last column) has the values (0, 0, 0, 1).
  * @GSK_TRANSFORM_CATEGORY_2D: The matrix is a 2D matrix. This is equivalent
- *     to graphene_matrix_is_2d() returning %TRUE. In particular, this
- *     means that Cairo can deal with the matrix.
+ *   to graphene_matrix_is_2d() returning %TRUE. In particular, this
+ *   means that Cairo can deal with the matrix.
  * @GSK_TRANSFORM_CATEGORY_2D_AFFINE: The matrix is a combination of 2D scale
- *     and 2D translation operations. In particular, this means that any
- *     rectangle can be transformed exactly using this matrix.
+ *   and 2D translation operations. In particular, this means that any
+ *   rectangle can be transformed exactly using this matrix.
  * @GSK_TRANSFORM_CATEGORY_2D_TRANSLATE: The matrix is a 2D translation.
  * @GSK_TRANSFORM_CATEGORY_IDENTITY: The matrix is the identity matrix.
  *
diff --git a/gsk/gskrenderer.c b/gsk/gskrenderer.c
index f418bfabb2..45b2981a47 100644
--- a/gsk/gskrenderer.c
+++ b/gsk/gskrenderer.c
@@ -403,7 +403,7 @@ gsk_renderer_render_texture (GskRenderer           *renderer,
  * @renderer: a `GskRenderer`
  * @root: a `GskRenderNode`
  * @region: (nullable): the `cairo_region_t` that must be redrawn or %NULL
- *     for the whole window
+ *   for the whole window
  *
  * Renders the scene graph, described by a tree of `GskRenderNode` instances,
  * ensuring that the given @region gets redrawn.
diff --git a/gsk/gskrendernode.c b/gsk/gskrendernode.c
index ed1a1eb7f8..f99aaefa39 100644
--- a/gsk/gskrendernode.c
+++ b/gsk/gskrendernode.c
@@ -607,8 +607,7 @@ gsk_render_node_write_to_file (GskRenderNode *node,
  *
  * For a discussion of the supported format, see that function.
  *
- * Returns: (nullable) (transfer full): a new `GskRenderNode` or %NULL on
- *     error.
+ * Returns: (nullable) (transfer full): a new `GskRenderNode`
  */
 GskRenderNode *
 gsk_render_node_deserialize (GBytes            *bytes,
diff --git a/gsk/gsktransform.c b/gsk/gsktransform.c
index 9448a4ef5e..cc1dea0e93 100644
--- a/gsk/gsktransform.c
+++ b/gsk/gsktransform.c
@@ -93,7 +93,7 @@ gsk_transform_has_class (GskTransform            *self,
  * gsk_transform_alloc:
  * @transform_class: class structure for this self
  * @category: The category of this transform. Will be used to initialize
- *     the result's category together with &next's category
+ *   the result's category together with &next's category
  * @next: (transfer full): Next transform to multiply with or %NULL if none
  *
  * Returns: (transfer full): the newly created #GskTransform
@@ -226,7 +226,7 @@ static const GskTransformClass GSK_IDENTITY_TRANSFORM_CLASS =
  * which just results in an identity transform when simplified.
  *
  * Returns: %TRUE  if this transform is a representation of
- *     the identity transform
+ *   the identity transform
  **/
 static gboolean
 gsk_transform_is_identity (GskTransform *self)
@@ -1288,8 +1288,8 @@ static const GskTransformClass GSK_PERSPECTIVE_TRANSFORM_CLASS =
  * gsk_transform_perspective:
  * @next: (allow-none) (transfer full): the next transform
  * @depth: distance of the z=0 plane. Lower values give a more
- *     flattened pyramid and therefore a more pronounced
- *     perspective effect.
+ *   flattened pyramid and therefore a more pronounced
+ *   perspective effect.
  *
  * Applies a perspective projection transform.
  *
@@ -1520,19 +1520,22 @@ gsk_transform_to_2d (GskTransform *self,
  * gsk_transform_to_affine:
  * @self: a `GskTransform`
  * @out_scale_x: (out): return location for the scale
- *     factor in the x direction
+ *   factor in the x direction
  * @out_scale_y: (out): return location for the scale
- *     factor in the y direction
+ *   factor in the y direction
  * @out_dx: (out): return location for the translation
- *     in the x direction
+ *   in the x direction
  * @out_dy: (out): return location for the translation
- *     in the y direction
+ *   in the y direction
  *
  * Converts a `GskTransform` to 2D affine transformation factors.
  *
  * @self must be a 2D transformation. If you are not
- * sure, use gsk_transform_get_category() >=
- * %GSK_TRANSFORM_CATEGORY_2D_AFFINE to check.
+ * sure, use
+ *
+ *     gsk_transform_get_category() >= %GSK_TRANSFORM_CATEGORY_2D_AFFINE
+ *
+ * to check.
  */
 void
 gsk_transform_to_affine (GskTransform *self,
@@ -1586,15 +1589,18 @@ gsk_transform_to_affine (GskTransform *self,
  * gsk_transform_to_translate:
  * @self: a `GskTransform`
  * @out_dx: (out): return location for the translation
- *     in the x direction
+ *   in the x direction
  * @out_dy: (out): return location for the translation
- *     in the y direction
+ *   in the y direction
  *
  * Converts a `GskTransform` to a translation operation.
  *
  * @self must be a 2D transformation. If you are not
- * sure, use gsk_transform_get_category() >= 
- * %GSK_TRANSFORM_CATEGORY_2D_TRANSLATE to check.
+ * sure, use
+ *
+ *     gsk_transform_get_category() >= %GSK_TRANSFORM_CATEGORY_2D_TRANSLATE
+ *
+ * to check.
  */
 void
 gsk_transform_to_translate (GskTransform *self,
@@ -1677,8 +1683,7 @@ gsk_transform_transform (GskTransform *next,
  * between those cases, you should check @self is not %NULL
  * before calling this function.
  *
- * Returns: (nullable): The inverted transform or %NULL if the transform
- *     cannot be inverted.
+ * Returns: (nullable): The inverted transform
  */
 GskTransform *
 gsk_transform_invert (GskTransform *self)
@@ -1705,7 +1710,7 @@ gsk_transform_invert (GskTransform *self)
  *
  * Checks two transforms for equality.
  *
- * Returns: %TRUE if the two transforms perform the same operation.
+ * Returns: %TRUE if the two transforms perform the same operation
  */
 gboolean
 gsk_transform_equal (GskTransform *first,
diff --git a/gtk/a11y/gtkatspipango.c b/gtk/a11y/gtkatspipango.c
index 1171c8758b..2f3697c83e 100644
--- a/gtk/a11y/gtkatspipango.c
+++ b/gtk/a11y/gtkatspipango.c
@@ -880,7 +880,7 @@ pango_layout_get_line_after (PangoLayout           *layout,
  * atk_text_get_text_before_offset().
  *
  * Returns: a newly allocated string containing a slice of text
- *     from layout. Free with g_free().
+ *   from layout. Free with g_free().
  */
 char *
 gtk_pango_get_text_before (PangoLayout           *layout,
@@ -985,7 +985,7 @@ gtk_pango_get_text_before (PangoLayout           *layout,
  * atk_text_get_text_after_offset().
  *
  * Returns: a newly allocated string containing a slice of text
- *     from layout. Free with g_free().
+ *   from layout. Free with g_free().
  */
 char *
 gtk_pango_get_text_after (PangoLayout           *layout,
@@ -1096,7 +1096,7 @@ gtk_pango_get_text_after (PangoLayout           *layout,
  * atk_text_get_text_after_offset().
  *
  * Returns: a newly allocated string containing a slice of text
- *     from layout. Free with g_free().
+ *   from layout. Free with g_free().
  */
 char *
 gtk_pango_get_text_at (PangoLayout           *layout,
diff --git a/gtk/css/gtkcssdataurl.c b/gtk/css/gtkcssdataurl.c
index d07f59c4c8..7bc9224dbd 100644
--- a/gtk/css/gtkcssdataurl.c
+++ b/gtk/css/gtkcssdataurl.c
@@ -37,7 +37,7 @@
  * gtk_css_data_url_parse:
  * @url: the URL to parse
  * @out_mimetype: (out nullable optional): Return location to set the contained
- *     mime type to. If no mime type was specified, this value is set to %NULL.
+ *   mime type to. If no mime type was specified, this value is set to %NULL.
  * @error: error location or %NULL for none
  *
  * Decodes a data URL according to RFC2397 and returns the decoded data.
diff --git a/gtk/css/gtkcssenums.h b/gtk/css/gtkcssenums.h
index a585ab2ae3..e83797e11a 100644
--- a/gtk/css/gtkcssenums.h
+++ b/gtk/css/gtkcssenums.h
@@ -35,15 +35,13 @@
 /**
  * GtkCssParserError:
  * @GTK_CSS_PARSER_ERROR_FAILED: Unknown failure.
- * @GTK_CSS_PARSER_ERROR_SYNTAX: The given text does not form valid
- *     syntax
+ * @GTK_CSS_PARSER_ERROR_SYNTAX: The given text does not form valid syntax
  * @GTK_CSS_PARSER_ERROR_IMPORT: Failed to import a resource
  * @GTK_CSS_PARSER_ERROR_NAME: The given name has not been defined
- * @GTK_CSS_PARSER_ERROR_UNKNOWN_VALUE: The given value is not
- *     correct
+ * @GTK_CSS_PARSER_ERROR_UNKNOWN_VALUE: The given value is not correct
  *
  * Errors that can occur while parsing CSS.
- * 
+ *
  * These errors are unexpected and will cause parts of the given CSS
  * to be ignored.
  */
@@ -59,11 +57,10 @@ typedef enum
 /**
  * GtkCssParserWarning:
  * @GTK_CSS_PARSER_WARNING_DEPRECATED: The given construct is
- *     deprecated and will be removed in a future version
+ *   deprecated and will be removed in a future version
  * @GTK_CSS_PARSER_WARNING_SYNTAX: A syntax construct was used
- *     that should be avoided
- * @GTK_CSS_PARSER_WARNING_UNIMPLEMENTED: A feature is not
- *     implemented
+ *   that should be avoided
+ * @GTK_CSS_PARSER_WARNING_UNIMPLEMENTED: A feature is not implemented
  *
  * Warnings that can occur while parsing CSS.
  *
diff --git a/gtk/css/gtkcsslocation.c b/gtk/css/gtkcsslocation.c
index bff0a0121a..41725ad2fe 100644
--- a/gtk/css/gtkcsslocation.c
+++ b/gtk/css/gtkcsslocation.c
@@ -23,12 +23,10 @@
  * GtkCssLocation:
  * @bytes: number of bytes parsed since the beginning
  * @chars: number of characters parsed since the beginning
- * @lines: number of full lines that have been parsed
- *     If you want to display this as a line number, you
- *     need to add 1 to this.
+ * @lines: number of full lines that have been parsed. If you want to
+ *   display this as a line number, you need to add 1 to this.
  * @line_bytes: Number of bytes parsed since the last line break
- * @line_chars: Number of characters parsed since the last line
- *     break
+ * @line_chars: Number of characters parsed since the last line break
  *
  * Represents a location in a file or other source of data parsed
  * by the CSS engine.
diff --git a/gtk/css/gtkcssparser.c b/gtk/css/gtkcssparser.c
index 99e4944784..f213900a84 100644
--- a/gtk/css/gtkcssparser.c
+++ b/gtk/css/gtkcssparser.c
@@ -173,9 +173,9 @@ gtk_css_parser_get_file (GtkCssParser *self)
  *
  * Resolves a given URL against the parser's location.
  *
- * Returns: (nullable) (transfer full): a new #GFile for the
- *     resolved URL or %NULL if the URI cannot be resolved.
- **/
+ * Returns: (nullable) (transfer full): a new `GFile` for the
+ *   resolved URL
+ */
 GFile *
 gtk_css_parser_resolve_url (GtkCssParser *self,
                             const char   *url)
@@ -890,13 +890,13 @@ gtk_css_parser_try_token (GtkCssParser    *self,
  * @self: a #GtkCssParser
  *
  * If the current token is an identifier, consumes it and returns
- * its name.  
+ * its name.
+ *
  * If the current token is not an identifier, an error is emitted
  * and %NULL is returned.
  *
  * Returns: (transfer full): the name of the consumed identifier
- *     or %NULL on error
- **/
+ */
 char *
 gtk_css_parser_consume_ident (GtkCssParser *self)
 {
@@ -921,12 +921,12 @@ gtk_css_parser_consume_ident (GtkCssParser *self)
  * gtk_css_parser_consume_string:
  * @self: a #GtkCssParser
  *
- * If the current token is a string, consumes it and return the string.  
+ * If the current token is a string, consumes it and return the string.
+ *
  * If the current token is not a string, an error is emitted
  * and %NULL is returned.
  *
- * Returns: (transfer full): the name of the consumed string 
- *     or %NULL on error
+ * Returns: (transfer full): the name of the consumed string
  **/
 char *
 gtk_css_parser_consume_string (GtkCssParser *self)
diff --git a/gtk/css/gtkcsssection.c b/gtk/css/gtkcsssection.c
index 472e045ad5..c0edb7e1ff 100644
--- a/gtk/css/gtkcsssection.c
+++ b/gtk/css/gtkcsssection.c
@@ -158,8 +158,8 @@ gtk_css_section_get_file (const GtkCssSection *section)
  * Returns the location in the CSS document where this section starts.
  *
  * Returns: (transfer none) (not nullable): The start location of
- *     this section
- **/
+ *   this section
+ */
 const GtkCssLocation *
 gtk_css_section_get_start_location (const GtkCssSection *section)
 {
@@ -175,8 +175,8 @@ gtk_css_section_get_start_location (const GtkCssSection *section)
  * Returns the location in the CSS document where this section ends.
  *
  * Returns: (transfer none) (not nullable): The end location of
- *     this section
- **/
+ *   this section
+ */
 const GtkCssLocation *
 gtk_css_section_get_end_location (const GtkCssSection *section)
 {
diff --git a/gtk/css/gtkcsstokenizer.c b/gtk/css/gtkcsstokenizer.c
index a406ad3d06..14a419b790 100644
--- a/gtk/css/gtkcsstokenizer.c
+++ b/gtk/css/gtkcsstokenizer.c
@@ -215,7 +215,7 @@ gtk_css_token_is_finite (const GtkCssToken *token)
  * gtk_css_token_is_preserved:
  * @token: a #GtkCssToken
  * @out_closing: (allow-none): Type of the token that closes a block
- *     started with this token
+ *   started with this token
  *
  * A token is considered preserved when it does not start a block.
  *
@@ -223,7 +223,7 @@ gtk_css_token_is_finite (const GtkCssToken *token)
  * so CSS parsers want to look at this function
  *
  * Returns: %TRUE if the token is considered preserved.
- **/
+ */
 gboolean
 gtk_css_token_is_preserved (const GtkCssToken *token,
                             GtkCssTokenType   *out_closing)
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 8922d574be..cf9d1934b4 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -374,7 +374,8 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    *
    * The name of the program.
    *
-   * If this is not set, it defaults to `g_get_application_name()`.
+   * If this is not set, it defaults to the value returned by
+   * `g_get_application_name()`.
    */
   props[PROP_NAME] =
     g_param_spec_string ("program-name",
@@ -426,7 +427,7 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
   /**
    * GtkAboutDialog:license: (attributes org.gtk.Property.get=gtk_about_dialog_get_license org.gtk.Property.set=gtk_about_dialog_set_license)
    *
-   * The license of the program, as free form text.
+   * The license of the program, as free-form text.
    *
    * This string is displayed in a text view in a secondary dialog, therefore
    * it is fine to use a long multi-paragraph text. Note that the text is only
@@ -453,7 +454,7 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    *
    * Information about the system on which the program is running.
    *
-   * This information is displayed in a separate tab, therefore it is fine
+   * This information is displayed in a separate page, therefore it is fine
    * to use a long multi-paragraph text. Note that the text should contain
    * the intended linebreaks.
    *
@@ -986,8 +987,7 @@ update_website (GtkAboutDialog *about)
  *
  * Returns the program name displayed in the about dialog.
  *
- * Returns: (nullable): The program name. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable): The program name
  */
 const char *
 gtk_about_dialog_get_program_name (GtkAboutDialog *about)
@@ -1027,7 +1027,8 @@ update_name_version (GtkAboutDialog *about)
  *
  * Sets the name to display in the about dialog.
  *
- * If `name` is not set, it defaults to `g_get_application_name()`.
+ * If `name` is not set, the string returned
+ * by `g_get_application_name()` is used.
  */
 void
 gtk_about_dialog_set_program_name (GtkAboutDialog *about,
@@ -1053,8 +1054,7 @@ gtk_about_dialog_set_program_name (GtkAboutDialog *about,
  *
  * Returns the version string.
  *
- * Returns: (nullable): The version string. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable): The version string
  */
 const char *
 gtk_about_dialog_get_version (GtkAboutDialog *about)
@@ -1094,8 +1094,7 @@ gtk_about_dialog_set_version (GtkAboutDialog *about,
  *
  * Returns the copyright string.
  *
- * Returns: (nullable): The copyright string. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable): The copyright string
  */
 const char *
 gtk_about_dialog_get_copyright (GtkAboutDialog *about)
@@ -1147,8 +1146,7 @@ gtk_about_dialog_set_copyright (GtkAboutDialog *about,
  *
  * Returns the comments string.
  *
- * Returns: (nullable): The comments. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable): The comments
  */
 const char *
 gtk_about_dialog_get_comments (GtkAboutDialog *about)
@@ -1198,8 +1196,7 @@ gtk_about_dialog_set_comments (GtkAboutDialog *about,
  *
  * Returns the license information.
  *
- * Returns: (nullable): The license information. The string is owned by the about
- *  dialog and must not be modified.
+ * Returns: (nullable): The license information
  */
 const char *
 gtk_about_dialog_get_license (GtkAboutDialog *about)
@@ -1214,10 +1211,10 @@ gtk_about_dialog_get_license (GtkAboutDialog *about)
  * @about: a `GtkAboutDialog`
  * @license: (nullable): the license information
  *
- * Sets the license information to be displayed in the secondary
- * license dialog.
+ * Sets the license information to be displayed in the
+ * about dialog.
  *
- * If `license` is `NULL`, the license button is hidden.
+ * If `license` is `NULL`, the license page is hidden.
  */
 void
 gtk_about_dialog_set_license (GtkAboutDialog *about,
@@ -1273,7 +1270,7 @@ gtk_about_dialog_get_system_information (GtkAboutDialog *about)
  * dialog.
  *
  * If `system_information` is `NULL`, the system information
- * tab is hidden.
+ * page is hidden.
  *
  * See [property@Gtk.AboutDialog:system-information].
  */
@@ -1377,7 +1374,7 @@ gtk_about_dialog_set_website (GtkAboutDialog *about,
  *
  * Returns the label used for the website link.
  *
- * Returns: (nullable) (transfer none): The label used for the website link.
+ * Returns: (nullable) (transfer none): The label used for the website link
  */
 const char *
 gtk_about_dialog_get_website_label (GtkAboutDialog *about)
@@ -1415,12 +1412,11 @@ gtk_about_dialog_set_website_label (GtkAboutDialog *about,
  * gtk_about_dialog_get_authors: (attributes org.gtk.Method.get_property=authors)
  * @about: a `GtkAboutDialog`
  *
- * Returns the string which are displayed in the authors tab
- * of the secondary credits dialog.
+ * Returns the names of the authors which are displayed
+ * in the credits page.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  `NULL`-terminated string array containing the authors. The array is
- *  owned by the about dialog and must not be modified.
+ *   `NULL`-terminated string array containing the authors
  */
 const char * const *
 gtk_about_dialog_get_authors (GtkAboutDialog *about)
@@ -1435,8 +1431,8 @@ gtk_about_dialog_get_authors (GtkAboutDialog *about)
  * @about: a `GtkAboutDialog`
  * @authors: (array zero-terminated=1): the authors of the application
  *
- * Sets the strings which are displayed in the "Authors" tab
- * of the secondary credits dialog.
+ * Sets the names of the authors which are displayed
+ * in the "Credits" page of the about dialog.
  */
 void
 gtk_about_dialog_set_authors (GtkAboutDialog  *about,
@@ -1459,12 +1455,11 @@ gtk_about_dialog_set_authors (GtkAboutDialog  *about,
  * gtk_about_dialog_get_documenters: (attributes org.gtk.Method.get_property=documenters)
  * @about: a `GtkAboutDialog`
  *
- * Returns the string which are displayed in the "Documenters"
- * tab of the secondary credits dialog.
+ * Returns the name of the documenters which are displayed
+ * in the credits page.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  `NULL`-terminated string array containing the documenters. The
- *  array is owned by the about dialog and must not be modified.
+ *   `NULL`-terminated string array containing the documenters
  */
 const char * const *
 gtk_about_dialog_get_documenters (GtkAboutDialog *about)
@@ -1480,8 +1475,8 @@ gtk_about_dialog_get_documenters (GtkAboutDialog *about)
  * @documenters: (array zero-terminated=1): the authors of the documentation
  *   of the application
  *
- * Sets the strings which are displayed in the "Documenters" tab
- * of the credits dialog.
+ * Sets the names of the documenters which are displayed
+ * in the "Credits" page.
  */
 void
 gtk_about_dialog_set_documenters (GtkAboutDialog *about,
@@ -1504,12 +1499,11 @@ gtk_about_dialog_set_documenters (GtkAboutDialog *about,
  * gtk_about_dialog_get_artists: (attributes org.gtk.Method.get_property=artists)
  * @about: a `GtkAboutDialog`
  *
- * Returns the string which are displayed in the "Artists" tab
- * of the secondary credits dialog.
+ * Returns the names of the artists which are displayed
+ * in the credits page.
  *
  * Returns: (array zero-terminated=1) (transfer none): A
- *  `NULL`-terminated string array containing the artists. The array is
- *  owned by the about dialog and must not be modified.
+ *   `NULL`-terminated string array containing the artists
  */
 const char * const *
 gtk_about_dialog_get_artists (GtkAboutDialog *about)
@@ -1525,8 +1519,8 @@ gtk_about_dialog_get_artists (GtkAboutDialog *about)
  * @artists: (array zero-terminated=1): the authors of the artwork
  *   of the application
  *
- * Sets the strings which are displayed in the "Artists" tab
- * of the secondary credits dialog.
+ * Sets the names of the artists to be displayed
+ * in the "Credits" page.
  */
 void
 gtk_about_dialog_set_artists (GtkAboutDialog *about,
@@ -1550,9 +1544,9 @@ gtk_about_dialog_set_artists (GtkAboutDialog *about,
  * @about: a `GtkAboutDialog`
  *
  * Returns the translator credits string which is displayed
- * in the translators tab of the secondary credits dialog.
+ * in the credits page.
  *
- * Returns: (nullable): The translator credits string.
+ * Returns: (nullable): The translator credits string
  */
 const char *
 gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
@@ -1568,7 +1562,7 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
  * @translator_credits: (nullable): the translator credits
  *
  * Sets the translator credits string which is displayed in
- * the translators tab of the secondary credits dialog.
+ * the credits page.
  *
  * The intended use for this string is to display the translator
  * of the language which is currently used in the user interface.
@@ -1581,10 +1575,10 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
  *                                           _("translator-credits"));
  * ```
  *
- * It is a good idea to use the customary `msgid` “translator-credits” for this
- * purpose, since translators will already know the purpose of that `msgid`, and
- * since `GtkAboutDialog` will detect if “translator-credits” is untranslated
- * and hide the tab.
+ * It is a good idea to use the customary `msgid` “translator-credits”
+ * for this purpose, since translators will already know the purpose of
+ * that `msgid`, and since `GtkAboutDialog` will detect if “translator-credits”
+ * is untranslated and omit translator credits.
  */
 void
 gtk_about_dialog_set_translator_credits (GtkAboutDialog *about,
@@ -1611,8 +1605,7 @@ gtk_about_dialog_set_translator_credits (GtkAboutDialog *about,
  *
  * Returns: (transfer none) (nullable): the paintable displayed as
  *   logo or `NULL` if the logo is unset or has been set via
- *   [method@Gtk.AboutDialog.set_logo_icon_name]. The
- *   paintable is owned by the about dialog.
+ *   [method@Gtk.AboutDialog.set_logo_icon_name]
  */
 GdkPaintable *
 gtk_about_dialog_get_logo (GtkAboutDialog *about)
@@ -1658,8 +1651,7 @@ gtk_about_dialog_set_logo (GtkAboutDialog *about,
  * Returns the icon name displayed as logo in the about dialog.
  *
  * Returns: (transfer none) (nullable): the icon name displayed as logo,
- *   or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo].
- *   The string is owned by the dialog.
+ *   or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo]
  */
 const char *
 gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about)
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 976a6c68ca..a4c1aa5021 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -228,19 +228,18 @@ is_keycode (const char *string)
 /**
  * gtk_accelerator_parse_with_keycode:
  * @accelerator: string representing an accelerator
- * @display: (allow-none): the #GdkDisplay to look up @accelerator_codes in
- * @accelerator_key: (out) (allow-none): return location for accelerator
- *     keyval, or %NULL
+ * @display: (allow-none): the `GdkDisplay` to look up @accelerator_codes in
+ * @accelerator_key: (out) (allow-none): return location for accelerator keyval
  * @accelerator_codes: (out) (array zero-terminated=1) (transfer full) (allow-none):
- *     return location for accelerator keycodes, or %NULL
+ *   return location for accelerator keycodes
  * @accelerator_mods: (out) (allow-none): return location for accelerator
- *     modifier mask, %NULL
+ *   modifier mask
  *
  * Parses a string representing an accelerator.
  *
  * This is similar to [func@Gtk.accelerator_parse] but handles keycodes as
  * well. This is only useful for system-level components, applications should
- * use gtk_accelerator_parse() instead.
+ * use [func@Gtk.accelerator_parse] instead.
  *
  * If @accelerator_codes is given and the result stored in it is non-%NULL,
  * the result must be freed with g_free().
@@ -479,10 +478,9 @@ out:
 /**
  * gtk_accelerator_parse:
  * @accelerator: string representing an accelerator
- * @accelerator_key: (out) (allow-none): return location for accelerator
- *     keyval, or %NULL
+ * @accelerator_key: (out) (allow-none): return location for accelerator keyval
  * @accelerator_mods: (out) (allow-none): return location for accelerator
- *     modifier mask, %NULL
+ *   modifier mask
  *
  * Parses a string representing an accelerator.
  *
@@ -507,7 +505,7 @@ gtk_accelerator_parse (const char      *accelerator,
 
 /**
  * gtk_accelerator_name_with_keycode:
- * @display: (allow-none): a #GdkDisplay or %NULL to use the default display
+ * @display: (allow-none): a `GdkDisplay` or %NULL to use the default display
  * @accelerator_key: accelerator keyval
  * @keycode: accelerator keycode
  * @accelerator_mods: accelerator modifier mask
@@ -517,7 +515,7 @@ gtk_accelerator_parse (const char      *accelerator,
  *
  * This is similar to [func@Gtk.accelerator_name] but handling keycodes.
  * This is only useful for system-level components, applications
- * should use gtk_accelerator_parse() instead.
+ * should use [func@Gtk.accelerator_name] instead.
  *
  * Returns: a newly allocated accelerator name.
  */
@@ -623,7 +621,7 @@ gtk_accelerator_name (guint           accelerator_key,
 
 /**
  * gtk_accelerator_get_label_with_keycode:
- * @display: (allow-none): a #GdkDisplay or %NULL to use the default display
+ * @display: (allow-none): a `GdkDisplay` or %NULL to use the default display
  * @accelerator_key: accelerator keyval
  * @keycode: accelerator keycode
  * @accelerator_mods: accelerator modifier mask
@@ -634,12 +632,11 @@ gtk_accelerator_name (guint           accelerator_key,
  * The string may be translated.
  *
  * This function is similar to [func@Gtk.accelerator_get_label],
- * but handling keycodes.
+ * but handling keycodes. This is only useful for system-level
+ * components, applications should use [func@Gtk.accelerator_get_label]
+ * instead.
  *
- * This is only useful for system-level components, applications
- * should use gtk_accelerator_parse() instead.
- *
- * Returns: a newly-allocated string representing the accelerator.
+ * Returns: (transfer full): a newly-allocated string representing the accelerator
  */
 char *
 gtk_accelerator_get_label_with_keycode (GdkDisplay      *display,
@@ -795,7 +792,7 @@ append_separator (GString *string)
  * Converts an accelerator keyval and modifier mask into a string
  * which can be used to represent the accelerator to the user.
  *
- * Returns: a newly-allocated string representing the accelerator.
+ * Returns: (transfer full): a newly-allocated string representing the accelerator
  */
 char *
 gtk_accelerator_get_label (guint           accelerator_key,
diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index cd5bf0e203..0c6e4cca4f 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -26,8 +26,7 @@
  *
  * Every accessible implementation has:
  *
- *  - a “role”, represented by a value of the [enum@Gtk.AccessibleRole]
- *    enumeration
+ *  - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration
  *  - an “attribute”, represented by a set of [enum@Gtk.AccessibleState],
  *    [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values
  *
diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c
index 974b881d2a..69581d2f1d 100644
--- a/gtk/gtkactionable.c
+++ b/gtk/gtkactionable.c
@@ -74,7 +74,7 @@ gtk_actionable_default_init (GtkActionableInterface *iface)
  *
  * Gets the action name for @actionable.
  *
- * Returns: (nullable): the action name, or %NULL if none is set
+ * Returns: (nullable): the action name
  */
 const char *
 gtk_actionable_get_action_name (GtkActionable *actionable)
@@ -88,7 +88,7 @@ gtk_actionable_get_action_name (GtkActionable *actionable)
 /**
  * gtk_actionable_set_action_name: (attributes org.gtk.Property.set=action-name)
  * @actionable: a `GtkActionable` widget
- * @action_name: (nullable): an action name, or %NULL
+ * @action_name: (nullable): an action name
  *
  * Specifies the name of the action with which this widget should be
  * associated.
@@ -134,7 +134,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
 /**
  * gtk_actionable_set_action_target_value: (attributes org.gtk.Method.set_property=action-target)
  * @actionable: a `GtkActionable` widget
- * @target_value: (nullable): a #GVariant to set as the target value, or %NULL
+ * @target_value: (nullable): a `GVariant` to set as the target value
  *
  * Sets the target value of an actionable widget.
  *
@@ -154,7 +154,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
  * is now equal to the target value of the button, the button will now
  * be rendered as active (and the other buttons, with different targets,
  * rendered inactive).
- **/
+ */
 void
 gtk_actionable_set_action_target_value (GtkActionable *actionable,
                                         GVariant      *target_value)
diff --git a/gtk/gtkactionbar.c b/gtk/gtkactionbar.c
index 7bbcddfae8..2d4e0d0af2 100644
--- a/gtk/gtkactionbar.c
+++ b/gtk/gtkactionbar.c
@@ -308,7 +308,7 @@ gtk_action_bar_set_center_widget (GtkActionBar *action_bar,
  *
  * Retrieves the center bar widget of the bar.
  *
- * Returns: (transfer none) (nullable): the center `GtkWidget` or %NULL.
+ * Returns: (transfer none) (nullable): the center `GtkWidget`
  */
 GtkWidget *
 gtk_action_bar_get_center_widget (GtkActionBar *action_bar)
@@ -362,7 +362,7 @@ gtk_action_bar_set_revealed (GtkActionBar *action_bar,
  * Gets whether the contents of the action bar are revealed.
  *
  * Returns: the current value of the [property@Gtk.ActionBar:revealed]
- * property.
+ *   property
  */
 gboolean
 gtk_action_bar_get_revealed (GtkActionBar *action_bar)
diff --git a/gtk/gtkactionobserver.c b/gtk/gtkactionobserver.c
index 0cefb9ab9a..0929c6a83e 100644
--- a/gtk/gtkactionobserver.c
+++ b/gtk/gtkactionobserver.c
@@ -58,10 +58,8 @@ gtk_action_observer_default_init (GtkActionObserverInterface *class)
  * @observable: the source of the event
  * @action_name: the name of the action
  * @enabled: %TRUE if the action is now enabled
- * @parameter_type: the parameter type for action invocations, or %NULL
- *                  if no parameter is required
- * @state: the current state of the action, or %NULL if the action is
- *         stateless
+ * @parameter_type: (nullable): the parameter type for action invocations
+ * @state: (nullable): the current state of the action
  *
  * This function is called when an action that the observer is
  * registered to receive events for is added.
diff --git a/gtk/gtkappchooser.c b/gtk/gtkappchooser.c
index a8188a9f41..1d1ba7da26 100644
--- a/gtk/gtkappchooser.c
+++ b/gtk/gtkappchooser.c
@@ -107,8 +107,7 @@ gtk_app_chooser_get_content_type (GtkAppChooser *self)
  * Returns the currently selected application.
  *
  * Returns: (nullable) (transfer full): a `GAppInfo` for the
- *   currently selected application, or %NULL if none is selected.
- *   Free with g_object_unref()
+ *   currently selected application
  */
 GAppInfo *
 gtk_app_chooser_get_app_info (GtkAppChooser *self)
diff --git a/gtk/gtkappchooserbutton.c b/gtk/gtkappchooserbutton.c
index 6c2626ba50..79d18f21c6 100644
--- a/gtk/gtkappchooserbutton.c
+++ b/gtk/gtkappchooserbutton.c
@@ -1058,7 +1058,7 @@ gtk_app_chooser_button_set_heading (GtkAppChooserButton *self,
  * Returns the text to display at the top of the dialog.
  *
  * Returns: (nullable): the text to display at the top of the dialog,
- *     or %NULL, in which case a default text is displayed
+ *   or %NULL, in which case a default text is displayed
  */
 const char *
 gtk_app_chooser_button_get_heading (GtkAppChooserButton *self)
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index b4350eec51..6eef3b1ded 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -911,12 +911,12 @@ gtk_application_get_menubar (GtkApplication *application)
 /**
  * GtkApplicationInhibitFlags:
  * @GTK_APPLICATION_INHIBIT_LOGOUT: Inhibit ending the user session
- *     by logging out or by shutting down the computer
+ *   by logging out or by shutting down the computer
  * @GTK_APPLICATION_INHIBIT_SWITCH: Inhibit user switching
  * @GTK_APPLICATION_INHIBIT_SUSPEND: Inhibit suspending the
- *     session or computer
+ *   session or computer
  * @GTK_APPLICATION_INHIBIT_IDLE: Inhibit the session being
- *     marked as idle (and possibly locked)
+ *   marked as idle (and possibly locked)
  *
  * Types of user actions that may be blocked by `GtkApplication`.
  *
@@ -1043,9 +1043,9 @@ gtk_application_list_action_descriptions (GtkApplication *application)
  * gtk_application_set_accels_for_action:
  * @application: a `GtkApplication`
  * @detailed_action_name: a detailed action name, specifying an action
- *     and target to associate accelerators with
+ *   and target to associate accelerators with
  * @accels: (array zero-terminated=1): a list of accelerators in the format
- *     understood by [func@Gtk.accelerator_parse]
+ *   understood by [func@Gtk.accelerator_parse]
  *
  * Sets zero or more keyboard accelerators that will trigger the
  * given action.
@@ -1195,7 +1195,7 @@ gtk_application_handle_window_map (GtkApplication *application,
  * for more information.
  *
  * Returns: (nullable) (transfer none): Gets the menu with the
- *     given id from the automatically loaded resources
+ *   given id from the automatically loaded resources
  */
 GMenu *
 gtk_application_get_menu_by_id (GtkApplication *application,
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index f0dad3c3b0..020eecda6f 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -1443,8 +1443,8 @@ gtk_assistant_new (void)
  * Returns the page number of the current page.
  *
  * Returns: The index (starting from 0) of the current
- *     page in the @assistant, or -1 if the @assistant has no pages,
- *     or no current page.
+ *   page in the @assistant, or -1 if the @assistant has no pages,
+ *   or no current page
  */
 int
 gtk_assistant_get_current_page (GtkAssistant *assistant)
@@ -1461,9 +1461,9 @@ gtk_assistant_get_current_page (GtkAssistant *assistant)
  * gtk_assistant_set_current_page:
  * @assistant: a `GtkAssistant`
  * @page_num: index of the page to switch to, starting from 0.
- *     If negative, the last page will be used. If greater
- *     than the number of pages in the @assistant, nothing
- *     will be done.
+ *   If negative, the last page will be used. If greater
+ *   than the number of pages in the @assistant, nothing
+ *   will be done.
  *
  * Switches the page to @page_num.
  *
@@ -1583,12 +1583,12 @@ gtk_assistant_get_n_pages (GtkAssistant *assistant)
  * gtk_assistant_get_nth_page:
  * @assistant: a `GtkAssistant`
  * @page_num: the index of a page in the @assistant,
- *     or -1 to get the last page
+ *   or -1 to get the last page
  *
  * Returns the child widget contained in page number @page_num.
  *
  * Returns: (nullable) (transfer none): the child widget, or %NULL
- *     if @page_num is out of bounds
+ *   if @page_num is out of bounds
  */
 GtkWidget*
 gtk_assistant_get_nth_page (GtkAssistant *assistant,
@@ -1656,7 +1656,7 @@ gtk_assistant_append_page (GtkAssistant *assistant,
  * @assistant: a `GtkAssistant`
  * @page: a `GtkWidget`
  * @position: the index (starting at 0) at which to insert the page,
- *     or -1 to append the page to the @assistant
+ *   or -1 to append the page to the @assistant
  *
  * Inserts a page in the @assistant at a given position.
  *
@@ -1753,7 +1753,7 @@ gtk_assistant_add_page (GtkAssistant *assistant,
  * gtk_assistant_remove_page:
  * @assistant: a `GtkAssistant`
  * @page_num: the index of a page in the @assistant,
- *     or -1 to remove the last page
+ *   or -1 to remove the last page
  *
  * Removes the @page_num’s page from @assistant.
  */
@@ -1777,7 +1777,7 @@ gtk_assistant_remove_page (GtkAssistant *assistant,
  * gtk_assistant_set_forward_page_func:
  * @assistant: a `GtkAssistant`
  * @page_func: (allow-none): the `GtkAssistant`PageFunc, or %NULL
- *     to use the default one
+ *   to use the default one
  * @data: user data for @page_func
  * @destroy: destroy notifier for @data
  *
diff --git a/gtk/gtkbitset.c b/gtk/gtkbitset.c
index af55601187..1b42e51096 100644
--- a/gtk/gtkbitset.c
+++ b/gtk/gtkbitset.c
@@ -309,7 +309,7 @@ gtk_bitset_new_range (guint start,
  * Creates a copy of @self.
  *
  * Returns: (transfer full): A new bitset that contains the same
- *     values as @self
+ *   values as @self
  */
 GtkBitset *
 gtk_bitset_copy (const GtkBitset *self)
@@ -346,7 +346,7 @@ gtk_bitset_remove_all (GtkBitset *self)
  * Adds @value to @self if it wasn't part of it before.
  *
  * Returns: %TRUE if @value was not part of @self and @self
- *     was changed.
+ *   was changed
  */
 gboolean
 gtk_bitset_add (GtkBitset *self,
@@ -365,7 +365,7 @@ gtk_bitset_add (GtkBitset *self,
  * Removes @value from @self if it was part of it before.
  *
  * Returns: %TRUE if @value was part of @self and @self
- *     was changed.
+ *   was changed
  */
 gboolean
 gtk_bitset_remove (GtkBitset *self,
diff --git a/gtk/gtkboolfilter.c b/gtk/gtkboolfilter.c
index 52f917186b..987ec1ff4d 100644
--- a/gtk/gtkboolfilter.c
+++ b/gtk/gtkboolfilter.c
@@ -187,12 +187,11 @@ gtk_bool_filter_init (GtkBoolFilter *self)
 /**
  * gtk_bool_filter_new:
  * @expression: (transfer full) (nullable): The expression to evaluate
- *     or %NULL for none
  *
  * Creates a new bool filter.
  *
  * Returns: a new `GtkBoolFilter`
- **/
+ */
 GtkBoolFilter *
 gtk_bool_filter_new (GtkExpression *expression)
 {
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 5c14b69696..232528ae95 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -197,7 +197,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
  * This is called for each unknown element under <child>.
  *
  * Returns: %TRUE if an object has a custom implementation, %FALSE
- *          if it doesn't.
+ *   if it doesn't.
  */
 gboolean
 gtk_buildable_custom_tag_start (GtkBuildable       *buildable,
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index e06fda638a..a69d1f45c1 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -1781,8 +1781,7 @@ gtk_builder_get_current_object (GtkBuilder *builder)
 /**
  * gtk_builder_set_current_object: (attributes org.gtk.Method.set_property=current-object)
  * @builder: a `GtkBuilder`
- * @current_object: (nullable) (transfer none): the new current object or
- *     %NULL for none
+ * @current_object: (nullable) (transfer none): the new current object
  *
  * Sets the current object for the @builder.
  *
@@ -1830,12 +1829,11 @@ gtk_builder_get_scope (GtkBuilder *builder)
 /**
  * gtk_builder_set_scope: (attributes org.gtk.Method.set_property=scope)
  * @builder: a `GtkBuilder`
- * @scope: (nullable) (transfer none): the scope to use or
- *     %NULL for the default
+ * @scope: (nullable) (transfer none): the scope to use
  *
  * Sets the scope the builder should operate in.
  *
- * If @scope is %NULL a new [class@Gtk.BuilderCScope] will be created.
+ * If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created.
  */
 void
 gtk_builder_set_scope (GtkBuilder      *builder,
diff --git a/gtk/gtkbuilder.h b/gtk/gtkbuilder.h
index b230136781..ed0043c8a8 100644
--- a/gtk/gtkbuilder.h
+++ b/gtk/gtkbuilder.h
@@ -65,8 +65,8 @@ typedef struct _GtkBuilderClass   GtkBuilderClass;
  * @GTK_BUILDER_ERROR_INVALID_SIGNAL: The specified signal is unknown for the object class.
  * @GTK_BUILDER_ERROR_INVALID_ID: An object id is unknown.
  * @GTK_BUILDER_ERROR_INVALID_FUNCTION: A function could not be found. This often happens
- *     when symbols are set to be kept private. Compiling code with -rdynamic or using the
- *     `gmodule-export-2.0` pkgconfig module can fix this problem.
+ *   when symbols are set to be kept private. Compiling code with -rdynamic or using the
+ *   `gmodule-export-2.0` pkgconfig module can fix this problem.
  *
  * Error codes that identify various errors that can occur while using
  * #GtkBuilder.
diff --git a/gtk/gtkbuilderlistitemfactory.c b/gtk/gtkbuilderlistitemfactory.c
index ffb0945785..0c30d0082f 100644
--- a/gtk/gtkbuilderlistitemfactory.c
+++ b/gtk/gtkbuilderlistitemfactory.c
@@ -370,8 +370,7 @@ gtk_builder_list_item_factory_get_bytes (GtkBuilderListItemFactory *self)
  *
  * If the data references a resource, gets the path of that resource.
  *
- * Returns: (transfer none) (nullable): The path to the resource or %NULL
- *     if none
+ * Returns: (transfer none) (nullable): The path to the resource
  */
 const char *
 gtk_builder_list_item_factory_get_resource (GtkBuilderListItemFactory *self)
diff --git a/gtk/gtkbuilderscope.h b/gtk/gtkbuilderscope.h
index 4ca48e2611..fc5d9de14b 100644
--- a/gtk/gtkbuilderscope.h
+++ b/gtk/gtkbuilderscope.h
@@ -52,20 +52,20 @@ typedef enum { /*< prefix=GTK_BUILDER_CLOSURE >*/
 /**
  * GtkBuilderScopeInterface:
  * @get_type_from_name: Try to lookup a #GType via the its name. See
- *     gtk_builder_get_type_from_name() for more details.  
- *     The C implementation will use g_type_from_name() and if that fails try to guess the
- *     correct function name for registering the type and then use dlsym() to load it.  
- *     The default implementation just tries g_type_from_name() and otherwise fails.
+ *   gtk_builder_get_type_from_name() for more details.
+ *   The C implementation will use g_type_from_name() and if that fails try to guess the
+ *   correct function name for registering the type and then use dlsym() to load it.
+ *   The default implementation just tries g_type_from_name() and otherwise fails.
  * @get_type_from_function: Try to lookup a #GType via the given function name, specified
- *     explicitly in a GtkBuilder file, like via the "type-func" attribute in the "<object>" tag.
- *     This function is very rarely used.  
- *     The C implementation will use dlsym() and call the resulting function as a #GTypeFunc.
- *     The default implementation will fail and just return %G_TYPE_INVALID.
+ *   explicitly in a GtkBuilder file, like via the "type-func" attribute in the "<object>" tag.
+ *   This function is very rarely used.
+ *   The C implementation will use dlsym() and call the resulting function as a #GTypeFunc.
+ *   The default implementation will fail and just return %G_TYPE_INVALID.
  * @create_closure: Create a closure with the given arguments. See gtk_builder_create_closure()
- *     for more details on those.  
- *     The C implementation will try to use dlsym() to locate the function name and then 
- *     g_cclosure_new() to create a closure for the symbol.
- *     The default implementation just fails and returns %NULL.
+ *   for more details on those.
+ *   The C implementation will try to use dlsym() to locate the function name and then
+ *   g_cclosure_new() to create a closure for the symbol.
+ *   The default implementation just fails and returns %NULL.
  *
  * The virtual function table to implement for #GtkBuilderScope implementations.
  * Default implementations for each function do exist, but they usually just fail,
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 1acc35d569..de6306ab64 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -665,7 +665,7 @@ gtk_button_new_from_icon_name (const char *icon_name)
 /**
  * gtk_button_new_with_mnemonic:
  * @label: The text of the button, with an underscore in front of the
- *         mnemonic character
+ *   mnemonic character
  *
  * Creates a new `GtkButton` containing a label.
  *
diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 93f1793078..a4360e1a78 100644
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -1613,8 +1613,7 @@ gtk_calendar_unmark_day (GtkCalendar *calendar,
  *
  * The returned date is in the local time zone.
  *
- * Returns: (transfer full): the `GDate` representing
- *     the shown date.
+ * Returns: (transfer full): the `GDate` representing the shown date
  */
 GDateTime *
 gtk_calendar_get_date (GtkCalendar *self)
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 549dc8ec1d..a4190f7957 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -101,7 +101,7 @@
  * exceedingly large amount of rows. The #GtkCellLayout widget in
  * that case would calculate the required width of the rows in an
  * idle or timeout source (see g_timeout_add()) and when the widget
- * is requested its actual width in #GtkWidgetClass.measure()
+ * is requested its actual width in [vfunc@Gtk.Widget.measure]
  * it can simply consult the width accumulated so far in the
  * #GtkCellAreaContext object.
  *
@@ -177,7 +177,7 @@
  * synchronously. The reasoning here is that any layouting widget is
  * at least capable of synchronously calculating enough height to fill
  * the screen height (or scrolled window height) in response to a single
- * call to #GtkWidgetClass.measure(). Returning
+ * call to [vfunc@Gtk.Widget.measure]. Returning
  * a perfect height for width that is larger than the screen area is
  * inconsequential since after the layouting receives an allocation
  * from a scrolled window it simply continues to drive the scrollbar
@@ -188,7 +188,7 @@
  *
  * Once area sizes have been acquired at least for the rows in the
  * visible area of the layouting widget they can be rendered at
- * #GtkWidgetClass.snapshot() time.
+ * [vfunc@Gtk.Widget.snapshot] time.
  *
  * A crude example of how to render all the rows at the root level
  * runs as follows:
@@ -245,14 +245,14 @@
  * area to paint the focus at render time.
  *
  * Layouting widgets that accept focus on cells should implement the
- * #GtkWidgetClass.focus() virtual method. The layouting widget is always
+ * [vfunc@Gtk.Widget.focus] virtual method. The layouting widget is always
  * responsible for knowing where #GtkTreeModel rows are rendered inside
- * the widget, so at #GtkWidgetClass.focus() time the layouting widget
+ * the widget, so at [vfunc@Gtk.Widget.focus] time the layouting widget
  * should use the #GtkCellArea methods to navigate focus inside the area
  * and then observe the GtkDirectionType to pass the focus to adjacent
  * rows and areas.
  *
- * A basic example of how the #GtkWidgetClass.focus() virtual method
+ * A basic example of how the [vfunc@Gtk.Widget.focus] virtual method
  * should be implemented:
  *
  * |[<!-- language="C" -->
diff --git a/gtk/gtkcellarea.h b/gtk/gtkcellarea.h
index b97baa8ced..0046f6e3e4 100644
--- a/gtk/gtkcellarea.h
+++ b/gtk/gtkcellarea.h
@@ -46,7 +46,7 @@ typedef struct _GtkCellAreaContext       GtkCellAreaContext;
 /**
  * GTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID:
  * @object: the #GObject on which set_cell_property() or get_cell_property()
- *     was called
+ *   was called
  * @property_id: the numeric id of the property
  * @pspec: the #GParamSpec of the property
  *
@@ -73,9 +73,9 @@ typedef gboolean    (*GtkCellCallback) (GtkCellRenderer  *renderer,
  * GtkCellAllocCallback:
  * @renderer: the cell renderer to operate on
  * @cell_area: the area allocated to @renderer inside the rectangle
- *     provided to gtk_cell_area_foreach_alloc().
+ *   provided to gtk_cell_area_foreach_alloc().
  * @cell_background: the background area for @renderer inside the
- *     background area provided to gtk_cell_area_foreach_alloc().
+ *   background area provided to gtk_cell_area_foreach_alloc().
  * @data: (closure): user-supplied data
  *
  * The type of the callback functions used for iterating over the
@@ -102,70 +102,70 @@ struct _GtkCellArea
  * @add: adds a #GtkCellRenderer to the area.
  * @remove: removes a #GtkCellRenderer from the area.
  * @foreach: calls the #GtkCellCallback function on every #GtkCellRenderer in
- *     the area with the provided user data until the callback returns %TRUE.
+ *   the area with the provided user data until the callback returns %TRUE.
  * @foreach_alloc: Calls the #GtkCellAllocCallback function on every
- *     #GtkCellRenderer in the area with the allocated area for the cell
- *     and the provided user data until the callback returns %TRUE.
+ *   #GtkCellRenderer in the area with the allocated area for the cell
+ *   and the provided user data until the callback returns %TRUE.
  * @event: Handle an event in the area, this is generally used to activate
- *     a cell at the event location for button events but can also be used
- *     to generically pass events to #GtkWidgets drawn onto the area.
+ *   a cell at the event location for button events but can also be used
+ *   to generically pass events to #GtkWidgets drawn onto the area.
  * @snapshot: Actually snapshot the area’s cells to the specified rectangle,
- *     @background_area should be correctly distributed to the cells
- *     corresponding background areas.
+ *   @background_area should be correctly distributed to the cells
+ *   corresponding background areas.
  * @apply_attributes: Apply the cell attributes to the cells. This is
- *     implemented as a signal and generally #GtkCellArea subclasses don't
- *     need to implement it since it is handled by the base class.
+ *   implemented as a signal and generally #GtkCellArea subclasses don't
+ *   need to implement it since it is handled by the base class.
  * @create_context: Creates and returns a class specific #GtkCellAreaContext
- *     to store cell alignment and allocation details for a said #GtkCellArea
- *     class.
+ *   to store cell alignment and allocation details for a said #GtkCellArea
+ *   class.
  * @copy_context: Creates a new #GtkCellAreaContext in the same state as
- *     the passed @context with any cell alignment data and allocations intact.
+ *   the passed @context with any cell alignment data and allocations intact.
  * @get_request_mode: This allows an area to tell its layouting widget whether
- *     it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or
- *     %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
+ *   it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or
+ *   %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
  * @get_preferred_width: Calculates the minimum and natural width of the
- *     areas cells with the current attributes applied while considering
- *     the particular layouting details of the said #GtkCellArea. While
- *     requests are performed over a series of rows, alignments and overall
- *     minimum and natural sizes should be stored in the corresponding
- *     #GtkCellAreaContext.
+ *   areas cells with the current attributes applied while considering
+ *   the particular layouting details of the said #GtkCellArea. While
+ *   requests are performed over a series of rows, alignments and overall
+ *   minimum and natural sizes should be stored in the corresponding
+ *   #GtkCellAreaContext.
  * @get_preferred_height_for_width: Calculates the minimum and natural height
- *     for the area if the passed @context would be allocated the given width.
- *     When implementing this virtual method it is safe to assume that @context
- *     has already stored the aligned cell widths for every #GtkTreeModel row
- *     that @context will be allocated for since this information was stored
- *     at #GtkCellAreaClass.get_preferred_width() time. This virtual method
- *     should also store any necessary alignments of cell heights for the
- *     case that the context is allocated a height.
+ *   for the area if the passed @context would be allocated the given width.
+ *   When implementing this virtual method it is safe to assume that @context
+ *   has already stored the aligned cell widths for every #GtkTreeModel row
+ *   that @context will be allocated for since this information was stored
+ *   at #GtkCellAreaClass.get_preferred_width() time. This virtual method
+ *   should also store any necessary alignments of cell heights for the
+ *   case that the context is allocated a height.
  * @get_preferred_height: Calculates the minimum and natural height of the
- *     areas cells with the current attributes applied. Essentially this is
- *     the same as #GtkCellAreaClass.get_preferred_width() only for areas
- *     that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT.
+ *   areas cells with the current attributes applied. Essentially this is
+ *   the same as #GtkCellAreaClass.get_preferred_width() only for areas
+ *   that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT.
  * @get_preferred_width_for_height: Calculates the minimum and natural width
- *     for the area if the passed @context would be allocated the given
- *     height. The same as #GtkCellAreaClass.get_preferred_height_for_width()
- *     only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT
- *     mode.
+ *   for the area if the passed @context would be allocated the given
+ *   height. The same as #GtkCellAreaClass.get_preferred_height_for_width()
+ *   only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT
+ *   mode.
  * @set_cell_property: This should be implemented to handle changes in child
- *     cell properties for a given #GtkCellRenderer that were previously
- *     installed on the #GtkCellAreaClass with gtk_cell_area_class_install_cell_property().
+ *   cell properties for a given #GtkCellRenderer that were previously
+ *   installed on the #GtkCellAreaClass with gtk_cell_area_class_install_cell_property().
  * @get_cell_property: This should be implemented to report the values of
- *     child cell properties for a given child #GtkCellRenderer.
+ *   child cell properties for a given child #GtkCellRenderer.
  * @focus: This virtual method should be implemented to navigate focus from
- *     cell to cell inside the #GtkCellArea. The #GtkCellArea should move
- *     focus from cell to cell inside the area and return %FALSE if focus
- *     logically leaves the area with the following exceptions: When the
- *     area contains no activatable cells, the entire area receives focus.
- *     Focus should not be given to cells that are actually “focus siblings”
- *     of other sibling cells (see gtk_cell_area_get_focus_from_sibling()).
- *     Focus is set by calling gtk_cell_area_set_focus_cell().
+ *   cell to cell inside the #GtkCellArea. The #GtkCellArea should move
+ *   focus from cell to cell inside the area and return %FALSE if focus
+ *   logically leaves the area with the following exceptions: When the
+ *   area contains no activatable cells, the entire area receives focus.
+ *   Focus should not be given to cells that are actually “focus siblings”
+ *   of other sibling cells (see gtk_cell_area_get_focus_from_sibling()).
+ *   Focus is set by calling gtk_cell_area_set_focus_cell().
  * @is_activatable: Returns whether the #GtkCellArea can respond to
- *     #GtkCellAreaClass.activate(), usually this does not need to be
- *     implemented since the base class takes care of this however it can
- *     be enhanced if the #GtkCellArea subclass can handle activation in
- *     other ways than activating its #GtkCellRenderers.
+ *   #GtkCellAreaClass.activate(), usually this does not need to be
+ *   implemented since the base class takes care of this however it can
+ *   be enhanced if the #GtkCellArea subclass can handle activation in
+ *   other ways than activating its #GtkCellRenderers.
  * @activate: This is called when the layouting widget rendering the
- *     #GtkCellArea activates the focus cell (see gtk_cell_area_get_focus_cell()).
+ *   #GtkCellArea activates the focus cell (see gtk_cell_area_get_focus_cell()).
  */
 struct _GtkCellAreaClass
 {
diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c
index f2ce80b3f5..4bb6836d40 100644
--- a/gtk/gtkcellareacontext.c
+++ b/gtk/gtkcellareacontext.c
@@ -367,9 +367,9 @@ gtk_cell_area_context_reset (GtkCellAreaContext *context)
  * gtk_cell_area_context_allocate:
  * @context: a #GtkCellAreaContext
  * @width: the allocated width for all #GtkTreeModel rows rendered
- *     with @context, or -1.
+ *   with @context, or -1
  * @height: the allocated height for all #GtkTreeModel rows rendered
- *     with @context, or -1.
+ *   with @context, or -1
  *
  * Allocates a width and/or a height for all rows which are to be
  * rendered with @context.
@@ -395,10 +395,8 @@ gtk_cell_area_context_allocate (GtkCellAreaContext *context,
 /**
  * gtk_cell_area_context_get_preferred_width:
  * @context: a #GtkCellAreaContext
- * @minimum_width: (out) (allow-none): location to store the minimum width,
- *     or %NULL
- * @natural_width: (out) (allow-none): location to store the natural width,
- *     or %NULL
+ * @minimum_width: (out) (allow-none): location to store the minimum width
+ * @natural_width: (out) (allow-none): location to store the natural width
  *
  * Gets the accumulative preferred width for all rows which have been
  * requested with this context.
@@ -425,10 +423,8 @@ gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context,
 /**
  * gtk_cell_area_context_get_preferred_height:
  * @context: a #GtkCellAreaContext
- * @minimum_height: (out) (allow-none): location to store the minimum height,
- *     or %NULL
- * @natural_height: (out) (allow-none): location to store the natural height,
- *     or %NULL
+ * @minimum_height: (out) (allow-none): location to store the minimum height
+ * @natural_height: (out) (allow-none): location to store the natural height
  *
  * Gets the accumulative preferred height for all rows which have been
  * requested with this context.
@@ -456,10 +452,8 @@ gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context,
  * gtk_cell_area_context_get_preferred_height_for_width:
  * @context: a #GtkCellAreaContext
  * @width: a proposed width for allocation
- * @minimum_height: (out) (allow-none): location to store the minimum height,
- *     or %NULL
- * @natural_height: (out) (allow-none): location to store the natural height,
- *     or %NULL
+ * @minimum_height: (out) (allow-none): location to store the minimum height
+ * @natural_height: (out) (allow-none): location to store the natural height
  *
  * Gets the accumulative preferred height for @width for all rows
  * which have been requested for the same said @width with this context.
@@ -486,10 +480,8 @@ gtk_cell_area_context_get_preferred_height_for_width (GtkCellAreaContext *contex
  * gtk_cell_area_context_get_preferred_width_for_height:
  * @context: a #GtkCellAreaContext
  * @height: a proposed height for allocation
- * @minimum_width: (out) (allow-none): location to store the minimum width,
- *     or %NULL
- * @natural_width: (out) (allow-none): location to store the natural width,
- *     or %NULL
+ * @minimum_width: (out) (allow-none): location to store the minimum width
+ * @natural_width: (out) (allow-none): location to store the natural width
  *
  * Gets the accumulative preferred width for @height for all rows which
  * have been requested for the same said @height with this context.
diff --git a/gtk/gtkcellareacontext.h b/gtk/gtkcellareacontext.h
index 6a856613cb..db852cc23e 100644
--- a/gtk/gtkcellareacontext.h
+++ b/gtk/gtkcellareacontext.h
@@ -49,15 +49,15 @@ struct _GtkCellAreaContext
 /**
  * GtkCellAreaContextClass:
  * @allocate: This tells the context that an allocation width or height
- *     (or both) have been decided for a group of rows. The context should
- *     store any allocations for internally aligned cells at this point so
- *     that they dont need to be recalculated at gtk_cell_area_render() time.
+ *   (or both) have been decided for a group of rows. The context should
+ *   store any allocations for internally aligned cells at this point so
+ *   that they dont need to be recalculated at gtk_cell_area_render() time.
  * @reset: Clear any previously stored information about requested and
- *     allocated sizes for the context.
+ *   allocated sizes for the context.
  * @get_preferred_height_for_width: Returns the aligned height for the given
- *     width that context must store while collecting sizes for it’s rows.
+ *   width that context must store while collecting sizes for it’s rows.
  * @get_preferred_width_for_height: Returns the aligned width for the given
- *     height that context must store while collecting sizes for it’s rows.
+ *   height that context must store while collecting sizes for it’s rows.
  */
 struct _GtkCellAreaContextClass
 {
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index d5274f41d8..c04ffdcf23 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -562,9 +562,9 @@ gtk_cell_layout_reorder (GtkCellLayout   *cell_layout,
  * Returns the cell renderers which have been added to @cell_layout.
  *
  * Returns: (element-type GtkCellRenderer) (transfer container):
- *     a list of cell renderers. The list, but not the renderers has
- *     been newly allocated and should be freed with g_list_free()
- *     when no longer needed.
+ *   a list of cell renderers. The list, but not the renderers has
+ *   been newly allocated and should be freed with g_list_free()
+ *   when no longer needed.
  */
 GList *
 gtk_cell_layout_get_cells (GtkCellLayout *cell_layout)
diff --git a/gtk/gtkcolorchooser.c b/gtk/gtkcolorchooser.c
index 27e74d3581..af9d742d99 100644
--- a/gtk/gtkcolorchooser.c
+++ b/gtk/gtkcolorchooser.c
@@ -155,7 +155,7 @@ gtk_color_chooser_set_rgba (GtkColorChooser *chooser,
  * Returns whether the color chooser shows the alpha channel.
  *
  * Returns: %TRUE if the color chooser uses the alpha channel,
- *     %FALSE if not
+ *   %FALSE if not
  */
 gboolean
 gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser)
@@ -190,7 +190,7 @@ gtk_color_chooser_set_use_alpha (GtkColorChooser *chooser,
  * gtk_color_chooser_add_palette:
  * @chooser: a `GtkColorChooser`
  * @orientation: %GTK_ORIENTATION_HORIZONTAL if the palette should
- *     be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns
+ *   be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns
  * @colors_per_line: the number of colors to show in each row/column
  * @n_colors: the total number of elements in @colors
  * @colors: (allow-none) (array length=n_colors): the colors of the palette, or %NULL
diff --git a/gtk/gtkcolumnview.c b/gtk/gtkcolumnview.c
index d166055659..51f0c4c94e 100644
--- a/gtk/gtkcolumnview.c
+++ b/gtk/gtkcolumnview.c
@@ -1500,7 +1500,7 @@ gtk_column_view_get_show_column_separators (GtkColumnView *self)
  * gtk_column_view_append_column:
  * @self: a `GtkColumnView`
  * @column: a `GtkColumnViewColumn` that hasn't been added to a
- *     `GtkColumnView` yet
+ *   `GtkColumnView` yet
  *
  * Appends the @column to the end of the columns in @self.
  */
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 177bd4bcd7..3fb5b8f070 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -1908,7 +1908,7 @@ gtk_combo_box_new_with_model_and_entry (GtkTreeModel *model)
  * [struct@Gtk.TreePath] of the active item.
  *
  * Returns: An integer which is the index of the currently active item,
- *     or -1 if there’s no active item.
+ *   or -1 if there’s no active item
  */
 int
 gtk_combo_box_get_active (GtkComboBox *combo_box)
@@ -2154,7 +2154,7 @@ out:
  * Returns the `GtkTreeModel` of @combo_box.
  *
  * Returns: (nullable) (transfer none): A `GtkTreeModel` which was passed
- *     during construction.
+ *   during construction.
  */
 GtkTreeModel *
 gtk_combo_box_get_model (GtkComboBox *combo_box)
diff --git a/gtk/gtkconstraintguide.c b/gtk/gtkconstraintguide.c
index 100741ae73..cab27e4568 100644
--- a/gtk/gtkconstraintguide.c
+++ b/gtk/gtkconstraintguide.c
@@ -500,10 +500,8 @@ gtk_constraint_guide_set_min_size (GtkConstraintGuide *guide,
 /**
  * gtk_constraint_guide_get_min_size:
  * @guide: a `GtkConstraintGuide` object
- * @width: (allow-none): return location for the minimum width,
- *     or %NULL
- * @height: (allow-none): return location for the minimum height,
- *     or %NULL
+ * @width: (allow-none): return location for the minimum width
+ * @height: (allow-none): return location for the minimum height
  *
  * Gets the minimum size of @guide.
  */
@@ -554,10 +552,8 @@ gtk_constraint_guide_set_nat_size (GtkConstraintGuide *guide,
 /**
  * gtk_constraint_guide_get_nat_size:
  * @guide: a `GtkConstraintGuide` object
- * @width: (allow-none): return location for the natural width,
- *     or %NULL
- * @height: (allow-none): return location for the natural height,
- *     or %NULL
+ * @width: (allow-none): return location for the natural width
+ * @height: (allow-none): return location for the natural height
  *
  * Gets the natural size of @guide.
  */
@@ -608,10 +604,8 @@ gtk_constraint_guide_set_max_size (GtkConstraintGuide *guide,
 /**
  * gtk_constraint_guide_get_max_size:
  * @guide: a `GtkConstraintGuide` object
- * @width: (allow-none): return location for the maximum width,
- *     or %NULL
- * @height: (allow-none): return location for the maximum height,
- *     or %NULL
+ * @width: (allow-none): return location for the maximum width
+ * @height: (allow-none): return location for the maximum height
  *
  * Gets the maximum size of @guide.
  */
diff --git a/gtk/gtkcountingbloomfilterprivate.h b/gtk/gtkcountingbloomfilterprivate.h
index 1918891030..9d7078a587 100644
--- a/gtk/gtkcountingbloomfilterprivate.h
+++ b/gtk/gtkcountingbloomfilterprivate.h
@@ -43,7 +43,7 @@ G_BEGIN_DECLS
  * be considered useful.
  *
  * See: [Bloom filter](https://en.wikipedia.org/wiki/Bloom_filter),
- *      [Counting Bloom filter](https://en.wikipedia.org/wiki/Counting_Bloom_filter)
+ *   [Counting Bloom filter](https://en.wikipedia.org/wiki/Counting_Bloom_filter)
  */
 
 /* The number of bits from the hash we care about */
diff --git a/gtk/gtkcssnumbervalue.c b/gtk/gtkcssnumbervalue.c
index cd384ff1da..dacf9c4476 100644
--- a/gtk/gtkcssnumbervalue.c
+++ b/gtk/gtkcssnumbervalue.c
@@ -474,7 +474,7 @@ gtk_css_dimension_value_new (double     value,
  * match.
  *
  * Returns: Magic value determining placement when printing calc()
- *     expression.
+ *   expression.
  */
 static int
 gtk_css_number_value_get_calc_term_order (const GtkCssValue *value)
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index 91e5f6240f..a5f7b77577 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -1321,7 +1321,7 @@ _gtk_css_find_theme (const char *name,
  * @provider: a `GtkCssProvider`
  * @name: A theme name
  * @variant: (allow-none): variant to load, for example, "dark", or
- *     %NULL for the default
+ *   %NULL for the default
  *
  * Loads a theme from the usual theme paths.
  *
diff --git a/gtk/gtkcssselector.c b/gtk/gtkcssselector.c
index b92556ad6f..158110c2d1 100644
--- a/gtk/gtkcssselector.c
+++ b/gtk/gtkcssselector.c
@@ -33,10 +33,10 @@
 /*
  * @GTK_CSS_SELECTOR_CATEGORY_SIMPLE: A simple selector
  * @GTK_CSS_SELECTOR_CATEGORY_SIMPLE_RADICAL: A simple selector that matches
- *     what change tracking considers a "radical change"
+ *   what change tracking considers a "radical change"
  * @GTK_CSS_SELECTOR_SIBLING: A selector matching siblings
  * @GTK_CSS_SELECTOR_CATEGORY_PARENT: A selector matching a parent or other
- *     ancestor
+ *   ancestor
  *
  * Categorize the selectors. This helps in various loops when matching.
  */
diff --git a/gtk/gtkcssvalue.c b/gtk/gtkcssvalue.c
index b0c32c8e82..fc79819ee1 100644
--- a/gtk/gtkcssvalue.c
+++ b/gtk/gtkcssvalue.c
@@ -348,8 +348,8 @@ gtk_css_value_is_dynamic (const GtkCssValue *value)
  * See gtk_css_value_is_dynamic() for details about dynamic values.
  *
  * Returns: (transfer full): The dynamic value for @value at the given
- *     timestamp
- **/
+ *   timestamp
+ */
 GtkCssValue *
 gtk_css_value_get_dynamic_value (GtkCssValue *value,
                                  gint64       monotonic_time)
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 53b13c68fd..a606513dc9 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -1058,7 +1058,7 @@ gtk_dialog_response (GtkDialog *dialog,
  * of a dialog.
  *
  * Returns: (nullable) (transfer none): the @widget button that uses the given
- *     @response_id, or %NULL.
+ *   @response_id
  */
 GtkWidget*
 gtk_dialog_get_widget_for_response (GtkDialog *dialog,
diff --git a/gtk/gtkdialog.h b/gtk/gtkdialog.h
index b23c42ba13..4530d518e8 100644
--- a/gtk/gtkdialog.h
+++ b/gtk/gtkdialog.h
@@ -38,7 +38,7 @@ G_BEGIN_DECLS
  * @GTK_DIALOG_MODAL: Make the constructed dialog modal
  * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its parent is destroyed
  * @GTK_DIALOG_USE_HEADER_BAR: Create dialog with actions in header
- *     bar instead of action area
+ *   bar instead of action area
  *
  * Flags used to influence dialog construction.
  */
@@ -52,7 +52,7 @@ typedef enum
 /**
  * GtkResponseType:
  * @GTK_RESPONSE_NONE: Returned if an action widget has no response id,
- *     or if the dialog gets programmatically hidden or destroyed
+ *   or if the dialog gets programmatically hidden or destroyed
  * @GTK_RESPONSE_REJECT: Generic response id, not used by GTK dialogs
  * @GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK dialogs
  * @GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted
diff --git a/gtk/gtkdirectorylist.c b/gtk/gtkdirectorylist.c
index 5f2c8f3753..3792f1856d 100644
--- a/gtk/gtkdirectorylist.c
+++ b/gtk/gtkdirectorylist.c
@@ -831,7 +831,7 @@ gtk_directory_list_is_loading (GtkDirectoryList *self)
  * successfully queried files will remain in the list.
  *
  * Returns: (nullable) (transfer none): The loading error or %NULL if
- *     loading finished successfully.
+ *   loading finished successfully
  */
 const GError *
 gtk_directory_list_get_error (GtkDirectoryList *self)
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index bd4e5f5f3b..987bd4735c 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -454,7 +454,7 @@ gtk_drawing_area_get_content_height (GtkDrawingArea *self)
  * gtk_drawing_area_set_draw_func:
  * @self: a `GtkDrawingArea`
  * @draw_func: (allow-none): callback that lets you draw
- *     the drawing area's contents
+ *   the drawing area's contents
  * @user_data: (closure): user data passed to @draw_func
  * @destroy: destroy notifier for @user_data
  *
diff --git a/gtk/gtkdropdown.c b/gtk/gtkdropdown.c
index c896f469a1..c96d14328c 100644
--- a/gtk/gtkdropdown.c
+++ b/gtk/gtkdropdown.c
@@ -889,7 +889,7 @@ gtk_drop_down_set_selected (GtkDropDown *self,
  * Gets the position of the selected item.
  *
  * Returns: the position of the selected item, or %GTK_INVALID_LIST_POSITION
- *     if not item is selected
+ *   if not item is selected
  */
 guint
 gtk_drop_down_get_selected (GtkDropDown *self)
diff --git a/gtk/gtkdroptargetasync.c b/gtk/gtkdroptargetasync.c
index e9f443cf1d..b8f360d1da 100644
--- a/gtk/gtkdroptargetasync.c
+++ b/gtk/gtkdroptargetasync.c
@@ -566,8 +566,7 @@ gtk_drop_target_async_new (GdkContentFormats *formats,
 /**
  * gtk_drop_target_async_set_formats: (attributes org.gtk.Method.set_property=formats)
  * @self: a `GtkDropTargetAsync`
- * @formats: (nullable): the supported data formats or %NULL for
- *     any format.
+ * @formats: (nullable): the supported data formats or %NULL for any format
  *
  * Sets the data formats that this drop target will accept.
  */
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index f822921277..ebdebabdf7 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -805,7 +805,7 @@ gtk_editable_get_alignment (GtkEditable *editable)
  * gtk_editable_set_alignment: (attributes org.gtk.Method.set_property=xalign)
  * @editable: a `GtkEditable`
  * @xalign: The horizontal alignment, from 0 (left) to 1 (right).
- *          Reversed for RTL layouts
+ *   Reversed for RTL layouts
  *
  * Sets the alignment for the contents of the editable.
  *
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index e5a4de8255..00f9f52399 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -2119,8 +2119,7 @@ gtk_entry_set_buffer (GtkEntry       *entry,
 /**
  * gtk_entry_set_visibility: (attributes org.gtk.Method.set_property=visibility)
  * @entry: a `GtkEntry`
- * @visible: %TRUE if the contents of the entry are displayed
- *           as plaintext
+ * @visible: %TRUE if the contents of the entry are displayed as plaintext
  *
  * Sets whether the contents of the entry are visible or not.
  *
diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index 6b34eb564d..97bedaf554 100644
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -927,8 +927,8 @@ gtk_entry_completion_set_model (GtkEntryCompletion *completion,
  *
  * Returns %NULL if the model is unset.
  *
- * Returns: (nullable) (transfer none): A #GtkTreeModel, or %NULL if none
- *     is currently being used
+ * Returns: (nullable) (transfer none): A `GtkTreeModel`, or %NULL if none
+ *   is currently being used
  */
 GtkTreeModel *
 gtk_entry_completion_get_model (GtkEntryCompletion *completion)
@@ -1567,8 +1567,7 @@ gtk_entry_completion_get_popup_set_width (GtkEntryCompletion *completion)
 /**
  * gtk_entry_completion_set_popup_single_match: (attributes org.gtk.Method.set_property=popup-single-match)
  * @completion: a `GtkEntryCompletion`
- * @popup_single_match: %TRUE if the popup should appear even for a single
- *     match
+ * @popup_single_match: %TRUE if the popup should appear even for a single match
  *
  * Sets whether the completion popup window will appear even if there is
  * only a single match.
diff --git a/gtk/gtkentrycompletion.h b/gtk/gtkentrycompletion.h
index 540afc0d1c..de5024363f 100644
--- a/gtk/gtkentrycompletion.h
+++ b/gtk/gtkentrycompletion.h
@@ -53,7 +53,7 @@ typedef struct _GtkEntryCompletion            GtkEntryCompletion;
  * `gtk_editable_get_text (GTK_EDITABLE (gtk_entry_completion_get_entry ()))`.
  *
  * Returns: %TRUE if @iter should be displayed as a possible completion
- *     for @key
+ *   for @key
  */
 typedef gboolean (* GtkEntryCompletionMatchFunc) (GtkEntryCompletion *completion,
                                                   const char         *key,
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index da20f7a87a..60dc3e431d 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -37,15 +37,12 @@ G_BEGIN_DECLS
 /**
  * GtkAlign:
  * @GTK_ALIGN_FILL: stretch to fill all space if possible, center if
- *     no meaningful way to stretch
- * @GTK_ALIGN_START: snap to left or top side, leaving space on right
- *     or bottom
- * @GTK_ALIGN_END: snap to right or bottom side, leaving space on left
- *     or top
- * @GTK_ALIGN_CENTER: center natural width of widget inside the
- *     allocation
- * @GTK_ALIGN_BASELINE: align the widget according to the baseline. See
- *     #GtkWidget
+ *   no meaningful way to stretch
+ * @GTK_ALIGN_START: snap to left or top side, leaving space on right or bottom
+ * @GTK_ALIGN_END: snap to right or bottom side, leaving space on left or top
+ * @GTK_ALIGN_CENTER: center natural width of widget inside the allocation
+ * @GTK_ALIGN_BASELINE: align the widget according to the baseline.
+ *   See [class@Gtk.Widget].
  *
  * Controls how a widget deals with extra space in a single dimension.
  *
@@ -327,9 +324,9 @@ typedef enum
 /**
  * GtkOverflow:
  * @GTK_OVERFLOW_VISIBLE: No change is applied. Content is drawn at the specified
- *     position.
+ *   position.
  * @GTK_OVERFLOW_HIDDEN: Content is clipped to the bounds of the area. Content
- *     outside the area is not drawn and cannot be interacted with.
+ *   outside the area is not drawn and cannot be interacted with.
  *
  * Defines how content overflowing a given area should be handled.
  *
@@ -424,15 +421,15 @@ typedef enum
  * @GTK_SELECTION_NONE: No selection is possible.
  * @GTK_SELECTION_SINGLE: Zero or one element may be selected.
  * @GTK_SELECTION_BROWSE: Exactly one element is selected.
- *     In some circumstances, such as initially or during a search
- *     operation, it’s possible for no element to be selected with
- *     %GTK_SELECTION_BROWSE. What is really enforced is that the user
- *     can’t deselect a currently selected element except by selecting
- *     another element.
+ *   In some circumstances, such as initially or during a search
+ *   operation, it’s possible for no element to be selected with
+ *   %GTK_SELECTION_BROWSE. What is really enforced is that the user
+ *   can’t deselect a currently selected element except by selecting
+ *   another element.
  * @GTK_SELECTION_MULTIPLE: Any number of elements may be selected.
- *      The Ctrl key may be used to enlarge the selection, and Shift
- *      key to select between the focus and the child pointed to.
- *      Some widgets may also allow Click-drag to select a range of elements.
+ *   The Ctrl key may be used to enlarge the selection, and Shift
+ *   key to select between the focus and the child pointed to.
+ *   Some widgets may also allow Click-drag to select a range of elements.
  *
  * Used to control what selections users are allowed to make.
  */
@@ -450,11 +447,11 @@ typedef enum
  * GtkWrapMode:
  * @GTK_WRAP_NONE: do not wrap lines; just make the text area wider
  * @GTK_WRAP_CHAR: wrap text, breaking lines anywhere the cursor can
- *     appear (between characters, usually - if you want to be technical,
- *     between graphemes, see pango_get_log_attrs())
+ *   appear (between characters, usually - if you want to be technical,
+ *   between graphemes, see pango_get_log_attrs())
  * @GTK_WRAP_WORD: wrap text, breaking lines in between words
  * @GTK_WRAP_WORD_CHAR: wrap text, breaking lines in between words, or if
- *     that is not enough, also between graphemes
+ *   that is not enough, also between graphemes
  *
  * Describes a type of line wrapping.
  */
@@ -861,11 +858,11 @@ typedef enum
  * @GTK_INPUT_HINT_LOWERCASE: Suggest to convert all text to lowercase
  * @GTK_INPUT_HINT_UPPERCASE_CHARS: Suggest to capitalize all text
  * @GTK_INPUT_HINT_UPPERCASE_WORDS: Suggest to capitalize the first
- *     character of each word
+ *   character of each word
  * @GTK_INPUT_HINT_UPPERCASE_SENTENCES: Suggest to capitalize the
- *     first word of each sentence
+ *   first word of each sentence
  * @GTK_INPUT_HINT_INHIBIT_OSK: Suggest to not show an onscreen keyboard
- *     (e.g for a calculator that already has all the keys).
+ *   (e.g for a calculator that already has all the keys).
  * @GTK_INPUT_HINT_VERTICAL_WRITING: The text is vertical
  * @GTK_INPUT_HINT_EMOJI: Suggest offering Emoji support
  * @GTK_INPUT_HINT_NO_EMOJI: Suggest not offering Emoji support
@@ -977,11 +974,11 @@ typedef enum
 /**
  * GtkShortcutScope:
  * @GTK_SHORTCUT_SCOPE_LOCAL: Shortcuts are handled inside
- *     the widget the controller belongs to.
+ *   the widget the controller belongs to.
  * @GTK_SHORTCUT_SCOPE_MANAGED: Shortcuts are handled by
- *     the first ancestor that is a #GtkShortcutManager
+ *   the first ancestor that is a #GtkShortcutManager
  * @GTK_SHORTCUT_SCOPE_GLOBAL: Shortcuts are handled by
- *     the root widget.
+ *   the root widget.
  *
  * Describes where `GtkShortcut`s added to a
  * `GtkShortcutController` get handled.
@@ -1103,18 +1100,20 @@ typedef enum {
 
 /**
  * GtkSystemSetting:
- * @GTK_SYSTEM_SETTING_DPI: the #GtkSettings:gtk-xft-dpi setting has changed
- * @GTK_SYSTEM_SETTING_FONT_NAME: The #GtkSettings:gtk-font-name setting has changed
+ * @GTK_SYSTEM_SETTING_DPI: the [property@Gtk.Settings:gtk-xft-dpi] setting has changed
+ * @GTK_SYSTEM_SETTING_FONT_NAME: The [property@Gtk.Settings:gtk-font-name] setting has changed
  * @GTK_SYSTEM_SETTING_FONT_CONFIG: The font configuration has changed in a way that
- *     requires text to be redrawn. This can be any of the
- *     #GtkSettings:gtk-xft-antialias, #GtkSettings:gtk-xft-hinting,
- *     #GtkSettings:gtk-xft-hintstyle, #GtkSettings:gtk-xft-rgba or
- *     #GtkSettings:gtk-fontconfig-timestamp settings
+ *   requires text to be redrawn. This can be any of the
+ *   [property@Gtk.Settings:gtk-xft-antialias],
+ *   [property@Gtk.Settings:gtk-xft-hinting],
+ *   [property@Gtk.Settings:gtk-xft-hintstyle],
+ *   [property@Gtk.Settings:gtk-xft-rgba] or
+ *   [property@Gtk.Settings:gtk-fontconfig-timestamp] settings
  * @GTK_SYSTEM_SETTING_DISPLAY: The display has changed
  * @GTK_SYSTEM_SETTING_ICON_THEME: The icon theme has changed in a way that requires
- *     icons to be looked up again
+ *   icons to be looked up again
  *
- * Values that can be passed to the GtkWidgetClass.system_setting_changed
+ * Values that can be passed to the [vfunc@Gtk.Widget.system_setting_changed]
  * vfunc.
  *
  * The values indicate which system setting has changed.
diff --git a/gtk/gtkeventcontrollerprivate.h b/gtk/gtkeventcontrollerprivate.h
index e639e2d82a..50349cc366 100644
--- a/gtk/gtkeventcontrollerprivate.h
+++ b/gtk/gtkeventcontrollerprivate.h
@@ -59,12 +59,12 @@ typedef struct _GtkCrossingData GtkCrossingData;
  * @mode: the crossing mode
  * @old_target: the old target
  * @old_descendent: the direct child of the receiving widget that
- *     is an ancestor of @old_target, or %NULL if @old_target is not
- *     a descendent of the receiving widget
+ *   is an ancestor of @old_target, or %NULL if @old_target is not
+ *   a descendent of the receiving widget
  * @new_target: the new target
  * @new_descendent: the direct child of the receiving widget that
- *     is an ancestor of @new_target, or %NULL if @new_target is not
- *     a descendent of the receiving widget
+ *   is an ancestor of @new_target, or %NULL if @new_target is not
+ *   a descendent of the receiving widget
  * @drop: the #GdkDrop if this is info for a drop operation
  *
  * The struct that is passed to gtk_event_controller_handle_crossing().
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index cce9876cca..f7370261e3 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -844,7 +844,7 @@ gtk_expander_new (const char *label)
 /**
  * gtk_expander_new_with_mnemonic:
  * @label: (nullable): the text of the label with an underscore
- *     in front of the mnemonic character
+ *   in front of the mnemonic character
  *
  * Creates a new expander using @label as the text of the label.
  *
@@ -985,7 +985,7 @@ gtk_expander_set_label (GtkExpander *expander,
  * container.
  *
  * Returns: (nullable): The text of the label widget. This string is owned
- *     by the widget and must not be modified or freed.
+ *   by the widget and must not be modified or freed.
  */
 const char *
 gtk_expander_get_label (GtkExpander *expander)
@@ -1031,7 +1031,7 @@ gtk_expander_set_use_underline (GtkExpander *expander,
  * Returns whether an underline in the text indicates a mnemonic.
  *
  * Returns: %TRUE if an embedded underline in the expander
- *     label indicates the mnemonic accelerator keys
+ *   label indicates the mnemonic accelerator keys
  */
 gboolean
 gtk_expander_get_use_underline (GtkExpander *expander)
@@ -1135,7 +1135,7 @@ gtk_expander_set_label_widget (GtkExpander *expander,
  * Retrieves the label widget for the frame.
  *
  * Returns: (nullable) (transfer none): the label widget,
- *     or %NULL if there is none
+ *   or %NULL if there is none
  */
 GtkWidget *
 gtk_expander_get_label_widget (GtkExpander *expander)
diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c
index d8e75cddc9..17a511ff4f 100644
--- a/gtk/gtkexpression.c
+++ b/gtk/gtkexpression.c
@@ -1867,9 +1867,8 @@ gtk_expression_watch_cb (gpointer data)
  * gtk_expression_watch:
  * @self: a `GtkExpression`
  * @this_: (transfer none) (type GObject) (nullable): the `this` argument to
- *     watch
- * @notify: (closure user_data): callback to invoke when the
- *     expression changes
+ *   watch
+ * @notify: (closure user_data): callback to invoke when the expression changes
  * @user_data: user data to pass to the `notify` callback
  * @user_destroy: destroy notify for `user_data`
  *
@@ -2104,7 +2103,7 @@ gtk_expression_bind_notify (gpointer data)
  * @target: (transfer none) (type GObject): the target object to bind to
  * @property: name of the property on `target` to bind to
  * @this_: (transfer none) (type GObject) (nullable): the this argument for
- *     the evaluation of `self`
+ *   the evaluation of `self`
  *
  * Bind `target`'s property named `property` to `self`.
  *
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index 51799ceac4..23a91ba07e 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -1479,9 +1479,8 @@ _gtk_file_system_model_set_show_folders (GtkFileSystemModel *model,
 /**
  * _gtk_file_system_model_set_show_files:
  * @model: a #GtkFileSystemModel
- * @show_files: whether files (as opposed to folders) should
- *              be displayed.
- * 
+ * @show_files: whether files (as opposed to folders) should be displayed.
+ *
  * Sets whether files (as opposed to folders) should be included
  * in the #GtkTreeModel for display.
  **/
@@ -1662,7 +1661,7 @@ _gtk_file_system_model_get_file (GtkFileSystemModel *model,
  * lookups. Both of which are slow.
  *
  * Returns: a pointer to the actual value as stored in @model or %NULL
- *          if no value available yet.
+ *   if no value available yet
  **/
 const GValue *
 _gtk_file_system_model_get_value (GtkFileSystemModel *model,
diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c
index 27c4d1bfe7..ca6e0e9463 100644
--- a/gtk/gtkfilter.c
+++ b/gtk/gtkfilter.c
@@ -122,7 +122,7 @@ gtk_filter_init (GtkFilter *self)
  * Checks if the given @item is matched by the filter or not.
  *
  * Returns: %TRUE if the filter matches the item and a filter model should
- *     keep it, %FALSE if not.
+ *   keep it, %FALSE if not.
  */
 gboolean
 gtk_filter_match (GtkFilter *self,
diff --git a/gtk/gtkfilter.h b/gtk/gtkfilter.h
index a370f20e3e..3bfb4971e0 100644
--- a/gtk/gtkfilter.h
+++ b/gtk/gtkfilter.h
@@ -31,11 +31,11 @@ G_BEGIN_DECLS
 /**
  * GtkFilterMatch:
  * @GTK_FILTER_MATCH_SOME: The filter matches some items,
- *     gtk_filter_match() may return %TRUE or %FALSE
+ *   gtk_filter_match() may return %TRUE or %FALSE
  * @GTK_FILTER_MATCH_NONE: The filter does not match any item,
- *     gtk_filter_match() will always return %FALSE.
+ *   gtk_filter_match() will always return %FALSE.
  * @GTK_FILTER_MATCH_ALL: The filter matches all items,
- *     gtk_filter_match() will alays return %TRUE.
+ *   gtk_filter_match() will alays return %TRUE.
  *
  * Describes the known strictness of a filter.
  *
@@ -52,13 +52,13 @@ typedef enum {
 /**
  * GtkFilterChange:
  * @GTK_FILTER_CHANGE_DIFFERENT: The filter change cannot be
- *     described with any of the other enumeration values.
+ *   described with any of the other enumeration values.
  * @GTK_FILTER_CHANGE_LESS_STRICT: The filter is less strict than
- *     it was before: All items that it used to return %TRUE for
- *     still return %TRUE, others now may, too.
+ *   it was before: All items that it used to return %TRUE for
+ *   still return %TRUE, others now may, too.
  * @GTK_FILTER_CHANGE_MORE_STRICT: The filter is more strict than
- *     it was before: All items that it used to return %FALSE for
- *     still return %FALSE, others now may, too.
+ *   it was before: All items that it used to return %FALSE for
+ *   still return %FALSE, others now may, too.
  *
  * Describes changes in a filter in more detail and allows objects
  * using the filter to optimize refiltering items.
diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 7717ecfc35..030d97ad6a 100644
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -679,7 +679,6 @@ gtk_filter_list_model_set_filter (GtkFilterListModel *self,
  * Gets the `GtkFilter` currently set on @self.
  *
  * Returns: (nullable) (transfer none): The filter currently in use
- *     or %NULL if the list isn't filtered
  */
 GtkFilter *
 gtk_filter_list_model_get_filter (GtkFilterListModel *self)
diff --git a/gtk/gtkflowbox.c b/gtk/gtkflowbox.c
index e05397f2e5..b85824cea0 100644
--- a/gtk/gtkflowbox.c
+++ b/gtk/gtkflowbox.c
@@ -632,7 +632,7 @@ gtk_flow_box_child_get_child (GtkFlowBoxChild *self)
  * Gets the current index of the @child in its `GtkFlowBox` container.
  *
  * Returns: the index of the @child, or -1 if the @child is not
- *     in a flow box.
+ *   in a flow box
  */
 int
 gtk_flow_box_child_get_index (GtkFlowBoxChild *child)
@@ -4135,8 +4135,8 @@ gtk_flow_box_insert (GtkFlowBox *box,
  * Gets the nth child in the @box.
  *
  * Returns: (transfer none) (nullable): the child widget, which will
- *     always be a `GtkFlowBoxChild` or %NULL in case no child widget
- *     with the given index exists.
+ *   always be a `GtkFlowBoxChild` or %NULL in case no child widget
+ *   with the given index exists.
  */
 GtkFlowBoxChild *
 gtk_flow_box_get_child_at_index (GtkFlowBox *box,
@@ -4557,7 +4557,7 @@ gtk_flow_box_set_activate_on_single_click (GtkFlowBox *box,
  * Returns whether children activate on single clicks.
  *
  * Returns: %TRUE if children are activated on single click,
- *     %FALSE otherwise
+ *   %FALSE otherwise
  */
 gboolean
 gtk_flow_box_get_activate_on_single_click (GtkFlowBox *box)
@@ -4587,8 +4587,8 @@ gtk_flow_box_set_accept_unpaired_release (GtkFlowBox *box,
  * Creates a list of all selected children.
  *
  * Returns: (element-type GtkFlowBoxChild) (transfer container):
- *     A `GList` containing the `GtkWidget` for each selected child.
- *     Free with g_list_free() when done.
+ *   A `GList` containing the `GtkWidget` for each selected child.
+ *   Free with g_list_free() when done.
  */
 GList *
 gtk_flow_box_get_selected_children (GtkFlowBox *box)
@@ -4806,7 +4806,7 @@ gtk_flow_box_get_selection_mode (GtkFlowBox *box)
  * gtk_flow_box_set_filter_func:
  * @box: a `GtkFlowBox`
  * @filter_func: (allow-none): callback that
- *     lets you filter which children to show
+ *   lets you filter which children to show
  * @user_data: (closure): user data passed to @filter_func
  * @destroy: destroy notifier for @user_data
  *
@@ -4881,7 +4881,7 @@ gtk_flow_box_invalidate_filter (GtkFlowBox *box)
  * should come first.
  *
  * Returns: < 0 if @child1 should be before @child2, 0 if
- *     the are equal, and > 0 otherwise
+ *   the are equal, and > 0 otherwise
  */
 
 /**
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index b92741d04d..229eb4c70f 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -581,7 +581,7 @@ gtk_grid_attach (GtkGrid   *grid,
  * @grid: a `GtkGrid`
  * @child: the widget to add
  * @sibling: (allow-none): the child of @grid that @child will be placed
- *     next to, or %NULL to place @child at the beginning or end
+ *   next to, or %NULL to place @child at the beginning or end
  * @side: the side of @sibling that @child is positioned next to
  * @width: the number of columns that @child will span
  * @height: the number of rows that @child will span
@@ -919,7 +919,7 @@ gtk_grid_remove_column (GtkGrid *grid,
  * gtk_grid_insert_next_to:
  * @grid: a `GtkGrid`
  * @sibling: the child of @grid that the new row or column will be
- *     placed next to
+ *   placed next to
  * @side: the side of @sibling that @child is positioned next to
  *
  * Inserts a row or column at the specified position.
diff --git a/gtk/gtkgridview.c b/gtk/gtkgridview.c
index 8a8b2f1346..e722881d6d 100644
--- a/gtk/gtkgridview.c
+++ b/gtk/gtkgridview.c
@@ -201,14 +201,14 @@ cell_augment (GtkRbTree *tree,
  * @self: a `GtkGridView`
  * @y: an offset in direction of @self's orientation
  * @position: (out caller-allocates) (optional): stores the position
- *     index of the returned row
+ *   index of the returned row
  * @offset: (out caller-allocates) (optional): stores the offset
- *     in pixels between y and top of cell.
+ *   in pixels between y and top of cell.
  * @offset: (out caller-allocates) (optional): stores the height
- *     of the cell
+ *   of the cell
  *
  * Gets the Cell that occupies the leftmost position in the row at offset
- * @y into the primary direction. 
+ * @y into the primary direction.
  *
  * If y is larger than the height of all cells, %NULL will be returned.
  * In particular that means that for an empty grid, %NULL is returned
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index dfc1b70d99..6cfe5cf1b0 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -770,7 +770,7 @@ gtk_header_bar_set_show_title_buttons (GtkHeaderBar *bar,
  * gtk_header_bar_set_decoration_layout: (attributes org.gtk.Method.set_property=decoration-layout)
  * @bar: a `GtkHeaderBar`
  * @layout: (allow-none): a decoration layout, or %NULL to
- *     unset the layout
+ *   unset the layout
  *
  * Sets the decoration layout for this header bar.
  *
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 45623c44d4..f1a7bf0034 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -1537,7 +1537,7 @@ gtk_icon_theme_add_search_path (GtkIconTheme *self,
  * gtk_icon_theme_set_resource_path:
  * @self: a `GtkIconTheme`
  * @path: NULL-terminated array of resource paths
- *     that are searched for icons
+ *   that are searched for icons
  *
  * Sets the resource paths that will be looked at when
  * looking for icons, similar to search paths.
@@ -2464,7 +2464,7 @@ load_icon_thread (GTask        *task,
  * GtkWidgetClass.css-changed() function.
  *
  * Returns: (transfer full): a `GtkIconPaintable` object
- *     containing the icon.
+ *   containing the icon.
  */
 GtkIconPaintable *
 gtk_icon_theme_lookup_icon (GtkIconTheme       *self,
@@ -3967,13 +3967,13 @@ icon_paintable_snapshot (GdkPaintable *paintable,
  * @width: width to snapshot in
  * @height: height to snapshot in
  * @foreground_color: (allow-none): a `GdkRGBA` representing the foreground color
- *      of the icon or %NULL to use the default color.
+ *   of the icon or %NULL to use the default color.
  * @success_color: (allow-none): a `GdkRGBA` representing the warning color
- *     of the icon or %NULL to use the default color
+ *   of the icon or %NULL to use the default color
  * @warning_color: (allow-none): a `GdkRGBA` representing the warning color
- *     of the icon or %NULL to use the default color
+ *   of the icon or %NULL to use the default color
  * @error_color: (allow-none): a `GdkRGBA` representing the error color
- *     of the icon or %NULL to use the default color (allow-none)
+ *   of the icon or %NULL to use the default color
  *
  * Snapshots the `GtkIconPaintable`.
  *
@@ -4079,7 +4079,7 @@ icon_paintable_init (GdkPaintableInterface *iface)
  * The icon can then be rendered by using it as a `GdkPaintable`.
  *
  * Returns: (transfer full): a `GtkIconPaintable` containing
- *     for the icon. Unref with g_object_unref()
+ *   for the icon. Unref with g_object_unref()
  */
 GtkIconPaintable *
 gtk_icon_paintable_new_for_file (GFile *file,
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 1d7cb97fcf..a07879a0b2 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -2010,9 +2010,9 @@ gtk_icon_view_set_cursor (GtkIconView     *icon_view,
  * gtk_icon_view_get_cursor:
  * @icon_view: A #GtkIconView
  * @path: (out) (allow-none) (transfer full): Return location for the current
- *        cursor path, or %NULL
+ *   cursor path
  * @cell: (out) (allow-none) (transfer none): Return location the current
- *        focus cell, or %NULL
+ *   focus cell
  *
  * Fills in @path and @cell with the current cursor path and cell. 
  * If the cursor isn’t currently set, then *@path will be %NULL.  
@@ -4257,10 +4257,9 @@ gtk_icon_view_set_tooltip_cell (GtkIconView     *icon_view,
  * @x: the x coordinate (relative to widget coordinates)
  * @y: the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
- * @model: (out) (allow-none) (transfer none): a pointer to receive a
- *         #GtkTreeModel or %NULL
- * @path: (out) (allow-none): a pointer to receive a #GtkTreePath or %NULL
- * @iter: (out) (allow-none): a pointer to receive a #GtkTreeIter or %NULL
+ * @model: (out) (allow-none) (transfer none): a pointer to receive a `GtkTreeModel`
+ * @path: (out) (allow-none): a pointer to receive a `GtkTreePath`
+ * @iter: (out) (allow-none): a pointer to receive a `GtkTreeIter`
  *
  * This function is supposed to be used in a #GtkWidget::query-tooltip
  * signal handler for #GtkIconView.  The @x, @y and @keyboard_tip values
@@ -4421,17 +4420,16 @@ gtk_icon_view_get_tooltip_column (GtkIconView *icon_view)
 /**
  * gtk_icon_view_get_visible_range:
  * @icon_view: A #GtkIconView
- * @start_path: (out) (allow-none): Return location for start of region,
- *              or %NULL
- * @end_path: (out) (allow-none): Return location for end of region, or %NULL
- * 
- * Sets @start_path and @end_path to be the first and last visible path. 
+ * @start_path: (out) (allow-none): Return location for start of region
+ * @end_path: (out) (allow-none): Return location for end of region
+ *
+ * Sets @start_path and @end_path to be the first and last visible path.
  * Note that there may be invisible paths in between.
- * 
+ *
  * Both paths should be freed with gtk_tree_path_free() after use.
- * 
+ *
  * Returns: %TRUE, if valid paths were placed in @start_path and @end_path
- **/
+ */
 gboolean
 gtk_icon_view_get_visible_range (GtkIconView  *icon_view,
 				 GtkTreePath **start_path,
@@ -4667,9 +4665,8 @@ gtk_icon_view_set_model (GtkIconView *icon_view,
  * Returns the model the #GtkIconView is based on.  Returns %NULL if the
  * model is unset.
  *
- * Returns: (nullable) (transfer none): A #GtkTreeModel, or %NULL if none is
- *     currently being used.
- **/
+ * Returns: (nullable) (transfer none): The currently used `GtkTreeModel`
+ */
 GtkTreeModel *
 gtk_icon_view_get_model (GtkIconView *icon_view)
 {
@@ -6429,11 +6426,11 @@ gtk_icon_view_set_drag_dest_item (GtkIconView              *icon_view,
  * gtk_icon_view_get_drag_dest_item:
  * @icon_view: a #GtkIconView
  * @path: (out) (allow-none): Return location for the path of
- *        the highlighted item, or %NULL.
- * @pos: (out) (allow-none): Return location for the drop position, or %NULL
- * 
+ *   the highlighted item
+ * @pos: (out) (allow-none): Return location for the drop position
+ *
  * Gets information about the item that is highlighted for feedback.
- **/
+ */
 void
 gtk_icon_view_get_drag_dest_item (GtkIconView              *icon_view,
 				  GtkTreePath             **path,
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 46b418ab73..12c1d414f5 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -436,9 +436,9 @@ gtk_im_context_real_get_surrounding_with_selection (GtkIMContext *context,
 /**
  * gtk_im_context_set_client_widget:
  * @context: a `GtkIMContext`
- * @widget: (allow-none):  the client widget. This may be %NULL to indicate
- *           that the previous client widget no longer exists.
- * 
+ * @widget: (allow-none): the client widget. This may be %NULL to indicate
+ *   that the previous client widget no longer exists.
+ *
  * Set the client widget for the input context.
  *
  * This is the `GtkWidget` holding the input focus. This widget is
@@ -460,14 +460,14 @@ gtk_im_context_set_client_widget (GtkIMContext *context,
 
 /**
  * gtk_im_context_get_preedit_string:
- * @context:    a `GtkIMContext`
- * @str:        (out) (transfer full): location to store the retrieved
- *              string. The string retrieved must be freed with g_free().
- * @attrs:      (out) (transfer full): location to store the retrieved
- *              attribute list.  When you are done with this list, you
- *              must unreference it with pango_attr_list_unref().
+ * @context: a `GtkIMContext`
+ * @str: (out) (transfer full): location to store the retrieved
+ *   string. The string retrieved must be freed with g_free().
+ * @attrs: (out) (transfer full): location to store the retrieved
+ *   attribute list. When you are done with this list, you
+ *   must unreference it with pango_attr_list_unref().
  * @cursor_pos: (out): location to store position of cursor (in characters)
- *              within the preedit string.
+ *   within the preedit string.
  *
  * Retrieve the current preedit string for the input context,
  * and a list of attributes to apply to the string.
@@ -717,8 +717,7 @@ gtk_im_context_set_use_preedit (GtkIMContext *context,
  * gtk_im_context_set_surrounding:
  * @context: a `GtkIMContext`
  * @text: text surrounding the insertion point, as UTF-8.
- *        the preedit string should not be included within
- *        @text.
+ *   the preedit string should not be included within @text
  * @len: the length of @text, or -1 if @text is nul-terminated
  * @cursor_index: the byte index of the insertion cursor within @text.
  *
@@ -744,8 +743,7 @@ gtk_im_context_set_surrounding (GtkIMContext  *context,
  * gtk_im_context_set_surrounding_with_selection:
  * @context: a #GtkIMContext
  * @text: text surrounding the insertion point, as UTF-8.
- *        the preedit string should not be included within
- *        @text.
+ *   the preedit string should not be included within @text
  * @len: the length of @text, or -1 if @text is nul-terminated
  * @cursor_index: the byte index of the insertion cursor within @text
  * @anchor_index: the byte index of the selection bound within @text
diff --git a/gtk/gtkimmodule.c b/gtk/gtkimmodule.c
index c5fd3479d3..d252d2fce3 100644
--- a/gtk/gtkimmodule.c
+++ b/gtk/gtkimmodule.c
@@ -78,7 +78,7 @@
  * ID @context_id.
  *
  * Returns: a newly created input context of or @context_id, or
- *     if that could not be created, a newly created GtkIMContextSimple.
+ *   if that could not be created, a newly created `GtkIMContextSimple`
  */
 GtkIMContext *
 _gtk_im_module_create (const char *context_id)
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index 214be6e8d7..fc317dfafe 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -666,7 +666,7 @@ add_buttons_valist (GtkInfoBar  *info_bar,
  * @info_bar: a `GtkInfoBar`
  * @first_button_text: button text
  * @...: response ID for first button, then more text-response_id pairs,
- *     ending with %NULL
+ *   ending with %NULL
  *
  * Adds multiple buttons.
  *
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 3b9c52d60e..625e5f7a75 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -2668,7 +2668,7 @@ gtk_label_new (const char *str)
 /**
  * gtk_label_new_with_mnemonic:
  * @str: (nullable): The text of the label, with an underscore in front of the
- *       mnemonic character
+ *   mnemonic character
  *
  * Creates a new `GtkLabel`, containing the text in @str.
  *
@@ -2872,7 +2872,7 @@ gtk_label_set_mnemonic_widget (GtkLabel  *self,
  * See [method@Gtk.Label.set_mnemonic_widget].
  *
  * Returns: (nullable) (transfer none): the target of the label’s mnemonic,
- *     or %NULL if none has been set and the default algorithm will be used.
+ *   or %NULL if none has been set and the default algorithm will be used.
  **/
 GtkWidget *
 gtk_label_get_mnemonic_widget (GtkLabel *self)
@@ -3090,7 +3090,7 @@ gtk_label_set_attributes (GtkLabel         *self,
  * `pango_layout_get_attribute (gtk_label_get_layout (self))`.
  *
  * Returns: (nullable) (transfer none): the attribute list, or %NULL
- *     if none was set.
+ *   if none was set.
  */
 PangoAttrList *
 gtk_label_get_attributes (GtkLabel *self)
diff --git a/gtk/gtklevelbar.c b/gtk/gtklevelbar.c
index 1208297b2c..a87f14b84a 100644
--- a/gtk/gtklevelbar.c
+++ b/gtk/gtklevelbar.c
@@ -1127,7 +1127,7 @@ gtk_level_bar_get_max_value (GtkLevelBar *self)
  * Returns the `value` of the `GtkLevelBar`.
  *
  * Returns: a value in the interval between
- *     `GtkLevelBar`:min-value and `GtkLevelBar`:max-value
+ *   [property@Gtk.LevelBar:min-value[ and [property@Gtk.LevelBar:max-value]
  */
 double
 gtk_level_bar_get_value (GtkLevelBar *self)
@@ -1225,7 +1225,7 @@ gtk_level_bar_set_max_value (GtkLevelBar *self,
  * gtk_level_bar_set_value: (attributes org.gtk.Method.set_property=value)
  * @self: a `GtkLevelBar`
  * @value: a value in the interval between
- *     [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value]
+ *   [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value]
  *
  * Sets the value of the `GtkLevelBar`.
  */
diff --git a/gtk/gtklistbase.c b/gtk/gtklistbase.c
index 5ef58dd4a4..55471a351a 100644
--- a/gtk/gtklistbase.c
+++ b/gtk/gtklistbase.c
@@ -112,7 +112,7 @@ static GParamSpec *properties[N_PROPS] = { NULL, };
  * @along:  position in pixels in the direction of the list
  * @pos: (out caller-allocates): set to the looked up position
  * @area: (out caller-allocates) (allow-none): set to the area occupied
- *     by the returned position.
+ *   by the returned position
  *
  * Given a coordinate in list coordinates, determine the position of the
  * item that occupies that position.
@@ -264,8 +264,7 @@ gtk_list_base_clear_adjustment (GtkListBase    *self,
  * gtk_list_base_move_focus_along:
  * @self: a #GtkListBase
  * @pos: position from which to move focus
- * @steps: steps to move focus - negative numbers
- *     move focus backwards
+ * @steps: steps to move focus - negative numbers move focus backwards
  *
  * Moves focus @steps in the direction of the list.
  * If focus cannot be moved, @pos is returned.
@@ -286,8 +285,7 @@ gtk_list_base_move_focus_along (GtkListBase *self,
  * gtk_list_base_move_focus_across:
  * @self: a #GtkListBase
  * @pos: position from which to move focus
- * @steps: steps to move focus - negative numbers
- *     move focus backwards
+ * @steps: steps to move focus - negative numbers move focus backwards
  *
  * Moves focus @steps in the direction across the list.
  * If focus cannot be moved, @pos is returned.
@@ -327,9 +325,9 @@ gtk_list_base_move_focus (GtkListBase    *self,
  * @self: a #GtkListBase
  * @pos: item to get the size of
  * @offset: (out caller-allocates) (allow-none) set to the offset
- *     of the top/left of the item
+ *   of the top/left of the item
  * @size: (out caller-allocates) (allow-none) set to the size of
- *     the item in the direction
+ *   the item in the direction
  *
  * Computes the allocation of the item in the direction along the sizing
  * axis.
@@ -350,9 +348,9 @@ gtk_list_base_get_allocation_along (GtkListBase *self,
  * @self: a #GtkListBase
  * @pos: item to get the size of
  * @offset: (out caller-allocates) (allow-none) set to the offset
- *     of the top/left of the item
+ *   of the top/left of the item
  * @size: (out caller-allocates) (allow-none) set to the size of
- *     the item in the direction
+ *   the item in the direction
  *
  * Computes the allocation of the item in the direction across to the sizing
  * axis.
@@ -373,11 +371,11 @@ gtk_list_base_get_allocation_across (GtkListBase *self,
  * @self: a #GtkListBase
  * @pos: item to select
  * @modify: %TRUE if the selection should be modified, %FALSE
- *     if a new selection should be done. This is usually set
- *     to %TRUE if the user keeps the <Shift> key pressed.
+ *   if a new selection should be done. This is usually set
+ *   to %TRUE if the user keeps the <Shift> key pressed.
  * @extend_pos: %TRUE if the selection should be extended.
- *     Selections are usually extended from the last selected
- *     position if the user presses the <Ctrl> key.
+ *   Selections are usually extended from the last selected
+ *   position if the user presses the <Ctrl> key.
  *
  * Selects the item at @pos according to how GTK list widgets modify
  * selections, both when clicking rows with the mouse or when using
@@ -1944,11 +1942,9 @@ gtk_list_base_get_anchor (GtkListBase *self)
  * @self: a #GtkListBase
  * @anchor_pos: position of the item to anchor
  * @anchor_align_across: how far in the across direction to anchor
- * @anchor_side_across: if the anchor should side to start or end
- *     of item
+ * @anchor_side_across: if the anchor should side to start or end of item
  * @anchor_align_along: how far in the along direction to anchor
- * @anchor_side_along: if the anchor should side to start or end
- *     of item
+ * @anchor_side_along: if the anchor should side to start or end of item
  *
  * Sets the anchor.
  * The anchor is the item that is always kept on screen.
@@ -2047,9 +2043,9 @@ gtk_list_base_set_anchor_max_widgets (GtkListBase *self,
  * @pos: position of the item to focus
  * @select: %TRUE to select the item
  * @modify: if selecting, %TRUE to modify the selected
- *     state, %FALSE to always select
+ *   state, %FALSE to always select
  * @extend: if selecting, %TRUE to extend the selection,
- *     %FALSE to only operate on this item
+ *   %FALSE to only operate on this item
  *
  * Tries to grab focus on the given item. If there is no item
  * at this position or grabbing focus failed, %FALSE will be
diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c
index 06e2342c59..3b2e2eb0c1 100644
--- a/gtk/gtklistbox.c
+++ b/gtk/gtklistbox.c
@@ -987,8 +987,8 @@ gtk_list_box_selected_foreach (GtkListBox            *box,
  * Creates a list of all selected children.
  *
  * Returns: (element-type GtkListBoxRow) (transfer container):
- *     A `GList` containing the `GtkWidget` for each selected child.
- *     Free with g_list_free() when done.
+ *   A `GList` containing the `GtkWidget` for each selected child.
+ *   Free with g_list_free() when done.
  */
 GList *
 gtk_list_box_get_selected_rows (GtkListBox *box)
diff --git a/gtk/gtklistbox.h b/gtk/gtklistbox.h
index 684395049f..7cd73104ad 100644
--- a/gtk/gtklistbox.h
+++ b/gtk/gtklistbox.h
@@ -91,7 +91,7 @@ typedef gboolean (*GtkListBoxFilterFunc) (GtkListBoxRow *row,
  * Compare two rows to determine which should be first.
  *
  * Returns: < 0 if @row1 should be before @row2, 0 if they are
- *     equal and > 0 otherwise
+ *   equal and > 0 otherwise
  */
 typedef int (*GtkListBoxSortFunc) (GtkListBoxRow *row1,
                                    GtkListBoxRow *row2,
diff --git a/gtk/gtklistitemmanager.c b/gtk/gtklistitemmanager.c
index 3271fe1de4..54e75a6a84 100644
--- a/gtk/gtklistitemmanager.c
+++ b/gtk/gtklistitemmanager.c
@@ -164,7 +164,7 @@ gtk_list_item_manager_get_root (GtkListItemManager *self)
  * represents a row with an existing widget, @offset will always be 0.
  *
  * Returns: (type GtkListItemManagerItem): the item for @position or
- *     %NULL if position is out of range
+ *   %NULL if position is out of range
  **/
 gpointer
 gtk_list_item_manager_get_nth (GtkListItemManager *self,
@@ -900,7 +900,7 @@ gtk_list_item_manager_get_model (GtkListItemManager *self)
  * @self: a #GtkListItemManager
  * @position: the row in the model to create a list item for
  * @prev_sibling: the widget this widget should be inserted before or %NULL
- *     if it should be the first widget
+ *   if it should be the first widget
  *
  * Creates a list item widget to use for @position. No widget may
  * yet exist that is used for @position.
@@ -945,7 +945,7 @@ gtk_list_item_manager_acquire_list_item (GtkListItemManager *self,
  * @self: a #GtkListItemManager
  * @position: the row in the model to create a list item for
  * @prev_sibling: the widget this widget should be inserted after or %NULL
- *     if it should be the first widget
+ *   if it should be the first widget
  *
  * Like gtk_list_item_manager_acquire_list_item(), but only tries to acquire list
  * items from those previously released as part of @change.
@@ -953,7 +953,7 @@ gtk_list_item_manager_acquire_list_item (GtkListItemManager *self,
  * gtk_list_item_manager_acquire_list_item().
  *
  * Returns: (nullable): a properly setup widget to use in @position or %NULL if
- *     no item for reuse existed
+ *   no item for reuse existed
  **/
 static GtkWidget *
 gtk_list_item_manager_try_reacquire_list_item (GtkListItemManager *self,
@@ -993,7 +993,7 @@ gtk_list_item_manager_try_reacquire_list_item (GtkListItemManager *self,
  * gtk_list_item_manager_move_list_item:
  * @self: a #GtkListItemManager
  * @list_item: an acquired #GtkListItem that should be moved to represent
- *     a different row
+ *   a different row
  * @position: the new position of that list item
  * @prev_sibling: the new previous sibling
  *
@@ -1052,9 +1052,9 @@ gtk_list_item_manager_update_list_item (GtkListItemManager *self,
  * gtk_list_item_manager_release_list_item:
  * @self: a #GtkListItemManager
  * @change: (allow-none): The change associated with this release or
- *     %NULL if this is a final removal
+ *   %NULL if this is a final removal
  * @item: an item previously acquired with
- *     gtk_list_item_manager_acquire_list_item()
+ *   gtk_list_item_manager_acquire_list_item()
  *
  * Releases an item that was previously acquired via
  * gtk_list_item_manager_acquire_list_item() and is no longer in use.
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 8485586221..80bffb481a 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -1680,9 +1680,9 @@ gtk_list_store_reorder_func (GSequenceIter *a,
  * gtk_list_store_reorder:
  * @store: A #GtkListStore.
  * @new_order: (array zero-terminated=1): an array of integers mapping the new
- *      position of each child to its old position before the re-ordering,
- *      i.e. @new_order`[newpos] = oldpos`. It must have
- *      exactly as many items as the list store’s length.
+ *   position of each child to its old position before the re-ordering,
+ *   i.e. @new_order`[newpos] = oldpos`. It must have
+ *   exactly as many items as the list store’s length.
  *
  * Reorders @store to follow the order indicated by @new_order. Note that
  * this function only works with unsorted stores.
@@ -2150,7 +2150,7 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
  * @list_store: A #GtkListStore
  * @iter: (out) (optional): An unset #GtkTreeIter to set to the new row
  * @position: position to insert the new row, or -1 to append after existing
- *     rows
+ *    rows
  * @...: pairs of column number and value, terminated with -1
  *
  * Creates a new row at @position. @iter will be changed to point to this new
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 27dea0f007..cf0e347956 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -570,7 +570,7 @@ do_post_parse_initialization (void)
  * interface.
  *
  * Returns: %TRUE if the windowing system has been successfully
- *     initialized, %FALSE otherwise
+ *   initialized, %FALSE otherwise
  */
 gboolean
 gtk_init_check (void)
@@ -772,7 +772,7 @@ gtk_get_locale_direction (void)
  * See that function for details.
  *
  * Returns: (transfer none): the default language as a #PangoLanguage,
- *     must not be freed
+ *   must not be freed
  */
 PangoLanguage *
 gtk_get_default_language (void)
@@ -1789,7 +1789,7 @@ gtk_get_current_event_time (void)
  * originally.
  *
  * Returns: (transfer none) (nullable): the widget that originally
- *     received @event, or %NULL
+ *   received @event, or %NULL
  */
 GtkWidget *
 gtk_get_event_widget (GdkEvent *event)
diff --git a/gtk/gtkmaplistmodel.h b/gtk/gtkmaplistmodel.h
index 85a39823ab..6d9cccdaee 100644
--- a/gtk/gtkmaplistmodel.h
+++ b/gtk/gtkmaplistmodel.h
@@ -47,8 +47,7 @@ G_DECLARE_FINAL_TYPE (GtkMapListModel, gtk_map_list_model, GTK, MAP_LIST_MODEL,
  * The returned items must conform to the item type of the model they are
  * used with.
  *
- * Returns: (type GObject) (transfer full): The item to map to.
- *     This function may not return %NULL
+ * Returns: (type GObject) (transfer full): The item to map to
  */
 typedef gpointer (* GtkMapListModelMapFunc) (gpointer item, gpointer user_data);
 
diff --git a/gtk/gtkmediacontrols.c b/gtk/gtkmediacontrols.c
index 9622d2038d..d48a99285b 100644
--- a/gtk/gtkmediacontrols.c
+++ b/gtk/gtkmediacontrols.c
@@ -306,8 +306,7 @@ gtk_media_controls_init (GtkMediaControls *controls)
 
 /**
  * gtk_media_controls_new:
- * @stream: (allow-none) (transfer none): a #GtkMediaStream to
- *     manage or %NULL for none.
+ * @stream: (allow-none) (transfer none): a `GtkMediaStream` to manage
  *
  * Creates a new `GtkMediaControls` managing the @stream passed to it.
  *
diff --git a/gtk/gtkmenubutton.c b/gtk/gtkmenubutton.c
index 15f06eb23a..6024068c2d 100644
--- a/gtk/gtkmenubutton.c
+++ b/gtk/gtkmenubutton.c
@@ -1030,7 +1030,7 @@ gtk_menu_button_set_use_underline (GtkMenuButton *menu_button,
  * mnemonic.
  *
  * Returns: %TRUE whether an embedded underline in the text indicates
- *     the mnemonic accelerator keys.
+ *   the mnemonic accelerator keys.
  */
 gboolean
 gtk_menu_button_get_use_underline (GtkMenuButton *menu_button)
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index df675d0191..c7dfd33007 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -739,7 +739,7 @@ gtk_message_dialog_format_secondary_markup (GtkMessageDialog *message_dialog,
  * for the corresponding function in the parent [class@Gtk.Dialog].
  *
  * Returns: (transfer none): A `GtkBox` corresponding to the
- *     “message area” in the @message_dialog.
+ *   “message area” in the @message_dialog
  */
 GtkWidget *
 gtk_message_dialog_get_message_area (GtkMessageDialog *message_dialog)
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index aa89cf6067..2b61e49c38 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -5678,12 +5678,12 @@ gtk_notebook_menu_label_unparent (GtkWidget *widget)
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the `GtkWidget` to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  *
  * Appends a page to @notebook.
  *
  * Returns: the index (starting from 0) of the appended
- *     page in the notebook, or -1 if function fails
+ *   page in the notebook, or -1 if function fails
  */
 int
 gtk_notebook_append_page (GtkNotebook *notebook,
@@ -5702,19 +5702,19 @@ gtk_notebook_append_page (GtkNotebook *notebook,
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the `GtkWidget` to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
- *     page-switch menu, if that is enabled. If %NULL, and @tab_label
- *     is a #GtkLabel or %NULL, then the menu label will be a newly
- *     created label with the same text as @tab_label; if @tab_label
- *     is not a `GtkLabel`, @menu_label must be specified if the
- *     page-switch menu is to be used.
+ *   page-switch menu, if that is enabled. If %NULL, and @tab_label
+ *   is a #GtkLabel or %NULL, then the menu label will be a newly
+ *   created label with the same text as @tab_label; if @tab_label
+ *   is not a `GtkLabel`, @menu_label must be specified if the
+ *   page-switch menu is to be used.
  *
  * Appends a page to @notebook, specifying the widget to use as the
  * label in the popup menu.
  *
  * Returns: the index (starting from 0) of the appended
- *     page in the notebook, or -1 if function fails
+ *   page in the notebook, or -1 if function fails
  */
 int
 gtk_notebook_append_page_menu (GtkNotebook *notebook,
@@ -5735,12 +5735,12 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook,
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the #GtkWidget to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  *
  * Prepends a page to @notebook.
  *
  * Returns: the index (starting from 0) of the prepended
- *     page in the notebook, or -1 if function fails
+ *   page in the notebook, or -1 if function fails
  */
 int
 gtk_notebook_prepend_page (GtkNotebook *notebook,
@@ -5759,19 +5759,19 @@ gtk_notebook_prepend_page (GtkNotebook *notebook,
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the `GtkWidget` to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
- *     page-switch menu, if that is enabled. If %NULL, and @tab_label
- *     is a #GtkLabel or %NULL, then the menu label will be a newly
- *     created label with the same text as @tab_label; if @tab_label
- *     is not a #GtkLabel, @menu_label must be specified if the
- *     page-switch menu is to be used.
+ *   page-switch menu, if that is enabled. If %NULL, and @tab_label
+ *   is a #GtkLabel or %NULL, then the menu label will be a newly
+ *   created label with the same text as @tab_label; if @tab_label
+ *   is not a #GtkLabel, @menu_label must be specified if the
+ *   page-switch menu is to be used.
  *
  * Prepends a page to @notebook, specifying the widget to use as the
  * label in the popup menu.
  *
  * Returns: the index (starting from 0) of the prepended
- *     page in the notebook, or -1 if function fails
+ *   page in the notebook, or -1 if function fails
  */
 int
 gtk_notebook_prepend_page_menu (GtkNotebook *notebook,
@@ -5792,14 +5792,14 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook,
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the `GtkWidget` to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  * @position: the index (starting at 0) at which to insert the page,
- *     or -1 to append the page after all other pages
+ *   or -1 to append the page after all other pages
  *
  * Insert a page into @notebook at the given position.
  *
  * Returns: the index (starting from 0) of the inserted
- *     page in the notebook, or -1 if function fails
+ *   page in the notebook, or -1 if function fails
  */
 int
 gtk_notebook_insert_page (GtkNotebook *notebook,
@@ -5849,21 +5849,21 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child,
  * @notebook: a `GtkNotebook`
  * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the `GtkWidget` to be used as the label
- *     for the page, or %NULL to use the default label, “page N”
+ *   for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
- *     page-switch menu, if that is enabled. If %NULL, and @tab_label
- *     is a #GtkLabel or %NULL, then the menu label will be a newly
- *     created label with the same text as @tab_label; if @tab_label
- *     is not a #GtkLabel, @menu_label must be specified if the
- *     page-switch menu is to be used.
+ *   page-switch menu, if that is enabled. If %NULL, and @tab_label
+ *   is a #GtkLabel or %NULL, then the menu label will be a newly
+ *   created label with the same text as @tab_label; if @tab_label
+ *   is not a #GtkLabel, @menu_label must be specified if the
+ *   page-switch menu is to be used.
  * @position: the index (starting at 0) at which to insert the page,
- *     or -1 to append the page after all other pages.
+ *   or -1 to append the page after all other pages.
  *
  * Insert a page into @notebook at the given position, specifying
  * the widget to use as the label in the popup menu.
  *
  * Returns: the index (starting from 0) of the inserted
- *     page in the notebook
+ *   page in the notebook
  */
 int
 gtk_notebook_insert_page_menu (GtkNotebook *notebook,
@@ -5888,7 +5888,7 @@ gtk_notebook_insert_page_menu (GtkNotebook *notebook,
  * gtk_notebook_remove_page:
  * @notebook: a `GtkNotebook`
  * @page_num: the index of a notebook page, starting
- *     from 0. If -1, the last page will be removed.
+ *   from 0. If -1, the last page will be removed.
  *
  * Removes a page from the notebook given its index
  * in the notebook.
@@ -5925,8 +5925,8 @@ gtk_notebook_remove_page (GtkNotebook *notebook,
  * Returns the page number of the current page.
  *
  * Returns: the index (starting from 0) of the current
- *     page in the notebook. If the notebook has no pages,
- *     then -1 will be returned.
+ *   page in the notebook. If the notebook has no pages,
+ *   then -1 will be returned.
  */
 int
 gtk_notebook_get_current_page (GtkNotebook *notebook)
@@ -5943,7 +5943,7 @@ gtk_notebook_get_current_page (GtkNotebook *notebook)
  * gtk_notebook_get_nth_page:
  * @notebook: a `GtkNotebook`
  * @page_num: the index of a page in the notebook, or -1
- *     to get the last page
+ *   to get the last page
  *
  * Returns the child widget contained in page number @page_num.
  *
@@ -5998,7 +5998,7 @@ gtk_notebook_get_n_pages (GtkNotebook *notebook)
  * widget.
  *
  * Returns: the index of the page containing @child, or
- *     -1 if @child is not in the notebook
+ *   -1 if @child is not in the notebook
  */
 int
 gtk_notebook_page_num (GtkNotebook      *notebook,
@@ -6029,9 +6029,9 @@ gtk_notebook_page_num (GtkNotebook      *notebook,
  * gtk_notebook_set_current_page: (attributes org.gtk.Method.set_property=page)
  * @notebook: a `GtkNotebook`
  * @page_num: index of the page to switch to, starting from 0.
- *     If negative, the last page will be used. If greater
- *     than the number of pages in the notebook, nothing
- *     will be done.
+ *   If negative, the last page will be used. If greater
+ *   than the number of pages in the notebook, nothing
+ *   will be done.
  *
  * Switches to the page number @page_num.
  *
@@ -6529,7 +6529,7 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook,
  * @notebook: a `GtkNotebook`
  * @child: the page
  * @tab_label: (allow-none): the tab label widget to use, or %NULL
- *     for default tab label
+ *   for default tab label
  *
  * Changes the tab label for @child.
  *
@@ -6884,7 +6884,7 @@ gtk_notebook_reorder_child (GtkNotebook *notebook,
  * gtk_notebook_set_group_name: (attributes org.gtk.Method.set_property=group-name)
  * @notebook: a `GtkNotebook`
  * @group_name: (allow-none): the name of the notebook group,
- *     or %NULL to unset it
+ *   or %NULL to unset it
  *
  * Sets a group name for @notebook.
  *
diff --git a/gtk/gtkorientable.c b/gtk/gtkorientable.c
index 67496ce38a..c8b2a2f9d7 100644
--- a/gtk/gtkorientable.c
+++ b/gtk/gtkorientable.c
@@ -63,7 +63,7 @@ gtk_orientable_default_init (GtkOrientableInterface *iface)
 /**
  * gtk_orientable_set_orientation: (attributes org.gtk.Method.set_property=orientation)
  * @orientable: a `GtkOrientable`
- * @orientation: the orientable’s new orientation.
+ * @orientation: the orientable’s new orientation
  *
  * Sets the orientation of the @orientable.
  */
@@ -87,7 +87,7 @@ gtk_orientable_set_orientation (GtkOrientable  *orientable,
  *
  * Retrieves the orientation of the @orientable.
  *
- * Returns: the orientation of the @orientable.
+ * Returns: the orientation of the @orientable
  */
 GtkOrientation
 gtk_orientable_get_orientation (GtkOrientable *orientable)
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index 23c7359f37..7466a1b063 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -575,7 +575,7 @@ string_to_enum (GType type,
  * @setup: a `GtkPageSetup`
  * @key_file: the `GKeyFile` to retrieve the page_setup from
  * @group_name: (allow-none): the name of the group in the key_file to read, or %NULL
- *              to use the default name “Page Setup”
+ *   to use the default name “Page Setup”
  * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads the page setup from the group @group_name in the key file
@@ -661,7 +661,7 @@ out:
  * gtk_page_setup_new_from_key_file:
  * @key_file: the `GKeyFile` to retrieve the page_setup from
  * @group_name: (allow-none): the name of the group in the key_file to read, or %NULL
- *              to use the default name “Page Setup”
+ *    to use the default name “Page Setup”
  * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads the page setup from the group @group_name in the key file
@@ -752,7 +752,7 @@ enum_to_string (GType type,
  * @setup: a `GtkPageSetup`
  * @key_file: the `GKeyFile` to save the page setup to
  * @group_name: (nullable): the group to add the settings to in @key_file,
- *      or %NULL to use the default name “Page Setup”
+ *   or %NULL to use the default name “Page Setup”
  *
  * This function adds the page setup from @setup to @key_file.
  */
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index f399449f96..bbef9d0ac5 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -1801,7 +1801,7 @@ gtk_paned_get_position (GtkPaned  *paned)
  * gtk_paned_set_position: (attributes org.gtk.Method.set_property=position)
  * @paned: a `GtkPaned` widget
  * @position: pixel position of divider, a negative value means that the position
- *            is unset.
+ *   is unset
  *
  * Sets the position of the divider between the two panes.
  **/
diff --git a/gtk/gtkpapersize.c b/gtk/gtkpapersize.c
index aa00370391..783065b6d4 100644
--- a/gtk/gtkpapersize.c
+++ b/gtk/gtkpapersize.c
@@ -567,7 +567,7 @@ gtk_paper_size_is_equal (GtkPaperSize *size1,
 /**
  * gtk_paper_size_get_paper_sizes:
  * @include_custom: whether to include custom paper sizes
- *     as defined in the page setup dialog
+ *   as defined in the page setup dialog
  *
  * Creates a list of known paper sizes.
  *
@@ -909,14 +909,14 @@ gtk_paper_size_get_default_right_margin (GtkPaperSize *size,
  * gtk_paper_size_new_from_key_file:
  * @key_file: the `GKeyFile` to retrieve the papersize from
  * @group_name: (nullable): the name of the group in the key file to read,
- *     or %NULL to read the first group
+ *   or %NULL to read the first group
  * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads a paper size from the group @group_name in the key file
  * @key_file.
  *
  * Returns: a new `GtkPaperSize` object with the restored
- *     paper size, or %NULL if an error occurred
+ *   paper size, or %NULL if an error occurred
  */
 GtkPaperSize *
 gtk_paper_size_new_from_key_file (GKeyFile     *key_file,
diff --git a/gtk/gtkplacessidebar.c b/gtk/gtkplacessidebar.c
index ff29383f22..e64e3df699 100644
--- a/gtk/gtkplacessidebar.c
+++ b/gtk/gtkplacessidebar.c
@@ -4846,7 +4846,7 @@ gtk_places_sidebar_remove_shortcut (GtkPlacesSidebar *sidebar,
  * @sidebar may or may not affect the returned model.
  *
  * Returns: (transfer full): a list model of #GFiles that have been added as
- *     application-specific shortcuts with gtk_places_sidebar_add_shortcut().
+ *   application-specific shortcuts with gtk_places_sidebar_add_shortcut()
  */
 GListModel *
 gtk_places_sidebar_get_shortcuts (GtkPlacesSidebar *sidebar)
diff --git a/gtk/gtkprintjob.h b/gtk/gtkprintjob.h
index 30fb5b55d6..47b14c7149 100644
--- a/gtk/gtkprintjob.h
+++ b/gtk/gtkprintjob.h
@@ -40,7 +40,7 @@ typedef struct _GtkPrintJob          GtkPrintJob;
  * @print_job: the #GtkPrintJob
  * @user_data: user data that has been passed to gtk_print_job_send()
  * @error: a #GError that contains error information if the sending
- *     of the print job failed, otherwise %NULL
+ *   of the print job failed, otherwise %NULL
  *
  * The type of callback that is passed to gtk_print_job_send().
  *
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index 2f95d848d4..3c7f4041ba 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -1016,7 +1016,7 @@ gtk_print_run_page_setup_dialog (GtkWindow        *parent,
  * @page_setup: (allow-none): an existing #GtkPageSetup, or %NULL
  * @settings: a #GtkPrintSettings
  * @done_cb: (scope async): a function to call when the user saves
- *           the modified page setup
+ *    the modified page setup
  * @data: user data to pass to @done_cb
  * 
  * Runs a page setup dialog, letting the user modify the values from @page_setup. 
diff --git a/gtk/gtkprintoperation.h b/gtk/gtkprintoperation.h
index 94d6dddbf4..fc6f6e5a56 100644
--- a/gtk/gtkprintoperation.h
+++ b/gtk/gtkprintoperation.h
@@ -49,17 +49,17 @@ typedef struct _GtkPrintOperation        GtkPrintOperation;
 /**
  * GtkPrintStatus:
  * @GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this
- *     status is set initially, and while the print dialog is shown.
+ *   status is set initially, and while the print dialog is shown.
  * @GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print
- *     signal is emitted and during pagination.
+ *   signal is emitted and during pagination.
  * @GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the
- *     pages are being rendered.
+ *   pages are being rendered.
  * @GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the
- *     printer.
+ *   printer.
  * @GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer,
- *     but is not printed for some reason, e.g. the printer may be stopped.
+ *   but is not printed for some reason, e.g. the printer may be stopped.
  * @GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during
- *     printing, e.g. a paper jam.
+ *   printing, e.g. a paper jam.
  * @GTK_PRINT_STATUS_PRINTING: The printer is processing the print job.
  * @GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully.
  * @GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted.
@@ -84,9 +84,9 @@ typedef enum {
  * @GTK_PRINT_OPERATION_RESULT_ERROR: An error has occurred.
  * @GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored.
  * @GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled,
- *     the print settings should not be stored.
+ *   the print settings should not be stored.
  * @GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete
- *     yet. This value will only be returned when running asynchronously.
+ *   yet. This value will only be returned when running asynchronously.
  *
  * The result of a print operation.
  *
@@ -103,10 +103,10 @@ typedef enum {
  * GtkPrintOperationAction:
  * @GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog.
  * @GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing
- *     the print dialog, based on the current print settings.
+ *   the print dialog, based on the current print settings.
  * @GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview.
  * @GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires
- *     the export-filename property to be set.
+ *   the export-filename property to be set.
  *
  * Determines what action the print operation should perform.
  *
@@ -205,7 +205,7 @@ struct _GtkPrintOperationClass
  * @GTK_PRINT_ERROR_INTERNAL_ERROR: An internal error occurred.
  * @GTK_PRINT_ERROR_NOMEM: A memory allocation failed.
  * @GTK_PRINT_ERROR_INVALID_FILE: An error occurred while loading a page setup
- *     or paper size from a key file.
+ *   or paper size from a key file.
  *
  * Error codes that identify various errors that can occur while
  * using the GTK printing support.
@@ -311,9 +311,9 @@ GtkPageSetup           *gtk_print_run_page_setup_dialog            (GtkWindow
 /**
  * GtkPageSetupDoneFunc:
  * @page_setup: the #GtkPageSetup that has been passed to
- *     gtk_print_run_page_setup_dialog_async()
+ *   gtk_print_run_page_setup_dialog_async()
  * @data: (closure): user data that has been passed to
- *     gtk_print_run_page_setup_dialog_async()
+ *   gtk_print_run_page_setup_dialog_async()
  *
  * The type of function that is passed to
  * gtk_print_run_page_setup_dialog_async().
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 55ad58d3fc..48363596ce 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -1685,7 +1685,7 @@ gtk_print_settings_load_key_file (GtkPrintSettings *settings,
  * gtk_print_settings_new_from_key_file:
  * @key_file: the `GKeyFile` to retrieve the settings from
  * @group_name: (allow-none): the name of the group to use, or %NULL to use
- *     the default “Print Settings”
+ *   the default “Print Settings”
  * @error: (allow-none): return location for errors, or %NULL
  *
  * Reads the print settings from the group @group_name in @key_file.
@@ -1777,7 +1777,7 @@ add_value_to_key_file (const char   *key,
  * @settings: a `GtkPrintSettings`
  * @key_file: the `GKeyFile` to save the print settings to
  * @group_name: (nullable): the group to add the settings to in @key_file, or
- *     %NULL to use the default “Print Settings”
+ *   %NULL to use the default “Print Settings”
  *
  * This function adds the print settings from @settings to @key_file.
  */
diff --git a/gtk/gtkrange.c b/gtk/gtkrange.c
index 7199387e0e..106ebd4cf2 100644
--- a/gtk/gtkrange.c
+++ b/gtk/gtkrange.c
@@ -964,10 +964,8 @@ gtk_range_get_range_rect (GtkRange     *range,
 /**
  * gtk_range_get_slider_range:
  * @range: a `GtkRange`
- * @slider_start: (out) (allow-none): return location for the slider's
- *     start, or %NULL
- * @slider_end: (out) (allow-none): return location for the slider's
- *     end, or %NULL
+ * @slider_start: (out) (allow-none): return location for the slider's start
+ * @slider_end: (out) (allow-none): return location for the slider's end
  *
  * This function returns sliders range along the long dimension,
  * in widget->window coordinates.
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 0353f57d6c..9af8765a5e 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -879,7 +879,7 @@ gtk_recent_manager_add_item (GtkRecentManager *manager,
  * applications that have registered it.
  *
  * Returns: %TRUE if the new item was successfully added to the
- *     recently used resources list, %FALSE otherwise
+ *   recently used resources list, %FALSE otherwise
  */
 gboolean
 gtk_recent_manager_add_full (GtkRecentManager    *manager,
@@ -1534,7 +1534,7 @@ gtk_recent_info_free (GtkRecentInfo *recent_info)
  * Increases the reference count of @recent_info by one.
  *
  * Returns: the recent info object with its reference count
- *     increased by one
+ *   increased by one
  */
 GtkRecentInfo *
 gtk_recent_info_ref (GtkRecentInfo *info)
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index cd8c41b382..5323a95def 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -1002,7 +1002,7 @@ gtk_scale_new_with_range (GtkOrientation orientation,
  * gtk_scale_set_digits: (attributes org.gtk.Method.set_property=digits)
  * @scale: a `GtkScale`
  * @digits: the number of decimal places to display,
- *     e.g. use 1 to display 1.0, 2 to display 1.00, etc
+ *   e.g. use 1 to display 1.0, 2 to display 1.00, etc
  *
  * Sets the number of decimal places that are displayed in the value.
  *
diff --git a/gtk/gtkscalebutton.c b/gtk/gtkscalebutton.c
index fc8089f86f..456863eff1 100644
--- a/gtk/gtkscalebutton.c
+++ b/gtk/gtkscalebutton.c
@@ -537,10 +537,10 @@ gtk_scale_button_dispose (GObject *object)
  * @min: the minimum value of the scale (usually 0)
  * @max: the maximum value of the scale (usually 100)
  * @step: the stepping of value when a scroll-wheel event,
- *        or up/down arrow event occurs (usually 2)
+ *   or up/down arrow event occurs (usually 2)
  * @icons: (allow-none) (array zero-terminated=1): a %NULL-terminated
- *         array of icon names, or %NULL if you want to set the list
- *         later with gtk_scale_button_set_icons()
+ *   array of icon names, or %NULL if you want to set the list
+ *   later with gtk_scale_button_set_icons()
  *
  * Creates a `GtkScaleButton`.
  *
diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c
index f9f2b4848b..5fbc41c2ac 100644
--- a/gtk/gtkscrollable.c
+++ b/gtk/gtkscrollable.c
@@ -40,7 +40,7 @@
  * - Because its preferred size is the size for a fully expanded widget,
  *   the scrollable widget must be able to cope with underallocations.
  *   This means that it must accept any value passed to its
- *   GtkWidgetClass.size_allocate() function.
+ *   [vfunc@Gtk.Widget.size_allocate] implementation.
  *
  * - When the parent allocates space to the scrollable child widget,
  *   the widget should update the adjustments’ properties with new values.
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index 35ca37ab72..c96b7ad941 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -2394,9 +2394,9 @@ gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
  * gtk_scrolled_window_get_policy:
  * @scrolled_window: a `GtkScrolledWindow`
  * @hscrollbar_policy: (out) (optional): location to store the policy
- *     for the horizontal scrollbar, or %NULL
+ *   for the horizontal scrollbar
  * @vscrollbar_policy: (out) (optional): location to store the policy
- *     for the vertical scrollbar, or %NULL
+ *   for the vertical scrollbar
  *
  * Retrieves the current policy values for the horizontal and vertical
  * scrollbars.
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index 91de4f8f4f..3f78141e58 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -375,7 +375,7 @@ gtk_selection_model_select_item (GtkSelectionModel *model,
  * Requests to unselect an item in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean the item was unselected.
+ *   tried. This does not mean the item was unselected.
  */
 gboolean
 gtk_selection_model_unselect_item (GtkSelectionModel *model,
@@ -399,7 +399,7 @@ gtk_selection_model_unselect_item (GtkSelectionModel *model,
  * Requests to select a range of items in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean the range was selected.
+ *   tried. This does not mean the range was selected.
  */
 gboolean
 gtk_selection_model_select_range (GtkSelectionModel *model,
@@ -424,7 +424,7 @@ gtk_selection_model_select_range (GtkSelectionModel *model,
  * Requests to unselect a range of items in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean the range was unselected.
+ *   tried. This does not mean the range was unselected.
  */
 gboolean
 gtk_selection_model_unselect_range (GtkSelectionModel *model,
@@ -446,7 +446,7 @@ gtk_selection_model_unselect_range (GtkSelectionModel *model,
  * Requests to select all items in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean that all items are now selected.
+ *   tried. This does not mean that all items are now selected.
  */
 gboolean
 gtk_selection_model_select_all (GtkSelectionModel *model)
@@ -466,7 +466,7 @@ gtk_selection_model_select_all (GtkSelectionModel *model)
  * Requests to unselect all items in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean that all items are now unselected.
+ *   tried. This does not mean that all items are now unselected.
  */
 gboolean
 gtk_selection_model_unselect_all (GtkSelectionModel *model)
@@ -482,8 +482,7 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
 /**
  * gtk_selection_model_set_selection:
  * @model: a `GtkSelectionModel`
- * @selected: bitmask specifying if items should be selected or
- *     unselected
+ * @selected: bitmask specifying if items should be selected or unselected
  * @mask: bitmask specifying which items should be updated
  *
  * Make selection changes.
@@ -521,8 +520,8 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
  * be selected.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean that all items were updated according
- *     to the inputs.
+ *   tried. This does not mean that all items were updated according
+ *   to the inputs.
  */
 gboolean
 gtk_selection_model_set_selection (GtkSelectionModel *model,
diff --git a/gtk/gtkselectionmodel.h b/gtk/gtkselectionmodel.h
index 4e5722c7e6..936a7d141d 100644
--- a/gtk/gtkselectionmodel.h
+++ b/gtk/gtkselectionmodel.h
@@ -37,24 +37,24 @@ G_DECLARE_INTERFACE (GtkSelectionModel, gtk_selection_model, GTK, SELECTION_MODE
  * GtkSelectionModelInterface:
  * @is_selected: Return if the item at the given position is selected.
  * @get_selection_in_range: Return a bitset with all currently selected
- *     items in the given range. By default, this function will call
- *     #GtkSelectionModel::is_selected() on all items in the given range.
+ *   items in the given range. By default, this function will call
+ *   #GtkSelectionModel::is_selected() on all items in the given range.
  * @select_item: Select the item in the given position. If the operation
- *     is known to fail, return %FALSE.
+ *   is known to fail, return %FALSE.
  * @unselect_item: Unselect the item in the given position. If the
- *     operation is known to fail, return %FALSE.
+ *   operation is known to fail, return %FALSE.
  * @select_range: Select all items in the given range. If the operation
- *     is unsupported or known to fail for all items, return %FALSE.
+ *   is unsupported or known to fail for all items, return %FALSE.
  * @unselect_range: Unselect all items in the given range. If the
- *     operation is unsupported or known to fail for all items, return
- *     %FALSE.
+ *   operation is unsupported or known to fail for all items, return
+ *   %FALSE.
  * @select_all: Select all items in the model. If the operation is
- *     unsupported or known to fail for all items, return %FALSE.
+ *   unsupported or known to fail for all items, return %FALSE.
  * @unselect_all: Unselect all items in the model. If the operation is
- *     unsupported or known to fail for all items, return %FALSE.
+ *   unsupported or known to fail for all items, return %FALSE.
  * @set_selection: Set selection state of all items in mask to selected.
- *     See gtk_selection_model_set_selection() for a detailed explanation
- *     of this function.
+ *   See gtk_selection_model_set_selection() for a detailed explanation
+ *   of this function.
  *
  * The list of virtual functions for the #GtkSelectionModel interface.
  * No function must be implemented, but unless #GtkSelectionModel::is_selected()
diff --git a/gtk/gtkshortcut.c b/gtk/gtkshortcut.c
index 6cfd920ec3..51982e63ef 100644
--- a/gtk/gtkshortcut.c
+++ b/gtk/gtkshortcut.c
@@ -231,9 +231,9 @@ gtk_shortcut_new (GtkShortcutTrigger *trigger,
  * gtk_shortcut_new_with_arguments: (skip)
  * @trigger: (transfer full) (nullable): The trigger that will trigger the shortcut
  * @action: (transfer full) (nullable): The action that will be activated upon
- *    triggering
+ *   triggering
  * @format_string: (allow-none): GVariant format string for arguments or %NULL for
- *     no arguments
+ *   no arguments
  * @...: arguments, as given by format string.
  *
  * Creates a new `GtkShortcut` that is triggered by @trigger and then activates
@@ -296,7 +296,7 @@ gtk_shortcut_get_action (GtkShortcut *self)
  * gtk_shortcut_set_action: (attributes org.gtk.Method.set_property=action)
  * @self: a `GtkShortcut`
  * @action: (transfer full) (nullable): The new action.
- *     If the @action is %NULL, the nothing action will be used.
+ *   If the @action is %NULL, the nothing action will be used.
  *
  * Sets the new action for @self to be @action.
  */
@@ -336,7 +336,7 @@ gtk_shortcut_get_trigger (GtkShortcut *self)
  * gtk_shortcut_set_trigger: (attributes org.gtk.Method.set_property=trigger)
  * @self: a `GtkShortcut`
  * @trigger: (transfer full) (nullable): The new trigger.
- *     If the @trigger is %NULL, the never trigger will be used.
+ *   If the @trigger is %NULL, the never trigger will be used.
  *
  * Sets the new trigger for @self to be @trigger.
  */
diff --git a/gtk/gtkshortcutaction.c b/gtk/gtkshortcutaction.c
index 62d213911d..249bd437eb 100644
--- a/gtk/gtkshortcutaction.c
+++ b/gtk/gtkshortcutaction.c
@@ -209,7 +209,6 @@ string_is_function (const char *string,
  * - `signal(NAME)`, for a `GtkSignalAction` for the signal `NAME`
  *
  * Returns: (nullable) (transfer full): a new `GtkShortcutAction`
- *     or %NULL on error
  */
 GtkShortcutAction *
 gtk_shortcut_action_parse_string (const char *string)
diff --git a/gtk/gtkshortcutaction.h b/gtk/gtkshortcutaction.h
index de2403e186..495fbbc44c 100644
--- a/gtk/gtkshortcutaction.h
+++ b/gtk/gtkshortcutaction.h
@@ -45,8 +45,8 @@ typedef gboolean (* GtkShortcutFunc) (GtkWidget *widget,
 /**
  * GtkShortcutActionFlags:
  * @GTK_SHORTCUT_ACTION_EXCLUSIVE: The action is the only
- *     action that can be activated. If this flag is not set,
- *     a future activation may select a different action.
+ *   action that can be activated. If this flag is not set,
+ *   a future activation may select a different action.
  *
  * List of flags that can be passed to action activation.
  *
diff --git a/gtk/gtkshortcutmanager.h b/gtk/gtkshortcutmanager.h
index fefea1286f..79dc6e583c 100644
--- a/gtk/gtkshortcutmanager.h
+++ b/gtk/gtkshortcutmanager.h
@@ -38,7 +38,7 @@ G_DECLARE_INTERFACE (GtkShortcutManager, gtk_shortcut_manager, GTK, SHORTCUT_MAN
  * GtkShortcutManagerInterface:
  * @add_controller: Add a #GtkShortcutController to be managed.
  * @remove_controller: Remove a #GtkShortcutController that had previously
- *     been added.
+ *   been added
  *
  * The list of functions that can be implemented for the #GtkShortcutManager interface.
  *
diff --git a/gtk/gtkshortcuttrigger.c b/gtk/gtkshortcuttrigger.c
index 2e99c9bc63..848860ae62 100644
--- a/gtk/gtkshortcuttrigger.c
+++ b/gtk/gtkshortcuttrigger.c
@@ -87,8 +87,8 @@ gtk_shortcut_trigger_init (GtkShortcutTrigger *self)
  * @self: a `GtkShortcutTrigger`
  * @event: the event to check
  * @enable_mnemonics: %TRUE if mnemonics should trigger. Usually the
- *     value of this property is determined by checking that the passed
- *     in @event is a Key event and has the right modifiers set.
+ *   value of this property is determined by checking that the passed
+ *   in @event is a Key event and has the right modifiers set.
  *
  * Checks if the given @event triggers @self.
  *
@@ -292,8 +292,8 @@ gtk_shortcut_trigger_to_label (GtkShortcutTrigger *self,
  * not guaranteed to stay identical.
  *
  * Returns: %TRUE if something was printed or %FALSE if the
- *     trigger did not have a textual representation suitable
- *     for end users.
+ *   trigger did not have a textual representation suitable
+ *   for end users.
  **/
 gboolean
 gtk_shortcut_trigger_print_label (GtkShortcutTrigger *self,
@@ -363,8 +363,8 @@ gtk_shortcut_trigger_equal (gconstpointer trigger1,
  * They must each be a `GtkShortcutTrigger`.
  *
  * Returns: An integer less than, equal to, or greater than zero if
- *     @trigger1 is found, respectively, to be less than, to match,
- *     or be greater than @trigger2.
+ *   @trigger1 is found, respectively, to be less than, to match,
+ *   or be greater than @trigger2.
  */
 int
 gtk_shortcut_trigger_compare (gconstpointer trigger1,
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 2362c8165e..1cedcb46c8 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -143,7 +143,7 @@ gtk_show_uri_full (GtkWindow           *parent,
  * of the operation.
  *
  * Returns: %TRUE if the URI was shown successfully.
- *     Otherwise, %FALSE is returned and @error is set
+ *   Otherwise, %FALSE is returned and @error is set
  */
 gboolean
 gtk_show_uri_full_finish (GtkWindow     *parent,
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index c614088b82..23cd11931b 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -674,10 +674,10 @@ compare_gap (gconstpointer p1,
 /**
  * gtk_distribute_natural_allocation:
  * @extra_space: Extra space to redistribute among children after subtracting
- *               minimum sizes and any child padding from the overall allocation
+ *   minimum sizes and any child padding from the overall allocation
  * @n_requested_sizes: Number of requests to fit into the allocation
  * @sizes: (array length=n_requested_sizes): An array of structs with a client pointer and a minimum/natural size
- *         in the orientation of the allocation.
+ *  in the orientation of the allocation.
  *
  * Distributes @extra_space to child @sizes by bringing smaller
  * children up to natural size first.
diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 304abbde79..b2fd486ec3 100644
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -54,7 +54,7 @@
  * gtk_snapshot_pop() to change the current node.
  *
  * The typical way to obtain a `GtkSnapshot` object is as an argument to
- * the GtkWidgetClass.snapshot() vfunc. If you need to create your own
+ * the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own
  * `GtkSnapshot`, use [ctor@Gtk.Snapshot.new].
  */
 
@@ -317,7 +317,7 @@ gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
  * gtk_snapshot_free_to_paintable: (skip)
  * @snapshot: (transfer full): a `GtkSnapshot`
  * @size: (allow-none): The size of the resulting paintable
- *     or %NULL to use the bounds of the snapshot
+ *   or %NULL to use the bounds of the snapshot
  *
  * Returns a paintable for the node that was
  * constructed by @snapshot and frees @snapshot.
@@ -1514,7 +1514,7 @@ gtk_snapshot_to_node (GtkSnapshot *snapshot)
  * gtk_snapshot_to_paintable:
  * @snapshot: a `GtkSnapshot`
  * @size: (allow-none): The size of the resulting paintable
- *     or %NULL to use the bounds of the snapshot
+ *   or %NULL to use the bounds of the snapshot
  *
  * Returns a paintable encapsulating the render node
  * that was constructed by @snapshot.
@@ -2421,9 +2421,9 @@ gtk_snapshot_append_repeating_radial_gradient (GtkSnapshot            *snapshot,
  * @snapshot: a `GtkSnapshot`
  * @outline: a `GskRoundedRect` describing the outline of the border
  * @border_width: (array fixed-size=4): the stroke width of the border on
- *     the top, right, bottom and left side respectively.
+ *   the top, right, bottom and left side respectively.
  * @border_color: (array fixed-size=4): the color used on the top, right,
- *     bottom and left side.
+ *   bottom and left side.
  *
  * Appends a stroked border rectangle inside the given @outline.
  *
diff --git a/gtk/gtksorter.c b/gtk/gtksorter.c
index 0ad3c2653b..9fe8a906cb 100644
--- a/gtk/gtksorter.c
+++ b/gtk/gtksorter.c
@@ -164,8 +164,8 @@ gtk_sorter_init (GtkSorter *self)
  * via the return value of [method@Gtk.Sorter.get_order].
  *
  * Returns: %GTK_ORDERING_EQUAL if @item1 == @item2,
- *     %GTK_ORDERING_SMALLER if @item1 < @item2,
- *     %GTK_ORDERING_LARGER if @item1 > @item2
+ *   %GTK_ORDERING_SMALLER if @item1 < @item2,
+ *   %GTK_ORDERING_LARGER if @item1 > @item2
  */
 GtkOrdering
 gtk_sorter_compare (GtkSorter *self,
diff --git a/gtk/gtksorter.h b/gtk/gtksorter.h
index b90cac1381..6cc248ec38 100644
--- a/gtk/gtksorter.h
+++ b/gtk/gtksorter.h
@@ -33,10 +33,10 @@ G_BEGIN_DECLS
  * GtkSorterOrder:
  * @GTK_SORTER_ORDER_PARTIAL: A partial order. Any #GtkOrdering is possible.
  * @GTK_SORTER_ORDER_NONE: No order, all elements are considered equal.
- *     gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL.
+ *   gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL.
  * @GTK_SORTER_ORDER_TOTAL: A total order. gtk_sorter_compare() will only
- *     return %GTK_ORDERING_EQUAL if an item is compared with itself. Two
- *     different items will never cause this value to be returned.
+ *   return %GTK_ORDERING_EQUAL if an item is compared with itself. Two
+ *   different items will never cause this value to be returned.
  *
  * Describes the type of order that a `GtkSorter` may produce.
  */
@@ -49,14 +49,14 @@ typedef enum {
 /**
  * GtkSorterChange:
  * @GTK_SORTER_CHANGE_DIFFERENT: The sorter change cannot be described
- *     by any of the other enumeration values
+ *   by any of the other enumeration values
  * @GTK_SORTER_CHANGE_INVERTED: The sort order was inverted. Comparisons
- *     that returned %GTK_ORDERING_SMALLER now return %GTK_ORDERING_LARGER
- *     and vice versa. Other comparisons return the same values as before.
+ *   that returned %GTK_ORDERING_SMALLER now return %GTK_ORDERING_LARGER
+ *   and vice versa. Other comparisons return the same values as before.
  * @GTK_SORTER_CHANGE_LESS_STRICT: The sorter is less strict: Comparisons
- *     may now return %GTK_ORDERING_EQUAL that did not do so before.
+ *   may now return %GTK_ORDERING_EQUAL that did not do so before.
  * @GTK_SORTER_CHANGE_MORE_STRICT: The sorter is more strict: Comparisons
- *     that did return %GTK_ORDERING_EQUAL may not do so anymore.
+ *   that did return %GTK_ORDERING_EQUAL may not do so anymore.
  *
  * Describes changes in a sorter in more detail and allows users
  * to optimize resorting.
@@ -77,7 +77,7 @@ G_DECLARE_DERIVABLE_TYPE (GtkSorter, gtk_sorter, GTK, SORTER, GObject)
  * GtkSorterClass
  * @compare: Compare two items. See gtk_sorter_compare() for details.
  * @get_order: Get the #GtkSorderOrder that applies to the current sorter.
- *     If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL.
+ *   If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL.
  *
  * The virtual table for `GtkSorter`.
  */
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 344f8870e6..12846ab98a 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -1706,7 +1706,7 @@ gtk_spin_button_default_output (GtkSpinButton *spin_button)
  * gtk_spin_button_configure:
  * @spin_button: a `GtkSpinButton`
  * @adjustment: (nullable): a `GtkAdjustment` to replace the spin button’s
- *     existing adjustment, or %NULL to leave its current adjustment unchanged
+ *   existing adjustment, or %NULL to leave its current adjustment unchanged
  * @climb_rate: the new climb rate
  * @digits: the number of decimal places to display in the spin button
  *
@@ -1774,9 +1774,9 @@ gtk_spin_button_configure (GtkSpinButton *spin_button,
 /**
  * gtk_spin_button_new:
  * @adjustment: (allow-none): the `GtkAdjustment` that this spin
- *     button should use, or %NULL
+ *   button should use, or %NULL
  * @climb_rate: specifies by how much the rate of change in the value will
- *     accelerate if you continue to hold down an up/down button or arrow key
+ *   accelerate if you continue to hold down an up/down button or arrow key
  * @digits: the number of decimal places to display
  *
  * Creates a new `GtkSpinButton`.
diff --git a/gtk/gtkspinbutton.h b/gtk/gtkspinbutton.h
index e3fb89b50a..350d0c3979 100644
--- a/gtk/gtkspinbutton.h
+++ b/gtk/gtkspinbutton.h
@@ -55,10 +55,10 @@ G_BEGIN_DECLS
 /**
  * GtkSpinButtonUpdatePolicy:
  * @GTK_UPDATE_ALWAYS: When refreshing your #GtkSpinButton, the value is
- *     always displayed
+ *   always displayed
  * @GTK_UPDATE_IF_VALID: When refreshing your #GtkSpinButton, the value is
- *     only displayed if it is valid within the bounds of the spin button's
- *     adjustment
+ *   only displayed if it is valid within the bounds of the spin button's
+ *   adjustment
  *
  * Determines whether the spin button displays values outside the adjustment
  * bounds.
diff --git a/gtk/gtkstacksidebar.c b/gtk/gtkstacksidebar.c
index 1817b47e78..41631859d1 100644
--- a/gtk/gtkstacksidebar.c
+++ b/gtk/gtkstacksidebar.c
@@ -426,7 +426,7 @@ gtk_stack_sidebar_set_stack (GtkStackSidebar *self,
  * Retrieves the stack.
  *
  * Returns: (nullable) (transfer none): the associated #GtkStack or
- *     %NULL if none has been set explicitly
+ *   %NULL if none has been set explicitly
  */
 GtkStack *
 gtk_stack_sidebar_get_stack (GtkStackSidebar *self)
diff --git a/gtk/gtkstringfilter.c b/gtk/gtkstringfilter.c
index 8e31627990..c4f3c9e630 100644
--- a/gtk/gtkstringfilter.c
+++ b/gtk/gtkstringfilter.c
@@ -309,7 +309,6 @@ gtk_string_filter_init (GtkStringFilter *self)
 /**
  * gtk_string_filter_new:
  * @expression: (transfer full) (nullable): The expression to evaluate
- *     or %NULL for none
  *
  * Creates a new string filter.
  *
@@ -352,7 +351,7 @@ gtk_string_filter_get_search (GtkStringFilter *self)
  * gtk_string_filter_set_search: (attributes org.gtk.Method.set_property=search)
  * @self: a `GtkStringFilter`
  * @search: (transfer none) (nullable): The string to search for
- *     or %NULL to clear the search
+ *   or %NULL to clear the search
  *
  * Sets the string to search for.
  */
diff --git a/gtk/gtkstringfilter.h b/gtk/gtkstringfilter.h
index 8852829314..b3ccf40a09 100644
--- a/gtk/gtkstringfilter.h
+++ b/gtk/gtkstringfilter.h
@@ -32,11 +32,11 @@ G_BEGIN_DECLS
 /**
  * GtkStringFilterMatchMode:
  * @GTK_STRING_FILTER_MATCH_MODE_EXACT: The search string and
- *     text must match exactly.
+ *   text must match exactly.
  * @GTK_STRING_FILTER_MATCH_MODE_SUBSTRING: The search string
- *     must be contained as a substring inside the text.
+ *   must be contained as a substring inside the text.
  * @GTK_STRING_FILTER_MATCH_MODE_PREFIX: The text must begin
- *     with the search string.
+ *   with the search string.
  *
  * Specifies how search strings are matched inside text.
  */
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index b95af474d1..5427e67879 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -1219,11 +1219,11 @@ gtk_snapshot_render_insertion_cursor (GtkSnapshot     *snapshot,
  * GtkStyleContextPrintFlags:
  * @GTK_STYLE_CONTEXT_PRINT_NONE: Default value.
  * @GTK_STYLE_CONTEXT_PRINT_RECURSE: Print the entire tree of
- *     CSS nodes starting at the style context's node
+ *   CSS nodes starting at the style context's node
  * @GTK_STYLE_CONTEXT_PRINT_SHOW_STYLE: Show the values of the
- *     CSS properties for each node
- * @GTK_STYLE_CONTEXT_PRINT_SHOW_CHANGE: Show information about 
- *     what changes affect the styles
+ *   CSS properties for each node
+ * @GTK_STYLE_CONTEXT_PRINT_SHOW_CHANGE: Show information about
+ *   what changes affect the styles
  *
  * Flags that modify the behavior of gtk_style_context_to_string().
  *
diff --git a/gtk/gtkstyleproperty.c b/gtk/gtkstyleproperty.c
index 964ac388ed..153c4f1b09 100644
--- a/gtk/gtkstyleproperty.c
+++ b/gtk/gtkstyleproperty.c
@@ -167,8 +167,8 @@ _gtk_style_property_init_properties (void)
  * property exists, %NULL is returned.
  *
  * Returns: (nullable) (transfer none): The property or %NULL if no
- *     property with the given name exists.
- **/
+ *   property with the given name exists.
+ */
 GtkStyleProperty *
 _gtk_style_property_lookup (const char *name)
 {
diff --git a/gtk/gtktestutils.c b/gtk/gtktestutils.c
index 6bcd1192c4..85a3c13d75 100644
--- a/gtk/gtktestutils.c
+++ b/gtk/gtktestutils.c
@@ -58,11 +58,10 @@
 /**
  * gtk_test_init:
  * @argcp: Address of the `argc` parameter of the
- *        main() function. Changed if any arguments were handled.
- * @argvp: (inout) (array length=argcp): Address of the 
- *        `argv` parameter of main().
- *        Any parameters understood by g_test_init() or gtk_init() are
- *        stripped before return.
+ *   main() function. Changed if any arguments were handled.
+ * @argvp: (inout) (array length=argcp): Address of the `argv`
+ *   parameter of main(). Any parameters understood by g_test_init()
+ *   or gtk_init() are stripped before return.
  * @...: currently unused
  *
  * This function is used to initialize a GTK test program.
diff --git a/gtk/gtktextattributes.c b/gtk/gtktextattributes.c
index 1028865247..19becb030e 100644
--- a/gtk/gtktextattributes.c
+++ b/gtk/gtktextattributes.c
@@ -59,7 +59,7 @@
  * a set of properties on some text.
  * 
  * Returns: a new #GtkTextAttributes,
- *     free with gtk_text_attributes_unref().
+ *   free with gtk_text_attributes_unref().
  */
 GtkTextAttributes*
 gtk_text_attributes_new (void)
@@ -87,7 +87,7 @@ gtk_text_attributes_new (void)
  * Copies @src and returns a new #GtkTextAttributes.
  *
  * Returns: a copy of @src,
- *     free with gtk_text_attributes_unref()
+ *   free with gtk_text_attributes_unref()
  */
 GtkTextAttributes*
 gtk_text_attributes_copy (GtkTextAttributes *src)
diff --git a/gtk/gtktextbtree.c b/gtk/gtktextbtree.c
index 748e65ae18..6d02b70098 100644
--- a/gtk/gtktextbtree.c
+++ b/gtk/gtktextbtree.c
@@ -5211,7 +5211,7 @@ gtk_text_btree_node_validate (BTreeView         *view,
  * @tree: a #GtkTextBTree
  * @view_id: view id
  * @max_pixels: the maximum number of pixels to validate. (No more
- *              than one paragraph beyond this limit will be validated)
+ *   than one paragraph beyond this limit will be validated)
  * @y: location to store starting y coordinate of validated region
  * @old_height: location to store old height of validated region
  * @new_height: location to store new height of validated region
diff --git a/gtk/gtktextlayout.c b/gtk/gtktextlayout.c
index 7d6770e252..ffc6795484 100644
--- a/gtk/gtktextlayout.c
+++ b/gtk/gtktextlayout.c
@@ -451,9 +451,9 @@ gtk_text_layout_set_overwrite_mode (GtkTextLayout *layout,
 /**
  * gtk_text_layout_set_cursor_direction:
  * @direction: the new direction(s) for which to draw cursors.
- *             %GTK_TEXT_DIR_NONE means draw cursors for both
- *             left-to-right insertion and right-to-left insertion.
- *             (The two cursors will be visually distinguished.)
+ *   %GTK_TEXT_DIR_NONE means draw cursors for both
+ *   left-to-right insertion and right-to-left insertion.
+ *   (The two cursors will be visually distinguished.)
  * 
  * Sets which text directions (left-to-right and/or right-to-left) for
  * which cursors will be drawn for the insertion point. The visual
@@ -566,7 +566,7 @@ gtk_text_layout_set_cursor_visible (GtkTextLayout *layout,
  * Returns whether the insertion cursor will be shown.
  *
  * Returns: if %FALSE, the insertion cursor will not be
- *     shown, even if the text is editable.
+ *   shown, even if the text is editable.
  */
 gboolean
 gtk_text_layout_get_cursor_visible (GtkTextLayout *layout)
@@ -886,13 +886,13 @@ update_layout_size (GtkTextLayout *layout)
  * gtk_text_layout_validate_yrange:
  * @layout: a #GtkTextLayout
  * @anchor: iter pointing into a line that will be used as the
- *          coordinate origin
+ *   coordinate origin
  * @y0_: offset from the top of the line pointed to by @anchor at
- *       which to begin validation. (The offset here is in pixels
- *       after validation.)
+ *   which to begin validation. (The offset here is in pixels
+ *   after validation.)
  * @y1_: offset from the top of the line pointed to by @anchor at
- *       which to end validation. (The offset here is in pixels
- *       after validation.)
+ *   which to end validation. (The offset here is in pixels
+ *   after validation.)
  *
  * Ensure that a region of a #GtkTextLayout is valid. The ::changed
  * signal will be emitted if any lines are validated.
@@ -1024,7 +1024,7 @@ gtk_text_layout_validate_yrange (GtkTextLayout *layout,
  * gtk_text_layout_validate:
  * @tree: a #GtkTextLayout
  * @max_pixels: the maximum number of pixels to validate. (No more
- *              than one paragraph beyond this limit will be validated)
+ *   than one paragraph beyond this limit will be validated)
  *
  * Validate regions of a #GtkTextLayout. The ::changed signal will
  * be emitted for each region validated.
@@ -2734,7 +2734,7 @@ get_line_at_y (GtkTextLayout *layout,
  * @target_iter: the iterator in which the result is stored
  * @y: the y position
  * @line_top: location to store the y coordinate of the
- *            top of the line. (Can by %NULL)
+ *   top of the line. (Can by %NULL)
  *
  * Get the iter at the beginning of the line which is displayed
  * at the given y.
@@ -2956,11 +2956,9 @@ _gtk_text_layout_get_block_cursor (GtkTextLayout *layout,
 /**
  * gtk_text_layout_get_line_yrange:
  * @layout: a #GtkTextLayout
- * @iter:   a #GtkTextIter
- * @y:      location to store the top of the paragraph in pixels,
- *          or %NULL.
- * @height  location to store the height of the paragraph in pixels,
- *          or %NULL.
+ * @iter: a #GtkTextIter
+ * @y: (nullable): location to store the top of the paragraph in pixels
+ * @height: (nullable): location to store the height of the paragraph in pixels
  *
  * Find the range of y coordinates for the paragraph containing
  * the given iter.
diff --git a/gtk/gtktextutil.c b/gtk/gtktextutil.c
index 74b3f5cc59..83f45a8e13 100644
--- a/gtk/gtktextutil.c
+++ b/gtk/gtktextutil.c
@@ -316,7 +316,7 @@ layout_get_char_width (PangoLayout *layout)
  * character
  *
  * Returns: whether cursor should actually be drawn as a rectangle.
- *     It may not be the case if character at index is invisible.
+ *   It may not be the case if character at index is invisible.
  */
 gboolean
 _gtk_text_util_get_block_cursor_location (PangoLayout    *layout,
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 2effe3eae2..7c6e22a248 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -2280,10 +2280,8 @@ gtk_text_view_get_buffer (GtkTextView *text_view)
  * gtk_text_view_get_cursor_locations:
  * @text_view: a `GtkTextView`
  * @iter: (allow-none): a `GtkTextIter`
- * @strong: (out) (allow-none): location to store the strong
- *     cursor position (may be %NULL)
- * @weak: (out) (allow-none): location to store the weak
- *     cursor position (may be %NULL)
+ * @strong: (out) (allow-none): location to store the strong cursor position
+ * @weak: (out) (allow-none): location to store the weak cursor position
  *
  * Determine the positions of the strong and weak cursors if the
  * insertion point is at @iter.
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index 93ba0e7c07..75fe0d4546 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -353,7 +353,7 @@ gtk_toggle_button_new_with_label (const char *label)
 /**
  * gtk_toggle_button_new_with_mnemonic:
  * @label: the text of the button, with an underscore in front of the
- *         mnemonic character
+ *   mnemonic character
  *
  * Creates a new `GtkToggleButton` containing a label.
  *
diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index 96fe9b4dff..35f1fe3ab0 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -736,7 +736,7 @@ gtk_tree_list_model_init (GtkTreeListModel *self)
  * @passthrough: %TRUE to pass through items from the models
  * @autoexpand: %TRUE to set the autoexpand property and expand the @root model
  * @create_func: Function to call to create the `GListModel` for the children
- *     of an item
+ *   of an item
  * @user_data: (closure): Data to pass to @create_func
  * @user_destroy: Function to call to free @user_data
  *
diff --git a/gtk/gtktreelistmodel.h b/gtk/gtktreelistmodel.h
index e5f76ac5aa..1a164e40ae 100644
--- a/gtk/gtktreelistmodel.h
+++ b/gtk/gtktreelistmodel.h
@@ -48,12 +48,12 @@ G_DECLARE_FINAL_TYPE (GtkTreeListRow, gtk_tree_list_row, GTK, TREE_LIST_ROW, GOb
  * gtk_tree_list_row_set_expanded() is called.
  *
  * This function can return %NULL to indicate that @item is guaranteed to be
- * a leaf node and will never have children.
- * If it does not have children but may get children later, it should return
- * an empty model that is filled once children arrive.
+ * a leaf node and will never have children. If it does not have children but
+ * may get children later, it should return an empty model that is filled once
+ * children arrive.
  *
- * Returns: (nullable) (transfer full): The model tracking the children of @item or %NULL if
- *     @item can never have children
+ * Returns: (nullable) (transfer full): The model tracking the children of
+ *   @item or %NULL if @item can never have children
  */
 typedef GListModel * (* GtkTreeListModelCreateModelFunc) (gpointer item, gpointer user_data);
 
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index a7e6b5ce16..df2d712868 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -727,7 +727,7 @@ gtk_tree_path_new_from_indicesv (int *indices,
 
 /**
  * gtk_tree_path_to_string:
- * @path: A #GtkTreePath-struct
+ * @path: a `GtkTreePath`
  *
  * Generates a string representation of the path.
  *
@@ -736,8 +736,7 @@ gtk_tree_path_new_from_indicesv (int *indices,
  * return value for this string. If the path has
  * depth 0, %NULL is returned.
  *
- * Returns: (nullable): A newly-allocated string.
- *     Must be freed with g_free().
+ * Returns: (nullable): A newly-allocated string
  */
 char *
 gtk_tree_path_to_string (GtkTreePath *path)
@@ -881,9 +880,9 @@ gtk_tree_path_get_indices (GtkTreePath *path)
 
 /**
  * gtk_tree_path_get_indices_with_depth: (rename-to gtk_tree_path_get_indices)
- * @path: a #GtkTreePath-struct
+ * @path: a `GtkTreePath`
  * @depth: (out) (allow-none): return location for number of elements
- *     returned in the integer array, or %NULL
+ *   returned in the integer array, or %NULL
  *
  * Returns the current indices of @path.
  *
@@ -892,7 +891,7 @@ gtk_tree_path_get_indices (GtkTreePath *path)
  * The array should not be freed.
  *
  * Returns: (array length=depth) (transfer none): The current
- *     indices, or %NULL
+ *   indices, or %NULL
  */
 int *
 gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
@@ -1075,7 +1074,7 @@ gtk_tree_path_next (GtkTreePath *path)
  * current depth, if it exists.
  *
  * Returns: %TRUE if @path has a previous node, and
- *     the move was made
+ *   the move was made
  */
 gboolean
 gtk_tree_path_prev (GtkTreePath *path)
@@ -1310,8 +1309,8 @@ gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
 
 /**
  * gtk_tree_model_get_string_from_iter:
- * @tree_model: a #GtkTreeModel
- * @iter: a #GtkTreeIter-struct
+ * @tree_model: a `GtkTreeModel`
+ * @iter: a `GtkTreeIter`
  *
  * Generates a string representation of the iter.
  *
@@ -1319,8 +1318,7 @@ gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
  * For example, “4:10:0:3” would be an acceptable
  * return value for this string.
  *
- * Returns: (nullable): a newly-allocated string.
- *     Must be freed with g_free().
+ * Returns: (nullable): a newly-allocated string
  */
 char *
 gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model,
@@ -1731,10 +1729,10 @@ gtk_tree_model_unref_node (GtkTreeModel *tree_model,
 
 /**
  * gtk_tree_model_get:
- * @tree_model: a #GtkTreeModel
+ * @tree_model: a `GtkTreeModel`
  * @iter: a row in @tree_model
  * @...: pairs of column number and value return locations,
- *     terminated by -1
+ *   terminated by -1
  *
  * Gets the value of one or more cells in the row referenced by @iter.
  * The variable argument list should contain integer column numbers,
@@ -1880,9 +1878,9 @@ gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
 
 /**
  * gtk_tree_model_row_deleted:
- * @tree_model: a #GtkTreeModel
- * @path: a #GtkTreePath-struct pointing to the previous location of
- *     the deleted row
+ * @tree_model: a `GtkTreeModel`
+ * @path: a `GtkTreePath` pointing to the previous location of
+ *   the deleted row
  *
  * Emits the #GtkTreeModel::row-deleted signal on @tree_model.
  *
@@ -1905,16 +1903,16 @@ gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
 
 /**
  * gtk_tree_model_rows_reordered: (skip)
- * @tree_model: a #GtkTreeModel
- * @path: a #GtkTreePath-struct pointing to the tree node whose children
- *     have been reordered
- * @iter: a valid #GtkTreeIter-struct pointing to the node whose children
- *     have been reordered, or %NULL if the depth of @path is 0
+ * @tree_model: a `GtkTreeModel`
+ * @path: a `GtkTreePath` pointing to the tree node whose children
+ *   have been reordered
+ * @iter: a valid `GtkTreeIter` pointing to the node whose children
+ *   have been reordered, or %NULL if the depth of @path is 0
  * @new_order: an array of integers mapping the current position of
- *     each child to its old position before the re-ordering,
- *     i.e. @new_order`[newpos] = oldpos`
+ *   each child to its old position before the re-ordering,
+ *   i.e. @new_order`[newpos] = oldpos`
  *
- * Emits the #GtkTreeModel::rows-reordered signal on @tree_model.
+ * Emits the ::rows-reordered signal on @tree_model.
  *
  * This should be called by models when their rows have been
  * reordered.
@@ -1933,19 +1931,19 @@ gtk_tree_model_rows_reordered (GtkTreeModel *tree_model,
 
 /**
  * gtk_tree_model_rows_reordered_with_length: (rename-to gtk_tree_model_rows_reordered)
- * @tree_model: a #GtkTreeModel
- * @path: a #GtkTreePath-struct pointing to the tree node whose children
- *     have been reordered
+ * @tree_model: a `GtkTreeModel`
+ * @path: a `GtkTreePath` pointing to the tree node whose children
+ *   have been reordered
  * @iter: (allow-none): a valid #GtkTreeIter-struct pointing to the node
- *     whose children have been reordered, or %NULL if the depth
- *     of @path is 0
+ *   whose children have been reordered, or %NULL if the depth
+ *   of @path is 0
  * @new_order: (array length=length): an array of integers
- *     mapping the current position of each child to its old
- *     position before the re-ordering,
- *     i.e. @new_order`[newpos] = oldpos`
+ *   mapping the current position of each child to its old
+ *   position before the re-ordering,
+ *   i.e. @new_order`[newpos] = oldpos`
  * @length: length of @new_order array
  *
- * Emits the #GtkTreeModel::rows-reordered signal on @tree_model.
+ * Emits the ::rows-reordered signal on @tree_model.
  *
  * This should be called by models when their rows have been
  * reordered.
diff --git a/gtk/gtktreemodel.h b/gtk/gtktreemodel.h
index 18c78dfb8a..d802bdbd77 100644
--- a/gtk/gtktreemodel.h
+++ b/gtk/gtktreemodel.h
@@ -60,13 +60,13 @@ typedef gboolean (* GtkTreeModelForeachFunc) (GtkTreeModel *model, GtkTreePath *
 /**
  * GtkTreeModelFlags:
  * @GTK_TREE_MODEL_ITERS_PERSIST: iterators survive all signals
- *     emitted by the tree
+ *   emitted by the tree
  * @GTK_TREE_MODEL_LIST_ONLY: the model is a list only, and never
- *     has children
+ *   has children
  *
- * These flags indicate various properties of a #GtkTreeModel.
+ * These flags indicate various properties of a `GtkTreeModel`.
  *
- * They are returned by gtk_tree_model_get_flags(), and must be
+ * They are returned by [method@Gtk.TreeModel.get_flags], and must be
  * static for the lifetime of the object. A more complete description
  * of #GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of
  * this section.
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index c542af00ba..002cc9fa36 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -2230,16 +2230,16 @@ gtk_tree_store_reorder_func (gconstpointer a,
 
 /**
  * gtk_tree_store_reorder: (skip)
- * @tree_store: A #GtkTreeStore
- * @parent: (nullable): A #GtkTreeIter, or %NULL
+ * @tree_store: A `GtkTreeStore`
+ * @parent: (nullable): A `GtkTreeIter`, or %NULL
  * @new_order: (array): an array of integers mapping the new position of each child
- *      to its old position before the re-ordering,
- *      i.e. @new_order`[newpos] = oldpos`.
+ *   to its old position before the re-ordering,
+ *   i.e. @new_order`[newpos] = oldpos`.
  *
  * Reorders the children of @parent in @tree_store to follow the order
  * indicated by @new_order. Note that this function only works with
  * unsorted stores.
- **/
+ */
 void
 gtk_tree_store_reorder (GtkTreeStore *tree_store,
 			GtkTreeIter  *parent,
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 044f6baaab..a5d50a2cbd 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -12634,10 +12634,9 @@ gtk_tree_view_convert_bin_window_to_tree_coords (GtkTreeView *tree_view,
 
 /**
  * gtk_tree_view_get_visible_range:
- * @tree_view: A #GtkTreeView
- * @start_path: (out) (allow-none): Return location for start of region,
- *              or %NULL.
- * @end_path: (out) (allow-none): Return location for end of region, or %NULL.
+ * @tree_view: A `GtkTreeView`
+ * @start_path: (out) (allow-none): Return location for start of region
+ * @end_path: (out) (allow-none): Return location for end of region
  *
  * Sets @start_path and @end_path to be the first and last visible path.
  * Note that there may be invisible paths in between.
@@ -12645,7 +12644,7 @@ gtk_tree_view_convert_bin_window_to_tree_coords (GtkTreeView *tree_view,
  * The paths should be freed with gtk_tree_path_free() after use.
  *
  * Returns: %TRUE, if valid paths were placed in @start_path and @end_path.
- **/
+ */
 gboolean
 gtk_tree_view_get_visible_range (GtkTreeView  *tree_view,
                                  GtkTreePath **start_path,
@@ -14677,28 +14676,28 @@ gtk_tree_view_set_tooltip_cell (GtkTreeView       *tree_view,
 
 /**
  * gtk_tree_view_get_tooltip_context:
- * @tree_view: a #GtkTreeView
+ * @tree_view: a `GtkTreeView`
  * @x: the x coordinate (relative to widget coordinates)
  * @y: the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
  * @model: (out) (optional) (nullable) (transfer none): a pointer to
- *         receive a #GtkTreeModel or %NULL
- * @path: (out) (optional): a pointer to receive a #GtkTreePath or %NULL
- * @iter: (out) (optional): a pointer to receive a #GtkTreeIter or %NULL
+ *   receive a `GtkTreeModel`
+ * @path: (out) (optional): a pointer to receive a `GtkTreePath`
+ * @iter: (out) (optional): a pointer to receive a `GtkTreeIter`
  *
- * This function is supposed to be used in a #GtkWidget::query-tooltip
- * signal handler for #GtkTreeView.  The @x, @y and @keyboard_tip values
+ * This function is supposed to be used in a ::query-tooltip
+ * signal handler for `GtkTreeView`. The @x, @y and @keyboard_tip values
  * which are received in the signal handler, should be passed to this
  * function without modification.
  *
  * The return value indicates whether there is a tree view row at the given
- * coordinates (%TRUE) or not (%FALSE) for mouse tooltips.  For keyboard
- * tooltips the row returned will be the cursor row.  When %TRUE, then any of
+ * coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard
+ * tooltips the row returned will be the cursor row. When %TRUE, then any of
  * @model, @path and @iter which have been provided will be set to point to
- * that row and the corresponding model.  @x and @y will always be converted
+ * that row and the corresponding model. @x and @y will always be converted
  * to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE.
  *
- * Returns: whether or not the given tooltip context points to a row.
+ * Returns: whether or not the given tooltip context points to a row
  */
 gboolean
 gtk_tree_view_get_tooltip_context (GtkTreeView   *tree_view,
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index 1f57b2453e..34383145e1 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -2422,14 +2422,14 @@ gtk_tree_view_column_set_widget (GtkTreeViewColumn *tree_column,
 
 /**
  * gtk_tree_view_column_get_widget:
- * @tree_column: A #GtkTreeViewColumn.
+ * @tree_column: A `GtkTreeViewColumn`
+ *
+ * Returns the `GtkWidget` in the button on the column header.
  *
- * Returns the #GtkWidget in the button on the column header.
  * If a custom widget has not been set then %NULL is returned.
  *
- * Returns: (nullable) (transfer none): The #GtkWidget in the column
- *     header, or %NULL
- **/
+ * Returns: (nullable) (transfer none): The `GtkWidget` in the column header
+ */
 GtkWidget *
 gtk_tree_view_column_get_widget (GtkTreeViewColumn *tree_column)
 {
@@ -2592,15 +2592,16 @@ gtk_tree_view_column_set_sort_column_id (GtkTreeViewColumn *tree_column,
 
 /**
  * gtk_tree_view_column_get_sort_column_id:
- * @tree_column: a #GtkTreeViewColumn
+ * @tree_column: a `GtkTreeViewColumn`
+ *
+ * Gets the logical @sort_column_id that the model sorts on
+ * when this column is selected for sorting.
  *
- * Gets the logical @sort_column_id that the model sorts on when this
- * column is selected for sorting.
- * See gtk_tree_view_column_set_sort_column_id().
+ * See [method@Gtk.TreeViewColumn.set_sort_column_id].
  *
  * Returns: the current @sort_column_id for this column, or -1 if
- *               this column can’t be used for sorting.
- **/
+ *   this column can’t be used for sorting
+ */
 int
 gtk_tree_view_column_get_sort_column_id (GtkTreeViewColumn *tree_column)
 {
@@ -2924,18 +2925,18 @@ _gtk_tree_view_column_cell_get_dirty (GtkTreeViewColumn  *tree_column)
 
 /**
  * gtk_tree_view_column_cell_get_position:
- * @tree_column: a #GtkTreeViewColumn
- * @cell_renderer: a #GtkCellRenderer
+ * @tree_column: a `GtkTreeViewColumn`
+ * @cell_renderer: a `GtkCellRenderer`
  * @x_offset: (out) (allow-none): return location for the horizontal
- *            position of @cell within @tree_column, may be %NULL
- * @width: (out) (allow-none): return location for the width of @cell,
- *         may be %NULL
+ *   position of @cell within @tree_column
+ * @width: (out) (allow-none): return location for the width of @cell
  *
- * Obtains the horizontal position and size of a cell in a column. If the
- * cell is not found in the column, @start_pos and @width are not changed and
- * %FALSE is returned.
- * 
- * Returns: %TRUE if @cell belongs to @tree_column.
+ * Obtains the horizontal position and size of a cell in a column.
+ *
+ * If the  cell is not found in the column, @start_pos and @width
+ * are not changed and %FALSE is returned.
+ *
+ * Returns: %TRUE if @cell belongs to @tree_column
  */
 gboolean
 gtk_tree_view_column_cell_get_position (GtkTreeViewColumn *tree_column,
@@ -2998,8 +2999,8 @@ gtk_tree_view_column_queue_resize (GtkTreeViewColumn *tree_column)
  * If @column is currently not inserted in any tree view, %NULL is
  * returned.
  *
- * Returns: (nullable) (transfer none): The tree view wherein @column has
- *     been inserted if any, %NULL otherwise.
+ * Returns: (nullable) (transfer none): The tree view wherein @column
+ *   has been inserted
  */
 GtkWidget *
 gtk_tree_view_column_get_tree_view (GtkTreeViewColumn *tree_column)
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a7bdf8b08f..3f02b02736 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1916,9 +1916,9 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * GtkWidget::query-tooltip:
    * @widget: the object which received the signal
    * @x: the x coordinate of the cursor position where the request has
-   *     been emitted, relative to @widget's left side
+   *   been emitted, relative to @widget's left side
    * @y: the y coordinate of the cursor position where the request has
-   *     been emitted, relative to @widget's top
+   *   been emitted, relative to @widget's top
    * @keyboard_mode: %TRUE if the tooltip was triggered using the keyboard
    * @tooltip: a #GtkTooltip
    *
@@ -3300,12 +3300,12 @@ ensure_surface_transform_data (GtkWidget *widget)
  * @user_data: (closure): data to pass to @callback
  * @notify: function to call to free @user_data when the callback is removed
  *
- * Invokes the callback whenever the surface relative transform of the widget
- * changes.
+ * Invokes the callback whenever the surface relative transform of
+ * the widget changes.
  *
- * Returns: an id for the connection of this callback. Remove the callback by
- *     passing the id returned from this function to
- *     [method@Gtk.Widget.remove_surface_transform_changed_callback]
+ * Returns: an id for the connection of this callback. Remove the
+ *   callback by passing the id returned from this function to
+ *   [method@Gtk.Widget.remove_surface_transform_changed_callback]
  */
 guint
 gtk_widget_add_surface_transform_changed_callback (GtkWidget                          *widget,
@@ -3525,7 +3525,7 @@ gtk_widget_get_surface_allocation (GtkWidget     *widget,
  * Schedules this widget to be redrawn in paint phase of the
  * current or the next frame.
  *
- * This means @widget's GtkWidgetClass.snapshot()
+ * This means @widget's [vfunc@Gtk.Widget.snapshot]
  * implementation will be called.
  */
 void
@@ -3558,7 +3558,7 @@ gtk_widget_set_alloc_needed (GtkWidget *widget);
  * gtk_widget_queue_allocate:
  * @widget: a `GtkWidget`
  *
- * Flags the widget for a rerun of the GtkWidgetClass::size_allocate
+ * Flags the widget for a rerun of the [vfunc@Gtk.Widget.size_allocate]
  * function.
  *
  * Use this function instead of [method@Gtk.Widget.queue_resize]
@@ -3643,9 +3643,9 @@ gtk_widget_queue_resize_internal (GtkWidget *widget)
  * enough space for the new text.
  *
  * Note that you cannot call gtk_widget_queue_resize() on a widget
- * from inside its implementation of the GtkWidgetClass::size_allocate
+ * from inside its implementation of the [vfunc@Gtk.Widget.size_allocate]
  * virtual method. Calls to gtk_widget_queue_resize() from inside
- * GtkWidgetClass::size_allocate will be silently ignored.
+ * [vfunc@Gtk.Widget.size_allocate] will be silently ignored.
  *
  * This function is only for use in widget implementations.
  */
@@ -4188,7 +4188,7 @@ gtk_widget_common_ancestor (GtkWidget *widget_a,
  * Returns: %FALSE if @src_widget and @dest_widget have no common
  *   ancestor. In this case, 0 is stored in *@dest_x and *@dest_y.
  *   Otherwise %TRUE.
- **/
+ */
 gboolean
 gtk_widget_translate_coordinates (GtkWidget  *src_widget,
                                   GtkWidget  *dest_widget,
@@ -4219,7 +4219,7 @@ gtk_widget_translate_coordinates (GtkWidget  *src_widget,
  * @target: the `GtkWidget` to transform into
  * @point: a point in @widget's coordinate system
  * @out_point: (out caller-allocates): Set to the corresponding coordinates in
- *     @target's coordinate system
+ *   @target's coordinate system
  *
  * Translates the given @point in @widget's coordinates to coordinates
  * relative to @target’s coordinate system.
@@ -4229,7 +4229,7 @@ gtk_widget_translate_coordinates (GtkWidget  *src_widget,
  *
  * Returns: %TRUE if the point could be determined, %FALSE on failure.
  *   In this case, 0 is stored in @out_point.
- **/
+ */
 gboolean
 gtk_widget_compute_point (GtkWidget              *widget,
                           GtkWidget              *target,
@@ -4258,9 +4258,9 @@ gtk_widget_compute_point (GtkWidget              *widget,
  * @keyval: key value of binding to install
  * @mods: key modifier of binding to install
  * @callback: the callback to call upon activation
- * @format_string: (nullable): GVariant format string for arguments or %NULL for
- *     no arguments
- * @...: arguments, as given by format string.
+ * @format_string: (nullable): GVariant format string for arguments
+ *   or %NULL for no arguments
+ * @...: arguments, as given by format string
  *
  * Creates a new shortcut for @widget_class that calls the given @callback
  * with arguments read according to @format_string.
@@ -4269,9 +4269,9 @@ gtk_widget_compute_point (GtkWidget              *widget,
  * with g_variant_new().
  *
  * This function is a convenience wrapper around
- * gtk_widget_class_add_shortcut() and must be called during class
+ * [method@Gtk.WidgetClass.add_shortcut] and must be called during class
  * initialization. It does not provide for user_data, if you need that,
- * you will have to use gtk_widget_class_add_shortcut() with a custom
+ * you will have to use [method@GtkWidgetClass.add_shortcut] with a custom
  * shortcut.
  */
 void
@@ -4308,9 +4308,9 @@ gtk_widget_class_add_binding (GtkWidgetClass  *widget_class,
  * @keyval: key value of binding to install
  * @mods: key modifier of binding to install
  * @signal: the signal to execute
- * @format_string: (nullable): GVariant format string for arguments or %NULL for
- *     no arguments
- * @...: arguments, as given by format string.
+ * @format_string: (nullable): GVariant format string for arguments
+ *   or %NULL for no arguments
+ * @...: arguments, as given by format string
  *
  * Creates a new shortcut for @widget_class that emits the given action
  * @signal with arguments read according to @format_string.
@@ -4319,7 +4319,7 @@ gtk_widget_class_add_binding (GtkWidgetClass  *widget_class,
  * with g_variant_new().
  *
  * This function is a convenience wrapper around
- * gtk_widget_class_add_shortcut() and must be called during class
+ * [method@Gtk.WidgetClass.add_shortcut] and must be called during class
  * initialization.
  */
 void
@@ -4358,9 +4358,9 @@ gtk_widget_class_add_binding_signal (GtkWidgetClass  *widget_class,
  * @keyval: key value of binding to install
  * @mods: key modifier of binding to install
  * @action_name: the action to activate
- * @format_string: (nullable): GVariant format string for arguments or %NULL for
- *     no arguments
- * @...: arguments, as given by format string.
+ * @format_string: (nullable): GVariant format string for arguments
+ *   or %NULL for no arguments
+ * @...: arguments, as given by format string
  *
  * Creates a new shortcut for @widget_class that activates the given
  * @action_name with arguments read according to @format_string.
@@ -4369,7 +4369,7 @@ gtk_widget_class_add_binding_signal (GtkWidgetClass  *widget_class,
  * with g_variant_new().
  *
  * This function is a convenience wrapper around
- * gtk_widget_class_add_shortcut() and must be called during class
+ * [method@Gtk.WidgetClass.add_shortcut] and must be called during class
  * initialization.
  */
 void
@@ -4404,7 +4404,7 @@ gtk_widget_class_add_binding_action (GtkWidgetClass  *widget_class,
 /**
  * gtk_widget_class_add_shortcut:
  * @widget_class: the class to add the shortcut to
- * @shortcut: (transfer none): the #GtkShortcut to add
+ * @shortcut: (transfer none): the `GtkShortcut` to add
  *
  * Installs a shortcut in @widget_class.
  *
@@ -4778,8 +4778,9 @@ gtk_widget_class_get_activate_signal (GtkWidgetClass *widget_class)
  * @signal_id: the id for the activate signal
  *
  * Sets the GtkWidgetClass.activate_signal field with the
- * given @signal_id; the signal will be emitted when calling
- * gtk_widget_activate().
+ * given @signal_id.
+ *
+ * The signal will be emitted when calling [method@Gtk.Widget.activate].
  *
  * The @signal_id must have been registered with g_signal_new()
  * or g_signal_newv() before calling this function.
@@ -4800,8 +4801,9 @@ gtk_widget_class_set_activate_signal (GtkWidgetClass *widget_class,
  * @signal_name: the name of the activate signal of @widget_type
  *
  * Sets the GtkWidgetClass.activate_signal field with the signal id for
- * the given @signal_name; the signal will be emitted when calling
- * gtk_widget_activate().
+ * the given @signal_name.
+ *
+ * The signal will be emitted when calling [method@Gtk.Widget.activate].
  *
  * The @signal_name of @widget_type must have been registered with
  * g_signal_new() or g_signal_newv() before calling this function.
@@ -4831,18 +4833,18 @@ gtk_widget_class_set_activate_signal_from_name (GtkWidgetClass *widget_class,
  * gtk_widget_activate:
  * @widget: a `GtkWidget` that’s activatable
  *
- * For widgets that can be “activated” (buttons, menu items, etc.)
+ * For widgets that can be “activated” (buttons, menu items, etc.),
  * this function activates them.
  *
  * The activation will emit the signal set using
- * gtk_widget_class_set_activate_signal() during class initialization.
+ * [method@Gtk.WidgetClass.set_activate_signal] during class initialization.
  *
  * Activation is what happens when you press Enter on a widget during
  * key navigation.
  *
  * If you wish to handle the activation keybinding yourself, it is
- * recommended to use gtk_widget_class_add_shortcut() with an action
- * created with gtk_signal_action_new().
+ * recommended to use [method@Gtk.WidgetClass.add_shortcut] with an action
+ * created with [constructor@Gtk.SignalAction.new].
  *
  * If @widget isn't activatable, the function returns %FALSE.
  *
@@ -4871,9 +4873,9 @@ gtk_widget_activate (GtkWidget *widget)
  *
  * Causes @widget to have the keyboard focus for the `GtkWindow` it's inside.
  *
- * If @widget is not focusable, or its ::grab_focus implementation cannot
- * transfer the focus to a descendant of @widget that is focusable, it will
- * not take focus and %FALSE will be returned.
+ * If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus]
+ * implementation cannot transfer the focus to a descendant of @widget
+ * that is focusable, it will not take focus and %FALSE will be returned.
  *
  * Calling [method@Gtk.Widget.grab_focus] on an already focused widget
  * is allowed, should not have an effect, and return %TRUE.
@@ -5132,7 +5134,7 @@ gtk_widget_real_keynav_failed (GtkWidget        *widget,
  * gtk_widget_set_can_focus: (attributes org.gtk.Method.set_property=can-focus)
  * @widget: a `GtkWidget`
  * @can_focus: whether or not the input focus can enter
- *     the widget or any of its children
+ *   the widget or any of its children
  *
  * Specifies whether the input focus can enter the widget
  * or any of its children.
@@ -5480,7 +5482,7 @@ gtk_widget_get_receives_default (GtkWidget *widget)
  * See also gtk_grab_add().
  *
  * Returns: %TRUE if the widget is in the grab_widgets stack
- **/
+ */
 gboolean
 gtk_widget_has_grab (GtkWidget *widget)
 {
@@ -6132,8 +6134,7 @@ gtk_widget_set_parent (GtkWidget *widget,
  *
  * Returns the parent widget of @widget.
  *
- * Returns: (transfer none) (nullable): the parent widget of @widget,
- *   or %NULL
+ * Returns: (transfer none) (nullable): the parent widget of @widget
  */
 GtkWidget *
 gtk_widget_get_parent (GtkWidget *widget)
@@ -6156,8 +6157,7 @@ gtk_widget_get_parent (GtkWidget *widget)
  *
  * `GtkRoot` widgets will return themselves here.
  *
- * Returns: (transfer none) (nullable): the root widget of @widget,
- *   or %NULL
+ * Returns: (transfer none) (nullable): the root widget of @widget
  */
 GtkRoot *
 gtk_widget_get_root (GtkWidget *widget)
@@ -6171,15 +6171,14 @@ gtk_widget_get_root (GtkWidget *widget)
  * gtk_widget_get_native:
  * @widget: a `GtkWidget`
  *
- * Returns the `GtkNative` widget that contains @widget.
+ * Returns the nearest `GtkNative` ancestor of @widget.
  *
  * This function will return %NULL if the widget is not
  * contained inside a widget tree with a native ancestor.
  *
  * `GtkNative` widgets will return themselves here.
  *
- * Returns: (transfer none) (nullable): the `GtkNative`
- *   widget of @widget, or %NULL
+ * Returns: (transfer none) (nullable): the `GtkNative` ancestor of @widget
  */
 GtkNative *
 gtk_widget_get_native (GtkWidget *widget)
@@ -6482,7 +6481,7 @@ gtk_widget_update_pango_context (GtkWidget *widget)
  * gtk_widget_set_font_options:
  * @widget: a `GtkWidget`
  * @options: (allow-none): a #cairo_font_options_t, or %NULL
- *   to unset any previously set default font options.
+ *   to unset any previously set default font options
  *
  * Sets the `cairo_font_options_t` used for Pango rendering
  * in this widget.
@@ -6514,13 +6513,12 @@ gtk_widget_set_font_options (GtkWidget                  *widget,
  * gtk_widget_get_font_options:
  * @widget: a `GtkWidget`
  *
- * Returns the `cairo_font_options_t` used for Pango rendering.
+ * Returns the `cairo_font_options_t` of widget.
  *
- * When not set, the defaults font options for the `GdkDisplay`
- * will be used.
+ * Seee [method@Gtk.Widget.set_font_options].
  *
  * Returns: (transfer none) (nullable): the `cairo_font_options_t`
- *   or %NULL if not set
+ *   of widget
  */
 const cairo_font_options_t *
 gtk_widget_get_font_options (GtkWidget *widget)
@@ -6625,7 +6623,7 @@ gtk_widget_create_pango_context (GtkWidget *widget)
 /**
  * gtk_widget_create_pango_layout:
  * @widget: a `GtkWidget`
- * @text: (nullable): text to set on the layout (can be %NULL)
+ * @text: (nullable): text to set on the layout
  *
  * Creates a new `PangoLayout` with the appropriate font map,
  * font description, and base direction for drawing text for
@@ -7065,8 +7063,8 @@ gtk_widget_set_size_request (GtkWidget *widget,
 /**
  * gtk_widget_get_size_request:
  * @widget: a `GtkWidget`
- * @width: (out) (allow-none): return location for width, or %NULL
- * @height: (out) (allow-none): return location for height, or %NULL
+ * @width: (out) (allow-none): return location for width
+ * @height: (out) (allow-none): return location for height
  *
  * Gets the size request that was explicitly set for the widget using
  * gtk_widget_set_size_request().
@@ -7124,8 +7122,7 @@ gtk_widget_has_size_request (GtkWidget *widget)
  * Note that unlike [method@Gtk.Widget.is_ancestor], this function
  * considers @widget to be an ancestor of itself.
  *
- * Returns: (transfer none) (nullable): the ancestor widget,
- *   or %NULL if not found
+ * Returns: (transfer none) (nullable): the ancestor widget
  */
 GtkWidget*
 gtk_widget_get_ancestor (GtkWidget *widget,
@@ -7152,9 +7149,9 @@ gtk_widget_get_ancestor (GtkWidget *widget,
  * Note that this function can only be called when the `GtkWidget`
  * is attached to a toplevel, since the settings object is specific
  * to a particular `GdkDisplay`. If you want to monitor the widget for
- * changes in its settings, connect to notify::display.
+ * changes in its settings, connect to the `notify::display` signal.
  *
- * Returns: (transfer none): the relevant #GtkSettings object
+ * Returns: (transfer none): the relevant `GtkSettings` object
  */
 GtkSettings*
 gtk_widget_get_settings (GtkWidget *widget)
@@ -7173,7 +7170,7 @@ gtk_widget_get_settings (GtkWidget *widget)
  * possibly with intermediate containers.
  *
  * Returns: %TRUE if @ancestor contains @widget as a child,
- *    grandchild, great grandchild, etc.
+ *   grandchild, great grandchild, etc.
  */
 gboolean
 gtk_widget_is_ancestor (GtkWidget *widget,
@@ -9552,7 +9549,7 @@ gtk_widget_set_margin_bottom (GtkWidget *widget,
  * Note that this function always works, even when @widget is not
  * realized yet.
  *
- * Returns: (transfer none): the appropriate clipboard object.
+ * Returns: (transfer none): the appropriate clipboard object
  */
 GdkClipboard *
 gtk_widget_get_clipboard (GtkWidget *widget)
@@ -9574,7 +9571,7 @@ gtk_widget_get_clipboard (GtkWidget *widget)
  * Note that this function always works, even when @widget is not
  * realized yet.
  *
- * Returns: (transfer none): the appropriate clipboard object.
+ * Returns: (transfer none): the appropriate clipboard object
  **/
 GdkClipboard *
 gtk_widget_get_primary_clipboard (GtkWidget *widget)
@@ -9628,8 +9625,7 @@ gtk_widget_list_mnemonic_labels (GtkWidget *widget)
  * See [method@Gtk.Widget.list_mnemonic_labels]. Note the
  * list of mnemonic labels for the widget is cleared when the
  * widget is destroyed, so the caller must make sure to update
- * its internal state at this point as well, by using a connection
- * to the [signal@Gtk.Widget::destroy] signal or a weak notifier.
+ * its internal state at this point as well.
  */
 void
 gtk_widget_add_mnemonic_label (GtkWidget *widget,
@@ -10116,8 +10112,7 @@ gtk_widget_do_pick (GtkWidget    *widget,
  * @y: Y coordinate to test, relative to @widget's origin
  * @flags: Flags to influence what is picked
  *
- * Finds the descendant of @widget closest
- * to the screen at the point (@x, @y).
+ * Finds the descendant of @widget closest to the point (@x, @y).
  *
  * The point must be given in widget coordinates, so (0, 0) is assumed
  * to be the top left of @widget's content area.
@@ -10133,7 +10128,7 @@ gtk_widget_do_pick (GtkWidget    *widget,
  * delivering events.
  *
  * Returns: (nullable) (transfer none): The widget descendant at
- *   the given coordinate or %NULL if none.
+ *   the given point
  */
 GtkWidget *
 gtk_widget_pick (GtkWidget    *widget,
@@ -10159,10 +10154,11 @@ gtk_widget_pick (GtkWidget    *widget,
  * Computes a matrix suitable to describe a transformation from
  * @widget's coordinate system into @target's coordinate system.
  *
- * Returns: %TRUE if the transform could be computed, %FALSE otherwise.
- *   The transform can not be computed in certain cases, for example when
- *   @widget and @target do not share a common ancestor. In that
- *   case @out_transform gets set to the identity matrix.
+ * The transform can not be computed in certain cases, for example
+ * when @widget and @target do not share a common ancestor. In that
+ * case @out_transform gets set to the identity matrix.
+ *
+ * Returns: %TRUE if the transform could be computed, %FALSE otherwise
  */
 gboolean
 gtk_widget_compute_transform (GtkWidget         *widget,
@@ -10678,7 +10674,7 @@ gtk_widget_class_set_css_name (GtkWidgetClass *widget_class,
  *
  * Gets the name used by this class for matching in CSS code.
  *
- * See gtk_widget_class_set_css_name() for details.
+ * See [method@Gtk.WidgetClass.set_css_name] for details.
  *
  * Returns: the CSS name of the given class
  */
@@ -10749,8 +10745,7 @@ _gtk_widget_peek_style_context (GtkWidget *widget)
  * The returned object is guaranteed to be the same
  * for the lifetime of @widget.
  *
- * Returns: (transfer none): a `GtkStyleContext`. This memory
- *   is owned by @widget and must not be freed.
+ * Returns: (transfer none): the widgets `GtkStyleContext`
  */
 GtkStyleContext *
 gtk_widget_get_style_context (GtkWidget *widget)
@@ -10841,7 +10836,8 @@ _gtk_widget_get_action_muxer (GtkWidget *widget,
  * gtk_widget_insert_action_group:
  * @widget: a `GtkWidget`
  * @name: the prefix for actions in @group
- * @group: (allow-none): a #GActionGroup, or %NULL
+ * @group: (allow-none): a `GActionGroup`, or %NULL to remove
+ *   the previously inserted group for @name
  *
  * Inserts @group into @widget.
  *
@@ -11043,7 +11039,7 @@ out:
 /**
  * gtk_widget_class_set_template:
  * @widget_class: A `GtkWidgetClass`
- * @template_bytes: A #GBytes holding the #GtkBuilder XML
+ * @template_bytes: A `GBytes` holding the `GtkBuilder` XML
  *
  * This should be called at class initialization time to specify
  * the `GtkBuilder` XML to be used to extend a widget.
@@ -11184,7 +11180,7 @@ gtk_widget_class_bind_template_callback_full (GtkWidgetClass *widget_class,
  * this class’s template data.
  *
  * Note that this must be called from a composite widget classes class
- * initializer after calling gtk_widget_class_set_template().
+ * initializer after calling [methoc@GtkWidgetClass.set_template].
  */
 void
 gtk_widget_class_set_template_scope (GtkWidgetClass  *widget_class,
@@ -11203,12 +11199,13 @@ gtk_widget_class_set_template_scope (GtkWidgetClass  *widget_class,
  * @widget_class: A `GtkWidgetClass`
  * @name: The “id” of the child defined in the template XML
  * @internal_child: Whether the child should be accessible as an “internal-child”
- *    when this class is used in GtkBuilder XML
- * @struct_offset: The structure offset into the composite widget’s instance public or private structure
- *    where the automated child pointer should be set, or 0 to not assign the pointer.
+ *   when this class is used in GtkBuilder XML
+ * @struct_offset: The structure offset into the composite widget’s instance
+ *   public or private structure where the automated child pointer should be set,
+ *   or 0 to not assign the pointer.
  *
- * Automatically assign an object declared in the class template XML to be
- * set to a location on a freshly built instance’s private data, or
+ * Automatically assign an object declared in the class template XML to
+ * be set to a location on a freshly built instance’s private data, or
  * alternatively accessible via [method@Gtk.Widget.get_template_child].
  *
  * The struct can point either into the public instance, then you should
@@ -11339,7 +11336,7 @@ gtk_widget_activate_action_variant (GtkWidget  *widget,
  * @widget: a `GtkWidget`
  * @name: the name of the action to activate
  * @format_string: GVariant format string for arguments or %NULL
- *    for no arguments
+ *   for no arguments
  * @...: arguments, as given by format string
  *
  * Looks up the action in the action groups associated
@@ -11432,7 +11429,7 @@ gtk_widget_cancel_event_sequence (GtkWidget             *widget,
  * gtk_widget_add_controller:
  * @widget: a `GtkWidget`
  * @controller: (transfer full): a #GtkEventController that hasn't been
- *     added to a widget yet
+ *   added to a widget yet
  *
  * Adds @controller to @widget so that it will receive events.
  *
@@ -11614,7 +11611,8 @@ gtk_widget_do_snapshot (GtkWidget *widget,
 
   render_node = gtk_widget_create_render_node (widget, snapshot);
   /* This can happen when nested drawing happens and a widget contains itself
-   * or when we replace a clipped area */
+   * or when we replace a clipped area
+   */
   g_clear_pointer (&priv->render_node, gsk_render_node_unref);
   priv->render_node = render_node;
 
@@ -11893,7 +11891,7 @@ gtk_widget_get_prev_sibling (GtkWidget *widget)
  * gtk_widget_insert_after:
  * @widget: a `GtkWidget`
  * @parent: the parent `GtkWidget` to insert @widget into
- * @previous_sibling: (nullable): the new previous sibling of @widget or %NULL
+ * @previous_sibling: (nullable): the new previous sibling of @widget
  *
  * Inserts @widget into the child widget list of @parent.
  *
@@ -11936,7 +11934,7 @@ gtk_widget_insert_after (GtkWidget *widget,
  * gtk_widget_insert_before:
  * @widget: a `GtkWidget`
  * @parent: the parent `GtkWidget` to insert @widget into
- * @next_sibling: (nullable): the new next sibling of @widget or %NULL
+ * @next_sibling: (nullable): the new next sibling of @widget
  *
  * Inserts @widget into the child widget list of @parent.
  *
@@ -11997,17 +11995,17 @@ gtk_widget_forall (GtkWidget   *widget,
  * gtk_widget_snapshot_child:
  * @widget: a `GtkWidget`
  * @child: a child of @widget
- * @snapshot: #GtkSnapshot as passed to the widget. In particular, no
+ * @snapshot: `GtkSnapshot` as passed to the widget. In particular, no
  *   calls to gtk_snapshot_translate() or other transform calls should
  *   have been made.
  *
  * Snapshot the a child of @widget.
  *
  * When a widget receives a call to the snapshot function,
- * it must send synthetic `GtkWidget`Class.snapshot() calls
+ * it must send synthetic [vfunc@Gtk.Widget.snapshot] calls
  * to all children. This function provides a convenient way
  * of doing this. A widget, when it receives a call to its
- * `GtkWidget`Class.snapshot() function, calls
+ * [vfunc@Gtk.Widget.snapshot] function, calls
  * gtk_widget_snapshot_child() once for each child, passing in
  * the @snapshot the widget received.
  *
@@ -12059,12 +12057,10 @@ gtk_widget_snapshot_child (GtkWidget   *widget,
  *
  * Set @child as the current focus child of @widget.
  *
- * The previous focus child will be unset.
- *
  * This function is only suitable for widget implementations.
  * If you want a certain widget to get the input focus, call
  * [method@Gtk.Widget.grab_focus] on it.
-*/
+ */
 void
 gtk_widget_set_focus_child (GtkWidget *widget,
                             GtkWidget *child)
@@ -12096,7 +12092,7 @@ gtk_widget_real_set_focus_child (GtkWidget *widget,
  * Returns the current focus child of @widget.
  *
  * Returns: (nullable) (transfer none): The current focus
- *   child of @widget, or %NULL in case the focus child is unset.
+ *   child of @widget
  */
 GtkWidget *
 gtk_widget_get_focus_child (GtkWidget *widget)
@@ -12111,8 +12107,7 @@ gtk_widget_get_focus_child (GtkWidget *widget)
 /**
  * gtk_widget_set_cursor: (attributes org.gtk.Method.set_property=cursor)
  * @widget: a `GtkWidget`
- * @cursor: (allow-none): the new cursor or %NULL to use
- *   the default cursor
+ * @cursor: (allow-none): the new cursor
  *
  * Sets the cursor to be shown when pointer devices point
  * towards @widget.
@@ -12143,8 +12138,7 @@ gtk_widget_set_cursor (GtkWidget *widget,
 /**
  * gtk_widget_set_cursor_from_name:
  * @widget: a `GtkWidget`
- * @name: (nullable): The name of the cursor or %NULL to use
- *   the default cursor
+ * @name: (nullable): The name of the cursor
  *
  * Sets a named cursor to be shown when pointer devices point
  * towards @widget.
@@ -12187,7 +12181,7 @@ gtk_widget_set_cursor_from_name (GtkWidget  *widget,
  * See [method@Gtk.Widget.set_cursor] for details.
  *
  * Returns: (nullable) (transfer none): the cursor
- *   currently in use or %NULL to use the default.
+ *   currently in use or %NULL if the cursor is inherited
  */
 GdkCursor *
 gtk_widget_get_cursor (GtkWidget *widget)
@@ -12245,9 +12239,9 @@ gtk_widget_get_can_target (GtkWidget *widget)
  *
  * Returns the content width of the widget.
  *
- * This function returns the size passed to its
- * size-allocate implementation, which is the size you
- * should be using in GtkWidgetClass.snapshot().
+ * This function returns the width passed to its
+ * size-allocate implementation, which is the width you
+ * should be using in [vfunc@Gtk.Widget.snapshot].
  *
  * For pointer events, see [method@Gtk.Widget.contains].
  *
@@ -12269,9 +12263,9 @@ gtk_widget_get_width (GtkWidget *widget)
  *
  * Returns the content height of the widget.
  *
- * This function returns the size passed to its
- * size-allocate implementation, which is the size you
- * should be using in GtkWidgetClass.snapshot().
+ * This function returns the height passed to its
+ * size-allocate implementation, which is the height you
+ * should be using in [vfunc@Gtk.Widget.snapshot].
  *
  * For pointer events, see [method@Gtk.Widget.contains].
  *
@@ -12322,8 +12316,8 @@ gtk_widget_get_size (GtkWidget      *widget,
  * @type: The object type that implements the `GtkLayoutManager`
  *   for @widget_class
  *
- * Sets the type to be used for creating layout managers for widgets of
- * @widget_class.
+ * Sets the type to be used for creating layout managers for
+ * widgets of @widget_class.
  *
  * The given @type must be a subtype of [class@Gtk.LayoutManager].
  *
@@ -12349,9 +12343,9 @@ gtk_widget_class_set_layout_manager_type (GtkWidgetClass *widget_class,
  * @widget_class: a `GtkWidgetClass`
  *
  * Retrieves the type of the [class@Gtk.LayoutManager]
- * used by the `GtkWidget` class.
+ * used by widgets of class @widget_class.
  *
- * See also: gtk_widget_class_set_layout_manager_type()
+ * See also: [method@Gtk.WidgetClass.set_layout_manager_type].
  *
  * Returns: type of a `GtkLayoutManager` subclass, or %G_TYPE_INVALID
  */
@@ -12372,9 +12366,8 @@ gtk_widget_class_get_layout_manager_type (GtkWidgetClass *widget_class)
  * @widget: a `GtkWidget`
  * @layout_manager: (nullable) (transfer full): a `GtkLayoutManager`
  *
- * Sets the layout manager delegate instance that
- * provides an implementation for measuring and
- * allocating the children of @widget.
+ * Sets the layout manager delegate instance that provides an
+ * implementation for measuring and allocating the children of @widget.
  */
 void
 gtk_widget_set_layout_manager (GtkWidget        *widget,
@@ -12408,7 +12401,7 @@ gtk_widget_set_layout_manager (GtkWidget        *widget,
  * gtk_widget_get_layout_manager: (attributes org.gtk.Method.get_property=layout-manager)
  * @widget: a `GtkWidget`
  *
- * Retrieves the layout manager used by @widget
+ * Retrieves the layout manager used by @widget.
  *
  * See [method@Gtk.Widget.set_layout_manager].
  *
@@ -12627,16 +12620,18 @@ gtk_widget_action_set_enabled (GtkWidget  *widget,
  * @parameter_type: (out) (nullable): return location for the parameter type
  * @property_name: (out) (nullable): return location for the property name
  *
- * Queries the actions that have been installed for
- * a widget class using [method@Gtk.WidgetClass.install_action]
- * during class initialization.
+ * Returns details about the @index_-th action that has been
+ * installed for @widget_class during class initialization.
+ *
+ * See [method@Gtk.WidgetClass.install_action] for details on
+ * how to install actions.
  *
  * Note that this function will also return actions defined
  * by parent classes. You can identify those by looking
  * at @owner.
  *
- * Returns: %TRUE if the action was found,
- *     %FALSE if @index_ is out of range
+ * Returns: %TRUE if the action was found, %FALSE if @index_
+ *   is out of range
  */
 gboolean
 gtk_widget_class_query_action (GtkWidgetClass      *widget_class,
@@ -12675,7 +12670,7 @@ gtk_widget_class_query_action (GtkWidgetClass      *widget_class,
  * Returns the CSS name that is used for @self.
  *
  * Returns: (transfer none): the CSS name
- **/
+ */
 const char *
 gtk_widget_get_css_name (GtkWidget *self)
 {
@@ -12783,7 +12778,7 @@ gtk_widget_has_css_class (GtkWidget  *widget,
  *
  * Returns: (transfer full): a %NULL-terminated list of
  *   css classes currently applied to @widget. The returned
- *   list can be freed using g_strfreev().
+ *   list must freed using g_strfreev().
  */
 char **
 gtk_widget_get_css_classes (GtkWidget *widget)
@@ -12813,7 +12808,7 @@ gtk_widget_get_css_classes (GtkWidget *widget)
  * @classes: (transfer none) (array zero-terminated=1):
  *   %NULL-terminated list of style classes to apply to @widget.
  *
- * Will clear all style classes applied to @widget
+ * Clear all style classes applied to @widget
  * and replace them with @classes.
  */
 void
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 5d6ba32897..7b7e94d6f6 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -2285,7 +2285,7 @@ gtk_window_set_startup_id (GtkWindow   *window,
  * gtk_window_set_default_widget: (attributes org.gtk.Property.set=default-widget)
  * @window: a `GtkWindow`
  * @default_widget: (allow-none): widget to be the default, or %NULL
- *     to unset the default widget for the toplevel
+ *   to unset the default widget for the toplevel
  *
  * Sets the default widget.
  *
diff --git a/gtk/gtkwindowcontrols.c b/gtk/gtkwindowcontrols.c
index cfdd0171a5..2efabb603c 100644
--- a/gtk/gtkwindowcontrols.c
+++ b/gtk/gtkwindowcontrols.c
@@ -662,8 +662,7 @@ gtk_window_controls_get_decoration_layout (GtkWindowControls *self)
 /**
  * gtk_window_controls_set_decoration_layout: (attributes org.gtk.Method.set_property=decoration-layout)
  * @self: a `GtkWindowControls`
- * @layout: (nullable): a decoration layout, or %NULL to
- *     unset the layout
+ * @layout: (nullable): a decoration layout, or %NULL to unset the layout
  *
  * Sets the decoration layout for the title buttons.
  *