ngl: Improve glyph caching

Avoid creating duplicate cache entries with miniscule
scale differences. It does not cost us much to use a
slightly larger texture for a glyph.

.gitlab-ci.yml

@@ -24,8 +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:v32"
+  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:v31"
 
 .only-default:
   only:
@@ -59,7 +60,6 @@ style-check-diff:
       - "${CI_PROJECT_DIR}/_build/testsuite/reftests/output/*/*.png"
       - "${CI_PROJECT_DIR}/_build/testsuite/gsk/compare/*/*/*.png"
       - "${CI_PROJECT_DIR}/_build/testsuite/css/output/*/*.syscap"
-      - "${CI_PROJECT_DIR}/_build_hello/meson-logs"
   cache:
     key: "$CI_JOB_NAME"
     paths:
@@ -79,14 +79,9 @@ fedora-x86_64:
   script:
     - .gitlab-ci/show-info-linux.sh
     - meson subprojects update
-    - mkdir _install
-    - meson --prefix=${CI_PROJECT_DIR}/_install
-            ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} ${BACKEND_FLAGS} ${FEATURE_FLAGS}
+    - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} ${BACKEND_FLAGS} ${FEATURE_FLAGS}
             _build
-    - meson compile -C _build
-    - meson install -C _build
-    - PKG_CONFIG_PATH=${CI_PROJECT_DIR}/_install/lib64/pkgconfig:${CI_PROJECT_DIR}/_install/share/pkgconfig meson setup _build_hello examples/hello
-    - meson compile -C _build_hello
+    - ninja -C _build
     - .gitlab-ci/run-tests.sh _build x11
     - .gitlab-ci/run-tests.sh _build wayland
     - .gitlab-ci/run-tests.sh _build broadway
@@ -170,8 +165,6 @@ macos:
     - export MESON_FORCE_BACKTRACE=1
   script:
     - meson -Dx11-backend=false
-            -Dbroadway-backend=true
-            -Dmacos-backend=true
             -Dintrospection=disabled
             -Dcpp_std=c++11
             -Dpixman:tests=disabled
@@ -309,7 +302,7 @@ asan-build:
   allow_failure: true
 
 reference:
-  image: $FEDORA_IMAGE
+  image: $DOCS_IMAGE
   stage: docs
   needs: []
   variables:

.gitlab-ci/fedora.Dockerfile

@@ -38,6 +38,7 @@ RUN dnf -y install \
     gstreamer1-plugins-good \
     gstreamer1-plugins-bad-free-devel \
     gstreamer1-plugins-base-devel \
+    gtk-doc \
     hicolor-icon-theme \
     iso-codes \
     itstool \

.gitlab-ci/flatpak-build.sh

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

NEWS

@@ -1,106 +1,3 @@
-Overview of Changes in 4.3.1
-============================
-
-* GtkEmojiChooser:
- - Update data from CLDR 39
- - Load Emoji data for both language and territory
-
-* GtkCalendar:
- - Fix an off-by-one error in day numbers
-
-* GtkListView:
- - Add .activatable style class to activatable items
-
-* GtkCheckButton:
- - Don't allow unchecking grouped radio buttons
-
-*GtkToggleButton:
- - Fix mnemonic activation propagation
-
-* GtkLabel:
- - Make mnemonics work even when invisible
- - Fix mnemonic activation propagation
-
-* GtkMenuButton:
- - Add a property to mark primary menus and make F10 work
-
-* GtkApplication:
- - Fix initial screensaver state async
-
-* GtkEntry:
- - Apply xalign to placeholder text (as it was in GTK 3)
-
-* GtkSpinButton:
- - Fix swipe gestures
-
-* GtkStackSwitcher:
- - Implement GtkOrientable (as it was in GTK 3)
- - Fix a use-after-free problem with drag timeouts
-
-* GtkFileChooser:
- - Add support for (case-insensitive) suffix matches in GtkFileFilter
-
-* GtkPasswordEntry:
- - Make GtkPasswordEntryBuffer public, to make it easier
-   to write your own password entry widget
-
-* Input:
- - Fix interference between various obscure XKB features
-   (e.g. overlays) and Compose sequences
-
-* Action support:
- - Fix submenu-action handling
-
-* Theme:
- - Update icons from the Adwaita icon theme
- - Fix icon names for GtkSwitch
- - Fix switch-off icon
-
-* GSK:
- - Improve transformed offscreen rendering
- - Add padding between cached glyphs
-
-* Wayland:
- - Fix monitor sizes in the presence of transforms
- - Add a getter for the EGLDisplay
- - Fix click-drag-release sequences for popovers
-
-* X11:
- - Support EGL for X11. Fall back to GLX if EGL isn't available
- - Always fall back to GLX on NVidia
- - Add a getter for the EGLDisplay
-
-* Broadway:
- - Add a setter for display scale
-
-* Windows:
- - Add a getter for the EGLDisplay
- - Make GL work for media playback
-
-* MacOS:
- - Fix menubar appearance
-
-* Tools:
- - gtk4-builder-tool: Replace can-focus with focusable in 3-to-4 conversion
-
-* Introspection:
- - Add missing annotations in a few places (e.g. gtk_free_view_row_activated)
-
-* Build:
- - Only build one source file with -mf16c
- - Fix devel styling for ci flatpak builds
- - Generate appdata for demo flatpaks
-
-* Docs:
- - Numerous fixes and additions
-
-* Translation updates:
- Friulian
- Nepali
- Norwegian Bokmål
- Ukrainian
-
-
 Overview of Changes in 4.3.0
 ============================
 

README.md

@@ -157,8 +157,8 @@ Release notes
 The release notes for GTK are part of the migration guide in the API
 reference. See:
 
