fixup: use cache dir

This tests the GtkApplication state saving support.

.gitlab-ci.yml

@@ -24,9 +24,9 @@ variables:
   BACKEND_FLAGS: "-Dx11-backend=true -Dwayland-backend=true -Dbroadway-backend=true"
   FEATURE_FLAGS: "-Dvulkan=enabled -Dcloudproviders=enabled"
   MESON_TEST_TIMEOUT_MULTIPLIER: 3
-  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v29"
+  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v31"
   FLATPAK_IMAGE: "registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master"
-  DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v29"
+  DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v31"
 
 .only-default:
   only:
@@ -77,6 +77,7 @@ fedora-x86_64:
   variables:
     EXTRA_MESON_FLAGS: "--buildtype=debug --default-library=both"
   script:
+    - .gitlab-ci/show-info-linux.sh
     - meson subprojects update
     - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} ${BACKEND_FLAGS} ${FEATURE_FLAGS}
             _build
@@ -92,6 +93,7 @@ release-build:
   variables:
     EXTRA_MESON_FLAGS: "--buildtype=release"
   script:
+    - .gitlab-ci/show-info-linux.sh
     - meson subprojects update
     - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} ${BACKEND_FLAGS} ${FEATURE_FLAGS}
             _build
@@ -106,6 +108,7 @@ installed-tests:
     EXTRA_MESON_FLAGS: "--prefix=/usr --libdir=/usr/lib64 -Dinstall-tests=true"
     G_TEST_ACCESSIBLE: 1
   script:
+    - .gitlab-ci/show-info-linux.sh
     - meson subprojects update
     - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} ${BACKEND_FLAGS} ${FEATURE_FLAGS}
             _build
@@ -155,7 +158,7 @@ macos:
     - macos
   needs: []
   before_script:
-    - bash .gitlab-ci/show-execution-environment.sh
+    - bash .gitlab-ci/show-info-osx.sh
     - pip3 install --user meson==0.56
     - pip3 install --user ninja
     - export PATH=/Users/gitlabrunner/Library/Python/3.7/bin:$PATH
@@ -172,6 +175,22 @@ macos:
     paths:
       - "${CI_PROJECT_DIR}/_build/meson-logs"
 
+vs2017-x64:
+  extends: .only-default
+  # TODO: Uncomment this when ready to merge.
+  #only:
+  #  - branches@GNOME/gtk
+  stage: build
+  tags:
+    - win32-ps
+  needs: []
+  script:
+    - .gitlab-ci/test-msvc.bat
+  artifacts:
+    when: always
+    paths:
+      - "${CI_PROJECT_DIR}/_build/meson-logs"
+
 .flatpak-defaults:
   image: $FLATPAK_IMAGE
   stage: flatpak

.gitlab-ci/fedora.Dockerfile

@@ -1,4 +1,4 @@
-FROM fedora:33
+FROM fedora:34
 
 RUN dnf -y install \
     adwaita-icon-theme \
@@ -10,6 +10,7 @@ RUN dnf -y install \
     ccache \
     clang \
     clang-analyzer \
+    clang-tools-extra \
     colord-devel \
     cups-devel \
     dbus-daemon \
@@ -73,6 +74,7 @@ RUN dnf -y install \
     pcre-devel \
     pcre-static \
     python3 \
+    python3-gobject \
     python3-jinja2 \
     python3-markdown \
     python3-pip \

.gitlab-ci/flatpak-build.sh

@@ -24,6 +24,7 @@ flatpak build ${builddir} meson \
                 -Dbuild-examples=false \
                 -Dintrospection=disabled \
                 -Ddemos=true \
+                -Dprofile=devel \
                 _flatpak_build
 
 flatpak build ${builddir} ninja -C _flatpak_build install

.gitlab-ci/show-info-linux.sh

@@ -0,0 +1,5 @@
+#! /bin/sh
+
+. /etc/os-release
+
+echo $PRETTY_NAME

.gitlab-ci/test-msvc.bat

@@ -0,0 +1,14 @@
+@echo on
+:: vcvarsall.bat sets various env vars like PATH, INCLUDE, LIB, LIBPATH for the
+:: specified build architecture
+call "C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+@echo on
+
+:: FIXME: make warnings fatal
+pip3 install --upgrade --user meson==0.56.2  || goto :error
+meson _build || goto :error
+ninja -C _build || goto :error
+
+goto :EOF
+:error
+exit /b 1

build-aux/flatpak/org.gtk.Demo4.json

@@ -104,7 +104,7 @@
              "sources": [
                  {
                      "type": "archive",
-                     "url": "https://dl.bintray.com/boostorg/release/1.69.0/source/boost_1_69_0.tar.bz2",
+                     "url": "https://boostorg.jfrog.io/artifactory/main/release/1.69.0/source/boost_1_69_0.tar.bz2",
                      "sha256": "8f32d4617390d1c2d16f26a27ab60d97807b35440d45891fa340fc2648b04406"
                  }
             ]

build-aux/meson/gen-demo-header.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import os
+import subprocess
+import sys
+
+repodir = sys.argv[1]
+profile = sys.argv[2]
+
+sys.stdout.write("/* This file is auto-generated. Do not edit. */\n")
+sys.stdout.write("#pragma once\n")
+sys.stdout.write("\n")
+sys.stdout.write(f"#define PROFILE \"{profile}\"\n")
+
+short_sha = os.environ.get('CI_COMMIT_SHORT_SHA')
+if short_sha is None:
+    cmd = ["git", "-C", repodir, "rev-parse", "--short", "HEAD"]
+    try:
+        with subprocess.Popen(cmd, stdout=subprocess.PIPE) as p:
+            short_sha = p.stdout.read().decode('utf-8').rstrip("\n")
+    except FileNotFoundError:
+        short_sha = ''
+        if profile != 'default':
+            short_sha = 'devel'
+
+sys.stdout.write(f"#define VCS_TAG \"{short_sha}\"\n")

config.h.meson

@@ -284,3 +284,6 @@
 #mesondefine HAVE_TRACKER3
 
 #mesondefine HAVE_F16C
+
+/* Does the OS support GDesktopAppInfo? */
+#mesondefine HAVE_DESKTOPAPPINFO

demos/gtk-demo/fishbowl.ui

@@ -13,13 +13,13 @@
             </style>
             <child>
               <object class="GtkButton">
-                <property name="icon-name">pan-start-symbolic</property>
+                <property name="icon-name">go-previous-symbolic</property>
                 <signal name="clicked" handler="fishbowl_prev_button_clicked_cb" object="bowl" swapped="no"/>
               </object>
             </child>
             <child>
               <object class="GtkButton">
-                <property name="icon-name">pan-end-symbolic</property>
+                <property name="icon-name">go-next-symbolic</property>
                 <signal name="clicked" handler="fishbowl_next_button_clicked_cb" object="bowl" swapped="no"/>
               </object>
             </child>

demos/gtk-demo/font-features.ui

@@ -10,12 +10,8 @@
           <object class="GtkButton" id="reset">
             <property name="receives-default">1</property>
             <property name="tooltip-text">Reset</property>
+            <property name="icon-name">view-refresh-symbolic</property>
             <signal name="clicked" handler="font_features_reset_features" swapped="no"/>
-            <child>
-              <object class="GtkImage">
-                <property name="icon-name">view-refresh-symbolic</property>
-              </object>
-            </child>
           </object>
         </child>
       </object>

demos/gtk-demo/font_features.c

@@ -1136,7 +1136,7 @@ done:
   g_free (design_coords);
 }
 
-void
+G_MODULE_EXPORT void
 font_features_font_changed (void)
 {
   update_script_combo ();
@@ -1144,14 +1144,14 @@ font_features_font_changed (void)
   update_font_variations ();
 }
 
-void
+G_MODULE_EXPORT void
 font_features_script_changed (void)
 {
   update_features ();
   update_display ();
 }
 
-void
+G_MODULE_EXPORT void
 font_features_reset_features (void)
 {
   GList *l;
@@ -1197,7 +1197,7 @@ switch_to_label (void)
   update_display ();
 }
 
-void
+G_MODULE_EXPORT void
 font_features_toggle_edit (void)
 {
   if (strcmp (gtk_stack_get_visible_child_name (GTK_STACK (stack)), "label") == 0)
@@ -1206,7 +1206,7 @@ font_features_toggle_edit (void)
     switch_to_label ();
 }
 
