[gtk/ebassi/gidocgen: 51/501] docs: Move detached sections into their own content file

[Emmanuele Bassi <ebassi src gnome org>]

commit 42d55bfc85da645e09409997ef8c9cdc6d5fa420
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Feb 17 17:41:56 2021 +0000

    docs: Move detached sections into their own content file

 docs/reference/gdk/events.md     |  10 ++++
 docs/reference/gdk/gdk4.toml.in  |   6 +++
 docs/reference/gdk/general.md    |  16 ++++++
 docs/reference/gdk/keys.md       | 113 +++++++++++++++++++++++++++++++++++++++
 docs/reference/gdk/macos.md      |  58 ++++++++++++++++++++
 docs/reference/gdk/pango.md      |  93 ++++++++++++++++++++++++++++++++
 docs/reference/gdk/wayland.md    |  48 +++++++++++++++++
 docs/reference/gdk/x11.md        |  47 ++++++++++++++++
 gdk/gdk.c                        |  21 --------
 gdk/gdkcursor.c                  |  29 +++++-----
 gdk/gdkevents.c                  |  13 -----
 gdk/gdkkeys.c                    | 111 --------------------------------------
 gdk/gdkpango.c                   |  95 --------------------------------
 gdk/gdkrectangle.c               |  17 +++---
 gdk/gdkrgba.c                    |   2 +-
 gdk/macos/gdkmacosdisplay.c      |  34 ------------
 gdk/wayland/gdkdisplay-wayland.c |  34 ------------
 gdk/x11/gdkmain-x11.c            |  33 ------------
 18 files changed, 416 insertions(+), 364 deletions(-)