- - [3.x release notes](https://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html)
- - [4.x release notes](https://docs.gtk.org/gtk4/migrating-3to4.html)
+ - [3.x release notes](https://developer.gnome.org/gtk3/unstable/gtk-migrating-2-to-3.html)
+ - [4.x release notes](https://developer.gnome.org/gtk4/unstable/gtk-migrating-3-to-4.html)
 
 Licensing terms
 ---------------

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

@@ -1,26 +0,0 @@
-#!/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")

demos/gtk-demo/gskshaderpaintable.c

@@ -23,10 +23,13 @@
 #include "gskshaderpaintable.h"
 
 /**
- * GskShaderPaintable:
+ * SECTION:gskshaderpaintable
+ * @Short_description: Drawing with shaders
+ * @Title: GskShaderPaintable
+ * @see_also: #GdkPaintable
  *
- * `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
@@ -35,7 +38,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.
  */
 
@@ -183,7 +186,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,
@@ -212,8 +215,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
@@ -238,11 +241,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)
@@ -254,12 +257,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.
@@ -281,7 +284,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().
@@ -298,9 +301,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
@@ -308,7 +311,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/gtkshadertoy.c

@@ -163,8 +163,8 @@ drag_update_cb (GtkGestureDrag *drag,
 
 static void
 drag_end_cb (GtkGestureDrag *drag,
-             double          dx,
-             double          dy,
+             gdouble         dx,
+             gdouble         dy,
              gpointer        user_data)
 {
   GtkShadertoy *shadertoy = GTK_SHADERTOY (user_data);

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/meson.build

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

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

@@ -31,9 +31,14 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
+    <release version="3.99.0" date="2020-07-30">
       <description>
-        <p>A new build of GTK.</p>
+        <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>
       </description>
     </release>
   </releases>

demos/gtk-demo/paintable_mediastream.c

@@ -150,7 +150,7 @@ gtk_nuclear_media_stream_step (gpointer data)
    * call our pause function to pause the stream.
    */
   if (nuclear->progress >= DURATION)
-    gtk_media_stream_stream_ended (GTK_MEDIA_STREAM (nuclear));
+    gtk_media_stream_ended (GTK_MEDIA_STREAM (nuclear));
 
   /* The timeout function is removed by the pause function,
    * so we can just always return this value.
@@ -267,11 +267,11 @@ gtk_nuclear_media_stream_init (GtkNuclearMediaStream *nuclear)
    * However, media streams need to tell GTK once they are initialized,
    * so we do that here.
    */
-  gtk_media_stream_stream_prepared (GTK_MEDIA_STREAM (nuclear),
-                                    FALSE,
-                                    TRUE,
-                                    TRUE,
-                                    DURATION);
+  gtk_media_stream_prepared (GTK_MEDIA_STREAM (nuclear),
+                             FALSE,
+                             TRUE,
+                             TRUE,
+                             DURATION);
 }
 
 /* And finally, we add the simple constructor we declared in the header. */

demos/gtk-demo/peg_solitaire.c

@@ -1,7 +1,7 @@
 /* Peg Solitaire
  * #Keywords: GtkGridView, game
  *
- * This demo demonstrates how to use drag-and-drop to implement peg solitaire.
+ * This demo demonstrates how to use drag'n'drop to implement peg solitaire.
  *
  */
 
@@ -98,7 +98,7 @@ solitaire_peg_init (SolitairePeg *peg)
 
 /* Add a little setter for the peg's position.
  * We want to track those so that we can check for legal moves
- * during drag-and-drop operations.
+ * during drag'n'drop operations.
  */
 static void
 solitaire_peg_set_position (SolitairePeg *peg,

demos/icon-browser/meson.build

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

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

@@ -30,9 +30,14 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
+    <release version="3.99.0" date="2020-07-30">
       <description>
-        <p>A new build of GTK.</p>
+        <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>
       </description>
     </release>
   </releases>

demos/meson.build

@@ -1,31 +1,19 @@
-gen_demo_header = find_program('../build-aux/meson/gen-demo-header.py')
-demo_profile = get_option('profile')
+demo_conf = configuration_data()
+demo_conf.set_quoted('PROFILE', get_option('profile'))
+demo_conf.set_quoted('VCS_TAG', '@VCS_TAG@')
 
 demo_conf_h = declare_dependency(
-  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,
-  )
+  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'
+           )
 )
 
-# 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

@@ -721,6 +721,7 @@ static const char ui_info[] =
   "        <item>"
   "          <attribute name='label'>_New</attribute>"
   "          <attribute name='action'>app.new</attribute>"
+  "          <attribute name='accel'>&lt;Primary&gt;n</attribute>"
   "        </item>"
   "        <item>"
   "          <attribute name='label'>_Open</attribute>"
@@ -729,10 +730,12 @@ static const char ui_info[] =
   "        <item>"
   "          <attribute name='label'>_Save</attribute>"
   "          <attribute name='action'>app.save</attribute>"
+  "          <attribute name='accel'>&lt;Primary&gt;s</attribute>"
   "        </item>"
   "        <item>"
   "          <attribute name='label'>Save _As...</attribute>"
   "          <attribute name='action'>app.save-as</attribute>"
+  "          <attribute name='accel'>&lt;Primary&gt;s</attribute>"
   "        </item>"
   "      </section>"
   "      <section>"
@@ -753,6 +756,7 @@ static const char ui_info[] =
   "        <item>"
   "          <attribute name='label'>_Quit</attribute>"
   "          <attribute name='action'>app.quit</attribute>"
+  "          <attribute name='accel'>&lt;Primary&gt;q</attribute>"
   "        </item>"
   "      </section>"
   "    </submenu>"
@@ -762,6 +766,7 @@ static const char ui_info[] =
   "        <item>"
   "          <attribute name='label'>_About Print Editor</attribute>"
   "          <attribute name='action'>app.about</attribute>"
+  "          <attribute name='accel'>&lt;Primary&gt;a</attribute>"
   "        </item>"
   "      </section>"
   "    </submenu>"
@@ -789,15 +794,6 @@ startup (GApplication *app)
 {
   GtkBuilder *builder;
   GMenuModel *menubar;
-  struct {
-    const char *action_and_target;
-    const char *accelerators[2];
-  } accels[] = {
-    { "app.new", { "<Control>n", NULL } },
-    { "app.quit", { "<Control>q", NULL } },
-    { "app.save", { "<Control>s", NULL } },
-    { "app.about", { "<Control>a", NULL } },
-  };
 
   builder = gtk_builder_new ();
   gtk_builder_add_from_string (builder, ui_info, -1, NULL);
@@ -806,9 +802,6 @@ startup (GApplication *app)
 
   gtk_application_set_menubar (GTK_APPLICATION (app), menubar);
 
-  for (int i = 0; i < G_N_ELEMENTS (accels); i++)
-    gtk_application_set_accels_for_action (GTK_APPLICATION (app), accels[i].action_and_target, accels[i].accelerators);
-
   g_object_unref (builder);
 }
 

demos/widget-factory/meson.build

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

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

@@ -32,9 +32,14 @@
   <update_contact>matthias.clasen_at_gmail.com</update_contact>
   <developer_name>Matthias Clasen and others</developer_name>
   <releases>
-    <release version="@BUILD_VERSION@" date="@BUILD_DATE@">
+    <release version="3.99.0" date="2020-07-30">
       <description>
-        <p>A new build of GTK.</p>
+        <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>
       </description>
     </release>
   </releases>

demos/widget-factory/widget-factory.c

@@ -1997,7 +1997,6 @@ activate (GApplication *app)
     const char *accelerators[2];
   } accels[] = {
     { "app.about", { "F1", NULL } },
-    { "app.shortcuts", { "<Control>question", NULL } },
     { "app.quit", { "<Control>q", NULL } },
     { "app.open-in", { "<Control>n", NULL } },
     { "win.dark", { "<Control>d", NULL } },

demos/widget-factory/widget-factory.ui

@@ -2902,7 +2902,7 @@ bad things might happen.</property>
 
     <action-widgets>
       <action-widget response="cancel">cancel_info_dialog</action-widget>
-      <action-widget response="ok" default="true">doit_info_dialog</action-widget>
+      <action-widget response="ok">doit_info_dialog</action-widget>
     </action-widgets>
   </object>
   <object class="GtkDialog" id="action_dialog">

docs/reference/gdk/gdk4.toml.in

@@ -5,7 +5,7 @@ repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
 website_url = "https://www.gtk.org"
 authors = "GTK Development Team"
 logo_url = "gtk-logo.svg"
-license = "LGPL-2.1-or-later"
+license = "GPL-2.1-or-later"
 description = "The GTK toolkit"
 dependencies = [ "GObject-2.0", "cairo-1.0", "Pango-1.0", "GdkWayland-4.0",  "GdkX11-4.0" ]
 devhelp = true

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 [struct@Gdk.KeymapKey] contains a group; groups are not used on
+  1. third, the #GdkKeymapKey contains a group; groups are not used on
      standard US keyboards, but are used in many other countries. On a
      keyboard with groups, there can be 3 or 4 symbols printed on a single
      key. The group indicates movement in a horizontal direction. Usually

docs/reference/gdk/meson.build

@@ -13,7 +13,6 @@ 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@',
@@ -35,7 +34,6 @@ 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@',
@@ -59,7 +57,6 @@ 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/gsk4.toml.in

@@ -5,7 +5,7 @@ repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
 website_url = "https://www.gtk.org"
 authors = "GTK Development Team"
 logo_url = "gtk-logo.svg"
-license = "LGPL-2.1-or-later"
+license = "GPL-2.1-or-later"
 description = "The GTK toolkit"
 dependencies = [ "GObject-2.0", "Graphene-1.0", "Pango-1.0", "Gdk-4.0" ]
 devhelp = true

docs/reference/gsk/meson.build

@@ -8,7 +8,6 @@ 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,16 +76,12 @@ 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/drag-and-drop.md

@@ -1,54 +0,0 @@
-Title: Drag-and-Drop in GTK
-
-Drag-and-Drop (DND) is a user interaction pattern where users drag a UI element
-from one place to another, either inside a single application or between
-different application windows.
-
-When the element is 'dropped', data is transferred from the source to the
-destination, according to the drag action that is negotiated between both
-sides. Most commonly, that is a _copy_, but it can also be a _move_ or a
-_link_, depending on the kind of data and how the drag operation has been
-set up.
-
-This chapter gives an overview over how Drag-and-Drop is handled with event
-controllers in GTK.
-
-## Drag sources
-
-To make data available via DND, you create a [class@Gtk.DragSource]. Drag sources
-are event controllers, which initiate a Drag-and-Drop operation when the user clicks
-and drags the widget.
-
-A drag source can be set up ahead of time, with the desired drag action(s) and the data
-to be transferred. But it is also possible to provide the data when a drag operation
-is about to begin, by connecting to the [signal@Gtk.DragSource::prepare] signal.
-
-The GtkDragSource emits the [signal@Gtk.DragSource::drag-begin] signal when the DND
-operation starts, and the [signal@Gtk.DragSource::drag-end] signal when it is done.
-But it is not normally necessary to handle these signals. One case in which a ::drag-end
-handler is necessary is to implement `GDK_ACTION_MOVE`.
-
-## Drop targets
-
-To receive data via DND, you create a [class@Gtk.DropTarget], and tell it what kind of
-data to accept. You need to connect to the [signal@Gtk.DropTarget::drop] signal to receive
-the data when a DND operation occurs.
-
-While a DND operation is ongoing, GTK provides updates when the pointer moves over
-the widget to which the drop target is associated. The [signal@Gtk.DropTarget::enter],
-[signal@Gtk.DropTarget::leave] and [signal@Gtk.DropTarget::motion] signals get emitted
-for this purpose.
-
-GtkDropTarget provides a simple API, and only provides the data when it has been completely
-transferred. If you need to handle the data transfer yourself (for example to provide progress
-information during the transfer), you can use the more complicated [class@Gtk.DropTargetAsync].
-
-## Other considerations
-
-It is sometimes necessary to update the UI of the destination while a DND operation is ongoing,
-say to scroll or expand a view, or to switch pages. Typically, such UI changes are triggered
-by hovering over the widget in question.
-
-[class@Gtk.DropControllerMotion] is an event controller that can help with implementing such
-behaviors. It is very similar to [class@Gtk.EventControllerMotion], but provides events during
-a DND operation.

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
@@ -161,19 +161,19 @@ activate (GtkApplication *app,
 {
   GtkWidget *window;
   GtkWidget *button;
+  GtkWidget *box;
 
   window = gtk_application_window_new (app);
   gtk_window_set_title (GTK_WINDOW (window), "Window");
   gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
 
-  button = gtk_button_new_with_label ("Hello World");
-  gtk_widget_set_halign (button, GTK_ALIGN_CENTER);
-  gtk_widget_set_valign (button, GTK_ALIGN_CENTER);
+  box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+  gtk_window_set_child (GTK_WINDOW (window), box);
 
+  button = gtk_button_new_with_label ("Hello World");
   g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
   g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_window_destroy), window);
-
-  gtk_window_set_child (GTK_WINDOW (window), button);
+  gtk_box_append (GTK_BOX (box), button);
 
   gtk_widget_show (window);
 }
@@ -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/gtk4-launch.xml

@@ -46,8 +46,7 @@ display, unless specified otherwise.
 <para>
 <command>gtk4-launch</command> takes at least one argument, the name of
 the application to launch. The name should match application desktop file name,
-as residing in the applications subdirectories of the XDG data directories, with
-or without the '.desktop' suffix.
+as residing in /usr/share/application, with or without the '.desktop' suffix.
 </para>
 <para>
 If called with more than one argument, the rest of them besides the application
@@ -72,14 +71,4 @@ application.
   </variablelist>
 </refsect1>
 
-<refsect1><title>Environment</title>
-  <para>Some environment variables affect the behavior of <command>gtk4-launch</command>.</para>
-  <variablelist>
-    <varlistentry>
-    <term><option>XDG_DATA_HOME</option>, <option>XDG_DATA_DIRS</option></term>
-      <listitem><para>The environment variables specifying the XDG dta directories.</para></listitem>
-    </varlistentry>
-  </variablelist>
-</refsect1>
-
 </refentry>

docs/reference/gtk/gtk4.toml.in

@@ -5,7 +5,7 @@ repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
 website_url = "https://www.gtk.org"
 authors = "GTK Development Team"
 logo_url = "gtk-logo.svg"
-license = "LGPL-2.1-or-later"
+license = "GPL-2.1-or-later"
 description = "The GTK toolkit"
 dependencies = [ "GObject-2.0", "Graphene-1.0", "Pango-1.0", "Gdk-4.0", "Gsk-4.0" ]
 devhelp = true
@@ -57,7 +57,6 @@ content_files = [
   "initialization.md",
   "actions.md",
   "input-handling.md",
-  "drag-and-drop.md",
   "drawing-model.md",
   "css-overview.md",
   "css-properties.md",

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,7 +37,6 @@ 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
-    [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].
+    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().
 
 12. How do I draw text?
 
     To draw a piece of text onto a cairo surface, use a Pango layout and
-    [func@PangoCairo.show_layout].
+    pango_cairo_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 [vfunc@Gtk.Widget.snapshot] implementation,
-    use [method@Gtk.Snapshot.append_layout].
+    To draw a piece of text in a widget snapshot() implementation, use
+    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
-    [method@Pango.Layout.get_pixel_size], using code like the following:
+    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 [class@Gtk.TreeView] widget. See the [tree widget overview](#TreeWidget).
+    option is a #GtkTreeView 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 [class@Gtk.ListBox],
+    and widgetry inside the list, then you probably want to use a #GtkListBox,
     which uses regular widgets for display.
 
 17. ...for multi-line text display or editing?
 
     See the [text widget overview](#TextWidget) -- you should use the
-    [class@Gtk.TextView] widget.
+    #GtkTextView widget.
 
-    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].
+    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.
 
 18. ...to display an image or animation?
 
-    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.
+    GTK has two widgets that are dedicated to displaying images. #GtkImage, for
+    small, fixed-size icons and #GtkPicture for content images.
 
     Both can display images in just about any format GTK understands.
-    You can also use [class@Gtk.DrawingArea] if you need to do something more complex,
+    You can also use #GtkDrawingArea if you need to do something more complex,
     such as draw text or graphics over the top of the image.
 
-    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
+    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
     it as a paintable:
 
         mediafile = gtk_media_file_new_for_filename ("example.webm");
@@ -347,10 +347,8 @@ 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 [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].
+    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.
 
 ## Questions about GtkWidget
 
@@ -359,8 +357,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
-    [method@Gtk.CssProvider.load_from_file] and its variants.
-    See [method@Gtk.StyleContext.add_provider].
+    gtk_css_provider_load_from_file() and its variants.
+    See gtk_style_context_add_provider().
 
 21. How do I change the font of a widget?
 
@@ -370,7 +368,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
@@ -379,24 +377,24 @@ the question you have, this list is a good place to start.
           font: Sans 30;
         }
 
-    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].
+    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().
     To associate this style information with your widget, set a style class
-    on the widget using [method@Gtk.Widget.add_css_class]. The advantage
+    on its #GtkStyleContext using gtk_style_context_add_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 [method@Gtk.Widget.set_sensitive].
+    See gtk_widget_set_sensitive().
 
 ## GtkTextView questions
 
 23. How do I get the contents of the entire text widget as a string?
 
-    See [method@Gtk.TextBuffer.get_bounds] and [method@Gtk.TextBuffer.get_text]
-    or [method@Gtk.TextIter.get_text].
+    See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
+    or gtk_text_iter_get_text().
 
         GtkTextIter start, end;
         GtkTextBuffer *buffer;
@@ -407,10 +405,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 [method@Gtk.TextBuffer.insert_with_tags] with appropriate tags to
+    If you use gtk_text_buffer_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.
@@ -423,40 +421,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
-    [method@Gtk.TextView.scroll_to_mark] to scroll to the mark after
+    gtk_text_view_scroll_to_mark() to scroll to the mark after
     inserting new text.
 
-    The gtk4-demo application contains an example of this technique.
+    The gtk-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 [class@Gtk.TreeModel] columns don't necessarily have to be
+    Remember that the #GtkTreeModel 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 [method@Gtk.TreeModel.get].
-    See the [tree widget overview](#TreeWidget).        
+    like any other data, and retrieve it with gtk_tree_model_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 [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
+    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
     column.
 
-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?
+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?
 
-    Both the [class@Gtk.TreeStore] and the [class@Gtk.ListStore] implement the [class@Gtk.TreeModel]
+    Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
     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
-    [method@Gtk.TreeModel.get].
+    gtk_tree_model_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 [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()`).
+    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()).
 
     The following example demonstrates this:
 
@@ -529,29 +527,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 [method@Gtk.TreeView.set_expander_column] and [method@Gtk.TreeViewColumn.set_visible].
+    See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
 
 ## Using cairo with GTK
 
 31. How do I use cairo to draw in GTK applications?
 
-    Use [method@Gtk.Snapshot.append_cairo] in your [vfunc@Gtk.Widget.snapshot] vfunc
+    Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.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, [method@Gtk.Snapshot.append_cairo]
+    If you use cairo for drawing your own widgets, 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 [class@Gtk.GLArea].
+    If you are interested in using GL for your own drawing, see #GtkGLArea.
 
-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 [ctor@Gdk.MemoryTexture.new].
+    by GTK, you may want to use an image surface and gdk_memory_texture_new().

docs/reference/gtk/running.md

@@ -22,26 +22,20 @@ 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`
-: Keyboard shortcuts
+: Keybindings
 
 `modules`
-: Modules and extensions
+: Loading of modules
 
 `printing`
-: Printing
+: Printing support
 
 `size-request`
 : Size requests
@@ -52,15 +46,6 @@ 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`
@@ -72,6 +57,15 @@ 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
 
@@ -330,14 +324,8 @@ using and the GDK backend supports them:
 `cairo`
 : Selects the fallback Cairo renderer
 
-`opengl`
-: Selects the default OpenGL renderer
-
 `gl`
-: Selects the "gl" OpenGL renderer
-
-`ngl`
-: Selects the "ngl" OpenGL renderer
+: Selects the default 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,7 +1,5 @@
 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,8 +18,3 @@ 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/windows.md

@@ -14,19 +14,14 @@ instructions, binary downloads, etc, can be found
 The Win32 GDK backend can be influenced with some additional environment
 variables.
 
-### GDK_WIN32_TABLET_INPUT_API
+### GDK_IGNORE_WINTAB
 
-If this variable is set, it determines the API that GTK uses for tablet support.
-The possible values are:
+If this variable is set, GTK doesn't use the Wintab API for tablet support.
 
-`none`
-: Disables tablet support
+### GDK_USE_WINTAB
 
-`wintab`
-: Use the Wintab API
-
-`winpointer`
-: Use the Windows Pointer Input Stack API. This is the default.
+If this variable is set, GTK uses the Wintab API for tablet support.
+This is the default.
 
 ## Windows-specific handling of cursors
 

docs/reference/gtk/x11.md

@@ -25,11 +25,6 @@ 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/bp/bloatpad.c

@@ -197,17 +197,6 @@ text_buffer_changed_cb (GtkTextBuffer *buffer,
     }
 }
 
-static void
-fullscreen_changed (GObject    *object,
-                    GParamSpec *pspec,
-                    gpointer    user_data)
-{
-  if (gtk_window_is_fullscreen (GTK_WINDOW (object)))
-    gtk_button_set_icon_name (GTK_BUTTON (user_data), "view-restore-symbolic");
-  else
-    gtk_button_set_icon_name (GTK_BUTTON (user_data), "view-fullscreen-symbolic");
-}
-
 static GActionEntry win_entries[] = {
   { "copy", window_copy, NULL, NULL, NULL },
   { "paste", window_paste, NULL, NULL, NULL },
@@ -225,18 +214,17 @@ new_window (GApplication *app,
   GtkWidget *window, *grid, *scrolled, *view;
   GtkWidget *toolbar;
   GtkWidget *button;
+  GtkWidget *sw, *box, *label;
 
   window = gtk_application_window_new (GTK_APPLICATION (app));
   gtk_window_set_default_size ((GtkWindow*)window, 640, 480);
   g_action_map_add_action_entries (G_ACTION_MAP (window), win_entries, G_N_ELEMENTS (win_entries), window);
   gtk_window_set_title (GTK_WINDOW (window), "Bloatpad");
-  gtk_application_window_set_show_menubar (GTK_APPLICATION_WINDOW (window), TRUE);
 
   grid = gtk_grid_new ();
   gtk_window_set_child (GTK_WINDOW (window), grid);
 
   toolbar = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
-  gtk_widget_add_css_class (toolbar, "toolbar");
   button = gtk_toggle_button_new ();
   gtk_button_set_icon_name (GTK_BUTTON (button), "format-justify-left");
   gtk_actionable_set_detailed_action_name (GTK_ACTIONABLE (button), "win.justify::left");
@@ -252,18 +240,21 @@ new_window (GApplication *app,
   gtk_actionable_set_detailed_action_name (GTK_ACTIONABLE (button), "win.justify::right");
   gtk_box_append (GTK_BOX (toolbar), button);
 
-  button = gtk_toggle_button_new ();
-  gtk_button_set_icon_name (GTK_BUTTON (button), "view-fullscreen-symbolic");
-  gtk_actionable_set_action_name (GTK_ACTIONABLE (button), "win.fullscreen");
-  gtk_box_append (GTK_BOX (toolbar), button);
-  g_signal_connect (window, "notify::fullscreened", G_CALLBACK (fullscreen_changed), button);
+  box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
+  gtk_widget_set_halign (box, GTK_ALIGN_END);
+  label = gtk_label_new ("Fullscreen:");
+  gtk_box_append (GTK_BOX (box), label);
+  sw = gtk_switch_new ();
+  gtk_widget_set_valign (sw, GTK_ALIGN_CENTER);
+  gtk_actionable_set_action_name (GTK_ACTIONABLE (sw), "win.fullscreen");
+  gtk_box_append (GTK_BOX (box), sw);
+  gtk_box_append (GTK_BOX (toolbar), box);
 
   gtk_grid_attach (GTK_GRID (grid), toolbar, 0, 0, 1, 1);
 
   scrolled = gtk_scrolled_window_new ();
   gtk_widget_set_hexpand (scrolled, TRUE);
   gtk_widget_set_vexpand (scrolled, TRUE);
-  gtk_scrolled_window_set_has_frame (GTK_SCROLLED_WINDOW (scrolled), TRUE);
   view = gtk_text_view_new ();
 
   g_object_set_data ((GObject*)window, "bloatpad-text", view);
@@ -353,7 +344,6 @@ static void
 combo_changed (GtkComboBox *combo,
                gpointer     user_data)
 {
-  GtkDialog *dialog = user_data;
   GtkEntry *entry = g_object_get_data (user_data, "entry");
   const char *action;
   char **accels;
@@ -369,17 +359,6 @@ combo_changed (GtkComboBox *combo,
   g_strfreev (accels);
 
   gtk_editable_set_text (GTK_EDITABLE (entry), str);
-  gtk_dialog_set_response_sensitive (dialog, GTK_RESPONSE_APPLY, FALSE);
-}
-
-static void
-entry_changed (GtkEntry   *entry,
-               GParamSpec *pspec,
-               gpointer    user_data)
-{
-  GtkDialog *dialog = user_data;
-
-  gtk_dialog_set_response_sensitive (dialog, GTK_RESPONSE_APPLY, TRUE);
 }
 
 static void
@@ -393,7 +372,7 @@ response (GtkDialog *dialog,
   const char *str;
   char **accels;
 
-  if (response_id == GTK_RESPONSE_CANCEL)
+  if (response_id == GTK_RESPONSE_CLOSE)
     {
       gtk_window_destroy (GTK_WINDOW (dialog));
       return;
@@ -409,8 +388,6 @@ response (GtkDialog *dialog,
 
   gtk_application_set_accels_for_action (gtk_window_get_application (user_data), action, (const char **) accels);
   g_strfreev (accels);
-
-  gtk_dialog_set_response_sensitive (dialog, GTK_RESPONSE_APPLY, FALSE);
 }
 
 static void
@@ -425,41 +402,22 @@ edit_accels (GSimpleAction *action,
   GtkWidget *dialog;
   int i;
 
-  dialog = gtk_dialog_new_with_buttons ("Accelerators",
-                                        NULL,
-                                        GTK_DIALOG_USE_HEADER_BAR,
-                                        "Close", GTK_RESPONSE_CANCEL,
-                                        "Set", GTK_RESPONSE_APPLY,
-                                        NULL);
-
+  dialog = gtk_dialog_new ();
   gtk_window_set_application (GTK_WINDOW (dialog), app);
   actions = gtk_application_list_action_descriptions (app);
-
   combo = gtk_combo_box_text_new ();
-  g_object_set (gtk_dialog_get_content_area (GTK_DIALOG (dialog)),
-                "margin-top", 10,
-                "margin-bottom", 10,
-                "margin-start", 10,
-                "margin-end", 10,
-                "spacing", 10,
-                NULL);
-
   gtk_box_append (GTK_BOX (gtk_dialog_get_content_area (GTK_DIALOG (dialog))), combo);
   for (i = 0; actions[i]; i++)
     gtk_combo_box_text_append (GTK_COMBO_BOX_TEXT (combo), actions[i], actions[i]);
   g_signal_connect (combo, "changed", G_CALLBACK (combo_changed), dialog);
-
   entry = gtk_entry_new ();
-  gtk_widget_set_hexpand (entry, TRUE);
-  g_signal_connect (entry, "notify::text", G_CALLBACK (entry_changed), dialog);
-
   gtk_box_append (GTK_BOX (gtk_dialog_get_content_area (GTK_DIALOG (dialog))), entry);
+  gtk_dialog_add_button (GTK_DIALOG (dialog), "Close", GTK_RESPONSE_CLOSE);
+  gtk_dialog_add_button (GTK_DIALOG (dialog), "Set", GTK_RESPONSE_APPLY);
   g_signal_connect (dialog, "response", G_CALLBACK (response), dialog);
   g_object_set_data (G_OBJECT (dialog), "combo", combo);
   g_object_set_data (G_OBJECT (dialog), "entry", entry);
 
-  gtk_combo_box_set_active (GTK_COMBO_BOX (combo), 0);
-
   gtk_widget_show (dialog);
 }
 
@@ -578,7 +536,7 @@ bloat_pad_startup (GApplication *application)
 
   menu = gtk_application_get_menu_by_id (GTK_APPLICATION (application), "icon-menu");
 
-  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/insert-image.png");
+  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/gtk-select-color.png");
   icon = g_file_icon_new (file);
   item = g_menu_item_new ("File Icon", NULL);
   g_menu_item_set_icon (item, icon);
@@ -594,7 +552,7 @@ bloat_pad_startup (GApplication *application)
   g_object_unref (item);
   g_object_unref (icon);
 
-  bytes = g_resources_lookup_data ("/org/gtk/libgtk/icons/16x16/actions/media-eject.png", 0, NULL);
+  bytes = g_resources_lookup_data ("/org/gtk/libgtk/icons/16x16/actions/gtk-select-font.png", 0, NULL);
   icon = g_bytes_icon_new (bytes);
   item = g_menu_item_new ("Bytes Icon", NULL);
   g_menu_item_set_icon (item, icon);
@@ -603,19 +561,19 @@ bloat_pad_startup (GApplication *application)
   g_object_unref (icon);
   g_bytes_unref (bytes);
 
-  icon = G_ICON (gdk_pixbuf_new_from_resource ("/org/gtk/libgtk/icons/16x16/actions/folder-new.png", NULL));
+  icon = G_ICON (gdk_pixbuf_new_from_resource ("/org/gtk/libgtk/icons/16x16/actions/gtk-preferences.png", NULL));
   item = g_menu_item_new ("Pixbuf", NULL);
   g_menu_item_set_icon (item, icon);
   g_menu_append_item (menu, item);
   g_object_unref (item);
   g_object_unref (icon);
 
-  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/bookmark-new.png");
+  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/gtk-page-setup.png");
   icon = g_file_icon_new (file);
   emblem = g_emblem_new (icon);
   g_object_unref (icon);
   g_object_unref (file);
-  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/dialog-warning.png");
+  file = g_file_new_for_uri ("resource:///org/gtk/libgtk/icons/16x16/actions/gtk-orientation-reverse-portrait.png");
   icon2 = g_file_icon_new (file);
   icon = g_emblemed_icon_new (icon2, emblem);
   item = g_menu_item_new ("Emblemed Icon", NULL);

examples/bp/bloatpad.gresources.xml

@@ -4,10 +4,5 @@
   <gresource prefix="/org/gtk/bloatpad">
     <file preprocess="xml-stripblanks">gtk/menus.ui</file>
     <file preprocess="xml-stripblanks">gtk/help-overlay.ui</file>
-    <file>icons/16x16/actions/format-justify-center-symbolic.symbolic.png</file>
-    <file>icons/16x16/actions/format-justify-left-symbolic.symbolic.png</file>
-    <file>icons/16x16/actions/format-justify-right-symbolic.symbolic.png</file>
-    <file>icons/16x16/actions/view-fullscreen-symbolic.symbolic.png</file>
-    <file>icons/16x16/actions/view-restore-symbolic.symbolic.png</file>
   </gresource>
 </gresources>

examples/drawing.c

@@ -132,6 +132,7 @@ activate (GtkApplication *app,
           gpointer        user_data)
 {
   GtkWidget *window;
+  GtkWidget *frame;
   GtkWidget *drawing_area;
   GtkGesture *drag;
   GtkGesture *press;
@@ -141,11 +142,14 @@ activate (GtkApplication *app,
 
   g_signal_connect (window, "destroy", G_CALLBACK (close_window), NULL);
 
+  frame = gtk_frame_new (NULL);
+  gtk_window_set_child (GTK_WINDOW (window), frame);
+
   drawing_area = gtk_drawing_area_new ();
   /* set a minimum size */
   gtk_widget_set_size_request (drawing_area, 100, 100);
 
-  gtk_window_set_child (GTK_WINDOW (window), drawing_area);
+  gtk_frame_set_child (GTK_FRAME (frame), drawing_area);
 
   gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (drawing_area), draw_cb, NULL, NULL);
 

examples/hello-world.c

@@ -13,19 +13,19 @@ activate (GtkApplication *app,
 {
   GtkWidget *window;
   GtkWidget *button;
+  GtkWidget *box;
 
   window = gtk_application_window_new (app);
   gtk_window_set_title (GTK_WINDOW (window), "Window");
   gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
 
-  button = gtk_button_new_with_label ("Hello World");
-  gtk_widget_set_halign (button, GTK_ALIGN_CENTER);
-  gtk_widget_set_valign (button, GTK_ALIGN_CENTER);
+  box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+  gtk_window_set_child (GTK_WINDOW (window), box);
 
+  button = gtk_button_new_with_label ("Hello World");
   g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
   g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_window_destroy), window);
-
-  gtk_window_set_child (GTK_WINDOW (window), button);
+  gtk_box_append (GTK_BOX (box), button);
 
   gtk_widget_show (window);
 }

examples/hello/meson.build

@@ -1,10 +0,0 @@
-project('hello', 'c',
-          version: '4.3.0',
-          meson_version: '>= 0.50.0',
-)
-
-executable('hello',
-  [ 'hello-world.c' ],
-  dependencies: [ dependency('gtk4') ],
-  install: false
-)

examples/meson.build

@@ -2,6 +2,7 @@ examples = [
   'builder',
   'drawing',
   'grid-packing',
+  'hello-world',
   'plugman',
   'search-bar',
   'sunny',

examples/squares.py

@@ -1,61 +0,0 @@
-#!/usr/bin/env -S GI_TYPELIB_PATH=${PWD}/build/gtk:${GI_TYPELIB_PATH} LD_PRELOAD=${LD_PRELOAD}:${PWD}/build/gtk/libgtk-4.so python3
-
-import gi
-
-gi.require_version('Gdk', '4.0')
-gi.require_version('Gtk', '4.0')
-
-from gi.repository import Gdk
-from gi.repository import Gtk
-from gi.repository import Graphene
-
-
-class DemoWidget(Gtk.Widget):
-
-    __gtype_name__ = "DemoWidget"
-
-    def __init__(self):
-        super().__init__()
-
-    def do_measure(self, orientation, for_size: int):
-        # We need some space to draw
-        return 100, 200, -1, -1
-
-    def do_snapshot(self, snapshot):
-        # Draw four color squares
-        color = Gdk.RGBA()
-        rect = Graphene.Rect.alloc()
-
-        width = self.get_width() / 2
-        height = self.get_height() / 2
-
-        Gdk.RGBA.parse(color, "red")
-        rect.init(0, 0, width, height)
-        snapshot.append_color(color, rect)
-
-        Gdk.RGBA.parse(color, "green")
-        rect.init(width, 0, width, height)
-        snapshot.append_color(color, rect)
-
-        Gdk.RGBA.parse(color, "yellow")
-        rect.init(0, height, width, height)
-        snapshot.append_color(color, rect)
-
-        Gdk.RGBA.parse(color, "blue")
-        rect.init(width, height, width, height)
-        snapshot.append_color(color, rect)
-
-def on_activate(app):
-    # Create a new window
-    win = Gtk.ApplicationWindow(application=app)
-    win.set_title("Squares")
-    icon = DemoWidget()
-    win.set_child(icon)
-    win.present()
-
-# Create a new application
-app = Gtk.Application(application_id='org.gtk.exampleapp')
-app.connect('activate', on_activate)
-
-# Run the application
-app.run(None)

examples/sunny.c

@@ -12,7 +12,7 @@ new_window (GApplication *app,
   gtk_application_window_set_show_menubar (GTK_APPLICATION_WINDOW (window), TRUE);
   gtk_window_set_default_size ((GtkWindow*)window, 640, 480);
   gtk_window_set_title (GTK_WINDOW (window), "Sunny");
-  gtk_window_set_icon_name (GTK_WINDOW (window), "weather-clear-symbolic");
+  gtk_window_set_icon_name (GTK_WINDOW (window), "sunny");
 
   header = gtk_header_bar_new ();
   gtk_window_set_titlebar (GTK_WINDOW (window), header);
@@ -78,7 +78,7 @@ show_about (GSimpleAction *action,
   gtk_show_about_dialog (NULL,
                          "program-name", "Sunny",
                          "title", "About Sunny",
-                         "logo-icon-name", "weather-clear-symbolic",
+                         "logo-icon-name", "sunny",
                          "comments", "A cheap Bloatpad clone.",
                          NULL);
 }

gdk/broadway/gdkbroadwaydisplay.h

@@ -48,8 +48,6 @@ void                    gdk_broadway_display_show_keyboard       (GdkBroadwayDis
 GDK_AVAILABLE_IN_ALL
 void                    gdk_broadway_display_hide_keyboard       (GdkBroadwayDisplay *display);
 
-GDK_AVAILABLE_IN_4_4
-int                     gdk_broadway_display_get_surface_scale   (GdkDisplay *display);
 GDK_AVAILABLE_IN_4_4
 void                    gdk_broadway_display_set_surface_scale   (GdkDisplay *display,
                                                                   int         scale);

gdk/broadway/gdkdisplay-broadway.c

@@ -361,29 +361,6 @@ gdk_broadway_display_set_surface_scale (GdkDisplay *display,
   gdk_monitor_set_scale_factor (self->monitor, scale);
 }
 
-/**
- * gdk_broadway_display_get_surface_scale:
- * @display: (type GdkBroadwayDisplay): the display
- *
- * Gets the surface scale that was previously set by the client or
- * gdk_broadway_display_set_surface_scale().
- *
- * Returns: the scale for surfaces
- *
- * Since: 4.4
- */
-int
-gdk_broadway_display_get_surface_scale (GdkDisplay *display)
-{
-  GdkBroadwayDisplay *self;
-
-  g_return_val_if_fail (GDK_IS_BROADWAY_DISPLAY (display), 1);
-
-  self = GDK_BROADWAY_DISPLAY (display);
-
-  return self->scale_factor;
-}
-
 static GListModel *
 gdk_broadway_display_get_monitors (GdkDisplay *display)
 {

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,7 +87,6 @@
  * 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.
  */
@@ -330,13 +329,14 @@ gdk_display_open_default (void)
 }
 
 /*< private >
- * gdk_get_startup_notification_id:
+ *
+ * gdk_get_startup_notification_id
  *
  * Returns the original value of the DESKTOP_STARTUP_ID environment
  * variable if it was defined and valid, or %NULL otherwise.
  *
  * Returns: (nullable) (transfer none): the original value of the
- *   DESKTOP_STARTUP_ID environment variable
+ *   DESKTOP_STARTUP_ID environment variable, or %NULL.
  */
 const char *
 gdk_get_startup_notification_id (void)

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: (nullable): a `GIcon`
+ * @icon: (allow-none): a #GIcon, or %NULL
  *
  * 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: (nullable): an icon name
+ * @icon_name: (allow-none): an icon name, or %NULL
  *
  * Sets the icon for applications that are launched with this context.
  *
  * The @icon_name will be interpreted in the same way as the Icon field
- * in desktop files. See also [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: (transfer full): A `cairo_region_t`
+ * Returns: A `cairo_region_t`; must be freed with cairo_region_destroy()
  */
 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,8 +70,9 @@ 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 draw on `GdkSurface
+ * 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.
  */
 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
- *   if the clipboard does not maintain any content
+ * Returns: (transfer none) (nullable): The content of a clipboard or %NULL
+ *     if the clipboard does not maintain any content.
  */
 GdkContentProvider *
 gdk_clipboard_get_content (GdkClipboard *clipboard)
@@ -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
+ * @io_priority: the I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore.
  *
  * 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
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -676,15 +676,15 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @out_mime_type: (out) (optional) (transfer none): location to store
- *   the chosen mime type
- * @error: a `GError` location to store the error occurring
+ * @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.
  *
  * Finishes an asynchronous clipboard read.
  *
  * See [method@Gdk.Clipboard.read_async].
  *
- * Returns: (transfer full) (nullable): a `GInputStream`
+ * Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error.
  */
 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
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -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
+ * @error: a GError` location to store the error occurring, or %NULL to ignore
  *
  * 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 [method@Gdk.Clipboard.read_async] directly if you
+ * Use that function or [methos@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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * Finishes an asynchronous clipboard read.
  *
  * See [method@Gdk.Clipboard.read_texture_async].
  *
- * Returns: (transfer full) (nullable): a new `GdkTexture`
+ * Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
  */
 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
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * Finishes an asynchronous clipboard read.
  *
  * See [method@Gdk.Clipboard.read_text_async].
  *
- * Returns: (transfer full) (nullable): a new string
+ * Returns: (transfer full) (nullable): a new string or %NULL on error
  */
 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) (nullable): the new contents of @clipboard
- *   or %NULL to clear the clipboard
+ * @provider: (transfer none) (allow-none): the new contents of @clipboard or
+ *     %NULL to clear the clipboard
  *
  * Sets a new content provider on @clipboard.
  *

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@Gdk.content_deserialize_async].
+ * This is the stream that was passed to [func@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 [func@Gdk.content_deserialize_async].
+ * This is the priority that was passed to [funccontent_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@Gdk.content_deserialize_async].
+ * This is the `GCancellable` that was passed to [func@content_deserialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -364,7 +364,7 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer)
 /**
  * gdk_content_deserializer_return_error:
  * @deserializer: a `GdkContentDeserializer`
- * @error: (transfer full): a `GError`
+ * @error: 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@Gdk.content_deserialize_finish] to get the result of the operation.
+ * call [func@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: (nullable): An interned string for the canonicalized
- *   mime type or %NULL if the string wasn't a valid mime type
+ * Returns: An interned string for the canonicalized mime type
+ *     or %NULL if the string wasn't a valid mime type
  */
 const char *
 gdk_intern_mime_type (const char *string)
@@ -125,7 +125,7 @@ gdk_content_formats_new_take (GType *      gtypes,
 
 /**
  * gdk_content_formats_new:
- * @mime_types: (array length=n_mime_types) (nullable): Pointer to an
+ * @mime_types: (array length=n_mime_types) (allow-none): Pointer to an
  *   array of mime types
  * @n_mime_types: number of entries in @mime_types.
  *
@@ -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 [struct@Gdk.ContentFormatsBuilder] instead.
+ * this, use `GdkContentFormatsBuilder` 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,15 +454,16 @@ 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 `GType`s contained in the return value
+ *     number of #GTypes contained in the return value
  *
- * Gets the `GType`s included in @formats.
+ * Gets the `GTypes` included in @formats.
  *
- * Note that @formats may not contain any `GType`s, in particular when
+ * Note that @formats may not contain any #GTypes, in particular when
  * they are empty. In that case %NULL will be returned.
  *
  * Returns: (transfer none) (nullable) (array length=n_gtypes zero-terminated=1):
- *   %G_TYPE_INVALID-terminated array of types included in @formats
+ *      %G_TYPE_INVALID-terminated array of types included in @formats or
+ *      %NULL if none.
  */
 const GType *
 gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
@@ -480,16 +481,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
+ * 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.
  */
 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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * 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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * 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 `GdkContentProvider`s to present the union of
+ *     The #GdkContentProviders to present the union of
  * @n_providers: the number of providers
  *
  * Creates a content provider that represents all the given @providers.

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@Gdk.content_register_serializer].
+ * serialization functions, use [func@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 [func@content_serialize_async].
+ * This is the `GCancellable` that was passed to [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: (transfer full): a `GError`
+ * @error: 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@Gdk.content_serialize_finish] to get the result of the operation.
+ * call [func@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: (nullable): %NULL or the `GdkCursor` to fall back to when
- *   this one cannot be supported
+ * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
+ *     this one cannot be supported
  *
  * Creates a new cursor by looking up @name in the current cursor
  * 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: (nullable): the `GdkCursor` to fall back to when
- *   this one cannot be supported
+ * @fallback: (allow-none): %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/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) (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
+ * @win_x: (out) (allow-none): return location for the X coordinate of the device location,
+ *         relative to the surface origin, or %NULL.
+ * @win_y: (out) (allow-none): return location for the Y coordinate of the device location,
+ *         relative to the surface origin, or %NULL.
  *
  * Obtains the surface underneath @device, returning the location of the
- * device in @win_x and @win_y.
+ * 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
+ *   device position, or %NULL
  */
 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
+ * Returns: (nullable): the vendor ID, or %NULL
  */
 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
+ * Returns: (nullable): the product ID, or %NULL
  */
 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`
+ * Returns: (transfer none): the `GdkDeviceTool`, or %NULL
  */
 GdkDeviceTool *
 gdk_device_get_device_tool (GdkDevice *device)
@@ -1368,7 +1368,8 @@ 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

@@ -384,11 +384,11 @@ gdk_display_is_closed  (GdkDisplay  *display)
  * gdk_display_get_event:
  * @display: a `GdkDisplay`
  *
- * Gets the next `GdkEvent` to be processed for @display,
- * fetching events from the windowing system if necessary.
+ * Gets the next `GdkEvent` to be processed for @display, fetching events from the
+ * windowing system if necessary.
  *
- * Returns: (nullable) (transfer full): the next `GdkEvent`
- *   to be processed
+ * Returns: (nullable) (transfer full): the next `GdkEvent` to be processed,
+ *   or %NULL if no events are pending
  */
 GdkEvent *
 gdk_display_get_event (GdkDisplay *display)
@@ -1036,7 +1036,8 @@ 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
+ * Returns: (transfer full): a new `GdkAppLaunchContext` for @display.
+ *     Free with g_object_unref() when done
  */
 GdkAppLaunchContext *
 gdk_display_get_app_launch_context (GdkDisplay *display)
@@ -1052,9 +1053,8 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
  *
  * Opens a display.
  *
- * If opening the display fails, `NULL` is returned.
- *
- * Returns: (nullable) (transfer none): a `GdkDisplay`
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if the
+ *     display could not be opened
  */
 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
+ * Returns: (nullable): the startup notification ID for @display, or %NULL
  */
 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`
+ * @display: a #GdkDisplay
+ * @context: (optional): a #GdkGLContext, or %NULL
  *
  * 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`
+ *     location for array of `GdkKeymapKey`, or %NULL
  * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
- *   location for array of keyvals
+ *     location for array of keyvals, or %NULL
  * @n_entries: length of @keys and @keyvals
  *
  * Returns the keyvals bound to @keycode.
@@ -1577,11 +1577,12 @@ gdk_display_map_keycode (GdkDisplay    *display,
  * @keycode: a keycode
  * @state: a modifier state
  * @group: active keyboard group
- * @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
+ * @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
  *
  * 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,7 +309,8 @@ gdk_display_manager_get (void)
  *
  * Gets the default `GdkDisplay`.
  *
- * Returns: (nullable) (transfer none): a `GdkDisplay`
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
+ *     there is no default display.
  */
 GdkDisplay *
 gdk_display_manager_get_default_display (GdkDisplayManager *manager)
@@ -323,8 +324,7 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager)
  * Gets the default `GdkDisplay`.
  *
  * This is a convenience function for:
- *
- *     gdk_display_manager_get_default_display (gdk_display_manager_get ())
+ * `gdk_display_manager_get_default_display (gdk_display_manager_get ())`.
  *
  * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
  *   there is no default display
@@ -361,7 +361,8 @@ 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
+ *     allocated `GSList` of `GdkDisplay` objects. Free with g_slist_free()
+ *     when you are done with it.
  */
 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
+ * Returns: (nullable) (transfer none): the drag surface, or %NULL
  */
 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): the `GdkDisplay`
+ * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
  */
 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`
+ * Returns: (nullable) (transfer none): a #GdkSurface or %NULL
  */
 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,7 +393,8 @@ 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
+ * Returns: (transfer none) (nullable): a Cairo region or %NULL if not drawing
+ *     a frame.
  */
 const cairo_region_t *
 gdk_draw_context_get_frame_region (GdkDrawContext *context)

gdk/gdkdrop.c

@@ -294,11 +294,8 @@ gdk_drop_finalize (GObject *object)
 
   /* someone forgot to send a LEAVE signal */
   g_warn_if_fail (!priv->entered);
-
   /* Should we emit finish() here if necessary?
-   * For now that's the backends' job
-   */
-  g_warn_if_fail (priv->state != GDK_DROP_STATE_DROPPING);
+   * For now that's the backends' job */
 
   g_clear_object (&priv->device);
   g_clear_object (&priv->drag);
@@ -574,7 +571,7 @@ gdk_drop_get_drag (GdkDrop *self)
  * the ones provided by [method@Gdk.Drop.get_actions]. Those actions may
  * change in the future, even depending on the actions you provide here.
  *
- * The @preferred action is a hint to the drag-and-drop mechanism about which
+ * The @preferred action is a hint to the drag'n'drop mechanism about which
  * action to use when multiple actions are possible.
  *
  * This function should be called by drag destinations in response to
@@ -660,11 +657,12 @@ 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: (nullable): optional `GCancellable` object
+ * @cancellable: (allow-none): optional `GCancellable` object,
+ *     %NULL to ignore
  * @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`
@@ -697,7 +695,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: (nullable): location to store error information on failure
+ * @error: (allow-none): location to store error information on failure, or %NULL
  *
  * Finishes an async drop read operation.
  *
@@ -708,7 +706,7 @@ gdk_drop_read_async (GdkDrop             *self,
  *
  * See [method@Gdk.Drop.read_async].
  *
- * Returns: (nullable) (transfer full): the `GInputStream`
+ * Returns: (nullable) (transfer full): the `GInputStream`, or %NULL
  */
 GInputStream *
 gdk_drop_read_finish (GdkDrop       *self,
@@ -865,7 +863,7 @@ gdk_drop_read_value_internal (GdkDrop             *self,
  * then call [method@Gdk.Drop.read_value_finish] to get the resulting
  * `GValue`.
  *
- * For local drag-and-drop operations that are available in the given
+ * For local drag'n'drop operations that are available in the given
  * `GType`, the value will be copied directly. Otherwise, GDK will
  * try to use [func@Gdk.content_deserialize_async] to convert the data.
  */
@@ -894,7 +892,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
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
  *
  * 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`:w
+ * @get_state: (nullable): the function to retrieve the #GdkModifierType
  *   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,13 +496,14 @@ _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
- */
+ * 
+ * Returns: (nullable): Pointer to the list node for that event, or
+ *   %NULL.
+ **/
 GList*
 _gdk_event_queue_find_first (GdkDisplay *display)
 {
@@ -536,13 +537,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)
@@ -554,11 +555,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)
@@ -568,13 +569,14 @@ _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
- */
+ * Returns: (nullable): the event, or %NULL. Ownership is transferred
+ * to the caller.
+ **/
 GdkEvent*
 _gdk_event_unqueue (GdkDisplay *display)
 {
@@ -1179,7 +1181,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)
@@ -1195,7 +1197,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)
@@ -1211,7 +1213,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)
@@ -1236,8 +1238,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
- */
+ * Returns: (transfer none) (nullable): The current device tool, or %NULL
+ **/
 GdkDeviceTool *
 gdk_event_get_device_tool (GdkEvent *event)
 {
@@ -1271,7 +1273,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 [enum@Gdk.ModifierType]
+ *   event. See #GdkModifierType.
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType.
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType.
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType.
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType.
  * @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 [enum@Gdk.ModifierType]
+ *   buttons. See #GdkModifierType.
  * @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 [method@Gdk.FrameClock.get_frame_time].
+ * animations, using the frame time given by [metohd@Gdk.FrameClock.get_frame_time].
  *
  * The frame time is reported in microseconds and generally in the same
  * timescale as g_get_monotonic_time(), however, it is not the same
@@ -481,11 +481,11 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock)
  * for the current frame or a recent frame.
  *
  * The `GdkFrameTimings` object may not yet be complete: see
- * [method@Gdk.FrameTimings.get_complete] and
- * [method@Gdk.FrameClock.get_history_start].
+ * [method@Gdk.FrameTimings.get_complete].
  *
  * Returns: (nullable) (transfer none): the `GdkFrameTimings` object
- *   for the specified frame, or %NULL if it is not available
+ *   for the specified frame, or %NULL if it is not available. See
+ *   [method@Gdk.FrameClock.get_history_start].
  */
 GdkFrameTimings *
 gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,

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`
+ * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
  */
 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`
+ * Returns: (nullable) (transfer none): a `GdkSurface` or %NULL
  */
 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`
+ * Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL
  */
 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`
+ * Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL
  */
 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`
+ *     location for array of #GdkKeymapKey, or %NULL
  * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
- *   location for array of keyvals
+ *     location for array of keyvals, or %NULL
  * @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,19 +545,20 @@ 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) (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
+ * @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
  *
- * 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.
@@ -565,7 +566,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
@@ -645,7 +646,8 @@ 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
+ *     of the key, or %NULL if @keyval is not a valid key. The string
+ *     should not be modified.
  */
 const char *
 gdk_keyval_name (guint keyval)
@@ -664,7 +666,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)
@@ -680,7 +682,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.
  *
@@ -53,8 +53,8 @@ G_BEGIN_DECLS
  * CAIRO_FORMAT_ARGB32 is represented by different `GdkMemoryFormats`
  * on architectures with different endiannesses.
  *
- * Its naming is modelled after
- * [VkFormat](https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat)
+ * Its naming is modelled after VkFormat (see
+ * https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat
  * for details).
  */
 typedef enum {
@@ -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

@@ -421,7 +421,8 @@ 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
+ * Returns: (transfer none) (nullable): the name of the manufacturer,
+ *   or %NULL
  */
 const char *
 gdk_monitor_get_manufacturer (GdkMonitor *monitor)
@@ -437,7 +438,7 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor)
  *
  * Gets the string identifying the monitor model, if available.
  *
- * Returns: (transfer none) (nullable): the monitor model
+ * Returns: (transfer none) (nullable): the monitor model, or %NULL
  */
 const char *
 gdk_monitor_get_model (GdkMonitor *monitor)

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,15 +439,17 @@ 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`.
  *
@@ -661,7 +663,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
- * [vfunc@Gdk.Paintable.get_current_image] virtual function
+ * #GdkPaintableInterface.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 [enum@Gdk.PaintableFlags]
- *   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 #GdkPaintableFlags
+ *     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 [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.
+ *     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.
  *
  * The list of functions that can be implemented for the `GdkPaintable`
  * interface.
  *
- * 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
+ * Note that apart from the #GdkPaintableInterface.snapshot() function, no
+ * virtual function of this interface is mandatory to implement, though it
+ * is a good idea to implement #GdkPaintableInterface.get_current_image()
+ * for non-static paintables and #GdkPaintableInterface.get_flags() if the
  * image is not dynamic as the default implementation returns no flags and
  * that will make the implementation likely quite slow.
  */

gdk/gdkpango.c

@@ -93,8 +93,9 @@ 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,16 +458,15 @@ 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
+ *     reference count of 1, or %NULL on error
  */
 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,7 +225,8 @@ 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`
+ * Returns: (transfer full) (nullable): a new #GdkPixbuf or %NULL
+ *   in case of an error
  */
 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 [iface@Gdk.Popup] relative to its parent.
+ * necessary position a [interface@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) (optional): return location for the
- *   intersection of @src1 and @src2
+ * @dest: (out caller-allocates) (allow-none): return location for the
+ *   intersection of @src1 and @src2, or %NULL
  *
  * 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,