-void
+G_MODULE_EXPORT void
 font_features_stop_edit (void)
 {
   g_signal_emit_by_name (edit_toggle, "clicked");

demos/gtk-demo/gskshaderpaintable.c

@@ -23,13 +23,10 @@
 #include "gskshaderpaintable.h"
 
 /**
- * SECTION:gskshaderpaintable
- * @Short_description: Drawing with shaders
- * @Title: GskShaderPaintable
- * @see_also: #GdkPaintable
+ * GskShaderPaintable:
  *
- * GskShaderPaintable is an implementation of the #GdkPaintable interface
- * that uses a #GskGLShader to create pixels.
+ * `GskShaderPaintable` is an implementation of the `GdkPaintable` interface
+ * that uses a `GskGLShader` to create pixels.
  *
  * You can set the uniform data that the shader needs for rendering
  * using gsk_shader_paintable_set_args(). This function can
@@ -38,7 +35,7 @@
  *
  * Commonly, time is passed to shaders as a float uniform containing
  * the elapsed time in seconds. The convenience API
- * gsk_shader_paintable_update_time() can be called from a #GtkTickCallback
+ * gsk_shader_paintable_update_time() can be called from a `GtkTickCallback`
  * to update the time based on the frame time of the frame clock.
  */
 
@@ -186,7 +183,7 @@ gsk_shader_paintable_init (GskShaderPaintable *self)
  * pixels. The shader must not require input textures.
  * If @data is %NULL, all uniform values are set to zero.
  *
- * Returns: (transfer full): a new #GskShaderPaintable
+ * Returns: (transfer full): a new `GskShaderPaintable`
  */
 GdkPaintable *
 gsk_shader_paintable_new (GskGLShader *shader,
@@ -215,8 +212,8 @@ gsk_shader_paintable_new (GskGLShader *shader,
 
 /**
  * gsk_shader_paintable_set_shader:
- * @self: a #GskShaderPaintable
- * @shader: the #GskGLShader to use
+ * @self: a `GskShaderPaintable`
+ * @shader: the `GskGLShader` to use
  *
  * Sets the shader that the paintable will use
  * to create pixels. The shader must not require
@@ -241,11 +238,11 @@ gsk_shader_paintable_set_shader (GskShaderPaintable *self,
 
 /**
  * gsk_shader_paintable_get_shader:
- * @self: a #GskShaderPaintable
+ * @self: a `GskShaderPaintable`
  *
  * Returns the shader that the paintable is using.
  *
- * Returns: (transfer none): the #GskGLShader that is used
+ * Returns: (transfer none): the `GskGLShader` that is used
  */
 GskGLShader *
 gsk_shader_paintable_get_shader (GskShaderPaintable *self)
@@ -257,12 +254,12 @@ gsk_shader_paintable_get_shader (GskShaderPaintable *self)
 
 /**
  * gsk_shader_paintable_set_args:
- * @self: a #GskShaderPaintable
+ * @self: a `GskShaderPaintable`
  * @data: Data block with uniform data for the shader
  *
  * Sets the uniform data that will be passed to the
  * shader when rendering. The @data will typically
- * be produced by a #GskUniformDataBuilder.
+ * be produced by a `GskUniformDataBuilder`.
  *
  * Note that the @data should be considered immutable
  * after it has been passed to this function.
@@ -284,7 +281,7 @@ gsk_shader_paintable_set_args (GskShaderPaintable *self,
 
 /**
  * gsk_shader_paintable_get_args:
- * @self: a #GskShaderPaintable
+ * @self: a `GskShaderPaintable`
  *
  * Returns the uniform data set with
  * gsk_shader_paintable_get_args().
@@ -301,9 +298,9 @@ gsk_shader_paintable_get_args (GskShaderPaintable *self)
 
 /**
  * gsk_shader_paintable_update_time:
- * @self: a #GskShaderPaintable
+ * @self: a `GskShaderPaintable`
  * @time_idx: the index of the uniform for time in seconds as float
- * @frame_time: the current frame time, as returned by #GdkFrameClock
+ * @frame_time: the current frame time, as returned by `GdkFrameClock`
  *
  * This function is a convenience wrapper for
  * gsk_shader_paintable_set_args() that leaves all
@@ -311,7 +308,7 @@ gsk_shader_paintable_get_args (GskShaderPaintable *self)
  * index @time_idx, which will be set to the elapsed time
  * in seconds, since the first call to this function.
  *
- * This function is usually called from a #GtkTickCallback.
+ * This function is usually called from a `GtkTickCallback`.
  */
 void
 gsk_shader_paintable_update_time (GskShaderPaintable *self,

demos/gtk-demo/gtkfishbowl.c

@@ -74,9 +74,9 @@ gtk_fishbowl_init (GtkFishbowl *fishbowl)
 /**
  * gtk_fishbowl_new:
  *
- * Creates a new #GtkFishbowl.
+ * Creates a new `GtkFishbowl`.
  *
- * Returns: a new #GtkFishbowl.
+ * Returns: a new `GtkFishbowl`.
  */
 GtkWidget*
 gtk_fishbowl_new (void)

demos/gtk-demo/headerbar.c

@@ -18,8 +18,6 @@ do_headerbar (GtkWidget *do_widget)
   GtkWidget *header;
   GtkWidget *button;
   GtkWidget *box;
-  GtkWidget *image;
-  GIcon *icon;
 
   if (!window)
     {
@@ -32,20 +30,14 @@ do_headerbar (GtkWidget *do_widget)
 
       header = gtk_header_bar_new ();
 
-      button = gtk_button_new ();
-      icon = g_themed_icon_new ("mail-send-receive-symbolic");
-      image = gtk_image_new_from_gicon (icon);
-      g_object_unref (icon);
-      gtk_button_set_child (GTK_BUTTON (button), image);
+      button = gtk_button_new_from_icon_name ("mail-send-receive-symbolic");
       gtk_header_bar_pack_end (GTK_HEADER_BAR (header), button);
 
       box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
       gtk_widget_add_css_class (box, "linked");
-      button = gtk_button_new ();
-      gtk_button_set_child (GTK_BUTTON (button), gtk_image_new_from_icon_name ("pan-start-symbolic"));
+      button = gtk_button_new_from_icon_name ("go-previous-symbolic");
       gtk_box_append (GTK_BOX (box), button);
-      button = gtk_button_new ();
-      gtk_button_set_child (GTK_BUTTON (button), gtk_image_new_from_icon_name ("pan-end-symbolic"));
+      button = gtk_button_new_from_icon_name ("go-next-symbolic");
       gtk_box_append (GTK_BOX (box), button);
 
       gtk_header_bar_pack_start (GTK_HEADER_BAR (header), box);

demos/gtk-demo/iconscroll.ui

@@ -13,13 +13,13 @@
             </style>
             <child>
               <object class="GtkButton">
-                <property name="icon-name">pan-start-symbolic</property>
+                <property name="icon-name">go-previous-symbolic</property>
                 <signal name="clicked" handler="iconscroll_prev_clicked_cb"/>
               </object>
             </child>
             <child>
               <object class="GtkButton">
-                <property name="icon-name">pan-end-symbolic</property>
+                <property name="icon-name">go-next-symbolic</property>
                 <signal name="clicked" handler="iconscroll_next_clicked_cb"/>
               </object>
             </child>

demos/gtk-demo/listview_applauncher.c

@@ -8,8 +8,8 @@
 
 #include <gtk/gtk.h>
 
-/* This is the function that creates the #GListModel that we need.
- * GTK list widgets need a #GListModel to display, as models support change
+/* This is the function that creates the GListModel that we need.
+ * GTK list widgets need a GListModel to display, as models support change
  * notifications.
  * Unfortunately various older APIs do not provide list models, so we create
  * our own.
@@ -20,10 +20,10 @@ create_application_list (void)
   GListStore *store;
   GList *apps, *l;
 
-  /* We use a #GListStore here, which is a simple array-like list implementation
+  /* We use a GListStore here, which is a simple array-like list implementation
    * for manual management.
    * List models need to know what type of data they provide, so we need to
-   * provide the type here. As we want to do a list of applications, #GAppInfo
+   * provide the type here. As we want to do a list of applications, GAppInfo
    * is the object we provide.
    */
   store = g_list_store_new (G_TYPE_APP_INFO);
@@ -39,7 +39,7 @@ create_application_list (void)
 }
 
 /* This is the function we use for setting up new listitems to display.
- * We add just an #GtkImage and a #GtkLabel here to display the application's
+ * We add just an GtkImage and a GtkLabel here to display the application's
  * icon and name, as this is just a simple demo.
  */
 static void
@@ -61,8 +61,8 @@ setup_listitem_cb (GtkListItemFactory *factory,
 
 /* Here we need to prepare the listitem for displaying its item. We get the
  * listitem already set up from the previous function, so we can reuse the
- * #GtkImage widget we set up above.
- * We get the item - which we know is a #GAppInfo because it comes out of
+ * GtkImage widget we set up above.
+ * We get the item - which we know is a GAppInfo because it comes out of
  * the model we set up above, grab its icon and display it.
  */
 static void
@@ -85,7 +85,7 @@ bind_listitem_cb (GtkListItemFactory *factory,
  * the listitem, but this is simple code, so the default implementations are
  * enough. If we had connected signals, this step would have been necessary.
  *
- * The #GtkSignalListItemFactory documentation contains more information about
+ * The GtkSignalListItemFactory documentation contains more information about
  * this step.
  */
 
@@ -108,8 +108,8 @@ activate_cb (GtkListView  *list,
   app_info = g_list_model_get_item (G_LIST_MODEL (gtk_list_view_get_model (list)), position);
 
   /* Prepare the context for launching the application and launch it. This
-   * code is explained in detail in the documentation for #GdkAppLaunchContext
-   * and #GAppInfo.
+   * code is explained in detail in the documentation for GdkAppLaunchContext
+   * and GAppInfo.
    */
   context = gdk_display_get_app_launch_context (gtk_widget_get_display (GTK_WIDGET (list)));
   if (!g_app_info_launch (app_info,
@@ -155,13 +155,13 @@ do_listview_applauncher (GtkWidget *do_widget)
       gtk_window_set_title (GTK_WINDOW (window), "Application Launcher");
       g_object_add_weak_pointer (G_OBJECT (window), (gpointer *) &window);
 
-      /* The #GtkListitemFactory is what is used to create #GtkListItems
+      /* The GtkListitemFactory is what is used to create GtkListItems
        * to display the data from the model. So it is absolutely necessary
        * to create one.
-       * We will use a #GtkSignalListItemFactory because it is the simplest
+       * We will use a GtkSignalListItemFactory because it is the simplest
        * one to use. Different ones are available for different use cases.
-       * The most powerful one is #GtkBuilderListItemFactory which uses
-       * #GtkBuilder .ui files, so it requires little code.
+       * The most powerful one is GtkBuilderListItemFactory which uses
+       * GtkBuilder .ui files, so it requires little code.
        */
       factory = gtk_signal_list_item_factory_new ();
       g_signal_connect (factory, "setup", G_CALLBACK (setup_listitem_cb), NULL);
@@ -184,7 +184,7 @@ do_listview_applauncher (GtkWidget *do_widget)
        */
       g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL);
 
-      /* List widgets should always be contained in a #GtkScrolledWindow,
+      /* List widgets should always be contained in a GtkScrolledWindow,
        * because otherwise they might get too large or they might not
        * be scrollable.
        */

demos/gtk-demo/listview_filebrowser.c

@@ -34,6 +34,7 @@ enum {
 };
 
 #define FILE_BROWSER_TYPE_VIEW (file_browser_view_get_type ())
+G_MODULE_EXPORT
 G_DECLARE_FINAL_TYPE (FileBrowserView, file_browser_view, FILE_BROWSER, VIEW, GObject);
 
 G_DEFINE_TYPE (FileBrowserView, file_browser_view, G_TYPE_OBJECT);
@@ -159,7 +160,7 @@ static void file_browser_view_init (FileBrowserView *self)
 {
 }
 
-char *
+G_MODULE_EXPORT char *
 filebrowser_get_display_name (GObject *object,
                               GFileInfo *info)
 {
@@ -169,7 +170,7 @@ filebrowser_get_display_name (GObject *object,
   return g_strdup (g_file_info_get_attribute_string (info, "standard::display-name"));
 }
 
-char *
+G_MODULE_EXPORT char *
 filebrowser_get_content_type (GObject *object,
                               GFileInfo *info)
 {
@@ -179,7 +180,7 @@ filebrowser_get_content_type (GObject *object,
   return g_strdup (g_file_info_get_attribute_string (info, "standard::content-type"));
 }
 
-char *
+G_MODULE_EXPORT char *
 filebrowser_get_size (GObject *object,
                       GFileInfo *info)
 {
@@ -189,7 +190,7 @@ filebrowser_get_size (GObject *object,
   return g_format_size (g_file_info_get_attribute_uint64 (info, "standard::size"));
 }
 
-GIcon *
+G_MODULE_EXPORT GIcon *
 filebrowser_get_icon (GObject *object,
                       GFileInfo *info)
 {
@@ -206,7 +207,7 @@ filebrowser_get_icon (GObject *object,
   return icon;
 }
 
-void
+G_MODULE_EXPORT void
 filebrowser_up_clicked_cb (GtkButton        *button,
                            GtkDirectoryList *list)
 {
@@ -219,7 +220,7 @@ filebrowser_up_clicked_cb (GtkButton        *button,
   gtk_directory_list_set_file (list, file);
 }
 
-void
+G_MODULE_EXPORT void
 filebrowser_view_activated_cb (GtkGridView      *view,
                                guint             pos,
                                GtkDirectoryList *list)

demos/gtk-demo/meson.build

@@ -205,4 +205,9 @@ install_data('org.gtk.Demo4.gschema.xml', install_dir: gtk_schemasdir)
 gnome.compile_schemas()
 
 # appdata
-install_data('org.gtk.Demo4.appdata.xml', install_dir: gtk_appdatadir)
+configure_file(
+  input: 'org.gtk.Demo4.appdata.xml.in',
+  output: 'org.gtk.Demo4.appdata.xml',
+  configuration: appdata_config,
+  install_dir: gtk_appdatadir
+)

demos/gtk-demo/org.gtk.Demo4.appdata.xml.in

@@ -31,14 +31,9 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="3.99.0" date="2020-07-30">
+    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
       <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
-      </description>
-    </release>
-    <release version="3.94.0" date="2018-06-25">
-      <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
+        <p>A new build of GTK.</p>
       </description>
     </release>
   </releases>

demos/gtk-demo/shortcuts.c

@@ -25,43 +25,43 @@ show_shortcuts (GtkWidget   *window,
   g_object_unref (builder);
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_builder_shortcuts (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-builder", NULL);
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_gedit_shortcuts (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-gedit", NULL);
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_clocks_shortcuts (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-clocks", NULL);
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_clocks_shortcuts_stopwatch (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-clocks", "stopwatch");
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_boxes_shortcuts (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-boxes", NULL);
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_boxes_shortcuts_wizard (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-boxes", "wizard");
 }
 
-void
+G_MODULE_EXPORT void
 shortcuts_boxes_shortcuts_display (GtkWidget *window)
 {
   show_shortcuts (window, "shortcuts-boxes", "display");

demos/gtk-demo/singular_value_decomposition.c

@@ -2,6 +2,7 @@
 #include <float.h>
 #include <math.h>
 #include <glib.h>
+#include <assert.h>
 
 /* See Golub and Reinsch,
  * "Handbook for Automatic Computation vol II - Linear Algebra",
@@ -39,6 +40,9 @@ householder_reduction (double *A,
   double *pu, *pui, *pv, *pvi;
   double half_norm_squared;
 
+  assert (nrows >= 2);
+  assert (ncols >= 2);
+
   memcpy (U, A, sizeof (double) * nrows * ncols);
 
   diagonal[0] = 0.0;
@@ -205,6 +209,9 @@ givens_reduction (int nrows,
   int rotation_test;
   int iteration_count;
 
+  assert (nrows >= 2);
+  assert (ncols >= 2);
+
   for (i = 0, x = 0.0; i < ncols; i++)
     {
       y = fabs (diagonal[i]) + fabs (superdiagonal[i]);
@@ -342,6 +349,9 @@ sort_singular_values (int     nrows,
   double temp;
   double *p1, *p2;
 
+  assert (nrows >= 2);
+  assert (ncols >= 2);
+
   for (i = 0; i < ncols - 1; i++)
     {
       max_index = i;
@@ -433,9 +443,12 @@ singular_value_decomposition_solve (double *U,
   double d;
   double tolerance;
 
+  assert (nrows >= 2);
+  assert (ncols >= 2);
+
   tolerance = DBL_EPSILON * S[0] * (double) ncols;
 
-  for ( i = 0, pv = V; i < ncols; i++, pv += ncols)
+  for (i = 0, pv = V; i < ncols; i++, pv += ncols)
     {
       x[i] = 0.0;
       for (j = 0; j < ncols; j++)

demos/gtk-demo/spinbutton.c

@@ -12,7 +12,7 @@
 #include <math.h>
 #include <stdlib.h>
 
-int
+G_MODULE_EXPORT int
 spinbutton_hex_spin_input (GtkSpinButton *spin_button,
                            double        *new_val)
 {
@@ -29,7 +29,7 @@ spinbutton_hex_spin_input (GtkSpinButton *spin_button,
     return TRUE;
 }
 
-int
+G_MODULE_EXPORT int
 spinbutton_hex_spin_output (GtkSpinButton *spin_button)
 {
   GtkAdjustment *adjustment;
@@ -49,7 +49,7 @@ spinbutton_hex_spin_output (GtkSpinButton *spin_button)
   return TRUE;
 }
 
-int
+G_MODULE_EXPORT int
 spinbutton_time_spin_input (GtkSpinButton *spin_button,
                             double        *new_val)
 {
@@ -88,7 +88,7 @@ spinbutton_time_spin_input (GtkSpinButton *spin_button,
   return TRUE;
 }
 
-int
+G_MODULE_EXPORT int
 spinbutton_time_spin_output (GtkSpinButton *spin_button)
 {
   GtkAdjustment *adjustment;
@@ -122,7 +122,7 @@ static const char *month[12] = {
   "December"
 };
 
-int
+G_MODULE_EXPORT int
 spinbutton_month_spin_input (GtkSpinButton *spin_button,
                              double        *new_val)
 {
@@ -151,7 +151,7 @@ spinbutton_month_spin_input (GtkSpinButton *spin_button,
   return TRUE;
 }
 
-int
+G_MODULE_EXPORT int
 spinbutton_month_spin_output (GtkSpinButton *spin_button)
 {
   GtkAdjustment *adjustment;

demos/icon-browser/meson.build

@@ -32,5 +32,10 @@ endforeach
 install_data('org.gtk.IconBrowser4.desktop', install_dir: gtk_applicationsdir)
 
 # appdata
-install_data('org.gtk.IconBrowser4.appdata.xml', install_dir: gtk_appdatadir)
+configure_file(
+  input: 'org.gtk.IconBrowser4.appdata.xml.in',
+  output: 'org.gtk.IconBrowser4.appdata.xml',
+  configuration: appdata_config,
+  install_dir: gtk_appdatadir
+)
 

demos/icon-browser/org.gtk.IconBrowser4.appdata.xml.in

@@ -30,14 +30,9 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="3.99.0" date="2020-07-30">
+    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
       <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
-      </description>
-    </release>
-    <release version="3.94.0" date="2018-06-25">
-      <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
+        <p>A new build of GTK.</p>
       </description>
     </release>
   </releases>

demos/meson.build

@@ -1,19 +1,31 @@
-demo_conf = configuration_data()
-demo_conf.set_quoted('PROFILE', get_option('profile'))
-demo_conf.set_quoted('VCS_TAG', '@VCS_TAG@')
+gen_demo_header = find_program('../build-aux/meson/gen-demo-header.py')
+demo_profile = get_option('profile')
 
 demo_conf_h = declare_dependency(
-  sources: vcs_tag(
-             command: [ 'git', 'rev-parse', '--short', 'HEAD' ],
-             fallback: get_option('profile') != 'default' ? 'devel' : '',
-             input: configure_file(
-                      output: 'demo_conf.h.in',
-                      configuration: demo_conf
-                    ),
-             output: 'demo_conf.h'
-           )
+  sources: custom_target('demo-header',
+    command: [gen_demo_header, meson.source_root(), demo_profile],
+    capture: true,
+    output: 'demo_conf.h',
+    build_by_default: true,
+    build_always_stale: true,
+  )
 )
 
+# appdata
+today = 'unknown'
+date = find_program('date',
+         required: false)
+if date.found()
+  r = run_command(date, '-I')
+  if r.returncode() == 0
+    today = r.stdout().strip()
+  endif
+endif
+
+appdata_config = configuration_data()
+appdata_config.set('BUILD_VERSION', meson.project_version())
+appdata_config.set('BUILD_DATE', today)
+
 subdir('constraint-editor')
 subdir('gtk-demo')
 subdir('icon-browser')

demos/print-editor/print-editor.c

@@ -159,7 +159,7 @@ save_file (GFile *save_filename)
 
   error = NULL;
   g_file_replace_contents (save_filename,
-                           text, -1,
+                           text, strlen (text),
                            NULL, FALSE,
                            G_FILE_CREATE_NONE,
                            NULL,

demos/widget-factory/meson.build

@@ -26,4 +26,9 @@ foreach size: ['scalable', 'symbolic']
 endforeach
 
 # appdata
-install_data('org.gtk.WidgetFactory4.appdata.xml', install_dir: gtk_appdatadir)
+configure_file(
+  input: 'org.gtk.WidgetFactory4.appdata.xml.in',
+  output: 'org.gtk.WidgetFactory4.appdata.xml',
+  configuration: appdata_config,
+  install_dir: gtk_appdatadir
+)

demos/widget-factory/org.gtk.WidgetFactory4.appdata.xml.in

@@ -32,14 +32,9 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="3.99.0" date="2020-07-30">
+    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
       <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
-      </description>
-    </release>
-    <release version="3.94.0" date="2018-06-25">
-      <description>
-        <p>A new developers snapshot towards GTK 4.0.</p>
+        <p>A new build of GTK.</p>
       </description>
     </release>
   </releases>

demos/widget-factory/widget-factory.ui

@@ -2606,12 +2606,12 @@ microphone-sensitivity-medium-symbolic</property>
                                     </style>
                                     <child>
                                       <object class="GtkButton">
-                                        <property name="icon-name">pan-start-symbolic</property>
+                                        <property name="icon-name">go-previous-symbolic</property>
                                       </object>
                                     </child>
                                     <child>
                                       <object class="GtkButton">
-                                        <property name="icon-name">pan-end-symbolic</property>
+                                        <property name="icon-name">go-next-symbolic</property>
                                       </object>
                                     </child>
                                   </object>

docs/reference/gdk/keys.md

@@ -3,7 +3,7 @@ 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.
+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.
 
@@ -28,8 +28,8 @@ 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
+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
@@ -45,7 +45,7 @@ information:
     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
+  1. third, the [struct@Gdk.KeymapKey] 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

docs/reference/gdk/meson.build

@@ -13,6 +13,7 @@ if get_option('gtk_doc')
       gidocgen,
       'generate',
       '--quiet',
+      '--fatal-warnings',
       '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
       '--config=@INPUT0@',
       '--output-dir=@OUTPUT@',
@@ -34,6 +35,7 @@ if get_option('gtk_doc')
         gidocgen,
         'generate',
         '--quiet',
+        '--fatal-warnings',
         '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
         '--config=@INPUT0@',
         '--output-dir=@OUTPUT@',
@@ -57,6 +59,7 @@ if get_option('gtk_doc')
         gidocgen,
         'generate',
         '--quiet',
+        '--fatal-warnings',
         '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
         '--config=@INPUT0@',
         '--output-dir=@OUTPUT@',

docs/reference/gsk/meson.build

@@ -8,6 +8,7 @@ if get_option('gtk_doc')
       gidocgen,
       'generate',
       '--quiet',
+      '--fatal-warnings',
       '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
       '--config=@INPUT0@',
       '--output-dir=@OUTPUT@',

docs/reference/gtk/css-properties.md

@@ -76,12 +76,16 @@ and in some cases a number as arguments.
 
 `lighter(Color)`
  : produces a brigher variant of Color
+
 `darker(Color)`
  : produces a darker variant of Color
+
 `shade(Color, Number)`
  : changes the lightness of Color. The number ranges from 0 for black to 2 for white.
+
 `alpha(Color, Number)`
  : replaces the alpha value of color with number (between 0 and 1)
+
 `mix(Color1, Color2, Number)`
  : interpolates between the two colors
 

docs/reference/gtk/getting_started.md

@@ -106,7 +106,7 @@ The call to [ctor@Gtk.ApplicationWindow.new] will create a new
 window will have a frame, a title bar, and window controls depending on the
 platform.
 
-A window title is set using [`method@Gtk.Window.set_title`]. This function
+A window title is set using [method@Gtk.Window.set_title]. This function
 takes a `GtkWindow` pointer and a string as input. As our `window` pointer
 is a `GtkWidget` pointer, we need to cast it to `GtkWindow`; instead of
 casting `window` via a typical C cast like `(GtkWindow*)`, `window` can be
@@ -115,7 +115,7 @@ pointer is an instance of the `GtkWindow` class, before casting, and emit a
 warning if the check fails. More information about this convention can be
 found [here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).
 
-Finally the window size is set using [`method@Gtk.Window.set_default_size`]
+Finally the window size is set using [method@Gtk.Window.set_default_size]
 and the window is then shown by GTK via [method@Gtk.Widget.show].
 
 When you close the window, by (for example) pressing the X button, the
@@ -212,10 +212,10 @@ The `GtkBox` widget is created with [ctor@Gtk.Box.new], which takes a
 this box will contain can either be laid out horizontally or vertically.
 This does not matter in this particular case, as we are dealing with only
 one button. After initializing box with the newly created `GtkBox`, the code
-adds the box widget to the window widget using [`method@Gtk.Window.set_child`].
+adds the box widget to the window widget using [method@Gtk.Window.set_child].
 
 Next the `button` variable is initialized in similar manner.
-[`ctor@Gtk.Button.new_with_label`] is called which returns a
+[ctor@Gtk.Button.new_with_label] is called which returns a
 [class@Gtk.Button] to be stored in `button`. Afterwards `button` is added to
 our `box`.
 
@@ -353,7 +353,7 @@ draw function.
 The contents of a widget often need to be partially or fully redrawn, e.g.
 when another window is moved and uncovers part of the widget, or when the
 window containing it is resized. It is also possible to explicitly cause a
-widget to be redrawn, by calling [`method@Gtk.Widget.queue_draw`]. GTK takes
+widget to be redrawn, by calling [method@Gtk.Widget.queue_draw]. GTK takes
 care of most of the details by providing a ready-to-use cairo context to the
 draw function.
 
@@ -690,16 +690,16 @@ gcc $( pkg-config --cflags gtk4 ) -o example-3 example-3.c $( pkg-config --libs
 
 Note that `GtkBuilder` can also be used to construct objects that are
 not widgets, such as tree models, adjustments, etc. That is the reason
-the method we use here is called [`method@Gtk.Builder.get_object`] and returns
+the method we use here is called [method@Gtk.Builder.get_object] and returns
 a `GObject` instead of a `GtkWidget`.
 
-Normally, you would pass a full path to [`method@Gtk.Builder.add_from_file`] to
+Normally, you would pass a full path to [method@Gtk.Builder.add_from_file] to
 make the execution of your program independent of the current directory.
 A common location to install UI descriptions and similar data is
 `/usr/share/appname`.
 
 It is also possible to embed the UI description in the source code as a
-string and use [`method@Gtk.Builder.add_from_string`] to load it. But keeping the
+string and use [method@Gtk.Builder.add_from_string] to load it. But keeping the
 UI description in a separate file has several advantages: It is then possible
 to make minor adjustments to the UI without recompiling your program, and,
 more importantly, graphical UI editors such as [Glade](http://glade.gnome.org)
@@ -985,7 +985,7 @@ glib-compile-resources exampleapp.gresource.xml --target=resources.c --generate-
 ```
 
 The gnome module of the [Meson build system](https://mesonbuild.com)
-provides the [`gnome.compile_resources()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
+provides the [gnome.compile_resources()](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
 method for this task.
 
 Our application now looks like this:
@@ -1081,7 +1081,7 @@ tell it to display information about our stack.
 
 The stack switcher gets all its information it needs to display tabs from
 the stack that it belongs to. Here, we are passing the label to show for
-each file as the last argument to the [`method@Gtk.Stack.add_titled`]
+each file as the last argument to the [method@Gtk.Stack.add_titled]
 function.
 
 Our application is beginning to take shape:
@@ -1221,7 +1221,7 @@ Before we can make use of this schema in our application, we need to compile
 it into the binary form that GSettings expects. GIO provides
 [macros](https://developer.gnome.org/gio/2.36/ch31s06.html) to do this in
 autotools-based projects, and the gnome module of the Meson build system
-provides the [`gnome.compile_schemas()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
+provides the [gnome.compile_schemas()](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
 method for this task.
 
 Next, we need to connect our settings to the widgets that they are supposed

docs/reference/gtk/initialization.md

@@ -7,7 +7,7 @@ Title: Initialization
 Before using GTK, you need to initialize it using [func@Gtk.init]; this
 connects to the windowing system, sets up the locale and performs other
 initialization tasks. [func@Gtk.init] exits the application if errors occur;
-to avoid this, you can use [`func@Gtk.init_check`], which allows you to recover
+to avoid this, you can use [func@Gtk.init_check], which allows you to recover
 from a failed GTK initialization; for instance, you might start up your
 application in text mode instead.
 

docs/reference/gtk/meson.build

@@ -37,6 +37,7 @@ if get_option('gtk_doc')
       gidocgen,
       'generate',
       '--quiet',
+      '--fatal-warnings',
       '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
       '--config=@INPUT0@',
       '--output-dir=@OUTPUT@',

docs/reference/gtk/question_index.md

@@ -33,13 +33,13 @@ the question you have, this list is a good place to start.
 
 4.  How does memory management work in GTK? Should I free data returned from functions?
 
-    See the documentation for #GObject and #GInitiallyUnowned. For #GObject note
-    specifically g_object_ref() and g_object_unref(). #GInitiallyUnowned is a
-    subclass of #GObject so the same points apply, except that it has a "floating"
+    See the documentation for `GObject` and `GInitiallyUnowned`. For `GObject` note
+    specifically `g_object_ref()` and `g_object_unref()`. `GInitiallyUnowned` is a
+    subclass of `GObject` so the same points apply, except that it has a "floating"
     state (explained in its documentation).
 
     For strings returned from functions, they will be declared "const" if they should
-    not be freed. Non-const strings should be freed with g_free(). Arrays follow the
+    not be freed. Non-const strings should be freed with `g_free()`. Arrays follow the
     same rule. If you find an undocumented exception to the rules, please
     [file a bug report.](https://gitlab.gnome.org/GNOME/gtk/issues/new).
 
@@ -47,7 +47,7 @@ the question you have, this list is a good place to start.
     documentation can provide useful hints for memory handling semantics as well.
 
 5.  Why does my program leak memory, if I destroy a widget immediately
-    after creating it ?
+    after creating it?
 
     If `GtkFoo` isn't a toplevel window, then
 
@@ -60,7 +60,7 @@ the question you have, this list is a good place to start.
     want standard reference counting, not floating reference counting.
 
     To get this, you must acquire a reference to the widget and drop the
-    floating reference (_ref and sink_ in GObject parlance) after creating it:
+    floating reference (_ref and sink_ in `GObject` parlance) after creating it:
 
         foo = gtk_foo_new ();
         g_object_ref_sink (foo);
@@ -72,12 +72,12 @@ the question you have, this list is a good place to start.
 6.  How do I use GTK with threads?
 
     GTK requires that all GTK API calls are made from the same thread in which
-    the #GtkApplication was created, or gtk_init() was called (the _main thread_).
+    the `GtkApplication` was created, or `gtk_init()` was called (the _main thread_).
 
     If you want to take advantage of multi-threading in a GTK application,
     it is usually best to send long-running tasks to worker threads, and feed
-    the results back to the main thread using g_idle_add() or #GAsyncQueue. GIO
-    offers useful tools for such an approach such as #GTask.
+    the results back to the main thread using `g_idle_add()` or `GAsyncQueue`. GIO
+    offers useful tools for such an approach such as `GTask`.
 
 7.  How do I internationalize a GTK program?
 
@@ -239,7 +239,7 @@ the question you have, this list is a good place to start.
 
         gdk_surface_set_events (gdk_surface,
                                 (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
-        
+
     There are very few functions that require this cast, however.
 
 10. How do I use GTK with other non-C languages?
@@ -250,14 +250,14 @@ the question you have, this list is a good place to start.
 11. How do I load an image or animation from a file?
 
     To load an image file straight into a display widget, use
-    gtk_image_new_from_file(). To load an image for another purpose, use
-    gdk_texture_new_from_file(). To load a video from a file, use
-    gtk_media_file_new_for_file().
+    [ctor@Gtk.Image.new_from_file]. To load an image for another purpose, use
+    [ctor@Gdk.Texture.new_from_file]. To load a video from a file, use
+    [ctor@Gtk.MediaFile.new_for_file].
 
 12. How do I draw text?
 
     To draw a piece of text onto a cairo surface, use a Pango layout and
-    pango_cairo_show_layout().
+    [func@PangoCairo.show_layout].
 
         layout = gtk_widget_create_pango_layout (widget, text);
         fontdesc = pango_font_description_from_string ("Luxi Mono 12");
@@ -265,17 +265,17 @@ the question you have, this list is a good place to start.
         pango_cairo_show_layout (cr, layout);
         pango_font_description_free (fontdesc);
         g_object_unref (layout);
-        
+
     See also the [Cairo Rendering](https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html)
     section of the [Pango documentation](https://developer.gnome.org/pango/stable/).
 
-    To draw a piece of text in a widget snapshot() implementation, use
-    gtk_snapshot_append_layout().
+    To draw a piece of text in a widget [vfunc@Gtk.Widget.snapshot] implementation,
+    use [method@Gtk.Snapshot.append_layout].
 
 13. How do I measure the size of a piece of text?
 
     To obtain the size of a piece of text, use a Pango layout and
-    pango_layout_get_pixel_size(), using code like the following:
+    [method@Pango.Layout.get_pixel_size], using code like the following:
 
         layout = gtk_widget_create_pango_layout (widget, text);
         fontdesc = pango_font_description_from_string ("Luxi Mono 12");
@@ -294,7 +294,7 @@ the question you have, this list is a good place to start.
     compiler to optimize the call away if it appears that the value is not
     being used.
 
-    GLib provides the g_type_ensure() function to work around this problem.
+    GLib provides the `g_type_ensure()` function to work around this problem.
 
         g_type_ensure (GTK_TYPE_BLAH);
 
@@ -311,34 +311,34 @@ the question you have, this list is a good place to start.
     and the required formatting flexibility.
 
     If you want to display a large amount of data in a uniform way, your best
-    option is a #GtkTreeView widget. See the [tree widget overview](#TreeWidget).
+    option is a [class@Gtk.TreeView] widget. See the [tree widget overview](#TreeWidget).
     A list is just a tree with no branches, so the treeview widget is used for
     lists as well.
 
     If you want to display a small amount of items, but need flexible formatting
-    and widgetry inside the list, then you probably want to use a #GtkListBox,
+    and widgetry inside the list, then you probably want to use a [class@Gtk.ListBox],
     which uses regular widgets for display.
 
 17. ...for multi-line text display or editing?
 
     See the [text widget overview](#TextWidget) -- you should use the
-    #GtkTextView widget.
+    [class@Gtk.TextView] widget.
 
-    If you only have a small amount of text, #GtkLabel may also be appropriate
-    of course. It can be made selectable with gtk_label_set_selectable(). For a
-    single-line text entry, see #GtkEntry.
+    If you only have a small amount of text, [class@Gtk.Label] may also be appropriate
+    of course. It can be made selectable with [method@Gtk.Label.set_selectable]. For a
+    single-line text entry, see [class@Gtk.Entry].
 
 18. ...to display an image or animation?
 
-    GTK has two widgets that are dedicated to displaying images. #GtkImage, for
-    small, fixed-size icons and #GtkPicture for content images.
+    GTK has two widgets that are dedicated to displaying images. [class@Gtk.Image], for
+    small, fixed-size icons and [class@Gtk.Picture] for content images.
 
     Both can display images in just about any format GTK understands.
-    You can also use #GtkDrawingArea if you need to do something more complex,
+    You can also use [class@Gtk.DrawingArea] if you need to do something more complex,
     such as draw text or graphics over the top of the image.
 
-    Both GtkImage and GtkPicture can display animations and videos as well.
-    To show an webm file, load it with the GtkMediaFile API and then use
+    Both [class@Gtk.Image] and [class@Gtk.Picture] can display animations and videos as well.
+    To show an webm file, load it with the [class@Gtk.MediaFile] API and then use
     it as a paintable:
 
         mediafile = gtk_media_file_new_for_filename ("example.webm");
@@ -347,8 +347,10 @@ the question you have, this list is a good place to start.
 19. ...for presenting a set of mutually-exclusive choices, where Windows
     would use a combo box?
 
-    With GTK, a #GtkComboBox is the recommended widget to use for this use case.
-    If you need an editable text entry, use the #GtkComboBox:has-entry property.
+    With GTK, a [class@Gtk.ComboBox] is the recommended widget to use for this use case.
+    If you need an editable text entry, use the [property@Gtk.ComboBox:has-entry] property.
+
+    A newer alternative is [class@Gtk.DropDown].
 
 ## Questions about GtkWidget
 
@@ -357,8 +359,8 @@ the question you have, this list is a good place to start.
     The background color of a widget is determined by the CSS style that applies
     to it. To change that, you can set style classes on the widget, and provide
     custom CSS to change the appearance. Such CSS can be loaded with
-    gtk_css_provider_load_from_file() and its variants.
-    See gtk_style_context_add_provider().
+    [method@Gtk.CssProvider.load_from_file] and its variants.
+    See [method@Gtk.StyleContext.add_provider].
 
 21. How do I change the font of a widget?
 
@@ -368,7 +370,7 @@ the question you have, this list is a good place to start.
         gtk_label_set_markup (label, "<big>big tex</big>");
 
     This is preferred for many apps because it's a relative size to the
-    user's chosen font size. See g_markup_escape_text() if you are
+    user's chosen font size. See `g_markup_escape_text()` if you are
     constructing such strings on the fly.
 
     You can also change the font of a widget by putting
@@ -377,24 +379,24 @@ the question you have, this list is a good place to start.
           font: Sans 30;
         }
 
-    in a CSS file, loading it with gtk_css_provider_load_from_file(), and
-    adding the provider with gtk_style_context_add_provider_for_display().
+    in a CSS file, loading it with [method@Gtk.CssProvider.load_from_file], and
+    adding the provider with [func@Gtk.StyleContext.add_provider_for_display].
     To associate this style information with your widget, set a style class
-    on its #GtkStyleContext using gtk_style_context_add_class(). The advantage
+    on the widget using [method@Gtk.Widget.add_css_class]. The advantage
     of this approach is that users can then override the font you have chosen.
-    See the #GtkStyleContext documentation for more discussion.
+    See the `GtkStyleContext` documentation for more discussion.
 
 22. How do I disable/ghost/desensitize a widget?
 
     In GTK a disabled widget is termed _insensitive_.
-    See gtk_widget_set_sensitive().
+    See [method@Gtk.Widget.set_sensitive].
 
 ## GtkTextView questions
 
 23. How do I get the contents of the entire text widget as a string?
 
-    See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
-    or gtk_text_iter_get_text().
+    See [method@Gtk.TextBuffer.get_bounds] and [method@Gtk.TextBuffer.get_text]
+    or [method@Gtk.TextIter.get_text].
 
         GtkTextIter start, end;
         GtkTextBuffer *buffer;
@@ -405,10 +407,10 @@ the question you have, this list is a good place to start.
         text = gtk_text_iter_get_text (&start, &end);
         /* use text */
         g_free (text);
-        
+
 24. How do I make a text widget display its complete contents in a specific font?
 
-    If you use gtk_text_buffer_insert_with_tags() with appropriate tags to
+    If you use [method@Gtk.TextBuffer.insert_with_tags] with appropriate tags to
     select the font, the inserted text will have the desired appearance, but
     text typed in by the user before or after the tagged block will appear in
     the default style.
@@ -421,40 +423,40 @@ the question you have, this list is a good place to start.
     *before*, keeping the mark at the end.
 
     To ensure that the end of the buffer remains visible, use
-    gtk_text_view_scroll_to_mark() to scroll to the mark after
+    [method@Gtk.TextView.scroll_to_mark] to scroll to the mark after
     inserting new text.
 
-    The gtk-demo application contains an example of this technique.
+    The gtk4-demo application contains an example of this technique.
 
 ## GtkTreeView questions
 
 26. How do I associate some data with a row in the tree?
 
-    Remember that the #GtkTreeModel columns don't necessarily have to be
+    Remember that the [class@Gtk.TreeModel] columns don't necessarily have to be
     displayed. So you can put non-user-visible data in your model just
-    like any other data, and retrieve it with gtk_tree_model_get().
-    See the [tree widget overview](#TreeWidget).
+    like any other data, and retrieve it with [method@Gtk.TreeModel.get].
+    See the [tree widget overview](#TreeWidget).        
 
 27. How do I put an image and some text in the same column?
 
-    You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
-    using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
-    So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
+    You can pack more than one [class@Gtk.CellRenderer] into a single [class@Gtk.TreeViewColumn]
+    using [method@Gtk.TreeViewColumn.pack_start] or [method@Gtk.TreeViewColumn.pack_end].
+    So pack both a [class@Gtk.CellRendererPixbuf] and a [class@Gtk.CellRendererText] into the
     column.
 
-28. I can set data easily on my #GtkTreeStore or #GtkListStore models using
-    gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
+28. I can set data easily on my [class@Gtk.TreeStore] or [class@Gtk.ListStore] models using
+    [method@Gtk.ListStore.set] and [method@Gtk.TreeStore.set], but can't read it back?
 
-    Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
+    Both the [class@Gtk.TreeStore] and the [class@Gtk.ListStore] implement the [class@Gtk.TreeModel]
     interface. As a consequence, you can use any function this interface
     implements. The easiest way to read a set of data back is to use
-    gtk_tree_model_get().
+    [method@Gtk.TreeModel.get].
 
-29. How do I change the way that numbers are formatted by #GtkTreeView?
+29. How do I change the way that numbers are formatted by `GtkTreeView`?
 
-    Use gtk_tree_view_insert_column_with_data_func() or
-    gtk_tree_view_column_set_cell_data_func() and do the conversion
-    from number to string yourself (with, say, g_strdup_printf()).
+    Use [method@Gtk.TreeView.insert_column_with_data_func] or
+    [method@Gtk.TreeViewColumn.set_cell_data_func] and do the conversion
+    from number to string yourself (with, say, `g_strdup_printf()`).
 
     The following example demonstrates this:
 
@@ -527,29 +529,29 @@ the question you have, this list is a good place to start.
 30. How do I hide the expander arrows in my tree view?
 
     Set the expander-column property of the tree view to a hidden column.
-    See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
+    See [method@Gtk.TreeView.set_expander_column] and [method@Gtk.TreeViewColumn.set_visible].
 
 ## Using cairo with GTK
 
 31. How do I use cairo to draw in GTK applications?
 
-    Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
+    Use [method@Gtk.Snapshot.append_cairo] in your [vfunc@Gtk.Widget.snapshot] vfunc
     to obtain a cairo context and draw with that.
-    
+
 32. Can I improve the performance of my application by using another backend
     of cairo (such as GL)?
 
     No. Most drawing in GTK is not done via cairo anymore (but instead
     by the GL or Vulkan renderers of GSK).
 
-    If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
+    If you use cairo for drawing your own widgets, [method@Gtk.Snapshot.append_cairo]
     will choose the most appropriate surface type for you.
 
-    If you are interested in using GL for your own drawing, see #GtkGLArea.
+    If you are interested in using GL for your own drawing, see [class@Gtk.GLArea].
 
-33. Can I use cairo to draw on a #GdkPixbuf?
+33. Can I use cairo to draw on a `GdkPixbuf`?
 
-    No. The cairo image surface does not support the pixel format used by GdkPixbuf.
+    No. The cairo image surface does not support the pixel format used by `GdkPixbuf`.
 
     If you need to get cairo drawing into a format that can be displayed efficiently
-    by GTK, you may want to use an image surface and gdk_memory_texture_new().
+    by GTK, you may want to use an image surface and [ctor@Gdk.MemoryTexture.new].

docs/reference/gtk/running.md

@@ -22,20 +22,26 @@ are only available when GTK has been configured with `-Ddebug=true`.
 `builder`
 : GtkBuilder support
 
+`builder-objects`
+: Unused GtkBuilder objects
+
 `geometry`
 : Size allocation
 
 `icontheme`
 : Icon themes
 
+`iconfallback`
+: Information about icon fallback
+
 `keybindings`
-: Keybindings
+: Keyboard shortcuts
 
 `modules`
-: Loading of modules
+: Modules and extensions
 
 `printing`
-: Printing support
+: Printing
 
 `size-request`
 : Size requests
@@ -46,6 +52,15 @@ are only available when GTK has been configured with `-Ddebug=true`.
 `tree`
 : Tree widget internals
 
+`constraints`
+: Constraints and the constraint solver
+
+`layout`
+: Layout managers
+
+`acccessibility`
+: Accessibility state changs
+
 A number of keys are influencing behavior instead of just logging:
 
 `interactive`
@@ -57,15 +72,6 @@ A number of keys are influencing behavior instead of just logging:
 `touchscreen`
 : Pretend the pointer is a touchscreen device
 
-`updates`
-: Visual feedback about window updates
-
-`resize`
-: Highlight resizing widgets
-
-`layout`
-: Show layout borders
-
 `snapshot`
 : Include debug render nodes in the generated snapshots
 
@@ -324,9 +330,15 @@ using and the GDK backend supports them:
 `cairo`
 : Selects the fallback Cairo renderer
 
-`gl`
+`opengl`
 : Selects the default OpenGL renderer
 
+`gl`
+: Selects the "gl" OpenGL renderer
+
+`ngl`
+: Selects the "ngl" OpenGL renderer
+
 `vulkan`
 : Selects the Vulkan renderer
 

docs/reference/gtk/section-accessibility.md

@@ -8,7 +8,7 @@ an application's user interface elements. Assistive technology (AT)
 applications, like Orca, convey this information to users with disabilities,
 or reduced abilities, to help them use the application.
 
-Standard GTK controls implement the #GtkAccessible interface and are thus
+Standard GTK controls implement the `GtkAccessible` interface and are thus
 accessible to ATs by default. This means that if you use GTK controls such
 as `GtkButton`, `GtkEntry`, or `GtkListView`, you only need to supply
 application-specific details when the defaults values are incomplete. You
@@ -103,39 +103,39 @@ for instance:
 
  - a toggle button will change its %GTK_ACCESSIBLE_STATE_CHECKED state every
    time it is toggled, either by the user or programmatically
- - setting the mnemonic widget on a #GtkLabel will update the
+ - setting the mnemonic widget on a `GtkLabel` will update the
    %GTK_ACCESSIBLE_RELATION_LABELLED_BY relation on the widget with a
    reference to the label
- - changing the #GtkAdjustment instance on a #GtkScrollbar will change the
+ - changing the `GtkAdjustment` instance on a `GtkScrollbar` will change the
    %GTK_ACCESSIBLE_PROPERTY_VALUE_MAX, %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN,
    and %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW properties with the upper, lower,
-   and value properties of the #GtkAdjustment
+   and value properties of the `GtkAdjustment`
 
 See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
 of attributes for additional information.
 
 #### List of accessible states
 
-Each state name is part of the #GtkAccessibleState enumeration.
+Each state name is part of the `GtkAccessibleState` enumeration.
 
 | State name | ARIA attribute | Value type | Notes |
 |------------|----------------|------------|-------|
 | %GTK_ACCESSIBLE_STATE_BUSY | “aria-busy” | boolean |
-| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.CheckButton] |
+| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | `GtkAccessibleTristate` | Indicates the current state of a [class@Gtk.CheckButton] |
 | %GTK_ACCESSIBLE_STATE_DISABLED | “aria-disabled” | boolean | Corresponds to the [property@Gtk.Widget:sensitive] property on [class@Gtk.Widget] |
 | %GTK_ACCESSIBLE_STATE_EXPANDED | “aria-expanded” | boolean or undefined | Corresponds to the  [property@Gtk.Expander:expanded] property on [class@Gtk.Expander] |
 | %GTK_ACCESSIBLE_STATE_HIDDEN | “aria-hidden” | boolean | Corresponds to the [property@Gtk.Widget:visible] property on [class@Gtk.Widget] |
-| %GTK_ACCESSIBLE_STATE_INVALID | “aria-invalid” | #GtkAccessibleInvalidState | Set when a widget is showing an error |
-| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.ToggleButton] |
+| %GTK_ACCESSIBLE_STATE_INVALID | “aria-invalid” | `GtkAccessibleInvalidState` | Set when a widget is showing an error |
+| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | `GtkAccessibleTristate` | Indicates the current state of a [class@Gtk.ToggleButton] |
 | %GTK_ACCESSIBLE_STATE_SELECTED | “aria-selected” | boolean or undefined | Set when a widget is selected |
 
 #### List of accessible properties
 
-Each property name is part of the #GtkAccessibleProperty enumeration.
+Each property name is part of the `GtkAccessibleProperty` enumeration.
 
 | State name | ARIA attribute | Value type |
 |------------|----------------|------------|
-| %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE | “aria-autocomplete” | #GtkAccessibleAutocomplete |
+| %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE | “aria-autocomplete” | `GtkAccessibleAutocomplete` |
 | %GTK_ACCESSIBLE_PROPERTY_DESCRIPTION | “aria-description” | translatable string |
 | %GTK_ACCESSIBLE_PROPERTY_HAS_POPUP | “aria-haspopup” | boolean |
 | %GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS | “aria-keyshortcuts” | string |
@@ -144,12 +144,12 @@ Each property name is part of the #GtkAccessibleProperty enumeration.
 | %GTK_ACCESSIBLE_PROPERTY_MODAL | “aria-modal” | boolean |
 | %GTK_ACCESSIBLE_PROPERTY_MULTI_LINE | “aria-multiline” | boolean |
 | %GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE | “aria-multiselectable” | boolean |
-| %GTK_ACCESSIBLE_PROPERTY_ORIENTATION | “aria-orientation” | #GtkOrientation |
+| %GTK_ACCESSIBLE_PROPERTY_ORIENTATION | “aria-orientation” | `GtkOrientation` |
 | %GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER | “aria-placeholder” | translatable string |
 | %GTK_ACCESSIBLE_PROPERTY_READ_ONLY | “aria-readonly” | boolean |
 | %GTK_ACCESSIBLE_PROPERTY_REQUIRED | “aria-required” | boolean |
 | %GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION | “aria-roledescription” | translatable string |
-| %GTK_ACCESSIBLE_PROPERTY_SORT | “aria-sort” | #GtkAccessibleSort |
+| %GTK_ACCESSIBLE_PROPERTY_SORT | “aria-sort” | `GtkAccessibleSort` |
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_MAX | “aria-valuemax” | double |
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN | “aria-valuemin” | double |
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW | “aria-valuenow” | double |
@@ -157,22 +157,22 @@ Each property name is part of the #GtkAccessibleProperty enumeration.
 
 #### List of accessible relations
 
-Each relation name is part of the #GtkAccessibleRelation enumeration.
+Each relation name is part of the `GtkAccessibleRelation` enumeration.
 
 | State name | ARIA attribute | Value type |
 |------------|----------------|------------|
-| %GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT | “aria-activedescendant” | #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT | “aria-activedescendant” | `GtkAccessible` |
 | %GTK_ACCESSIBLE_RELATION_COL_COUNT | “aria-colcount” | integer |
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX | “aria-colindex” | integer |
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT | “aria-colindextext” | translatable string |
 | %GTK_ACCESSIBLE_RELATION_COL_SPAN | “aria-colspan” | integer |
-| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of `GtkAccessible` |
+| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of `GtkAccessible` |
 | %GTK_ACCESSIBLE_RELATION_POS_IN_SET | “aria-posinset” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_COUNT | “aria-rowcount” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_INDEX | “aria-rowindex” | integer |
@@ -219,11 +219,11 @@ be used as part of the application's test suite to avoid regressions.
 
 ## Implementations
 
-Each UI control implements the #GtkAccessible interface to allow widget and
+Each UI control implements the `GtkAccessible` interface to allow widget and
 application developers to specify the roles, state, and relations between UI
 controls. This API is purely descriptive.
 
-Each `GtkAccessible` implementation must provide a #GtkATContext instance,
+Each `GtkAccessible` implementation must provide a `GtkATContext` instance,
 which acts as a proxy to the specific platform's accessibility API:
 
  * AT-SPI on Linux/BSD
@@ -256,7 +256,7 @@ is a promise that the widget being created will provide the same keyboard
 interactions expected for a button. An accessible role of a button will not
 turn automatically any widget into a `GtkButton`; but if your widget behaves
 like a button, using the %GTK_ACCESSIBLE_ROLE_BUTTON will allow any
-assistive technology to handle it like they would a #GtkButton.
+assistive technology to handle it like they would a `GtkButton`.
 
 ### Attributes can both hide and enhance
 
@@ -308,7 +308,7 @@ interface.
 
 A "presentation" role should not be confused with the
 %GTK_ACCESSIBLE_STATE_HIDDEN state; the "hidden" state is transient, and is
-typically controlled by showing and hiding a widget using the #GtkWidget
+typically controlled by showing and hiding a widget using the `GtkWidget`
 API.
 
 ## Design patterns and custom widgets
@@ -322,7 +322,7 @@ as well.
 A button is a widget that enables users to trigger an action. While it is
 recommended you use `GtkButton` for anything that looks and behaves like a
 button, it is possible to apply a button behavior to UI elements like images
-by using a #GtkGestureClick gesture. When doing so, you should:
+by using a `GtkGestureClick` gesture. When doing so, you should:
 
   - Give your widget the role %GTK_ACCESSIBLE_ROLE_BUTTON
   - Install an action with no parameters, which will activate the widget
@@ -336,7 +336,7 @@ in the same way as a `GtkSpinButton` or `GtkSearchEntry`.
 
 ### Tab-based UI
 
-If you make a tab-based interface, you should consider using #GtkStack
+If you make a tab-based interface, you should consider using `GtkStack`
 as the core, and just make a custom tab widget to control the active
 stack page. When doing so, the following extra steps will ensure that
 your tabs are accessible in the same way as `GtkStackSwitcher` or `GtkNotebook`:
@@ -344,7 +344,7 @@ your tabs are accessible in the same way as `GtkStackSwitcher` or `GtkNotebook`:
 - Give your tab container the role %GTK_ACCESSIBLE_ROLE_TAB_LIST
 - Give your tab widgets the role %GTK_ACCESSIBLE_ROLE_TAB
 - Set up the %GTK_ACCESSIBLE_RELATION_CONTROLS relation between each
-  tab and the #GtkStackPage object for its page
+  tab and the `GtkStackPage` object for its page
 - Set the %GTK_ACCESSIBLE_PROPERTY_SELECTED property on each tab, with
   the active tab getting the value %TRUE, all others %FALSE
 
@@ -357,7 +357,7 @@ or add a `activate-tab` action on each tab.
 ### Value controls
 
 A value control (ie a widget that controls a one-dimensional quantity
-that can be represented by a #GtkAdjustment) can be represented to
+that can be represented by a `GtkAdjustment`) can be represented to
 accessible technologies by setting the %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN,
 %GTK_ACCESSIBLE_PROPERTY_VALUE_MAX, and %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW
 properties.

docs/reference/gtk/section-list-widget.md

@@ -24,25 +24,25 @@ you should be aware of what they refer to. These are often generic terms that
 have a specific meaning in this context.
 
 **_Views_** or **_list widgets_** are the widgets that hold and manage the lists.
-Examples of these widgets would be #GtkListView or #GtkGridView.
+Examples of these widgets would be `GtkListView` or `GtkGridView`.
 
-Views display data from a **_model_**. A model is a #GListModel and models can
+Views display data from a **_model_**. A model is a `GListModel` and models can
 be provided in 3 ways or combinations thereof:
 
  * Many list models implementations already exist. There are models that provide
-   specific data, like #GtkDirectoryList. And there are models like #GListStore
+   specific data, like `GtkDirectoryList`. And there are models like `GListStore`
    that allow building lists manually.
 
- * Wrapping list models like #GtkFilterListModel or #GtkSortListModel
+ * Wrapping list models like `GtkFilterListModel` or `GtkSortListModel`
    modify, adapt or combine other models.
 
- * Last but not least, developers are encouraged to create their own #GListModel
+ * Last but not least, developers are encouraged to create their own `GListModel`
    implementations. The interface is kept deliberately small to make this easy.
 
 The same model can be used in multiple different views and wrapped with
 multiple different models at once.
 
-The elements in a model are called **_items_**. All items are #GObjects.
+The elements in a model are called **_items_**. All items are `GObjects`.
 
 Every item in a model has a **_position_** which is the unsigned integer that
 describes where in the model the item is located. The first item in a model is
@@ -56,11 +56,11 @@ with models. Oftentimes some things are really hard to do one way but very easy
 the other way.
 
 The other important part of a view is a **_factory_**. Each factory is
-a #GtkListItemFactory implementation that takes care of mapping the items
+a `GtkListItemFactory` implementation that takes care of mapping the items
 of the model to widgets that can be shown in the view.
 
 The way factories do this is by creating a **_listitem_** for each item that
-is currently in use. Listitems are always #GtkListItem objects. They are only
+is currently in use. Listitems are always `GtkListItem` objects. They are only
 ever created by GTK and provide information about what item they are meant
 to display.
 
@@ -71,28 +71,28 @@ for the data displayed, the programming language and development environment
 is an important task that can simplify setting up the view tremendously.
 
 Views support selections via a **_selection model_**. A selection model is an
-implementation of the #GtkSelectionModel interface on top of the #GListModel
+implementation of the `GtkSelectionModel` interface on top of the `GListModel`
 interface that allows marking each item in a model as either selected or not
 selected. Just like regular models, this can be implemented either by
-implementing #GtkSelectionModel directly or by wrapping a model with one of
-the GTK models provided for this purposes, such as #GtkNoSelection
-or #GtkSingleSelection.
+implementing `GtkSelectionModel` directly or by wrapping a model with one of
+the GTK models provided for this purposes, such as `GtkNoSelection`
+or `GtkSingleSelection`.
 
 The behavior of selection models - ie which items they allow selecting and
 what effect this has on other items - is completely up to the selection model.
 As such, single-selections, multi-selections or sharing selection state between
 different selection models and/or views is possible. The selection state of an
-item is exposed in the listitem via the #GtkListItem:selected property.
+item is exposed in the listitem via the `GtkListItem:selected` property.
 
 Views and listitems also support activation. Activation means that double
 clicking or pressing enter while inside a focused row will cause the view
-to emit and activation signal such as #GtkListView::activate. This provides
+to emit and activation signal such as `GtkListView::activate`. This provides
 an easy way to set up lists, but can also be turned off on listitems if undesired.
 
 Both selections and activation are supported among other things via widget
 [actions](#actions-overview). This allows developers to add widgets to their
 lists that cause selections to change or to trigger activation via
-the #GtkActionable interface. For a list of all supported actions see the
+the `GtkActionable` interface. For a list of all supported actions see the
 relevant documentation.
 
 ## Behind the scenes
@@ -114,8 +114,8 @@ new position at any time causing any state to be lost.
 
 Another important requirement for views is that they need to know which items
 are not visible so they can be recycled. Views achieve that by implementing
-the #GtkScrollable interface and expecting to be placed directly into
-a #GtkScrolledWindow.
+the `GtkScrollable` interface and expecting to be placed directly into
+a `GtkScrolledWindow`.
 
 Of course, if you are only using models with few items, this is not important
 and you can treat views like any other widget. But if you use large lists and
@@ -128,8 +128,8 @@ tradeoffs of those and experiment with them.
 
 GTK offers a wide variety of wrapping models which change or supplement an
 existing model (or models) in some way. But when it comes to storing your
-actual data, there are only a few ready-made choices available: #GListStore
-and #GtkStringList.
+actual data, there are only a few ready-made choices available: `GListStore`
+and `GtkStringList`.
 
 GListStore is backed by a balanced tree and has performance characteristics
 that are expected for that data structure. It works reasonably well for dataset
@@ -143,7 +143,7 @@ place where you would otherwise use `char*[]` and works best if the dataset
 is not very dynamic.
 
 If these models don't fit your use case or scalability requirements, you
-should make a custom #GListModel. It is a small interface and not very hard
+should make a custom `GListModel`. It is a small interface and not very hard
 to implement.
 
 For asymptotic performance comparisons between tree- and array-based
@@ -152,23 +152,23 @@ implementations, see this
 
 ## Displaying trees
 
-While #GtkTreeView provided built-in support for trees, the list widgets, and
-in particular #GListModel do not. This was a design choice because the common
+While `GtkTreeView` provided built-in support for trees, the list widgets, and
+in particular `GListModel` do not. This was a design choice because the common
 use case is displaying lists and not trees and it greatly simplifies the API
 interface provided.
 
 However, GTK provides functionality to make trees look and behave like lists
 for the people who still want to display lists. This is achieved by using
-the #GtkTreeListModel model to flatten a tree into a list. The #GtkTreeExpander
+the `GtkTreeListModel` model to flatten a tree into a list. The `GtkTreeExpander`
 widget can then be used inside a listitem to allow users to expand and collapse
-rows and provide a similar experience to #GtkTreeView.
+rows and provide a similar experience to `GtkTreeView`.
 
 Developers should refer to those objects' API reference for more discussion
 on the topic.
 
 ## List styles
 
-One of the advantages of the new list widgets over #GtkTreeViews and cell
+One of the advantages of the new list widgets over `GtkTreeViews` and cell
 renderers is that they are fully themable using GTK CSS. This provides a
 lot of flexibility. The themes that ship with GTK provide a few predefined
 list styles that can be used in many situations:
@@ -192,7 +192,7 @@ style class.
 
 ## Comparison to GtkTreeView
 
-Developers familiar with #GtkTreeView may wonder how this way of doing lists
+Developers familiar with `GtkTreeView` may wonder how this way of doing lists
 compares to the way they know. This section will try to outline the similarities
 and differences between the two.
 
@@ -200,26 +200,26 @@ This new approach tries to provide roughly the same functionality as the old
 approach but often uses a very different approach to achieve these goals.
 
 The main difference and one of the primary reasons for this new development is
-that items can be displayed using regular widgets and #GtkCellRenderer is no
+that items can be displayed using regular widgets and `GtkCellRenderer` is no
 longer necessary. This allows all benefits that widgets provide, such as complex
 layout and animating widgets and not only makes cell renderers obsolete, but
-also #GtkCellArea.
+also `GtkCellArea`.
 
-The other big difference is the massive change to the data model. #GtkTreeModel
-was a rather complex interface for a tree data structure and #GListModel was
+The other big difference is the massive change to the data model. `GtkTreeModel`
+was a rather complex interface for a tree data structure and `GListModel` was
 deliberately designed to be a simple data structure for lists only. (See
 [above](#displaying-trees)) for how to still do trees with this new model.)
 Another big change is that the new model allows for bulk changes via
-the #GListModel:items-changed signal while #GtkTreeModel only allows a single
+the `GListModel:items-changed` signal while `GtkTreeModel` only allows a single
 item to change at once. The goal here is of course to encourage implementation
 of custom list models.
 
 Another consequence of the new model is that it is now easily possible to
 refer to the contents of a row in the model directly by keeping the item,
-while #GtkTreeRowReference was a very slow mechanism to achieve the same.
+while `GtkTreeRowReference` was a very slow mechanism to achieve the same.
 And because the items are real objects, developers can make them emit change
 signals causing listitems and their children to update, which wasn't possible
-with #GtkTreeModel.
+with `GtkTreeModel`.
 
 The selection handling is also different. While selections used to be managed
 via custom code in each widget, selection state is now meant to be managed by
@@ -229,24 +229,24 @@ specialized requirements.
 Finally here's a quick list of equivalent functionality to look for when
 transitioning code for easy lookup:
 
-| Old                 | New                                 |
-| ------------------- | ----------------------------------- |
-| #GtkTreeModel       | #GListModel                         |
-| #GtkTreePath        | #guint position, #GtkTreeListRow    |
-| #GtkTreeIter        | #guint position                     |
-| #GtkTreeRowReference | #GObject item                       |
-| #GtkListStore       | #GListStore                         |
-| #GtkTreeStore       | #GtkTreeListModel, #GtkTreeExpander |
-| #GtkTreeSelection   | #GtkSelectionModel                  |
-| #GtkTreeViewColumn  | #GtkColumnView                      |
-| #GtkTreeView        | #GtkListView, #GtkColumnView        |
-| #GtkCellView        | #GtkListItemWidget                  |
-| #GtkComboBox        | #GtkDropDown                        |
-| #GtkIconView        | #GtkGridView                        |
-| #GtkTreeSortable    | #GtkColumnView                      |
-| #GtkTreeModelSort   | #GtkSortListModel                   |
-| #GtkTreeModelFilter | #GtkFilterListModel                 |
-| #GtkCellLayout      | #GtkListItemFactory                 |
-| #GtkCellArea        | #GtkWidget                          |
-| #GtkCellRenderer    | #GtkWidget                          |
+| Old                  | New                                  |
+| -------------------- | ------------------------------------ |
+| `GtkTreeModel`       | `GListModel`                         |
+| `GtkTreePath`        | `guint` position, `GtkTreeListRow`   |
+| `GtkTreeIter`        | `guint` position                     |
+| `GtkTreeRowReference`| `GObject` item                       |
+| `GtkListStore`       | `GListStore`                         |
+| `GtkTreeStore`       | `GtkTreeListModel`, `GtkTreeExpander`|
+| `GtkTreeSelection`   | `GtkSelectionModel`                  |
+| `GtkTreeViewColumn`  | `GtkColumnView`                      |
+| `GtkTreeView`        | `GtkListView`, `GtkColumnView`       |
+| `GtkCellView`        | `GtkListItemWidget`                  |
+| `GtkComboBox`        | `GtkDropDown`                        |
+| `GtkIconView`        | `GtkGridView`                        |
+| `GtkTreeSortable`    | `GtkColumnView`                      |
+| `GtkTreeModelSort`   | `GtkSortListModel`                   |
+| `GtkTreeModelFilter` | `GtkFilterListModel`                 |
+| `GtkCellLayout`      | `GtkListItemFactory`                 |
+| `GtkCellArea`        | `GtkWidget`                          |
+| `GtkCellRenderer`    | `GtkWidget`                          |
 

docs/reference/gtk/section-text-widget.md

@@ -2,15 +2,15 @@ Title: Text Widget Overview
 Slug: gtk-textview
 
 GTK has an extremely powerful framework for multiline text editing.  The
-primary objects involved in the process are #GtkTextBuffer, which represents the 
-text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer. 
+primary objects involved in the process are `GtkTextBuffer`, which represents the
+text being edited, and `GtkTextView`, a widget which can display a `GtkTextBuffer`.
 Each buffer can be displayed by any number of views.
 
 One of the important things to remember about text in GTK is that it's in
 the UTF-8 encoding. This means that one character can be encoded as multiple
 bytes. Character counts are usually referred to as _offsets_, while byte
 counts are called _indexes_. If you confuse these two, things will work fine
-with ASCII, but as soon as your buffer contains multibyte characters, bad 
+with ASCII, but as soon as your buffer contains multibyte characters, bad
 things will happen.
 
 Text in a buffer can be marked with _tags_. A tag is an attribute that can
@@ -19,10 +19,10 @@ and make the text inside the tag bold. However, the tag concept is more
 general than that; tags don't have to affect appearance. They can instead
 affect the behavior of mouse and key presses, "lock" a range of text so the
 user can't edit it, or countless other things. A tag is represented by a
-#GtkTextTag object. One #GtkTextTag can be applied to any number of text
+`GtkTextTag` object. One `GtkTextTag` can be applied to any number of text
 ranges in any number of buffers.
 
-Each tag is stored in a #GtkTextTagTable. A tag table defines a set of
+Each tag is stored in a `GtkTextTagTable`. A tag table defines a set of
 tags that can be used together. Each buffer has one tag table associated with
 it; only tags from that tag table can be used with the buffer. A single tag
 table can be shared between multiple buffers, however.
@@ -32,36 +32,36 @@ your tag that makes things bold "bold"), but they can also be anonymous (which
 is convenient if you're creating tags on-the-fly).
 
 Most text manipulation is accomplished with _iterators_, represented by a
-#GtkTextIter. An iterator represents a position between two characters in
-the text buffer. #GtkTextIter is a struct designed to be allocated on the
+`GtkTextIter`. An iterator represents a position between two characters in
+the text buffer. `GtkTextIter` is a struct designed to be allocated on the
 stack; it's guaranteed to be copiable by value and never contain any
 heap-allocated data. Iterators are not valid indefinitely; whenever the
 buffer is modified in a way that affects the number of characters in the
 buffer, all outstanding iterators become invalid. (Note that deleting 5
-characters and then reinserting 5 still invalidates iterators, though you 
-end up with the same number of characters you pass through a state with a 
+characters and then reinserting 5 still invalidates iterators, though you
+end up with the same number of characters you pass through a state with a
 different number).
 
 Because of this, iterators can't be used to preserve positions across buffer
-modifications. To preserve a position, the #GtkTextMark object is ideal. You
-can think of a mark as an invisible cursor or insertion point; it floats in 
-the buffer, saving a position. If the text surrounding the mark is deleted, 
-the mark remains in the position the text once occupied; if text is inserted 
-at the mark, the mark ends up either to the left or to the right of the new 
+modifications. To preserve a position, the `GtkTextMark` object is ideal. You
+can think of a mark as an invisible cursor or insertion point; it floats in
+the buffer, saving a position. If the text surrounding the mark is deleted,
+the mark remains in the position the text once occupied; if text is inserted
+at the mark, the mark ends up either to the left or to the right of the new
 text, depending on its _gravity_. The standard text cursor in left-to-right
 languages is a mark with right gravity, because it stays to the right of
 inserted text.
 
 Like tags, marks can be either named or anonymous. There are two marks
-built-in to #GtkTextBuffer; these are named "insert" and "selection_bound"
+built-in to `GtkTextBuffer`; these are named "insert" and "selection_bound"
 and refer to the insertion point and the boundary of the selection which
 is not the insertion point, respectively. If no text is selected, these
 two marks will be in the same position. You can manipulate what is selected
 and where the cursor appears by moving these marks around.
 
 If you want to place the cursor in response to a user action, be sure to use
-gtk_text_buffer_place_cursor(), which moves both at once without causing a 
-temporary selection (moving one then the other temporarily selects the range in 
+gtk_text_buffer_place_cursor(), which moves both at once without causing a
+temporary selection (moving one then the other temporarily selects the range in
 between the old and new positions).
 
 Text buffers always contain at least one line, but may be empty (that
@@ -69,7 +69,7 @@ is, buffers can contain zero characters). The last line in the text
 buffer never ends in a line separator (such as newline); the other
 lines in the buffer always end in a line separator. Line separators
 count as characters when computing character counts and character
-offsets. Note that some Unicode line separators are represented with 
+offsets. Note that some Unicode line separators are represented with
 multiple bytes in UTF-8, and the two-character sequence "\r\n" is also
 considered a line separator.
 
@@ -83,7 +83,7 @@ gtk_text_buffer_end_irreversible_action().
 
 ## Simple Example
 
-The simplest usage of #GtkTextView  might look like this:
+The simplest usage of `GtkTextView` might look like this:
 
 ``` {.c}
 GtkWidget *view;
@@ -101,17 +101,17 @@ gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
  */
 ```
 
-In many cases it's also convenient to first create the buffer with 
-gtk_text_buffer_new(), then create a widget for that buffer with 
-gtk_text_view_new_with_buffer(). Or you can change the buffer the widget 
+In many cases it's also convenient to first create the buffer with
+gtk_text_buffer_new(), then create a widget for that buffer with
+gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
 displays after the widget is created with gtk_text_view_set_buffer().
 
 ## Example of Changing Text Attributes
 
-The way to affect text attributes in #GtkTextView is to
+The way to affect text attributes in `GtkTextView` is to
 apply tags that change the attributes for a region of text.
-For text features that come from the theme — such as font and
-foreground color -- use CSS to override their default values.
+For text features that come from the theme — such as font and
+foreground color — use CSS to override their default values.
 
 ```
 GtkWidget *view;
@@ -148,11 +148,11 @@ gtk_text_view_set_left_margin (GTK_TEXT_VIEW (view), 30);
 /* Use a tag to change the color for just one part of the widget */
 tag = gtk_text_buffer_create_tag (buffer, "blue_foreground",
                                   "foreground", "blue",
-                                  NULL);  
+                                  NULL);
 gtk_text_buffer_get_iter_at_offset (buffer, &start, 7);
 gtk_text_buffer_get_iter_at_offset (buffer, &end, 12);
 gtk_text_buffer_apply_tag (buffer, tag, &start, &end);
 ```
 
 The `gtk4-demo` application that comes with
-GTK contains more example code for #GtkTextView.
+GTK contains more example code for `GtkTextView`.

docs/reference/gtk/section-tree-widget.md

@@ -1,8 +1,8 @@
 Title: Tree and List Widget Overview
 Slug: gtk-treeview
 
-To create a tree or list in GTK, use the #GtkTreeModel interface in
-conjunction with the #GtkTreeView widget.  This widget is designed around
+To create a tree or list in GTK, use the `GtkTreeModel` interface in
+conjunction with the `GtkTreeView` widget. This widget is designed around
 a _Model/View/Controller_ design and consists of four major parts:
 
 - The tree view widget (GtkTreeView)
@@ -25,9 +25,9 @@ it be rendered as a checkbox?
 
 ## Creating a model
 
-GTK provides two simple models that can be used: the #GtkListStore
-and the #GtkTreeStore. GtkListStore is used to model list widgets,
-while the GtkTreeStore models trees. It is possible to develop a new
+GTK provides two simple models that can be used: the `GtkListStore`
+and the `GtkTreeStore`. `GtkListStore` is used to model list widgets,
+while the `GtkTreeStore` models trees. It is possible to develop a new
 type of model, but the existing models should be satisfactory for all
 but the most specialized of situations. Creating the model is quite
 
@@ -59,7 +59,7 @@ GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS,       /* Total number of co
 
 Adding data to the model is done using gtk_tree_store_set() or
 gtk_list_store_set(), depending upon which sort of model was
-created. To do this, a #GtkTreeIter must be acquired. The iterator
+created. To do this, a `GtkTreeIter` must be acquired. The iterator
 points to the location where data will be added.
 
 Once an iterator has been acquired, gtk_tree_store_set() is used to
@@ -119,8 +119,8 @@ gtk_tree_store_set (store, &iter2,
 
 While there are several different models to choose from, there is
 only one view widget to deal with. It works with either the list
-or the tree store. Setting up a #GtkTreeView is not a difficult
-matter. It needs a #GtkTreeModel to know where to retrieve its data
+or the tree store. Setting up a `GtkTreeView` is not a difficult
+matter. It needs a `GtkTreeModel` to know where to retrieve its data
 from.
 
 ``` {.c}
@@ -131,16 +131,16 @@ tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
 
 ## Columns and cell renderers
 
-Once the #GtkTreeView widget has a model, it will need to know how
+Once the `GtkTreeView` widget has a model, it will need to know how
 to display the model. It does this with columns and cell renderers.
 
 Cell renderers are used to draw the data in the tree model in a
 way. There are a number of cell renderers that come with GTK,
-including the #GtkCellRendererText, #GtkCellRendererPixbuf and
-the #GtkCellRendererToggle. It is relatively easy to write a
+including the `GtkCellRendererText`, `GtkCellRendererPixbuf` and
+the `GtkCellRendererToggle`. It is relatively easy to write a
 custom renderer.
 
-A #GtkTreeViewColumn is the object that GtkTreeView uses to organize
+A `GtkTreeViewColumn` is the object that `GtkTreeView` uses to organize
 the vertical columns in the tree view. It needs to know the name of
 the column to label for the user, what type of cell renderer to use,
 and which piece of data to retrieve from the model for a given row.
@@ -166,7 +166,7 @@ created and columns are added to it.
 Most applications will need to not only deal with displaying data,
 but also receiving input events from users. To do this, simply get
 a reference to a selection object and connect to the
-#GtkTreeSelection::changed signal.
+`GtkTreeSelection::changed` signal.
 
 ``` {.c}
 /* Prototype for selection handler callback */
@@ -205,11 +205,11 @@ tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
 
 ## Simple Example
 
-Here is a simple example of using a #GtkTreeView widget in context
+Here is a simple example of using a `GtkTreeView` widget in context
 of the other widgets. It simply creates a simple model and view,
 and puts them together. Note that the model is never populated
-with data — that is left as an exercise for the reader.
-More information can be found on this in the #GtkTreeModel section.
+with data — that is left as an exercise for the reader.
+More information can be found on this in the `GtkTreeModel` section.
 
 ``` {.c}
 enum

docs/reference/gtk/visual_index.md

@@ -1,5 +1,7 @@
 Title: Widget Gallery
 
+<style>p { display: flex; flex-flow: row wrap; }</style>
+
 ## Display widgets
 
 [![label](label.png)](class.Label.html)

docs/reference/gtk/wayland.md

@@ -18,3 +18,8 @@ or wayland-1.
 ### XDG_RUNTIME_DIR
 
 Used to locate the Wayland socket to use.
+
+## Wayland-specific APIs
+
+See the [documentation](https://docs.gtk.org/gdk4-wayland/) for
+Wayland-specific GDK APIs.

docs/reference/gtk/x11.md

@@ -25,6 +25,11 @@ high-dpi displays. Normally, GDK will pick up a suitable scale factor
 for each monitor from the display system. This environment variable
 allows to override that.
 
+## X11-specific APIs
+
+See the [documentation](https://docs.gtk.org/gdk4-x11/) for
+X11-specific GDK APIs.
+
 ## Understanding the X11 architecture
 
 People coming from a Windows or MacOS background often find certain

examples/application9/exampleapp.c

@@ -59,12 +59,14 @@ example_app_startup (GApplication *app)
 }
 
 static void
-example_app_activate (GApplication *app)
+example_app_create_window (GtkApplication *app,
+                           const char     *save_id)
 {
   ExampleAppWindow *win;
 
   win = example_app_window_new (EXAMPLE_APP (app));
-  gtk_window_present (GTK_WINDOW (win));
+  gtk_widget_set_save_id (GTK_WIDGET (win), save_id);
+  /* FIXME: differentiate save ids */
 }
 
 static void
@@ -93,8 +95,8 @@ static void
 example_app_class_init (ExampleAppClass *class)
 {
   G_APPLICATION_CLASS (class)->startup = example_app_startup;
-  G_APPLICATION_CLASS (class)->activate = example_app_activate;
   G_APPLICATION_CLASS (class)->open = example_app_open;
+  GTK_APPLICATION_CLASS (class)->create_window = example_app_create_window;
 }
 
 ExampleApp *
@@ -103,5 +105,7 @@ example_app_new (void)
   return g_object_new (EXAMPLE_APP_TYPE,
                        "application-id", "org.gtk.exampleapp",
                        "flags", G_APPLICATION_HANDLES_OPEN,
+                       "register-session", TRUE,
+                       "save-state", TRUE,
                        NULL);
 }

examples/application9/exampleappwin.c

@@ -17,6 +17,8 @@ struct _ExampleAppWindow
   GtkWidget *words;
   GtkWidget *lines;
   GtkWidget *lines_label;
+
+  GList *files;
 };
 
 G_DEFINE_TYPE (ExampleAppWindow, example_app_window, GTK_TYPE_APPLICATION_WINDOW)
@@ -211,14 +213,68 @@ example_app_window_dispose (GObject *object)
 
   g_clear_object (&win->settings);
 
+  g_list_free_full (win->files, g_object_unref);
+  win->files = NULL;
+
   G_OBJECT_CLASS (example_app_window_parent_class)->dispose (object);
 }
 
+static gboolean
+example_app_window_save_state (GtkWidget    *widget,
+                               GVariantDict *dict,
+                               gboolean     *save_children)
+{
+  ExampleAppWindow *win = EXAMPLE_APP_WINDOW (widget);
+  GVariantBuilder builder;
+
+  g_variant_builder_init (&builder, G_VARIANT_TYPE ("as"));
+  for (GList *l = win->files; l; l = l->next)
+    {
+      g_variant_builder_add (&builder, "s", g_file_peek_path (G_FILE (l->data)));
+    }
+
+  g_variant_dict_insert_value (dict, "files", g_variant_builder_end (&builder));
+
+  /* Save window state */
+  GTK_WIDGET_CLASS (example_app_window_parent_class)->save_state (widget, dict, save_children);
+
+  *save_children = TRUE;
+  return TRUE;
+}
+
+static gboolean
+example_app_window_restore_state (GtkWidget *widget,
+                                  GVariant  *state)
+{
+  ExampleAppWindow *win = EXAMPLE_APP_WINDOW (widget);
+  GVariantIter *iter;
+
+  /* Restore window state */
+  GTK_WIDGET_CLASS (example_app_window_parent_class)->restore_state (widget, state);
+
+  if (g_variant_lookup (state, "files", "as", &iter))
+    {
+       const char *path;
+
+       while (g_variant_iter_next (iter, "&s", &path))
+         {
+           GFile *file = g_file_new_for_path (path);
+           example_app_window_open (win, file);
+           g_object_unref (file);
+         }
+    }
+
+  return TRUE;
+}
+
 static void
 example_app_window_class_init (ExampleAppWindowClass *class)
 {
   G_OBJECT_CLASS (class)->dispose = example_app_window_dispose;
 
+  GTK_WIDGET_CLASS (class)->save_state = example_app_window_save_state;
+  GTK_WIDGET_CLASS (class)->restore_state = example_app_window_restore_state;
+
   gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
                                                "/org/gtk/exampleapp/window.ui");
 
@@ -288,4 +344,6 @@ example_app_window_open (ExampleAppWindow *win,
 
   update_words (win);
   update_lines (win);
+
+  win->files = g_list_append (win->files, g_object_ref (file));
 }

examples/application9/window.ui

@@ -4,6 +4,7 @@
     <property name="title" translatable="yes">Example Application</property>
     <property name="default-width">600</property>
     <property name="default-height">400</property>
+    <property name="save-id">window</property>
     <child type="titlebar">
       <object class="GtkHeaderBar" id="header">
         <child>
@@ -26,6 +27,7 @@
           <object class="GtkToggleButton" id="search">
             <property name="sensitive">0</property>
             <property name="icon-name">edit-find-symbolic</property>
+            <property name="save-id">search</property>
           </object>
         </child>
         <child type="end">
@@ -38,6 +40,7 @@
     <child>
       <object class="GtkBox" id="content_box">
         <property name="orientation">vertical</property>
+        <property name="save-id">content_box</property>
         <child>
           <object class="GtkSearchBar" id="searchbar">
             <child>
@@ -49,8 +52,10 @@
         </child>
         <child>
           <object class="GtkBox" id="hbox">
+            <property name="save-id">hbox</property>
             <child>
               <object class="GtkRevealer" id="sidebar">
+                <property name="save-id">sidebar</property>
                 <property name="transition-type">slide-right</property>
                 <child>
                   <object class="GtkScrolledWindow" id="sidebar-sw">
@@ -66,6 +71,7 @@
             </child>
             <child>
               <object class="GtkStack" id="stack">
+                <property name="save-id">stack</property>
                 <signal name="notify::visible-child" handler="visible_child_changed"/>
               </object>
             </child>

gdk/broadway/gdkbroadwaydisplay.h

@@ -48,6 +48,10 @@ void                    gdk_broadway_display_show_keyboard       (GdkBroadwayDis
 GDK_AVAILABLE_IN_ALL
 void                    gdk_broadway_display_hide_keyboard       (GdkBroadwayDisplay *display);
 
+GDK_AVAILABLE_IN_4_4
+void                    gdk_broadway_display_set_surface_scale   (GdkDisplay *display,
+                                                                  int         scale);
+
 G_END_DECLS
 
 #endif /* __GDK_BROADWAY_DISPLAY_H__ */

gdk/broadway/gdkdisplay-broadway.c

@@ -94,10 +94,12 @@ _gdk_broadway_display_size_changed (GdkDisplay                      *display,
 
   if (msg->width == current_size.width &&
       msg->height == current_size.height &&
-      msg->scale == broadway_display->scale_factor)
+      (msg->scale == broadway_display->scale_factor ||
+       broadway_display->fixed_scale))
     return;
 
-  broadway_display->scale_factor = msg->scale;
+  if (!broadway_display->fixed_scale)
+    broadway_display->scale_factor = msg->scale;
 
   gdk_monitor_set_geometry (monitor, &(GdkRectangle) { 0, 0, msg->width, msg->height });
   gdk_monitor_set_scale_factor (monitor, msg->scale);
@@ -112,7 +114,8 @@ _gdk_broadway_display_size_changed (GdkDisplay                      *display,
         gdk_broadway_surface_move_resize (GDK_SURFACE (toplevel),
                                           0, 0,
                                           msg->width, msg->height);
-    }}
+    }
+}
 
 static GdkDevice *
 create_core_pointer (GdkDisplay *display)
@@ -327,6 +330,37 @@ gdk_broadway_display_hide_keyboard (GdkBroadwayDisplay *display)
   _gdk_broadway_server_set_show_keyboard (display->server, FALSE);
 }
 
+/**
+ * gdk_broadway_display_set_surface_scale:
+ * @display: (type GdkBroadwayDisplay): the display
+ * @scale: The new scale value, as an integer >= 1
+ *
+ * Forces a specific window scale for all windows on this display,
+ * instead of using the default or user configured scale. This
+ * is can be used to disable scaling support by setting @scale to
+ * 1, or to programmatically set the window scale.
+ *
+ * Once the scale is set by this call it will not change in
+ * response to later user configuration changes.
+ *
+ * Since: 4.4
+ */
+void
+gdk_broadway_display_set_surface_scale (GdkDisplay *display,
+                                        int         scale)
+{
+  GdkBroadwayDisplay *self;
+
+  g_return_if_fail (GDK_IS_BROADWAY_DISPLAY (display));
+  g_return_if_fail (scale > 0);
+
+  self = GDK_BROADWAY_DISPLAY (display);
+
+  self->scale_factor = scale;
+  self->fixed_scale = TRUE;
+  gdk_monitor_set_scale_factor (self->monitor, scale);
+}
+
 static GListModel *
 gdk_broadway_display_get_monitors (GdkDisplay *display)
 {

gdk/broadway/gdkdisplay-broadway.h

@@ -57,6 +57,7 @@ struct _GdkBroadwayDisplay
   GListStore *monitors;
   GdkMonitor *monitor;
   int scale_factor;
+  gboolean fixed_scale;
 
   GHashTable *texture_cache;
 

gdk/gdk.c

@@ -50,7 +50,7 @@
 /**
  * GDK_WINDOWING_X11:
  *
- * The #GDK_WINDOWING_X11 macro is defined if the X11 backend
+ * The `GDK_WINDOWING_X11` macro is defined if the X11 backend
  * is supported.
  *
  * Use this macro to guard code that is specific to the X11 backend.
@@ -59,7 +59,7 @@
 /**
  * GDK_WINDOWING_WIN32:
  *
- * The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
+ * The `GDK_WINDOWING_WIN32` macro is defined if the Win32 backend
  * is supported.
  *
  * Use this macro to guard code that is specific to the Win32 backend.
@@ -68,7 +68,7 @@
 /**
  * GDK_WINDOWING_MACOS:
  *
- * The #GDK_WINDOWING_MACOS macro is defined if the MacOS backend
+ * The `GDK_WINDOWING_MACOS` macro is defined if the MacOS backend
  * is supported.
  *
  * Use this macro to guard code that is specific to the MacOS backend.
@@ -77,7 +77,7 @@
 /**
  * GDK_WINDOWING_WAYLAND:
  *
- * The #GDK_WINDOWING_WAYLAND macro is defined if the Wayland backend
+ * The `GDK_WINDOWING_WAYLAND` macro is defined if the Wayland backend
  * is supported.
  *
  * Use this macro to guard code that is specific to the Wayland backend.
@@ -87,6 +87,7 @@
  * GDK_DISABLE_DEPRECATION_WARNINGS:
  *
  * A macro that should be defined before including the gdk.h header.
+ *
  * If it is defined, no compiler warnings will be produced for uses
  * of deprecated GDK APIs.
  */
@@ -126,6 +127,7 @@ static const GdkDebugKey gdk_debug_keys[] = {
   { "gl-legacy",       GDK_DEBUG_GL_LEGACY, "Use a legacy OpenGL context" },
   { "gl-gles",         GDK_DEBUG_GL_GLES, "Use a GLES OpenGL context" },
   { "gl-debug",        GDK_DEBUG_GL_DEBUG, "Insert debugging information in OpenGL" },
+  { "gl-glx",          GDK_DEBUG_GL_GLX, "Use GLX on X11" },
   { "vulkan-disable",  GDK_DEBUG_VULKAN_DISABLE, "Disable Vulkan support" },
   { "vulkan-validate", GDK_DEBUG_VULKAN_VALIDATE, "Load the Vulkan validation layer" },
   { "default-settings",GDK_DEBUG_DEFAULT_SETTINGS, "Force default values for xsettings" },

gdk/gdkapplaunchcontext.c

@@ -237,7 +237,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
 /**
  * gdk_app_launch_context_set_icon:
  * @context: a `GdkAppLaunchContext`
- * @icon: (allow-none): a #GIcon, or %NULL
+ * @icon: (nullable): a `GIcon`
  *
  * Sets the icon for applications that are launched with this
  * context.
@@ -267,12 +267,12 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
 /**
  * gdk_app_launch_context_set_icon_name:
  * @context: a `GdkAppLaunchContext`
- * @icon_name: (allow-none): an icon name, or %NULL
+ * @icon_name: (nullable): an icon name
  *
  * Sets the icon for applications that are launched with this context.
  *
  * The @icon_name will be interpreted in the same way as the Icon field
- * in desktop files. See also [method@Gdk.AppLaunchContext.set_icon()].
+ * in desktop files. See also [method@Gdk.AppLaunchContext.set_icon].
  *
  * If both @icon and @icon_name are set, the @icon_name takes priority.
  * If neither @icon or @icon_name is set, the icon is taken from either

gdk/gdkcairo.c

@@ -26,9 +26,9 @@
 /**
  * gdk_cairo_set_source_rgba:
  * @cr: a cairo context
- * @rgba: a #GdkRGBA
+ * @rgba: a `GdkRGBA`
  *
- * Sets the specified #GdkRGBA as the source color of @cr.
+ * Sets the specified `GdkRGBA` as the source color of @cr.
  */
 void
 gdk_cairo_set_source_rgba (cairo_t       *cr,
@@ -47,7 +47,7 @@ gdk_cairo_set_source_rgba (cairo_t       *cr,
 /**
  * gdk_cairo_rectangle:
  * @cr: a cairo context
- * @rectangle: a #GdkRectangle
+ * @rectangle: a `GdkRectangle`
  *
  * Adds the given rectangle to the current path of @cr.
  */
@@ -66,7 +66,7 @@ gdk_cairo_rectangle (cairo_t            *cr,
 /**
  * gdk_cairo_region:
  * @cr: a cairo context
- * @region: a #cairo_region_t
+ * @region: a `cairo_region_t`
  *
  * Adds the given region to the current path of @cr.
  */
@@ -185,7 +185,7 @@ gdk_cairo_surface_paint_pixbuf (cairo_surface_t *surface,
 /**
  * gdk_cairo_set_source_pixbuf:
  * @cr: a cairo context
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  * @pixbuf_x: X coordinate of location to place upper left corner of @pixbuf
  * @pixbuf_y: Y coordinate of location to place upper left corner of @pixbuf
  *
@@ -232,7 +232,7 @@ gdk_cairo_set_source_pixbuf (cairo_t         *cr,
  * You must explicitly check the return value of you want to handle
  * that case.
  *
- * Returns: %TRUE if the extents fit in a #GdkRectangle, %FALSE if not
+ * Returns: %TRUE if the extents fit in a `GdkRectangle`, %FALSE if not
  */
 gboolean
 _gdk_cairo_surface_extents (cairo_surface_t *surface,
@@ -287,7 +287,7 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
  * This function takes into account device offsets that might be
  * set with cairo_surface_set_device_offset().
  *
- * Returns: A `cairo_region_t`; must be freed with cairo_region_destroy()
+ * Returns: (transfer full): A `cairo_region_t`
  */
 cairo_region_t *
 gdk_cairo_region_create_from_surface (cairo_surface_t *surface)

gdk/gdkcairocontext.c

@@ -34,8 +34,8 @@
  * draw context.
  *
  * `GdkCairoContext`s are created for a surface using
- * [method@Gdk.Surface.create_cairo_context], and the context can then be used
- * to draw on that surface.
+ * [method@Gdk.Surface.create_cairo_context], and the context
+ * can then be used to draw on that surface.
  */
 
 typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate;
@@ -59,7 +59,7 @@ gdk_cairo_context_init (GdkCairoContext *self)
 
 /**
  * gdk_cairo_context_cairo_create:
- * @self: a #GdkCairoContext that is currently drawing
+ * @self: a `GdkCairoContext` that is currently drawing
  *
  * Retrieves a Cairo context to be used to draw on the `GdkSurface`
  * of @context.
@@ -70,9 +70,8 @@ gdk_cairo_context_init (GdkCairoContext *self)
  * The returned context is guaranteed to be valid until
  * [method@Gdk.DrawContext.end_frame] is called.
  *
- * Returns: (transfer full) (nullable): a Cairo context to be used
- *   to draw the contents of the `GdkSurface`. %NULL is returned
- *   when @context is not drawing.
+ * Returns: (transfer full) (nullable): a Cairo context
+ *   to draw on `GdkSurface
  */
 cairo_t *
 gdk_cairo_context_cairo_create (GdkCairoContext *self)

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)
@@ -520,8 +520,8 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)
 /**
  * gdk_clipboard_store_async:
  * @clipboard: a `GdkClipboard`
- * @io_priority: the I/O priority of the request.
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
+ * @io_priority: the I/O priority of the request
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -574,7 +574,7 @@ gdk_clipboard_store_async (GdkClipboard        *clipboard,
  * gdk_clipboard_store_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @error: a `GError` location to store the error occurring, or %NULL to ignore.
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an asynchronous clipboard store.
  *
@@ -637,7 +637,7 @@ gdk_clipboard_read_internal (GdkClipboard        *clipboard,
  * @clipboard: a `GdkClipboard`
  * @mime_types: a %NULL-terminated array of mime types to choose from
  * @io_priority: the I/O priority of the request
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -676,15 +676,15 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_finish:
  * @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.
+ * @out_mime_type: (out) (optional) (transfer none): location to store
+ *   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`
  */
 GInputStream *
 gdk_clipboard_read_finish (GdkClipboard  *clipboard,
@@ -833,7 +833,7 @@ gdk_clipboard_read_value_internal (GdkClipboard        *clipboard,
  * @clipboard: a `GdkClipboard`
  * @type: a `GType` to read
  * @io_priority: the I/O priority of the request
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -872,7 +872,7 @@ gdk_clipboard_read_value_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_value_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @error: a GError` location to store the error occurring, or %NULL to ignore
+ * @error: a GError` location to store the error occurring
  *
  * Finishes an asynchronous clipboard read.
  *
@@ -905,7 +905,7 @@ gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,
  * call [method@Gdk.Clipboard.read_texture_finish] to get the result.
  *
  * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
- * Use that function or [methos@Gdk.Clipboard.read_async] directly if you
+ * Use that function or [method@Gdk.Clipboard.read_async] directly if you
  * need more control over the operation.
  */
 void
@@ -931,13 +931,13 @@ gdk_clipboard_read_texture_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_texture_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an asynchronous clipboard read.
  *
  * See [method@Gdk.Clipboard.read_texture_async].
  *
- * Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
+ * Returns: (transfer full) (nullable): a new `GdkTexture`
  */
 GdkTexture *
 gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
@@ -960,7 +960,7 @@ gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
 /**
  * gdk_clipboard_read_text_async:
  * @clipboard: a `GdkClipboard`
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -996,13 +996,13 @@ gdk_clipboard_read_text_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_text_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an asynchronous clipboard read.
  *
  * See [method@Gdk.Clipboard.read_text_async].
  *
- * Returns: (transfer full) (nullable): a new string or %NULL on error
+ * Returns: (transfer full) (nullable): a new string
  */
 char *
 gdk_clipboard_read_text_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) (nullable): the new contents of @clipboard
+ *   or %NULL to clear the clipboard
  *
  * Sets a new content provider on @clipboard.
  *

gdk/gdkcontentdeserializer.c

@@ -190,9 +190,9 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer)
  * gdk_content_deserializer_get_gtype:
  * @deserializer: a `GdkContentDeserializer`
  *
- * Gets the GType to create an instance of.
+ * Gets the `GType` to create an instance of.
  *
- * Returns: the GType for the current operation
+ * Returns: the `GType` for the current operation
  */
 GType
 gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer)
@@ -224,7 +224,7 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
  *
  * Gets the input stream for the current operation.
  *
- * This is the stream that was passed to [func@content_deserialize_async].
+ * This is the stream that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: (transfer none): the input stream for the current operation
  */
@@ -242,7 +242,7 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer)
  *
  * Gets the I/O priority for the current operation.
  *
- * This is the priority that was passed to [funccontent_deserialize_async].
+ * This is the priority that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: the I/O priority for the current operation
  */
@@ -260,7 +260,7 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
  *
  * Gets the cancellable for the current operation.
  *
- * This is the `GCancellable` that was passed to [func@content_deserialize_async].
+ * This is the `GCancellable` that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -364,7 +364,7 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer)
 /**
  * gdk_content_deserializer_return_error:
  * @deserializer: a `GdkContentDeserializer`
- * @error: a `GError`
+ * @error: (transfer full): a `GError`
  *
  * Indicate that the deserialization has ended with an error.
  *
@@ -539,7 +539,7 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
  * indicate a higher priority.
  *
  * When the operation is finished, @callback will be called. You must then
- * call [func@content_deserialize_finish] to get the result of the operation.
+ * call [func@Gdk.content_deserialize_finish] to get the result of the operation.
  */
 void
 gdk_content_deserialize_async (GInputStream        *stream,

gdk/gdkcontentdeserializer.h

@@ -36,7 +36,7 @@ typedef struct _GdkContentDeserializer GdkContentDeserializer;
 
 /**
  * GdkContentDeserializeFunc:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
  *
  * The type of a function that can be registered with gdk_content_register_deserializer().
  *

gdk/gdkcontentformats.c

@@ -48,7 +48,7 @@
  *
  * `GdkContentFormats` is an immutable struct. After creation, you cannot change
  * the types it represents. Instead, new `GdkContentFormats` have to be created.
- * The [struct@Gdk.ContentFormatsBuilder]` structure is meant to help in this
+ * The [struct@Gdk.ContentFormatsBuilder] structure is meant to help in this
  * endeavor.
  */
 
@@ -84,8 +84,8 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
  * If @string is not a valid mime type, %NULL is returned instead.
  * 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
+ * Returns: (nullable): An interned string for the canonicalized
+ *   mime type or %NULL if the string wasn't a valid mime type
  */
 const char *
 gdk_intern_mime_type (const char *string)
@@ -125,7 +125,7 @@ gdk_content_formats_new_take (GType *      gtypes,
 
 /**
  * gdk_content_formats_new:
- * @mime_types: (array length=n_mime_types) (allow-none): Pointer to an
+ * @mime_types: (array length=n_mime_types) (nullable): Pointer to an
  *   array of mime types
  * @n_mime_types: number of entries in @mime_types.
  *
@@ -133,7 +133,7 @@ gdk_content_formats_new_take (GType *      gtypes,
  *
  * The mime types must be valid and different from each other or the
  * behavior of the return value is undefined. If you cannot guarantee
- * this, use `GdkContentFormatsBuilder` instead.
+ * this, use [struct@Gdk.ContentFormatsBuilder] instead.
  *
  * Returns: (transfer full): the new `GdkContentFormats`.
  */
@@ -384,7 +384,7 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first,
  *
  * If no matching mime type is found, %NULL is returned.
  *
- * Returns: (nullable): The first common mime type or %NULL if none.
+ * Returns: (nullable): The first common mime type or %NULL if none
  */
 const char *
 gdk_content_formats_match_mime_type (const GdkContentFormats *first,
@@ -411,7 +411,7 @@ gdk_content_formats_match_mime_type (const GdkContentFormats *first,
  *
  * Checks if a given `GType` is part of the given @formats.
  *
- * Returns: %TRUE if the #GType was found
+ * Returns: %TRUE if the `GType` was found
  */
 gboolean
 gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
@@ -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
+ * Note that @formats may not contain any `GType`s, 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,

gdk/gdkcontentprovider.c

@@ -218,7 +218,7 @@ gdk_content_provider_init (GdkContentProvider *provider)
 
 /**
  * gdk_content_provider_ref_formats: (attributes org.gtk.Method.get_property=formats)
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
  *
  * Gets the formats that the provider can provide its current contents in.
  *
@@ -234,7 +234,7 @@ gdk_content_provider_ref_formats (GdkContentProvider *provider)
 
 /**
  * gdk_content_provider_ref_storable_formats: (attributes org.gtk.Method.get_property=storable-formats)
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
  *
  * Gets the formats that the provider suggests other applications to store
  * the data in.
@@ -288,7 +288,7 @@ gdk_content_provider_content_changed (GdkContentProvider *provider)
  *
  * The given mime type does not need to be listed in the formats returned by
  * [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is
- * not supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
+ * not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported.
  *
  * The given @stream will not be closed.
  */
@@ -319,14 +319,14 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,
  * gdk_content_provider_write_mime_type_finish:
  * @provider: a `GdkContentProvider`
  * @result: a `GAsyncResult`
- * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an asynchronous write operation.
  *
  * 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,
@@ -343,7 +343,7 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
  * gdk_content_provider_get_value:
  * @provider: a `GdkContentProvider`
  * @value: the `GValue` to fill
- * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ * @error: a `GError` location to store the error occurring
  *
  * Gets the contents of @provider stored in @value.
  *
@@ -351,10 +351,10 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
  * provided in. This given `GType` does not need to be listed in the formats
  * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
  * given `GType` is not supported, this operation can fail and
- * #G_IO_ERROR_NOT_SUPPORTED will be reported.
+ * `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,

gdk/gdkcontentprovider.h

@@ -45,9 +45,9 @@ struct _GdkContentProvider
 
 /**
  * GdkContentProviderClass:
- * @content_changed: Signal class closure for #GdkContentProvider::content-changed
+ * @content_changed: Signal class closure for `GdkContentProvider::content-changed`
  *
- * Class structure for #GdkContentProvider.
+ * Class structure for `GdkContentProvider`.
  */
 struct _GdkContentProviderClass
 {

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 `GdkContentProvider`s to present the union of
  * @n_providers: the number of providers
  *
  * Creates a content provider that represents all the given @providers.

gdk/gdkcontentserializer.c

@@ -43,7 +43,7 @@
  *
  * GTK provides serializers and deserializers for common data types
  * such as text, colors, images or file lists. To register your own
- * serialization functions, use [func@content_register_serializer].
+ * serialization functions, use [func@Gdk.content_register_serializer].
  *
  * Also see [class@Gdk.ContentDeserializer].
  */
@@ -264,7 +264,7 @@ gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
  *
  * Gets the cancellable for the current operation.
  *
- * This is the `GCancellable` that was passed to [content_serialize_async].
+ * This is the `GCancellable` that was passed to [func@content_serialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -368,7 +368,7 @@ gdk_content_serializer_return_success (GdkContentSerializer *serializer)
 /**
  * gdk_content_serializer_return_error:
  * @serializer: a `GdkContentSerializer`
- * @error: a `GError`
+ * @error: (transfer full): a `GError`
  *
  * Indicate that the serialization has ended with an error.
  *
@@ -533,7 +533,7 @@ serialize_not_found (GdkContentSerializer *serializer)
  * @mime_type: the mime type to serialize to
  * @value: the content to serialize
  * @io_priority: the I/O priority of the operation
- * @cancellable: (nullable): optional #GCancellable object
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the operation is done
  * @user_data: (closure): data to pass to the callback function
  *
@@ -543,7 +543,7 @@ serialize_not_found (GdkContentSerializer *serializer)
  * indicate a higher priority.
  *
  * When the operation is finished, @callback will be called. You must then
- * call [func@content_serialize_finish] to get the result of the operation.
+ * call [func@Gdk.content_serialize_finish] to get the result of the operation.
  */
 void
 gdk_content_serialize_async (GOutputStream       *stream,

gdk/gdkcontentserializer.h

@@ -36,7 +36,7 @@ typedef struct _GdkContentSerializer GdkContentSerializer;
 
 /**
  * GdkContentSerializeFunc:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
  *
  * The type of a function that can be registered with gdk_content_register_serializer().
  *

gdk/gdkcursor.c

@@ -298,8 +298,8 @@ 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
+ * @fallback: (nullable): %NULL or the `GdkCursor` to fall back to when
+ *   this one cannot be supported
  *
  * Creates a new cursor by looking up @name in the current cursor
  * theme.
@@ -340,8 +340,8 @@ gdk_cursor_new_from_name (const char *name,
  * @texture: the texture providing the pixel data
  * @hotspot_x: the horizontal offset of the “hotspot” of the cursor
  * @hotspot_y: the vertical offset of the “hotspot” of the cursor
- * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
- *     this one cannot be supported
+ * @fallback: (nullable): %NULL or the `GdkCursor` to fall back to when
+ *   this one cannot be supported
  *
  * Creates a new cursor from a `GdkTexture`.
  *
@@ -379,7 +379,7 @@ gdk_cursor_new_from_texture (GdkTexture *texture,
  * it is used on does not support textured cursors.
  *
  * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL
- *  to use the default cursor as fallback.
+ *   to use the default cursor as fallback
  */
 GdkCursor *
 gdk_cursor_get_fallback (GdkCursor *cursor)
@@ -410,7 +410,7 @@ gdk_cursor_get_name (GdkCursor *cursor)
 
 /**
  * gdk_cursor_get_texture:
- * @cursor: a #GdkCursor.
+ * @cursor: a `GdkCursor`
  *
  * Returns the texture for the cursor.
  *

gdk/gdkdebug.h

@@ -41,9 +41,10 @@ typedef enum {
   GDK_DEBUG_GL_LEGACY       = 1 << 15,
   GDK_DEBUG_GL_GLES         = 1 << 16,
   GDK_DEBUG_GL_DEBUG        = 1 << 17,
-  GDK_DEBUG_VULKAN_DISABLE  = 1 << 18,
-  GDK_DEBUG_VULKAN_VALIDATE = 1 << 19,
-  GDK_DEBUG_DEFAULT_SETTINGS= 1 << 20
+  GDK_DEBUG_GL_GLX          = 1 << 18,
+  GDK_DEBUG_VULKAN_DISABLE  = 1 << 19,
+  GDK_DEBUG_VULKAN_VALIDATE = 1 << 20,
+  GDK_DEBUG_DEFAULT_SETTINGS= 1 << 21
 } GdkDebugFlags;
 
 extern guint _gdk_debug_flags;

gdk/gdkdevice.c

@@ -107,7 +107,7 @@ gdk_device_class_init (GdkDeviceClass *klass)
   /**
    * GdkDevice:display: (attributes org.gtk.Property.get=gdk_device_get_display)
    *
-   * The #GdkDisplay the #GdkDevice pertains to.
+   * The `GdkDisplay` the `GdkDevice` pertains to.
    */
   device_props[PROP_DISPLAY] =
       g_param_spec_object ("display",
@@ -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) (optional): return location for the X coordinate
+ *   of the device location relative to the surface origin
+ * @win_y: (out) (optional): 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,
@@ -1145,7 +1145,7 @@ _gdk_device_surface_at_position (GdkDevice       *device,
  *  }
  * ```
  *
- * Returns: (nullable): the vendor ID, or %NULL
+ * Returns: (nullable): the vendor ID
  */
 const char *
 gdk_device_get_vendor_id (GdkDevice *device)
@@ -1164,7 +1164,7 @@ gdk_device_get_vendor_id (GdkDevice *device)
  * This ID is retrieved from the device, and does not change.
  * See [method@Gdk.Device.get_vendor_id] for more information.
  *
- * Returns: (nullable): the product ID, or %NULL
+ * Returns: (nullable): the product ID
  */
 const char *
 gdk_device_get_product_id (GdkDevice *device)
@@ -1190,7 +1190,7 @@ gdk_device_set_seat (GdkDevice *device,
 
 /**
  * gdk_device_get_seat: (attributes org.gtk.Method.get_property=seat)
- * @device: A #GdkDevice
+ * @device: A `GdkDevice`
  *
  * Returns the `GdkSeat` the device belongs to.
  *
@@ -1239,7 +1239,7 @@ gdk_device_get_num_touches (GdkDevice *device)
  *
  * Retrieves the current tool for @device.
  *
- * Returns: (transfer none): the `GdkDeviceTool`, or %NULL
+ * Returns: (transfer none): the `GdkDeviceTool`
  */
 GdkDeviceTool *
 gdk_device_get_device_tool (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)

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.
  */
@@ -64,11 +64,11 @@ typedef enum
 
 /**
  * GdkTimeCoord:
- * @time: The timestamp for this event.
+ * @time: The timestamp for this event
  * @flags: Flags indicating what axes are present
  * @axes: (array fixed-size=12): axis values
  *
- * A #GdkTimeCoord stores a single event in a motion history.
+ * A `GdkTimeCoord` stores a single event in a motion history.
  */
 struct _GdkTimeCoord
 {

gdk/gdkdevicepad.c

@@ -36,7 +36,7 @@
  * (current) for each given group, different groups may have different
  * current modes. The number of available modes in a group can be found
  * out through [method@Gdk.DevicePad.get_group_n_modes], and the current mode
- * for a given group will be notified through events of type #GDK_PAD_GROUP_MODE.
+ * for a given group will be notified through events of type `GDK_PAD_GROUP_MODE`.
  */
 
 #include "config.h"

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)
@@ -1141,13 +1141,13 @@ gdk_display_create_surface (GdkDisplay     *display,
                                                           x, y, width, height);
 }
 
-/**
+/*< private >
  * gdk_display_get_keymap:
  * @display: the `GdkDisplay`
  *
- * Returns the #GdkKeymap attached to @display.
+ * Returns the `GdkKeymap` attached to @display.
  *
- * Returns: (transfer none): the #GdkKeymap attached to @display.
+ * Returns: (transfer none): the `GdkKeymap` attached to @display.
  */
 GdkKeymap *
 gdk_display_get_keymap (GdkDisplay *display)
@@ -1159,8 +1159,8 @@ gdk_display_get_keymap (GdkDisplay *display)
 
 /*< private >
  * gdk_display_make_gl_context_current:
- * @display: a #GdkDisplay
- * @context: (optional): a #GdkGLContext, or %NULL
+ * @display: a `GdkDisplay`
+ * @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)
 {
@@ -1365,7 +1365,7 @@ gdk_display_list_seats (GdkDisplay *display)
  * You can listen to the GListModel::items-changed signal on
  * this list to monitor changes to the monitor of this display.
  *
- * Returns: (transfer none): a #GListModel of `GdkMonitor`
+ * Returns: (transfer none): a `GListModel` of `GdkMonitor`
  */
 GListModel *
 gdk_display_get_monitors (GdkDisplay *self)
@@ -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.

gdk/gdkdisplaymanager.c

@@ -76,7 +76,7 @@
  *
  * When writing backend-specific code that is supposed to work with
  * multiple GDK backends, you have to consider both compile time and
- * runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32
+ * runtime. At compile time, use the `GDK_WINDOWING_X11`, `GDK_WINDOWING_WIN32`
  * macros, etc. to find out which backends are present in the GDK library
  * you are building your application against. At runtime, use type-check
  * macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
@@ -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)

gdk/gdkdrag.c

@@ -692,7 +692,7 @@ gdk_drag_set_selected_action (GdkDrag       *drag,
  * drag operation. The surface is owned by @drag and will be destroyed
  * when the drag operation is over.
  *
- * Returns: (nullable) (transfer none): the drag surface, or %NULL
+ * Returns: (nullable) (transfer none): the drag surface
  */
 GdkSurface *
 gdk_drag_get_drag_surface (GdkDrag *drag)

gdk/gdkdragsurface.c

@@ -26,7 +26,7 @@
 /**
  * GdkDragSurface:
  *
- * A #GdkDragSurface is an interface for surfaces used during DND.
+ * A `GdkDragSurface` is an interface for surfaces used during DND.
  */
 
 /**

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)
@@ -219,7 +219,7 @@ gdk_draw_context_surface_resized (GdkDrawContext *context)
  *
  * Retrieves the `GdkDisplay` the @context is created for
  *
- * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
+ * Returns: (nullable) (transfer none): the `GdkDisplay`
  */
 GdkDisplay *
 gdk_draw_context_get_display (GdkDrawContext *context)
@@ -237,7 +237,7 @@ gdk_draw_context_get_display (GdkDrawContext *context)
  *
  * Retrieves the surface that @context is bound to.
  *
- * Returns: (nullable) (transfer none): a #GdkSurface or %NULL
+ * Returns: (nullable) (transfer none): a `GdkSurface`
  */
 GdkSurface *
 gdk_draw_context_get_surface (GdkDrawContext *context)
@@ -271,7 +271,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
  * Note that the @region passed to this function is the minimum region that
  * needs to be drawn and depending on implementation, windowing system and
  * hardware in use, it might be necessary to draw a larger region. Drawing
- * implementation must use [method@Gdk.DrawContext.get_frame_region() to
+ * implementation must use [method@Gdk.DrawContext.get_frame_region] to
  * query the region that must be drawn.
  *
  * When using GTK, the widget system automatically places calls to
@@ -382,7 +382,7 @@ gdk_draw_context_end_frame (GdkDrawContext *context)
 
 /**
  * gdk_draw_context_get_frame_region:
- * @context: a #GdkDrawContext
+ * @context: a `GdkDrawContext`
  *
  * Retrieves the region that is currently being repainted.
  *
@@ -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)

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: (nullable): 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`
@@ -695,7 +694,7 @@ gdk_drop_read_async (GdkDrop             *self,
  * @self: a `GdkDrop`
  * @result: a `GAsyncResult`
  * @out_mime_type: (out) (type utf8): return location for the used mime type
- * @error: (allow-none): location to store error information on failure, or %NULL
+ * @error: (nullable): location to store error information on failure
  *
  * Finishes an async drop read operation.
  *
@@ -706,7 +705,7 @@ gdk_drop_read_async (GdkDrop             *self,
  *
  * See [method@Gdk.Drop.read_async].
  *
- * Returns: (nullable) (transfer full): the `GInputStream`, or %NULL
+ * Returns: (nullable) (transfer full): the `GInputStream`
  */
 GInputStream *
 gdk_drop_read_finish (GdkDrop       *self,
@@ -892,7 +891,7 @@ gdk_drop_read_value_async (GdkDrop             *self,
  * gdk_drop_read_value_finish:
  * @self: a `GdkDrop`
  * @result: a `GAsyncResult`
- * @error: a `GError` location to store the error occurring, or %NULL to ignore
+ * @error: a `GError` location to store the error occurring
  *
  * Finishes an async drop read.
  *

gdk/gdkevents.c

@@ -258,7 +258,7 @@ gdk_event_get_type (void)
  * @instance_size: the size of the instance of a GdkEvent subclass
  * @instance_init: (nullable): the function to initialize the instance data
  * @finalize: (nullable): the function to free the instance data
- * @get_state: (nullable): the function to retrieve the #GdkModifierType
+ * @get_state: (nullable): the function to retrieve the `GdkModifierType`:w
  *   associated to the event
  * @get_position: (nullable): the function to retrieve the event coordinates
  * @get_sequence: (nullable): the function to retrieve the event sequence
@@ -358,7 +358,7 @@ static GType gdk_event_types[GDK_EVENT_LAST];
  * Similarly to %G_DEFINE_TYPE_WITH_CODE, this macro will generate a `get_type()`
  * function that registers the event type.
  *
- * You can specify code to be run after the type registration; the #GType of
+ * You can specify code to be run after the type registration; the `GType` of
  * the event is available in the `gdk_define_event_type_id` variable.
  */
 #define GDK_DEFINE_EVENT_TYPE(TypeName, type_name, type_info, _C_) \
@@ -382,8 +382,8 @@ type_name ## _get_type (void) \
 /*< private >
  * gdk_event_alloc:
  * @event_type: the `GdkEvent`Type to allocate
- * @surface: (nullable): the #GdkSurface of the event
- * @device: (nullable): the #GdkDevice of the event
+ * @surface: (nullable): the `GdkSurface` of the event
+ * @device: (nullable): the `GdkDevice` of the event
  * @time_: the event serial
  *
  * Allocates a `GdkEvent` for the given @event_type, and sets its
@@ -496,14 +496,13 @@ _gdk_event_emit (GdkEvent *event)
 
 /**
  * _gdk_event_queue_find_first:
- * @display: a #GdkDisplay
- * 
+ * @display: a `GdkDisplay`
+ *
  * Find the first event on the queue that is not still
  * being filled in.
- * 
- * Returns: (nullable): Pointer to the list node for that event, or
- *   %NULL.
- **/
+ *
+ * Returns: (nullable): Pointer to the list node for that event
+ */
 GList*
 _gdk_event_queue_find_first (GdkDisplay *display)
 {
@@ -537,13 +536,13 @@ _gdk_event_queue_find_first (GdkDisplay *display)
 
 /**
  * _gdk_event_queue_append:
- * @display: a #GdkDisplay
- * @event: Event to append.
- * 
+ * @display: a `GdkDisplay`
+ * @event: Event to append
+ *
  * Appends an event onto the tail of the event queue.
  *
  * Returns: the newly appended list node.
- **/
+ */
 GList *
 _gdk_event_queue_append (GdkDisplay *display,
 			 GdkEvent   *event)
@@ -555,11 +554,11 @@ _gdk_event_queue_append (GdkDisplay *display,
 
 /*
  * _gdk_event_queue_remove_link:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @node: node to remove
  *
  * Removes a specified list node from the event queue.
- **/
+ */
 void
 _gdk_event_queue_remove_link (GdkDisplay *display,
 			      GList      *node)
@@ -569,14 +568,13 @@ _gdk_event_queue_remove_link (GdkDisplay *display,
 
 /*
  * _gdk_event_unqueue:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Removes and returns the first event from the event
  * queue that is not still being filled in.
  *
- * Returns: (nullable): the event, or %NULL. Ownership is transferred
- * to the caller.
- **/
+ * Returns: (nullable): the event
+ */
 GdkEvent*
 _gdk_event_unqueue (GdkDisplay *display)
 {
@@ -1181,7 +1179,7 @@ gdk_event_get_event_type (GdkEvent *event)
  *
  * Extracts the surface associated with an event.
  *
- * Returns: (transfer none): The #GdkSurface associated with the event
+ * Returns: (transfer none): The `GdkSurface` associated with the event
  */
 GdkSurface *
 gdk_event_get_surface (GdkEvent *event)
@@ -1197,7 +1195,7 @@ gdk_event_get_surface (GdkEvent *event)
  *
  * Returns the seat that originated the event.
  *
- * Returns: (nullable) (transfer none): a #GdkSeat.
+ * Returns: (nullable) (transfer none): a `GdkSeat`.
  */
 GdkSeat *
 gdk_event_get_seat (GdkEvent *event)
@@ -1213,7 +1211,7 @@ gdk_event_get_seat (GdkEvent *event)
  *
  * Returns the device of an event.
  *
- * Returns: (nullable) (transfer none): a #GdkDevice.
+ * Returns: (nullable) (transfer none): a `GdkDevice`
  */
 GdkDevice *
 gdk_event_get_device (GdkEvent *event)
@@ -1238,8 +1236,8 @@ gdk_event_get_device (GdkEvent *event)
  * the application lifetime, if settings must be stored
  * persistently across runs, see [method@Gdk.DeviceTool.get_serial].
  *
- * Returns: (transfer none) (nullable): The current device tool, or %NULL
- **/
+ * Returns: (transfer none) (nullable): The current device tool
+ */
 GdkDeviceTool *
 gdk_event_get_device_tool (GdkEvent *event)
 {
@@ -1273,7 +1271,7 @@ gdk_event_get_time (GdkEvent *event)
  *
  * Retrieves the display associated to the @event.
  *
- * Returns: (transfer none) (nullable): a #GdkDisplay
+ * Returns: (transfer none) (nullable): a `GdkDisplay`
  */
 GdkDisplay *
 gdk_event_get_display (GdkEvent *event)

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.

gdk/gdkeventsprivate.h

@@ -105,7 +105,7 @@ struct _GdkDeleteEvent
  * GdkMotionEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) set during the motion
- *   event. See #GdkModifierType.
+ *   event. See [enum@Gdk.ModifierType]
  * @x: the x coordinate of the pointer relative to the surface.
  * @y: the y coordinate of the pointer relative to the surface.
  * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
@@ -132,7 +132,7 @@ struct _GdkMotionEvent
  * GdkButtonEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
+ *   buttons. See [enum@Gdk.ModifierType]
  * @button: the button which was pressed or released, numbered from 1 to 5.
  *   Normally button 1 is the left mouse button, 2 is the middle button,
  *   and 3 is the right button. On 2-button mice, the middle button can
@@ -141,7 +141,7 @@ struct _GdkMotionEvent
  * @y: the y coordinate of the pointer relative to the surface.
  * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
  *   the mouse.
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
  *
  * Used for button press and button release events. The
  * @type field will be one of %GDK_BUTTON_PRESS or %GDK_BUTTON_RELEASE,
@@ -162,7 +162,7 @@ struct _GdkButtonEvent
  * GdkTouchEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType
+ *   buttons. See [enum@Gdk.ModifierType]
  * @x: the x coordinate of the pointer relative to the surface
  * @y: the y coordinate of the pointer relative to the surface
  * @axes: @x, @y translated to the axes of the event's device, or %NULL
@@ -200,7 +200,7 @@ struct _GdkTouchEvent
  * @y: the y coordinate of the pointer relative to the surface.
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
+ *   buttons. See [enum@Gdk.ModifierType]
  * @direction: the direction to scroll to (one of %GDK_SCROLL_UP,
  *   %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT, %GDK_SCROLL_RIGHT or
  *   %GDK_SCROLL_SMOOTH).
@@ -208,7 +208,7 @@ struct _GdkTouchEvent
  * @delta_y: the y coordinate of the scroll delta
  * @pointer_emulated: whether the scroll event was the result of
  *   a pointer emulation
- * @tool: a #GdkDeviceTool
+ * @tool: a `GdkDeviceTool`
  * @history: (element-type GdkScrollHistory): array of times and deltas
  *   for other scroll events that were compressed before delivering the
  *   current event
@@ -256,7 +256,7 @@ typedef struct {
  * GdkKeyEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
+ *   buttons. See [enum@Gdk.ModifierType]
  * @keycode: the raw code of the key that was pressed or released.
  * @translated: the result of translating @keycode. First with the full
  *   @state, then while ignoring Caps Lock.
@@ -277,7 +277,7 @@ struct _GdkKeyEvent
  * GdkCrossingEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
+ *   buttons. See [enum@Gdk.ModifierType]
  * @mode: the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB,
  *  %GDK_CROSSING_UNGRAB, %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB or
  *  %GDK_CROSSING_STATE_CHANGED).  %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB,
@@ -324,7 +324,7 @@ struct _GdkFocusEvent
 
 /*
  * GdkProximityEvent:
- * @tool: the #GdkDeviceTool associated to the event
+ * @tool: the `GdkDeviceTool` associated to the event
  *
  * A proximity event indicates that a tool of a graphic tablet, or similar
  * devices that report proximity, has moved in or out of contact with the
@@ -351,7 +351,7 @@ struct _GdkProximityEvent
  * when the grab surface becomes unviewable (i.e. it or one of its ancestors
  * is unmapped), or if the same application grabs the pointer or keyboard
  * again. Note that implicit grabs (which are initiated by button presses)
- * can also cause #GdkGrabBrokenEvent events.
+ * can also cause `GdkGrabBrokenEvent` events.
  */
 struct _GdkGrabBrokenEvent
 {
@@ -364,7 +364,7 @@ struct _GdkGrabBrokenEvent
 
 /*
  * GdkDNDEvent:
- * @drop: the #GdkDrop for the current DND operation.
+ * @drop: the `GdkDrop` for the current DND operation.
  * @x: the X coordinate of the pointer
  * @y: the Y coordinate of the pointer
  *
@@ -383,7 +383,7 @@ struct _GdkDNDEvent
  * GdkTouchpadEvent:
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
+ *   buttons. See [enum@Gdk.ModifierType]
  * @phase: (type GdkTouchpadGesturePhase): the current phase of the gesture
  * @n_fingers: The number of fingers triggering the pinch
  * @time: the time of the event in milliseconds

gdk/gdkframeclock.c

@@ -51,7 +51,7 @@
  * `GdkFrameClock` class for documentation of the phases.
  * %GDK_FRAME_CLOCK_PHASE_UPDATE and the [signal@GdkFrameClock::update] signal
  * are most interesting for application writers, and are used to update the
- * animations, using the frame time given by [metohd@Gdk.FrameClock.get_frame_time].
+ * animations, using the frame time given by [method@Gdk.FrameClock.get_frame_time].
  *
  * The frame time is reported in microseconds and generally in the same
  * timescale as g_get_monotonic_time(), however, it is not the same

gdk/gdkgl.c

@@ -303,8 +303,8 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
  *
  * The main way to draw GL content in GTK.
  *
- * It takes a render buffer ID (@source_type == #GL_RENDERBUFFER) or a texture
- * id (@source_type == #GL_TEXTURE) and draws it onto @cr with an OVER operation,
+ * It takes a render buffer ID (@source_type == GL_RENDERBUFFER) or a texture
+ * id (@source_type == GL_TEXTURE) and draws it onto @cr with an OVER operation,
  * respecting the current clip. The top left corner of the rectangle specified
  * by @x, @y, @width and @height will be drawn at the current (0,0) position of
  * the `cairo_t`.
@@ -315,8 +315,8 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
  * no special effects applied to @cr it will however use a more efficient
  * approach.
  *
- * For #GL_RENDERBUFFER the code will always fall back to software for buffers
- * with alpha components, so make sure you use #GL_TEXTURE if using alpha.
+ * For GL_RENDERBUFFER the code will always fall back to software for buffers
+ * with alpha components, so make sure you use GL_TEXTURE if using alpha.
  *
  * Calling this may change the current GL context.
  */

gdk/gdkglcontext.c

@@ -1127,7 +1127,7 @@ gdk_gl_context_make_current (GdkGLContext *context)
  *
  * Retrieves the display the @context is created for
  *
- * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
+ * Returns: (nullable) (transfer none): a `GdkDisplay`
  */
 GdkDisplay *
 gdk_gl_context_get_display (GdkGLContext *context)
@@ -1143,7 +1143,7 @@ gdk_gl_context_get_display (GdkGLContext *context)
  *
  * Retrieves the surface used by the @context.
  *
- * Returns: (nullable) (transfer none): a `GdkSurface` or %NULL
+ * Returns: (nullable) (transfer none): a `GdkSurface`
  */
 GdkSurface *
 gdk_gl_context_get_surface (GdkGLContext *context)
@@ -1159,7 +1159,7 @@ gdk_gl_context_get_surface (GdkGLContext *context)
  *
  * Retrieves the `GdkGLContext` that this @context share data with.
  *
- * Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL
+ * Returns: (nullable) (transfer none): a `GdkGLContext`
  */
 GdkGLContext *
 gdk_gl_context_get_shared_context (GdkGLContext *context)
@@ -1223,7 +1223,7 @@ gdk_gl_context_clear_current (void)
  *
  * Retrieves the current `GdkGLContext`.
  *
- * Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL
+ * Returns: (nullable) (transfer none): the current `GdkGLContext`
  */
 GdkGLContext *
 gdk_gl_context_get_current (void)

gdk/gdkkeys.c

@@ -201,13 +201,13 @@ gdk_keymap_init (GdkKeymap *keymap)
   keymap->cache = g_hash_table_new (g_direct_hash, g_direct_equal);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_display:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
- * Retrieves the #GdkDisplay associated to the @keymap.
+ * Retrieves the `GdkDisplay` associated to the @keymap.
  *
- * Returns: (transfer none): a #GdkDisplay
+ * Returns: (transfer none): a `GdkDisplay`
  */
 GdkDisplay *
 gdk_keymap_get_display (GdkKeymap *keymap)
@@ -302,9 +302,9 @@ gdk_keyval_is_lower (guint keyval)
   return FALSE;
 }
 
-/**
+/*< private >
  * gdk_keymap_get_direction:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Returns the direction of effective layout of the keymap.
  *
@@ -314,7 +314,7 @@ gdk_keyval_is_lower (guint keyval)
  * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
  *   if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
  *   otherwise.
- **/
+ */
 PangoDirection
 gdk_keymap_get_direction (GdkKeymap *keymap)
 {
@@ -323,15 +323,15 @@ gdk_keymap_get_direction (GdkKeymap *keymap)
   return GDK_KEYMAP_GET_CLASS (keymap)->get_direction (keymap);
 }
 
-/**
+/*< private >
  * gdk_keymap_have_bidi_layouts:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Determines if keyboard layouts for both right-to-left and left-to-right
  * languages are in use.
  *
  * Returns: %TRUE if there are layouts in both directions, %FALSE otherwise
- **/
+ */
 gboolean
 gdk_keymap_have_bidi_layouts (GdkKeymap *keymap)
 {
@@ -340,9 +340,9 @@ gdk_keymap_have_bidi_layouts (GdkKeymap *keymap)
   return GDK_KEYMAP_GET_CLASS (keymap)->have_bidi_layouts (keymap);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_caps_lock_state:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Returns whether the Caps Lock modifier is locked.
  *
@@ -356,9 +356,9 @@ gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
   return GDK_KEYMAP_GET_CLASS (keymap)->get_caps_lock_state (keymap);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_num_lock_state:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Returns whether the Num Lock modifier is locked.
  *
@@ -372,9 +372,9 @@ gdk_keymap_get_num_lock_state (GdkKeymap *keymap)
   return GDK_KEYMAP_GET_CLASS (keymap)->get_num_lock_state (keymap);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_scroll_lock_state:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Returns whether the Scroll Lock modifier is locked.
  *
@@ -388,9 +388,9 @@ gdk_keymap_get_scroll_lock_state (GdkKeymap *keymap)
   return GDK_KEYMAP_GET_CLASS (keymap)->get_scroll_lock_state (keymap);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_modifier_state:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  *
  * Returns the current modifier state.
  *
@@ -407,12 +407,12 @@ gdk_keymap_get_modifier_state (GdkKeymap *keymap)
   return 0;
 }
 
-/**
+/*< private >
  * gdk_keymap_get_entries_for_keyval:
- * @keymap: a #GdkKeymap
+ * @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
@@ -422,7 +422,7 @@ gdk_keymap_get_modifier_state (GdkKeymap *keymap)
  * right symbol is used. On US keyboards, the shift key changes the
  * keyboard level, and there are no groups. A group switch key might
  * convert a keyboard between Hebrew to English modes, for example.
- * #GdkEventKey contains a %group field that indicates the active
+ * `GdkEventKey` contains a %group field that indicates the active
  * keyboard group. The level is computed from the modifier mask.
  * The returned array should be freed
  * with g_free().
@@ -489,18 +489,18 @@ gdk_keymap_get_cached_entries_for_keyval (GdkKeymap     *keymap,
   *keys = (GdkKeymapKey *)&g_array_index (keymap->cached_keys, GdkKeymapKey, offset);
 }
 
-/**
+/*< private >
  * gdk_keymap_get_entries_for_keycode:
- * @keymap: a #GdkKeymap
+ * @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.
- * The Nth #GdkKeymapKey in @keys is bound to the Nth
+ * The Nth `GdkKeymapKey` in @keys is bound to the Nth
  * keyval in @keyvals. Free the returned arrays with g_free().
  * When a keycode is pressed by the user, the keyval from
  * this list of entries is selected by considering the effective
@@ -522,10 +522,10 @@ gdk_keymap_get_entries_for_keycode (GdkKeymap     *keymap,
                                                                  keys, keyvals, n_entries);
 }
 
-/**
+/*< private >
  * gdk_keymap_lookup_key:
- * @keymap: a #GdkKeymap
- * @key: a #GdkKeymapKey with keycode, group, and level initialized
+ * @keymap: a `GdkKeymap`
+ * @key: a `GdkKeymapKey` with keycode, group, and level initialized
  *
  * Looks up the keyval mapped to a keycode/group/level triplet.
  * If no keyval is bound to @key, returns 0. For normal user input,
@@ -545,20 +545,19 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
   return GDK_KEYMAP_GET_CLASS (keymap)->lookup_key (keymap, key);
 }
 
-/**
+/*< private >
  * gdk_keymap_translate_keyboard_state:
- * @keymap: a #GdkKeymap
+ * @keymap: a `GdkKeymap`
  * @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
- * @consumed_modifiers: (out) (allow-none): 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_modifiers: (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
+ * Translates the contents of a `GdkEventKey` into a keyval, effective
  * group, and level. Modifiers that affected the translation and
  * are thus unavailable for application use are returned in
  * @consumed_modifiers.
@@ -566,7 +565,7 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * groups and levels. The @effective_group is the group that was
  * actually used for the translation; some keys such as Enter are not
  * affected by the active keyboard group. The @level is derived from
- * @state. For convenience, #GdkEventKey already contains the translated
+ * @state. For convenience, `GdkEventKey` already contains the translated
  * keyval, so this function isn’t as useful as you might think.
  *
  * @consumed_modifiers gives modifiers that should be masked outfrom @state
@@ -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)
@@ -682,7 +680,7 @@ gdk_keyval_from_name (const char *keyval_name)
  *
  * Obtains the upper- and lower-case versions of the keyval @symbol.
  *
- * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
+ * Examples of keyvals are `GDK_KEY_a`, `GDK_KEY_Enter`, `GDK_KEY_F1`, etc.
  */
 void
 gdk_keyval_convert_case (guint symbol,

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.
  *
@@ -79,7 +79,7 @@ typedef enum {
  * This is the format provided by [method@Gdk.Texture.download].
  * It is equal to %CAIRO_FORMAT_ARGB32.
  *
- * Be aware that unlike the #GdkMemoryFormat values, this format
+ * Be aware that unlike the `GdkMemoryFormat` values, this format
  * is different for different endianness.
  */
 #if G_BYTE_ORDER == G_LITTLE_ENDIAN

gdk/gdkmonitor.c

@@ -299,7 +299,7 @@ gdk_monitor_class_init (GdkMonitorClass *class)
    * GdkMonitor:valid: (attributes org.gtk.Property.get=gdk_monitor_is_valid)
    *
    * Whether the object is still valid.
-   */ 
+   */
   props[PROP_VALID] =
     g_param_spec_boolean ("valid",
                           "Valid",
@@ -421,8 +421,7 @@ gdk_monitor_get_connector (GdkMonitor *monitor)
  * The PNP ID registry is located at
  * [https://uefi.org/pnp_id_list](https://uefi.org/pnp_id_list).
  *
- * Returns: (transfer none) (nullable): the name of the manufacturer,
- *   or %NULL
+ * Returns: (transfer none) (nullable): the name of the manufacturer
  */
 const char *
 gdk_monitor_get_manufacturer (GdkMonitor *monitor)
@@ -438,7 +437,7 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor)
  *
  * Gets the string identifying the monitor model, if available.
  *
- * Returns: (transfer none) (nullable): the monitor model, or %NULL
+ * Returns: (transfer none) (nullable): the monitor model
  */
 const char *
 gdk_monitor_get_model (GdkMonitor *monitor)
@@ -449,7 +448,7 @@ gdk_monitor_get_model (GdkMonitor *monitor)
 }
 
 /**
- * gdk_monitor_get_scale_factor: (attributes org.gtk.Method.get_prooperty=scale-factor)
+ * gdk_monitor_get_scale_factor: (attributes org.gtk.Method.get_property=scale-factor)
  * @monitor: a `GdkMonitor`
  *
  * Gets the internal scale factor that maps from monitor coordinates

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`.
  *
@@ -663,7 +661,7 @@ gdk_empty_paintable_init (GdkEmptyPaintable *self)
  * Returns a paintable that has the given intrinsic size and draws nothing.
  *
  * This is often useful for implementing the
- * #GdkPaintableInterface.get_current_image() virtual function
+ * [vfunc@Gdk.Paintable.get_current_image] virtual function
  * when the paintable is in an incomplete state (like a
  * [class@Gtk.MediaStream] before receiving the first frame).
  *

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,32 +55,32 @@ 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()
- * for non-static paintables and #GdkPaintableInterface.get_flags() if the
+ * 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 [vfunc@Gdk.PaintableInterface.get_flags] if the
  * image is not dynamic as the default implementation returns no flags and
  * that will make the implementation likely quite slow.
  */

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

gdk/gdkpipeiostream.c

@@ -458,15 +458,16 @@ gdk_pipe_io_stream_init (GdkPipeIOStream *pipe)
 /**
  * gdk_pipe_io_stream_new:
  *
- * Creates a #GIOStream whose input- and output-stream behave like a pipe.
+ * Creates a `GIOStream` whose input- and output-stream behave like a pipe.
+ *
  * Data written into the output stream becomes available for reading on
  * the input stream.
  *
  * Note that this is data transfer in the opposite direction to
  * g_output_stream_splice().
  *
- * Returns: a new #GIOStream
- **/
+ * Returns: a new `GIOStream`
+ */
 GIOStream *
 gdk_pipe_io_stream_new (void)
 {

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;
@@ -225,8 +225,7 @@ gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
  * stages will almost certainly convert the pixbuf back into a texture
  * to draw it on screen.
  *
- * Returns: (transfer full) (nullable): a new #GdkPixbuf or %NULL
- *   in case of an error
+ * Returns: (transfer full) (nullable): a new `GdkPixbuf`
  */
 GdkPixbuf *
 gdk_pixbuf_get_from_texture (GdkTexture *texture)

gdk/gdkpopup.c

@@ -111,7 +111,7 @@ gdk_popup_default_init (GdkPopupInterface *iface)
  * @height: the unconstrained popup height to layout
  * @layout: the `GdkPopupLayout` object used to layout
  *
- * Present @popup after having processed the #GdkPopupLayout rules.
+ * Present @popup after having processed the `GdkPopupLayout` rules.
  *
  * If the popup was previously now showing, it will be showed,
  * otherwise it will change position according to @layout.

gdk/gdkpopuplayout.c

@@ -26,7 +26,7 @@
  * GdkPopupLayout:
  *
  * The `GdkPopupLayout` struct contains information that is
- * necessary position a [interface@Gdk.Popup] relative to its parent.
+ * necessary position a [iface@Gdk.Popup] relative to its parent.
  *
  * The positioning requires a negotiation with the windowing system,
  * since it depends on external constraints, such as the position of

gdk/gdkrectangle.c

@@ -91,8 +91,8 @@ gdk_rectangle_union (const GdkRectangle *src1,
  * gdk_rectangle_intersect:
  * @src1: a `GdkRectangle`
  * @src2: a `GdkRectangle`
- * @dest: (out caller-allocates) (allow-none): return location for the
- *   intersection of @src1 and @src2, or %NULL
+ * @dest: (out caller-allocates) (optional): return location for the
+ *   intersection of @src1 and @src2
  *
  * Calculates the intersection of two rectangles.
  *
@@ -149,9 +149,9 @@ gdk_rectangle_intersect (const GdkRectangle *src1,
  * @x: X coordinate
  * @y: Y coordinate
  *
- * Returns #TRUE if @rect contains the point described by @x and @y.
+ * Returns %TRUE if @rect contains the point described by @x and @y.
  *
- * Returns: #TRUE if @rect contains the point
+ * Returns: %TRUE if @rect contains the point
  **/
 gboolean
 gdk_rectangle_contains_point (const GdkRectangle *rect,

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.
  */

gdk/gdkseat.c

@@ -150,7 +150,7 @@ gdk_seat_class_init (GdkSeatClass *klass)
    *
    * The tool may later be assigned to a device (i.e. on
    * proximity with a tablet). The device will emit the
-   * [signalGdkDevice::tool-changed] signal accordingly.
+   * [signal@Gdk.Device::tool-changed] signal accordingly.
    *
    * A same tool may be used by several devices.
    */
@@ -315,7 +315,7 @@ gdk_seat_ungrab (GdkSeat *seat)
 
 /**
  * gdk_seat_get_devices:
- * @seat: a #GdkSeat
+ * @seat: a `GdkSeat`
  * @capabilities: capabilities to get devices for
  *
  * Returns the devices that match the given capabilities.

gdk/gdksurface.c

@@ -1164,8 +1164,7 @@ gdk_surface_get_paint_gl_context (GdkSurface  *surface,
  * Before using the returned `GdkGLContext`, you will need to
  * call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize].
  *
- * Returns: (transfer full): the newly created `GdkGLContext`,
- *   or %NULL on error
+ * Returns: (transfer full) (nullable): the newly created `GdkGLContext`
  */
 GdkGLContext *
 gdk_surface_create_gl_context (GdkSurface   *surface,
@@ -1438,7 +1437,7 @@ gdk_surface_paint_on_clock (GdkFrameClock *clock,
 /*
  * gdk_surface_invalidate_rect:
  * @surface: a `GdkSurface`
- * @rect: (allow-none): rectangle to invalidate or %NULL to
+ * @rect: (nullable): rectangle to invalidate or %NULL to
  *   invalidate the whole surface
  *
  * Invalidate a rectangular region of @surface.
@@ -1696,9 +1695,9 @@ gdk_surface_constrain_size (GdkGeometry    *geometry,
  * gdk_surface_get_device_position:
  * @surface: a `GdkSurface`
  * @device: pointer `GdkDevice` to query to
- * @x: (out) (allow-none): return locatio for the X coordinate of @device, or %NULL
- * @y: (out) (allow-none): return location for the Y coordinate of @device, or %NULL
- * @mask: (out) (allow-none): return location for the modifier mask, or %NULL
+ * @x: (out) (optional): return location for the X coordinate of @device
+ * @y: (out) (optional): return location for the Y coordinate of @device
+ * @mask: (out) (optional): return location for the modifier mask
  *
  * Obtains the current device position and modifier state.
  *
@@ -1839,10 +1838,9 @@ gdk_surface_set_cursor_internal (GdkSurface *surface,
  * If the return value is %NULL then there is no custom cursor set on
  * the surface, and it is using the cursor for its parent surface.
  *
- * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
- *   returned object is owned by the `GdkSurface` and should not be
- *   unreferenced directly. Use [method@Gdk.Surface.set_cursor] to
- *   unset the cursor of the surface
+ * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+ *
+ * Returns: (nullable) (transfer none): a `GdkCursor`
  */
 GdkCursor *
 gdk_surface_get_cursor (GdkSurface *surface)
@@ -1855,7 +1853,7 @@ gdk_surface_get_cursor (GdkSurface *surface)
 /**
  * gdk_surface_set_cursor: (attributes org.gtk.Method.set_property=cursor)
  * @surface: a `GdkSurface`
- * @cursor: (allow-none): a `GdkCursor`
+ * @cursor: (nullable): a `GdkCursor`
  *
  * Sets the default mouse pointer for a `GdkSurface`.
  *
@@ -1920,10 +1918,9 @@ gdk_surface_set_cursor (GdkSurface *surface,
  * If the return value is %NULL then there is no custom cursor set on the
  * specified surface, and it is using the cursor for its parent surface.
  *
- * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
- *   returned object is owned by the `GdkSurface` and should not be
- *   unreferenced directly. Use [method@Gdk.Surface.set_cursor] to unset
- *   the cursor of the surface
+ * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+ *
+ * Returns: (nullable) (transfer none): a `GdkCursor`
  */
 GdkCursor *
 gdk_surface_get_device_cursor (GdkSurface *surface,
@@ -1970,10 +1967,10 @@ gdk_surface_set_device_cursor (GdkSurface *surface,
 /*
  * gdk_surface_get_geometry:
  * @surface: a `GdkSurface`
- * @x: (out) (allow-none): return location for X coordinate of surface (relative to its parent)
- * @y: (out) (allow-none): return location for Y coordinate of surface (relative to its parent)
- * @width: (out) (allow-none): return location for width of surface
- * @height: (out) (allow-none): return location for height of surface
+ * @x: (out) (optional): return location for X coordinate of surface (relative to its parent)
+ * @y: (out) (optional): return location for Y coordinate of surface (relative to its parent)
+ * @width: (out) (optional): return location for width of surface
+ * @height: (out) (optional): return location for height of surface
  *
  * Get the geometry of the surface.
  *
@@ -2415,8 +2412,7 @@ gdk_surface_destroy_notify (GdkSurface *surface)
  * the source if [method@Gdk.Drag.get_selected_action] returns
  * %GDK_ACTION_MOVE.
  *
- * Returns: (transfer full) (nullable): a newly created [class@Gdk.Drag]
- *   or %NULL on error
+ * Returns: (transfer full) (nullable): a newly created `GdkDrag`
  */
 GdkDrag *
 gdk_drag_begin (GdkSurface          *surface,
@@ -2624,7 +2620,8 @@ gdk_surface_get_scale_factor (GdkSurface *surface)
 /**
  * gdk_surface_set_opaque_region:
  * @surface: a top-level `GdkSurface`
- * @region: (allow-none):  a region, or %NULL
+ * @region: (nullable): a region, or %NULL to make the entire
+ *   surface opaque
  *
  * Marks a region of the `GdkSurface` as opaque.
  *
@@ -2640,7 +2637,7 @@ gdk_surface_get_scale_factor (GdkSurface *surface)
  * GTK will update this property automatically if the @surface background
  * is opaque, as we know where the opaque regions are. If your surface
  * background is not opaque, please update this property in your
- * #GtkWidgetClass.css_changed() handler.
+ * [vfunc@Gtk.Widget.css_changed] handler.
  */
 void
 gdk_surface_set_opaque_region (GdkSurface      *surface,

gdk/gdktexture.c

@@ -353,7 +353,7 @@ gdk_texture_new_from_resource (const char *resource_path)
  *
  * If %NULL is returned, then @error will be set.
  *
- * Return value: A newly-created `GdkTexture` or %NULL if an error occurred.
+ * Return value: A newly-created `GdkTexture`
  */
 GdkTexture *
 gdk_texture_new_from_file (GFile   *file,
@@ -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.

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)
@@ -680,7 +679,7 @@ gdk_toplevel_begin_resize (GdkToplevel    *toplevel,
 
 /**
  * gdk_toplevel_begin_move:
- * @toplevel: a #GdkToplevel
+ * @toplevel: a `GdkToplevel`
  * @device: the device used for the operation
  * @button: the button being used to drag, or 0 for a keyboard-initiated drag
  * @x: surface X coordinate of mouse click that began the drag

gdk/gdktoplevellayout.c

@@ -64,7 +64,7 @@ G_DEFINE_BOXED_TYPE (GdkToplevelLayout, gdk_toplevel_layout,
  * The size is in ”application pixels”, not
  * ”device pixels” (see gdk_surface_get_scale_factor()).
  *
- * Returns: (transfer full): newly created instance of #GdkToplevelLayout
+ * Returns: (transfer full): newly created instance of `GdkToplevelLayout`
  */
 GdkToplevelLayout *
 gdk_toplevel_layout_new (void)
@@ -85,7 +85,7 @@ gdk_toplevel_layout_new (void)
 
 /**
  * gdk_toplevel_layout_ref:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  *
  * Increases the reference count of @layout.
  *
@@ -100,7 +100,7 @@ gdk_toplevel_layout_ref (GdkToplevelLayout *layout)
 
 /**
  * gdk_toplevel_layout_unref:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  *
  * Decreases the reference count of @layout.
  */
@@ -116,9 +116,9 @@ gdk_toplevel_layout_unref (GdkToplevelLayout *layout)
 
 /**
  * gdk_toplevel_layout_copy:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  *
- * Create a new #GdkToplevelLayout and copy the contents of @layout into it.
+ * Create a new `GdkToplevelLayout` and copy the contents of @layout into it.
  *
  * Returns: (transfer full): a copy of @layout.
  */
@@ -143,13 +143,13 @@ gdk_toplevel_layout_copy (GdkToplevelLayout *layout)
 
 /**
  * gdk_toplevel_layout_equal:
- * @layout: a #GdkToplevelLayout
- * @other: another #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
+ * @other: another `GdkToplevelLayout`
  *
  * 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,
@@ -168,7 +168,7 @@ gdk_toplevel_layout_equal (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_set_resizable:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  * @resizable: %TRUE to allow resizing
  *
  * Sets whether the layout should allow the user
@@ -183,7 +183,7 @@ gdk_toplevel_layout_set_resizable (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_get_resizable:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  *
  * Returns whether the layout should allow the user
  * to resize the surface.
@@ -198,7 +198,7 @@ gdk_toplevel_layout_get_resizable (GdkToplevelLayout *layout)
 
 /**
  * gdk_toplevel_layout_set_maximized:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  * @maximized: %TRUE to maximize
  *
  * Sets whether the layout should cause the surface
@@ -214,7 +214,7 @@ gdk_toplevel_layout_set_maximized (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_get_maximized:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  * @maximized: (out): set to %TRUE if the toplevel should be maximized
  *
  * If the layout specifies whether to the toplevel should go maximized,
@@ -238,7 +238,7 @@ gdk_toplevel_layout_get_maximized (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_set_fullscreen:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  * @fullscreen: %TRUE to fullscreen the surface
  * @monitor: (nullable): the monitor to fullscreen on
  *
@@ -258,7 +258,7 @@ gdk_toplevel_layout_set_fullscreen (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_get_fullscreen:
- * @layout: a #GdkToplevelLayout
+ * @layout: a ``GdkToplevelLayout`
  * @fullscreen: (out): location to store whether the toplevel should be fullscreen
  *
  * If the layout specifies whether to the toplevel should go fullscreen,
@@ -282,7 +282,7 @@ gdk_toplevel_layout_get_fullscreen (GdkToplevelLayout *layout,
 
 /**
  * gdk_toplevel_layout_get_fullscreen_monitor:
- * @layout: a #GdkToplevelLayout
+ * @layout: a `GdkToplevelLayout`
  *
  * Returns the monitor that the layout is fullscreening
  * the surface on.