---
diff --git a/docs/reference/gdk/events.md b/docs/reference/gdk/events.md
new file mode 100644
index 0000000000..9925c1dec7
--- /dev/null
+++ b/docs/reference/gdk/events.md
@@ -0,0 +1,10 @@
+Title: Events
+
+## Handling events from the window system
+
+In GTK applications the events are handled automatically by toplevel
+widgets and passed on to the event controllers of appropriate widgets,
+so using [class@Gdk.Event] and its related API is rarely needed.
+
+[class@Gdk.Event] and its derived types are immutable data structures,
+created by GTK itself to represent windowing system events.
diff --git a/docs/reference/gdk/gdk4.toml.in b/docs/reference/gdk/gdk4.toml.in
index cb8f938d79..d8ab5bff5d 100644
--- a/docs/reference/gdk/gdk4.toml.in
+++ b/docs/reference/gdk/gdk4.toml.in
@@ -32,7 +32,13 @@ base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/";
 
 [extra]
 content_files = [
+  "events.md",
+  "keys.md",
   "cairo.md",
+  "pango.md",
+  "wayland.md",
+  "x11.md",
+  "macos.md",
 ]
 content_images = [
   "images/gtk-logo.svg",
diff --git a/docs/reference/gdk/general.md b/docs/reference/gdk/general.md
new file mode 100644
index 0000000000..6e8243b6cc
--- /dev/null
+++ b/docs/reference/gdk/general.md
@@ -0,0 +1,16 @@
+Title: Library initialization and versioning
+
+The GDK and GTK headers annotate deprecated APIs in a way that produces
+compiler warnings if these deprecated APIs are used. The warnings
+can be turned off by defining the macro `GDK_DISABLE_DEPRECATION_WARNINGS`
+before including the `gdk.h` header.
+
+GDK and GTK also provide support for building applications against defined
+subsets of deprecated or new APIs. You can define the macro
+`GDK_VERSION_MIN_REQUIRED` to specify up to what version you want to receive
+warnings about deprecated APIs; and the macro `GDK_VERSION_MAX_ALLOWED` to
+specify the newest version whose API you want to use. If you attempt to use
+a function deprecated before the version of GTK specified in
+`GDK_VERSION_MIN_REQUIRED`, or a function introduced after the version of
+GTK specified in `GDK_VERSION_MAX_ALLOWED`, the compiler will warn you when
+building your code.
diff --git a/docs/reference/gdk/keys.md b/docs/reference/gdk/keys.md
new file mode 100644
index 0000000000..e44d0e13ce
--- /dev/null
+++ b/docs/reference/gdk/keys.md
@@ -0,0 +1,113 @@
+Title: Key Values
+
+## Functions for manipulating keyboard codes
+
+Key values are the codes which are sent whenever a key is pressed or released.
+They are included in the data contained in a key press or release #GdkEvent.
+The complete list of key values can be found in the `gdk/gdkkeysyms.h` header
+file.
+
+Key values are regularly updated from the upstream X.org X11 implementation,
+so new values are added regularly. They will be prefixed with GDK_KEY_ rather
+than XF86XK_ or XK_ (for older symbols).
+
+Key values can be converted into a string representation using
+gdk_keyval_name(). The reverse function, converting a string to a key value,
+is provided by gdk_keyval_from_name().
+
+The case of key values can be determined using gdk_keyval_is_upper() and
+gdk_keyval_is_lower(). Key values can be converted to upper or lower case
+using gdk_keyval_to_upper() and gdk_keyval_to_lower().
+
+When it makes sense, key values can be converted to and from
+Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
+
+## Key groups
+
+At the lowest level, physical keys on the keyboard are represented by
+numeric keycodes, and GDK knows how to translate these keycodes into
+key values according to the configured keyboard layout and the current
+state of the keyboard. In the GDK api, the mapping from keycodes to key
+values is available via [`method@Gdk.Display.map_keycode`], and the reverse
+mapping is available via [`method@Gdk.Display.map_keyval`]. The results of
+these functions are returned in [struct@Gdk.KeymapKey] structures.
+
+You can think of a [struct@Gdk.KeymapKey] as a representation of a symbol
+printed on a physical keyboard key. That is, it contains three pieces of
+information:
+
+  1. first, it contains the hardware keycode; this is an identifying number
+    for a physical key
+  1. second, it contains the “level” of the key. The level indicates which
+    symbol on the key will be used, in a vertical direction. So on a standard
+    US keyboard, the key with the number “1“ on it also has the exclamation
+    point (”!”) character on it. The level indicates whether to use the “1”
+    or the “!” symbol. The letter keys are considered to have a lowercase
+    letter at level 0, and an uppercase letter at level 1, though normally
+    only the uppercase letter is printed on the key
+  1. third, the #GdkKeymapKey contains a group; groups are not used on
+     standard US keyboards, but are used in many other countries. On a
+     keyboard with groups, there can be 3 or 4 symbols printed on a single
+     key. The group indicates movement in a horizontal direction. Usually
+     groups are used for two different languages. In group 0, a key might
+     have two English characters, and in group 1 it might have two Hebrew
+     characters. The Hebrew characters will be printed on the key next to
+     the English characters.
+
+When GDK creates a key event in order to deliver a key press or release,
+it first converts the current keyboard state into an effective group and
+level. This is done via a set of rules that varies widely according to
+type of keyboard and user configuration. The input to this translation
+consists of the hardware keycode pressed, the active modifiers, and the
+active group. It then applies the appropriate rules, and returns the
+group/level to be used to index the keymap, along with the modifiers
+which did not affect the group and level. i.e. it returns “unconsumed
+modifiers.” The keyboard group may differ from the effective group used
+for lookups because some keys don't have multiple groups - e.g. the
+<kbd>Enter</kbd> key is always in group 0 regardless of keyboard state.
+
+The results of the translation, including the keyval, are all included
+in the key event and can be obtained via [class@Gdk.KeyEvent] getters.
+
+### Consumed modifiers
+
+The `consumed_modifiers` in a key event are modifiers that should be masked
+out from @state when comparing this key press to a hot key. For instance,
+on a US keyboard, the `plus` symbol is shifted, so when comparing a key
+press to a `<Control>plus` accelerator `<Shift>` should be masked out.
+
+```c
+// We want to ignore irrelevant modifiers like ScrollLock
+#define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK)
+state = gdk_event_get_modifier_state (event);
+gdk_keymap_translate_keyboard_state (keymap,
+                                     gdk_key_event_get_keycode (event),
+                                     state,
+                                     gdk_key_event_get_group (event),
+                                     &keyval, NULL, NULL, &consumed);
+if (keyval == GDK_PLUS &&
+    (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
+  // Control was pressed
+```
+
+An older interpretation of `consumed_modifiers` was that it contained
+all modifiers that might affect the translation of the key;
+this allowed accelerators to be stored with irrelevant consumed
+modifiers, by doing:
+
+```c
+// XXX Don’t do this XXX
+if (keyval == accel_keyval &&
+    (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
+  // Accelerator was pressed
+```
+
+However, this did not work if multi-modifier combinations were
+used in the keymap, since, for instance, `<Control>` would be
+masked out even if only `<Control><Alt>` was used in
+the keymap. To support this usage as well as well as possible, all single
+modifier combinations that could affect the key for any combination
+of modifiers will be returned in `consumed_modifiers`; multi-modifier
+combinations are returned only when actually found in `state`. When
+you store accelerators, you should always store them with consumed
+modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`.
diff --git a/docs/reference/gdk/macos.md b/docs/reference/gdk/macos.md
new file mode 100644
index 0000000000..1a0429be9d
--- /dev/null
+++ b/docs/reference/gdk/macos.md
@@ -0,0 +1,58 @@
+Title: macOS Interaction
+
+## macOS backend-specific functions
+
+The functions in this section are specific to the GDK macOS backend.
+To use them, you need to include the `<gdk/macos/gdkmacos.h>` header and
+use the macOS-specific pkg-config `gtk4-macos` file to build your
+application.
+
+## Checking for the macOS backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_MACOS
+#include <gdk/macos/gdkmacos.h>
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+
+#ifdef GDK_WINDOWING_MACOS
+  if (GDK_IS_MACOS_DISPLAY (display))
+    {
+      // make macOS-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_MACOS`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For Wayland, the display objects will be of type
+`GdkMacosDisplay`.
diff --git a/docs/reference/gdk/pango.md b/docs/reference/gdk/pango.md
new file mode 100644
index 0000000000..c439530156
--- /dev/null
+++ b/docs/reference/gdk/pango.md
@@ -0,0 +1,93 @@
+ Title: Pango Interaction
+
+Pango is the text layout system used by GDK and GTK. The functions
+and types in this section are used to obtain clip regions for
+`PangoLayout`s, and to get `PangoContext`s that can be used with
+GDK.
+
+## Using Pango in GDK
+
+Creating a `PangoLayout` object is the first step in rendering text,
+and requires getting a handle to a `PangoContext`. For GTK programs,
+you’ll usually want to use `gtk_widget_get_pango_context()`, or
+`gtk_widget_create_pango_layout()`. Once you have a `PangoLayout`,
+you can set the text and attributes of it with Pango functions like
+`pango_layout_set_text()` and get its size with `pango_layout_get_size()`.
+
+*Note*: Pango uses a fixed point system internally, so converting
+between Pango units and pixels using `PANGO_SCALE` or the `PANGO_PIXELS()`
+macro.
+
+Rendering a Pango layout is done most simply with `pango_cairo_show_layout()`;
+you can also draw pieces of the layout with `pango_cairo_show_layout_line()`.
+
+### Draw transformed text with Pango and cairo
+
+```c
+#define RADIUS 100
+#define N_WORDS 10
+#define FONT "Sans Bold 18"
+
+PangoContext *context;
+PangoLayout *layout;
+PangoFontDescription *desc;
+
+double radius;
+int width, height;
+int i;
+
+// Set up a transformation matrix so that the user space coordinates for
+// where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
+// We first center, then change the scale
+
+width = gdk_surface_get_width (surface);
+height = gdk_surface_get_height (surface);
+radius = MIN (width, height) / 2.;
+
+cairo_translate (cr,
+                 radius + (width - 2 * radius) / 2,
+                 radius + (height - 2 * radius) / 2);
+                 cairo_scale (cr, radius / RADIUS, radius / RADIUS);
+
+// Create a PangoLayout, set the font and text
+context = gdk_pango_context_get_for_display (display);
+layout = pango_layout_new (context);
+pango_layout_set_text (layout, "Text", -1);
+desc = pango_font_description_from_string (FONT);
+pango_layout_set_font_description (layout, desc);
+pango_font_description_free (desc);
+
+// Draw the layout N_WORDS times in a circle
+for (i = 0; i < N_WORDS; i++)
+  {
+    double red, green, blue;
+    double angle = 2 * G_PI * i / n_words;
+
+    cairo_save (cr);
+
+    // Gradient from red at angle == 60 to blue at angle == 300
+    red = (1 + cos (angle - 60)) / 2;
+    green = 0;
+    blue = 1 - red;
+
+    cairo_set_source_rgb (cr, red, green, blue);
+    cairo_rotate (cr, angle);
+
+    // Inform Pango to re-layout the text with the new transformation matrix
+    pango_cairo_update_layout (cr, layout);
+
+    pango_layout_get_size (layout, &width, &height);
+
+    cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
+    pango_cairo_show_layout (cr, layout);
+
+    cairo_restore (cr);
+  }
+
+g_object_unref (layout);
+g_object_unref (context);
+```
+
+The example code above will yield the following result:
+
+![](rotated-text.png)
diff --git a/docs/reference/gdk/wayland.md b/docs/reference/gdk/wayland.md
new file mode 100644
index 0000000000..040e96a4e9
--- /dev/null
+++ b/docs/reference/gdk/wayland.md
@@ -0,0 +1,48 @@
+Title: Wayland Interaction
+
+## Wayland backend-specific functions
+
+The functions in this section are specific to the GDK Wayland backend.
+To use them, you need to include the `<gdk/wayland/gdkwayland.h>` header and
+use the Wayland-specific pkg-config `gtk4-wayland` file to build your
+application.
+
+## Checking for the Wayland backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_WAYLAND`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For Wayland, the display objects will be of type
+`GdkWaylandDisplay`.
diff --git a/docs/reference/gdk/x11.md b/docs/reference/gdk/x11.md
new file mode 100644
index 0000000000..6602e24b82
--- /dev/null
+++ b/docs/reference/gdk/x11.md
@@ -0,0 +1,47 @@
+Title: X Window System Interaction
+
+## X backend-specific functions
+
+The functions in this section are specific to the GDK X11 backend.
+To use them, you need to include the `<gdk/x11/gdkx.h>` header and use
+the X11-specific pkg-config file `gtk4-x11` to build your application.
+
+## Checking for the X11 backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For X11, the symbol is `GDK_WINDOWING_X11`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For X11, the display objects will be of type
+`GdkX11Display`.
diff --git a/gdk/gdk.c b/gdk/gdk.c
index a0938af58a..5cd0e1922d 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -47,27 +47,6 @@
 #include <fribidi.h>
 
 
-/**
- * SECTION:general
- * @Short_description: Library initialization and versioning
- * @Title: General
- *
- * This section describes miscellaneous macros and utility functions
- * related to library versioning, as well as deprecation facilities.
- *
- * The GDK and GTK headers annotate deprecated APIs in a way that produces
- * compiler warnings if these deprecated APIs are used. The warnings
- * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS
- * before including the glib.h header.
- *
- * GDK and GTK also provide support for building applications against
- * defined subsets of deprecated or new APIs. Define the macro
- * %GDK_VERSION_MIN_REQUIRED to specify up to what version
- * you want to receive warnings about deprecated APIs. Define the
- * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version
- * whose API you want to use.
- */
-
 /**
  * GDK_WINDOWING_X11:
  *
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index a0d5bc276d..ebb87c5c7b 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -37,37 +37,38 @@
 #include <errno.h>
 
 /**
- * SECTION:cursors
+ * SECTION:gdkcursor
  * @Short_description: Named and texture cursors
  * @Title: Cursors
  *
- * These functions are used to create and destroy cursors. Cursors
- * are immutable objects, so once you created them, there is no way
- * to modify them later. Create a new cursor when you want to change
- * something about it.
+ * `GdkCursor` is used to create and destroy cursors. Cursors are immutable
+ * objects, so once you created them, there is no way to modify them later.
+ * You should create a new cursor when you want to change something about
+ * it.
  *
- * Cursors by themselves are not very interesting, they must be
- * bound to a window for users to see them. This is done with
- * gdk_surface_set_cursor() or gdk_surface_set_device_cursor().
- * Applications will typically use higher-level GTK functions such
- * as gtk_widget_set_cursor() instead.
+ * Cursors by themselves are not very interesting: they must be bound to a
+ * window for users to see them. This is done with [method@Gdk.Surface.set_cursor]
+ * or [method@Gdk.Surface.set_device_cursor]. Applications will typically
+ * use higher-level GTK functions such as `gtk_widget_set_cursor()` instead.
  *
- * Cursors are not bound to a given #GdkDisplay, so they can be shared.
+ * Cursors are not bound to a given [class@Gdk.Display], so they can be shared.
  * However, the appearance of cursors may vary when used on different
  * platforms.
  *
+ * ## Named and texture cursors
+ *
  * There are multiple ways to create cursors. The platform's own cursors
- * can be created with gdk_cursor_new_from_name(). That function lists
+ * can be created with [ctor@Gdk.Cursor.new_from_name]. That function lists
  * the commonly available names that are shared with the CSS specification.
  * Other names may be available, depending on the platform in use. On some
  * platforms, what images are used for named cursors may be influenced by
  * the cursor theme.
  *
- * Another option to create a cursor is to use gdk_cursor_new_from_texture()
+ * Another option to create a cursor is to use [ctor@Gdk.Cursor.new_from_texture]
  * and provide an image to use for the cursor.
  *
  * To ease work with unsupported cursors, a fallback cursor can be provided.
- * If a #GdkSurface cannot use a cursor because of the reasons mentioned above,
+ * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above,
  * it will try the fallback cursor. Fallback cursors can themselves have fallback
  * cursors again, so it is possible to provide a chain of progressively easier
  * to support cursors. If none of the provided cursors can be supported, the
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 2ce34f80ec..43692c4f95 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -38,19 +38,6 @@
 #include <string.h>
 #include <math.h>
 
-/**
- * SECTION:events
- * @Short_description: Functions for handling events from the window system
- * @Title: Events
- *
- * This section describes functions dealing with events from the window
- * system.
- *
- * In GTK applications the events are handled automatically by toplevel
- * widgets and passed on to the event controllers of appropriate widgets,
- * so these functions are rarely needed.
- */
-
 /**
  * GdkEvent: (ref-func gdk_event_ref) (unref-func gdk_event_unref)
  *
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 0c74dd64f4..f25647f74f 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -29,117 +29,6 @@
 #include "gdkdisplay.h"
 #include "gdkdisplaymanagerprivate.h"
 
-
-/**
- * SECTION:keys
- * @Short_description: Functions for manipulating keyboard codes
- * @Title: Key Values
- *
- * Key values are the codes which are sent whenever a key is pressed or released.
- * They are included in the data contained in a key press or release #GdkEvent.
- * The complete list of key values can be found in the `gdk/gdkkeysyms.h` header
- * file.
- *
- * Key values are regularly updated from the upstream X.org X11 implementation,
- * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
- * than XF86XK_ or XK_ (for older symbols).
- *
- * Key values can be converted into a string representation using
- * gdk_keyval_name(). The reverse function, converting a string to a key value,
- * is provided by gdk_keyval_from_name().
- *
- * The case of key values can be determined using gdk_keyval_is_upper() and
- * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
- * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
- *
- * When it makes sense, key values can be converted to and from
- * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
- *
- * # Groups # {#key-group-explanation}
- *
- * At the lowest level, physical keys on the keyboard are represented by
- * numeric keycodes, and GDK knows how to translate these keycodes into
- * key values according to the configured keyboard layout and the current
- * state of the keyboard. In the GDK api, the mapping from keycodes to key
- * values is available via gdk_display_map_keycode(), and the reverse mapping
- * is available via gdk_display_map_keyval(). The results of these functions
- * are returned in #GdkKeymapKey structs.
- *
- * You can think of a #GdkKeymapKey as a representation of a symbol printed on
- * a physical keyboard key. That is, it contains three pieces of information.
- * First, it contains the hardware keycode; this is an identifying number for
- * a physical key. Second, it contains the “level” of the key. The level indicates
- * which symbol on the key will be used, in a vertical direction. So on a standard
- * US keyboard, the key with the number “1“ on it also has the exclamation point
- * (”!”) character on it. The level indicates whether to use the “1” or the “!”
- * symbol. The letter keys are considered to have a lowercase letter at level 0,
- * and an uppercase letter at level 1, though normally only the uppercase letter
- * is printed on the key. Third, the #GdkKeymapKey contains a group; groups are
- * not used on standard US keyboards, but are used in many other countries. On a
- * keyboard with groups, there can be 3 or 4 symbols printed on a single key.
- * The group indicates movement in a horizontal direction. Usually groups are
- * used for two different languages. In group 0, a key might have two English
- * characters, and in group 1 it might have two Hebrew characters. The Hebrew
- * characters will be printed on the key next to the English characters.
- *
- * When GDK creates a key event in order to deliver a key press or release,
- * it first converts the current keyboard state into an effective group and
- * level. This is done via a set of rules that varies widely according to
- * type of keyboard and user configuration. The input to this translation
- * consists of the hardware keycode pressed, the active modifiers, and the
- * active group. It then applies the appropriate rules, and returns the
- * group/level to be used to index the keymap, along with the modifiers
- * which did not affect the group and level. i.e. it returns “unconsumed
- * modifiers.” The keyboard group may differ from the effective group used
- * for lookups because some keys don't have multiple groups - e.g. the Enter
- * key is always in group 0 regardless of keyboard state.
- *
- * The results of the translation, including the keyval, are all included
- * in the key event and can be obtained via #GdkEvent getters.
- *
- * # Consumed modifiers
- *
- * The @consumed_modifiers in a key event are modifiers that should be masked
- * out from @state when comparing this key press to a hot key. For instance,
- * on a US keyboard, the `plus` symbol is shifted, so when comparing a key
- * press to a `<Control>plus` accelerator `<Shift>` should be masked out.
- *
- * |[<!-- language="C" -->
- * // We want to ignore irrelevant modifiers like ScrollLock
- * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK)
- * state = gdk_event_get_modifier_state (event);
- * gdk_keymap_translate_keyboard_state (keymap,
- *                                      gdk_key_event_get_keycode (event),
- *                                      state,
- *                                      gdk_key_event_get_group (event),
- *                                      &keyval, NULL, NULL, &consumed);
- * if (keyval == GDK_PLUS &&
- *     (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
- *   // Control was pressed
- * ]|
- *
- * An older interpretation @consumed_modifiers was that it contained
- * all modifiers that might affect the translation of the key;
- * this allowed accelerators to be stored with irrelevant consumed
- * modifiers, by doing:
- * |[<!-- language="C" -->
- * // XXX Don’t do this XXX
- * if (keyval == accel_keyval &&
- *     (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
- *   // Accelerator was pressed
- * ]|
- *
- * However, this did not work if multi-modifier combinations were
- * used in the keymap, since, for instance, `<Control>` would be
- * masked out even if only `<Control><Alt>` was used in the keymap.
- * To support this usage as well as well as possible, all single
- * modifier combinations that could affect the key for any combination
- * of modifiers will be returned in @consumed_modifiers; multi-modifier
- * combinations are returned only when actually found in @state. When
- * you store accelerators, you should always store them with consumed
- * modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`.
- */
-
 enum {
   PROP_0,
   PROP_DISPLAY,
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index e050b985c6..5c25b3521b 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -25,101 +25,6 @@
 #include <pango/pangocairo.h>
 
 
-/**
- * SECTION:pango_interaction
- * @Short_description: Using Pango in GDK
- * @Title: Pango Interaction
- *
- * Pango is the text layout system used by GDK and GTK. The functions
- * and types in this section are used to obtain clip regions for
- * #PangoLayouts, and to get #PangoContexts that can be used with
- * GDK.
- *
- * Creating a #PangoLayout object is the first step in rendering text,
- * and requires getting a handle to a #PangoContext. For GTK programs,
- * you’ll usually want to use gtk_widget_get_pango_context(), or
- * gtk_widget_create_pango_layout(). Once you have a #PangoLayout,
- * you can set the text and attributes of it with Pango functions like
- * pango_layout_set_text() and get its size with pango_layout_get_size().
- * (Note that Pango uses a fixed point system internally, so converting
- * between Pango units and pixels using [PANGO_SCALE][PANGO-SCALE-CAPS]
- * or the PANGO_PIXELS() macro.)
- *
- * Rendering a Pango layout is done most simply with pango_cairo_show_layout();
- * you can also draw pieces of the layout with pango_cairo_show_layout_line().
- *
- * ## Draw transformed text with Pango and cairo ## {#rotated-example}
- *
- * |[<!-- language="C" -->
- * #define RADIUS 100
- * #define N_WORDS 10
- * #define FONT "Sans Bold 18"
- *
- * PangoContext *context;
- * PangoLayout *layout;
- * PangoFontDescription *desc;
- *
- * double radius;
- * int width, height;
- * int i;
- *
- * // Set up a transformation matrix so that the user space coordinates for
- * // where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
- * // We first center, then change the scale
- *
- * width = gdk_surface_get_width (surface);
- * height = gdk_surface_get_height (surface);
- * radius = MIN (width, height) / 2.;
- *
- * cairo_translate (cr,
- *                  radius + (width - 2 * radius) / 2,
- *                  radius + (height - 2 * radius) / 2);
- *                  cairo_scale (cr, radius / RADIUS, radius / RADIUS);
- *
- * // Create a PangoLayout, set the font and text
- * context = gdk_pango_context_get_for_display (display);
- * layout = pango_layout_new (context);
- * pango_layout_set_text (layout, "Text", -1);
- * desc = pango_font_description_from_string (FONT);
- * pango_layout_set_font_description (layout, desc);
- * pango_font_description_free (desc);
- *
- * // Draw the layout N_WORDS times in a circle
- * for (i = 0; i < N_WORDS; i++)
- *   {
- *     double red, green, blue;
- *     double angle = 2 * G_PI * i / n_words;
- *
- *     cairo_save (cr);
- *
- *     // Gradient from red at angle == 60 to blue at angle == 300
- *     red = (1 + cos (angle - 60)) / 2;
- *     green = 0;
- *     blue = 1 - red;
- *
- *     cairo_set_source_rgb (cr, red, green, blue);
- *     cairo_rotate (cr, angle);
- *
- *     // Inform Pango to re-layout the text with the new transformation matrix
- *     pango_cairo_update_layout (cr, layout);
- *
- *     pango_layout_get_size (layout, &width, &height);
- *
- *     cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
- *     pango_cairo_show_layout (cr, layout);
- *
- *     cairo_restore (cr);
- *   }
- *
- * g_object_unref (layout);
- * g_object_unref (context);
- * ]|
- *
- * ## Output of the [example][rotated-example] above.
- *
- * ![](rotated-text.png)
- */
-
 /* Get a clip region to draw only part of a layout. index_ranges
  * contains alternating range starts/stops. The region is the
  * region which contains the given ranges, i.e. if you draw with the
diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c
index 8043716044..83b77429cf 100644
--- a/gdk/gdkrectangle.c
+++ b/gdk/gdkrectangle.c
@@ -29,23 +29,24 @@
 
 
 /**
- * SECTION:regions
+ * SECTION:gdkregion
  * @Short_description: Simple graphical data type
  * @Title: GdkRectangle
  *
- * GDK provides a #GdkRectangle data type for representing rectangles.
- * Together with Cairo’s #cairo_region_t data type, these are the central
+ * GDK provides a `GdkRectangle` data type for representing rectangles.
+ * Together with Cairo’s `cairo_region_t` data type, these are the central
  * types for representing sets of pixels.
  *
  * A #GdkRectangle represents the position and size of a rectangle.
+ *
  * The intersection of two rectangles can be computed with
- * gdk_rectangle_intersect(). To find the union of two rectangles use
- * gdk_rectangle_union().
+ * [method@Gdk.Rectangle.intersect]; to find the union of two rectangles use
+ * [method@Gdk.Rectangle.union].
  *
- * #cairo_region_t is usually used for managing clipping of graphical
- * operations.
+ * The `cairo_region_t` type provided by Cairo is usually used for managing
+ * non-rectangular clipping of graphical operations.
  *
- * The graphene library has a number of other data types for regions and
+ * The Graphene library has a number of other data types for regions and
  * volumes in 2D and 3D.
  */
 
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index 1de2bd45a9..a2525591c9 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -31,7 +31,7 @@
 #include <math.h>
 
 /**
- * SECTION:rgba_colors
+ * SECTION:gdkrgba
  * @Title: GdkRGBA
  * @Short_description: RGBA colors
  *
diff --git a/gdk/macos/gdkmacosdisplay.c b/gdk/macos/gdkmacosdisplay.c
index ea07215794..ed15a49bf2 100644
--- a/gdk/macos/gdkmacosdisplay.c
+++ b/gdk/macos/gdkmacosdisplay.c
@@ -38,40 +38,6 @@
 #include "gdkmacossurface-private.h"
 #include "gdkmacosutils-private.h"
 
-/**
- * SECTION:macos_interaction
- * @Short_description: macOS backend-specific functions
- * @Title: macOS Interaction
- * @Include: gdk/macos/gdkmacos.h
- *
- * The functions in this section are specific to the GDK macOS backend.
- * To use them, you need to include the `<gdk/macos/gdkmacos.h>` header and
- * use the macOS-specific pkg-config `gtk4-macos` file to build your
- * application.
- *
- * To make your code compile with other GDK backends, guard backend-specific
- * calls by an ifdef as follows. Since GDK may be built with multiple
- * backends, you should also check for the backend that is in use (e.g. by
- * using the GDK_IS_MACOS_DISPLAY() macro).
- * |[<!-- language="C" -->
- * #ifdef GDK_WINDOWING_MACOS
- *   if (GDK_IS_MACOS_DISPLAY (display))
- *     {
- *       // make macOS-specific calls here
- *     }
- *   else
- * #endif
- * #ifdef GDK_WINDOWING_X11
- *   if (GDK_IS_X11_DISPLAY (display))
- *     {
- *       // make X11-specific calls here
- *     }
- *   else
- * #endif
- *   g_error ("Unsupported GDK backend");
- * ]|
- */
-
 G_DEFINE_TYPE (GdkMacosDisplay, gdk_macos_display, GDK_TYPE_DISPLAY)
 
 #define EVENT_MAP_MAX_SIZE 10
diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c
index 9448beda2d..673c9d3478 100644
--- a/gdk/wayland/gdkdisplay-wayland.c
+++ b/gdk/wayland/gdkdisplay-wayland.c
@@ -58,40 +58,6 @@
 
 #include "gdk/gdk-private.h"
 
-/**
- * SECTION:wayland_interaction
- * @Short_description: Wayland backend-specific functions
- * @Title: Wayland Interaction
- * @Include: gdk/wayland/gdkwayland.h
- *
- * The functions in this section are specific to the GDK Wayland backend.
- * To use them, you need to include the `<gdk/wayland/gdkwayland.h>` header and
- * use the Wayland-specific pkg-config `gtk4-wayland` file to build your
- * application.
- *
- * To make your code compile with other GDK backends, guard backend-specific
- * calls by an ifdef as follows. Since GDK may be built with multiple
- * backends, you should also check for the backend that is in use (e.g. by
- * using the GDK_IS_WAYLAND_DISPLAY() macro).
- * |[<!-- language="C" -->
- * #ifdef GDK_WINDOWING_WAYLAND
- *   if (GDK_IS_WAYLAND_DISPLAY (display))
- *     {
- *       // make Wayland-specific calls here
- *     }
- *   else
- * #endif
- * #ifdef GDK_WINDOWING_X11
- *   if (GDK_IS_X11_DISPLAY (display))
- *     {
- *       // make X11-specific calls here
- *     }
- *   else
- * #endif
- *   g_error ("Unsupported GDK backend");
- * ]|
- */
-
 #define MIN_SYSTEM_BELL_DELAY_MS 20
 
 #define GTK_SHELL1_VERSION       4
diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c
index 7c5fbf2763..8fc8253295 100644
--- a/gdk/x11/gdkmain-x11.c
+++ b/gdk/x11/gdkmain-x11.c
@@ -46,39 +46,6 @@
 #include <X11/XKBlib.h>
 #endif
 
-/**
- * SECTION:x_interaction
- * @Short_description: X backend-specific functions
- * @Title: X Window System Interaction
- * @Include: gdk/x11/gdkx.h
- *
- * The functions in this section are specific to the GDK X11 backend.
- * To use them, you need to include the `<gdk/x11/gdkx.h>` header and use
- * the X11-specific pkg-config file `gtk4-x11` to build your application.
- *
- * To make your code compile with other GDK backends, guard backend-specific
- * calls by an ifdef as follows. Since GDK may be built with multiple
- * backends, you should also check for the backend that is in use (e.g. by
- * using the GDK_IS_X11_DISPLAY() macro).
- * |[
- * #ifdef GDK_WINDOWING_X11
- *   if (GDK_IS_X11_DISPLAY (display))
- *     {
- *       // make X11-specific calls here
- *     }
- *   else
- * #endif
- * #ifdef GDK_WINDOWING_MACOS
- *   if (GDK_IS_MACOS_DISPLAY (display))
- *     {
- *       // make MacOS-specific calls here
- *     }
- *   else
- * #endif
- *   g_error ("Unsupported GDK backend");
- * ]|
- */
-
 /* non-GDK previous error handler */
 typedef int (*GdkXErrorHandler) (Display *, XErrorEvent *);
 static GdkXErrorHandler _gdk_old_error_handler;