Merge branch 'ebassi/gi-docgen' into 'master'

Switch to gi-docgen for our documentation

See merge request GNOME/gdk-pixbuf!105

27 files changed, 1420 insertions, 1407 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 7e1c7febd..0d52caf6b 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -10,7 +10,7 @@ variables:
   COMMON_MESON_FLAGS: "-Dwerror=true -Dglib:werror=false"
   LOADERS_FLAGS: "-Dpng=true -Djpeg=true -Dtiff=true"
   MESON_TEST_TIMEOUT_MULTIPLIER: 3
-  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v1"
+  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v2"
 
 .only-default:
   only:
@@ -23,8 +23,8 @@ variables:
   before_script:
     - mkdir -p _ccache
   script:
-    - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build .
-    - ninja -C _build
+    - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build .
+    - meson compile -C _build
     - .gitlab/scripts/run-tests.sh _build
   artifacts:
     when: always
@@ -69,7 +69,7 @@ macos:
     - export PATH=/Users/gitlabrunner/Library/Python/3.7/bin:$PATH
   script:
     - meson setup -Dintrospection=disabled -Dinstalled_tests=false -Dman=false -Dgtk_doc=false _build
-    - meson compile -C_build
+    - meson compile -C _build
   artifacts:
     when: always
     paths:
@@ -90,9 +90,11 @@ reference:
   variables:
     BUILD_OPTS: "-Dbuildtype=release -Dgtk_doc=true"
   script:
-    - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build .
-    - ninja -C _build gdk-pixbuf-doc
-    - mv _build/docs/html _reference
+    - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build .
+    - meson compile -C _build
+    - mkdir -p _reference
+    - mv _build/docs/gdk-pixbuf/ _reference/gdk-pixbuf/
+    - mv _build/docs/gdk-pixdata/ _reference/gdk-pixdata/
   artifacts:
     when: on_success
     paths:
@@ -105,7 +107,7 @@ static-scan:
   variables:
     BUILD_OPTS: "--buildtype=debug"
   script:
-    - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _scan_build
+    - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _scan_build
     - ninja -C _scan_build scan-build
   artifacts:
     paths:
@@ -121,8 +123,8 @@ asan-build:
   needs: []
   variables:
   script:
-    - CC=clang meson --buildtype=debugoptimized -Db_sanitize=address -Db_lundef=false -Dintrospection=disabled _build
-    - ninja -C _build
+    - CC=clang meson setup --buildtype=debugoptimized -Db_sanitize=address -Db_lundef=false -Dintrospection=disabled _build
+    - meson compile -C _build
     - .gitlab/scripts/run-tests.sh _build
   artifacts:
     paths:
@@ -139,13 +141,14 @@ release-dist:
     - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build .
     - meson compile -C _build
     - meson dist -C _build
-    - ninja -C _build gdk-pixbuf-doc
-    - tar -c -J -f _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/
+    - tar -c -J -f _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/gdk-pixbuf/
+    - tar -c -J -f _build/gdk-pixdata-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/gdk-pixdata/
   artifacts:
     when: on_success
     paths:
       - _build/meson-dist/gdk-pixbuf-${CI_COMMIT_TAG}.tar.xz
       - _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz
+      - _build/gdk-pixdata-docs-${CI_COMMIT_TAG}.tar.xz
   only:
     - tags
 
diff --git a/.gitlab/ci/fedora.Dockerfile b/.gitlab/ci/fedora.Dockerfile
index 83fe27d98..804024823 100644
--- a/.gitlab/ci/fedora.Dockerfile
+++ b/.gitlab/ci/fedora.Dockerfile
@@ -23,8 +23,11 @@ RUN dnf -y install \
         meson \
         python3 \
         python3-jinja2 \
+        python3-markdown \
         python3-pip \
         python3-pygments \
+        python3-toml \
+        python3-typogrify \
         python3-wheel \
         redhat-rpm-config \
         shared-mime-info \
diff --git a/docs/gdk-pixbuf-from-drawables.xml b/docs/gdk-pixbuf-from-drawables.xml
deleted file mode 100644
index 99fe3be07..000000000
--- a/docs/gdk-pixbuf-from-drawables.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gdk-pixbuf-gdk-pixbuf-from-drawables">
-<refmeta>
-<refentrytitle>Drawables to Pixbufs</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Drawables to Pixbufs</refname><refpurpose>Getting parts of a GDK drawable's image data into a pixbuf.</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Description</title>
-  <para>
-    The functions to take the image data from a GDK windowing system surface
-    and store them into a GdkPixbuf are provided by GDK; see
-    <ulink url="https://developer.gnome.org/gdk3/stable/gdk3-Pixbufs.html">the
-    GDK documentation</ulink>.
-  </para>
-</refsect1>
-
-</refentry>
diff --git a/docs/gdk-pixbuf-rendering.xml b/docs/gdk-pixbuf-rendering.xml
deleted file mode 100644
index 26c8776cc..000000000
--- a/docs/gdk-pixbuf-rendering.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gdk-pixbuf-gdk-pixbuf-rendering">
-<refmeta>
-<refentrytitle>Rendering</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Rendering</refname><refpurpose>Rendering a pixbuf to a GDK drawable.</refpurpose>
-</refnamediv>
-
-
-<refsect1>
-<title>Description</title>
-  <para>
-    The functions to render pixbufs to GDK drawables are provided by GDK, see
-    the <ulink url="https://developer.gnome.org/gdk3/stable/gdk3-Cairo-Interaction.html">GDK
-    documentation</ulink>.
-  </para>
-</refsect1>
-
-</refentry>
diff --git a/docs/gdk-pixbuf.toml.in b/docs/gdk-pixbuf.toml.in
new file mode 100644
index 000000000..bd5cfe935
--- /dev/null
+++ b/docs/gdk-pixbuf.toml.in
@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2021 GNOME Foundation
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[library]
+name = "gdk-pixbuf"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/"
+repository_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+license = "GPL-2.1-or-later"
+description = "Image loading library"
+dependencies = [ "gobject", "gio" ]
+devhelp = true
+search_index = true
+
+  [dependencies.gobject]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies.gio]
+  name = "GIO"
+  description = "GObject Interfaces and Objects"
+  docs_url = "https://developer.gnome.org/gio/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/-/blob/master/"
+
+[extra]
+urlmap_file = "urlmap.js"
+content_images = [
+  'apple-red-1a.png',
+  'apple-red-2c.png',
+  'composite.png',
+  'gnome-gmush-1.png',
+]
+content_files = [
+  'scaling-compositing.md',
+]
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_0_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_2_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_4_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_6_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_8_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_10_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_12_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_14_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_16_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_18_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_20_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_22_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_24_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_26_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_28_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_30_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_32_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_34_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_36_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_38_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_40_FOR"
+hidden = true
diff --git a/docs/gdk-pixbuf.xml b/docs/gdk-pixbuf.xml
deleted file mode 100644
index efe977bdd..000000000
--- a/docs/gdk-pixbuf.xml
+++ /dev/null
@@ -1,229 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GDK-PixBuf Reference Manual</title>
-    <releaseinfo>
-      Version &version;
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://library.gnome.org/devel/gdk-pixbuf/unstable/">http://library.gnome.org/devel/gdk-pixbuf/unstable/</ulink>.
-    </releaseinfo>
-    <authorgroup>
-      <author>
-	<firstname>Federico</firstname>
-	<surname>Mena Quintero</surname>
-	<affiliation>
-	  <address>
-	    <email>federico@gimp.org</email>
-	  </address>
-	</affiliation>
-      </author>
-    </authorgroup>
-
-    <copyright>
-      <year>2000</year>
-      <holder>The Free Software Foundation</holder>
-    </copyright>
-
-    <legalnotice>
-      <para>
-	Permission is granted to copy, distribute and/or modify this
-	document under the terms of the <citetitle>GNU Free
-	Documentation License</citetitle>, Version 1.1 or any later
-	version published by the Free Software Foundation with no
-	Invariant Sections, no Front-Cover Texts, and no Back-Cover
-	Texts. You may obtain a copy of the <citetitle>GNU Free
-	Documentation License</citetitle> from the Free Software
-	Foundation by visiting <ulink type="http"
-	url="http://www.fsf.org">their Web site</ulink> or by writing
-	to:
-
-	<address>
-	  The Free Software Foundation, Inc.,
-	  <street>59 Temple Place</street> - Suite 330,
-	  <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
-	  <country>USA</country>
-	</address>
-      </para>
-
-      <para>
-	Many of the names used by companies to distinguish their
-	products and services are claimed as trademarks. Where those
-	names appear in any GNOME documentation, and those trademarks
-	are made aware to the members of the GNOME Documentation
-	Project, the names have been printed in caps or initial caps.
-      </para>
-    </legalnotice>
-  </bookinfo>
-
-  <reference>
-    <title>API Reference</title>
-
-    <partintro>
-      <para>
-	This part presents the class and function reference for the
-	gdk-pixbuf library.  Classes are described together with
-	their methods; individual functions are grouped by functional
-	group.
-      </para>
-    </partintro>
-
-    <xi:include href="xml/initialization_versions.xml" />
-
-    <xi:include href="xml/gdk-pixbuf.xml" />
-    <xi:include href="xml/refcounting.xml" />
-    <xi:include href="xml/file-loading.xml" />
-    <xi:include href="xml/file-saving.xml" />
-    <xi:include href="xml/creating.xml" />
-    <xi:include href="xml/inline.xml" />
-    <xi:include href="xml/scaling.xml" />
-    <xi:include href="xml/util.xml" />
-    <xi:include href="xml/animation.xml" />
-
-    <chapter id="LoadableModules">
-      <title>Loadable modules</title>
-      <xi:include href="xml/module_interface.xml" />
-      <xi:include href="xml/gdk-pixbuf-loader.xml" />
-    </chapter>
-
-    <chapter id="Gdk">
-      <title>GDK integration (deprecated)</title>
-      <xi:include href="xml/gdk-pixbuf-rendering.xml" />
-      <xi:include href="xml/gdk-pixbuf-from-drawables.xml" />
-    </chapter>
-  </reference>
-
-  <reference>
-    <title>Tools Reference</title>
-
-    <partintro>
-      <para>
-	This part presents the tools which are shipped with the gdk-pixbuf library.
-      </para>
-    </partintro>
-
-    <xi:include href="gdk-pixbuf-csource.xml" />
-    <xi:include href="gdk-pixbuf-query-loaders.xml" />
-  </reference>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-2" role="2.2">
-    <title>Index of new symbols in 2.2</title>
-    <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-4" role="2.4">
-    <title>Index of new symbols in 2.4</title>
-    <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-6" role="2.6">
-    <title>Index of new symbols in 2.6</title>
-    <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-8" role="2.8">
-    <title>Index of new symbols in 2.8</title>
-    <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-12" role="2.12">
-    <title>Index of new symbols in 2.12</title>
-    <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-14" role="2.14">
-    <title>Index of new symbols in 2.14</title>
-    <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-18" role="2.18">
-    <title>Index of new symbols in 2.18</title>
-    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-22" role="2.22">
-    <title>Index of new symbols in 2.22</title>
-    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-24" role="2.24">
-    <title>Index of new symbols in 2.24</title>
-    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-26" role="2.26">
-    <title>Index of new symbols in 2.26</title>
-    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-28" role="2.28">
-    <title>Index of new symbols in 2.28</title>
-    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-30" role="2.30">
-    <title>Index of new symbols in 2.30</title>
-    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-32" role="2.32">
-    <title>Index of new symbols in 2.32</title>
-    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-36" role="2.36">
-    <title>Index of new symbols in 2.36</title>
-    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-36-8" role="2.36.8">
-    <title>Index of new symbols in 2.36.8</title>
-    <xi:include href="xml/api-index-2.36.8.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-38" role="2.38">
-    <title>Index of new symbols in 2.38</title>
-    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-40" role="2.40">
-    <title>Index of new symbols in 2.40</title>
-    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <!-- License -->
-
-  <appendix id="license">
-    <title>License</title>
-	
-    <para>
-      This library is free software; you can redistribute it and/or
-      modify it under the terms of the <citetitle>GNU Library General
-      Public License</citetitle> as published by the Free Software
-      Foundation; either version 2 of the License, or (at your option)
-      any later version.
-    </para>
-
-    <para>
-      This library is distributed in the hope that it will be useful,
-      but WITHOUT ANY WARRANTY; without even the implied warranty of
-      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-      <citetitle>GNU Library General Public License</citetitle> for
-      more details.
-    </para>
-
-    <para>
-      You may obtain a copy of the <citetitle>GNU Library General
-      Public License</citetitle> from the Free Software Foundation by
-      visiting <ulink type="http" url="http://www.fsf.org">their Web
-      site</ulink> or by writing to:
-
-      <address>
-	Free Software Foundation, Inc.
-	<street>59 Temple Place</street> - Suite 330
-	<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
-	<country>USA</country>
-      </address>
-    </para>
-  </appendix>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
-
diff --git a/docs/gdk-pixdata.toml.in b/docs/gdk-pixdata.toml.in
new file mode 100644
index 000000000..47f37cb25
--- /dev/null
+++ b/docs/gdk-pixdata.toml.in
@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2021 GNOME Foundation
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[library]
+name = "gdk-pixdata"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/"
+repository_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+license = "GPL-2.1-or-later"
+description = "Inline image data"
+dependencies = [ "gobject", "gio", "gdk-pixbuf" ]
+devhelp = true
+search_index = true
+
+  [dependencies.gobject]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies.gio]
+  name = "GIO"
+  description = "GObject Interfaces and Objects"
+  docs_url = "https://developer.gnome.org/gio/stable"
+
+  [dependencies."gdk-pixbuf"]
+  name = "GdkPixbuf"
+  description = "Image loading library"
+  docs_url = "../gdk-pixbuf/index.html"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/-/blob/master/"
+
+[extra]
+urlmap_file = "urlmap.js"
diff --git a/docs/meson.build b/docs/meson.build
index c7c8fe721..c9a16a49b 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,69 +1,68 @@
-version_xml = configuration_data()
-version_xml.set('GDK_PIXBUF_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in',
-               output: 'version.xml',
-               configuration: version_xml)
+gidocgen_dep = dependency('gi-docgen',
+  version: '>= 2021.1',
+  fallback: ['gi-docgen', 'dummy_dep'],
+  required: get_option('gtk_doc'),
+)
 
-if gobject_dep.type_name() == 'pkgconfig'
-  glib_prefix = gobject_dep.get_pkgconfig_variable('prefix')
-else
-  glib_prefix = get_option('prefix')
-endif
-glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
-docpath = join_paths(gdk_pixbuf_datadir, 'gtk-doc', 'html')
 
-private_headers = [
-  'pixops',
-  'gdk-pixbuf.h',
-  'gdk-pixbuf-alias.h',
-  'gdk-pixbuf-autocleanups.h',
-  'gdk-pixbuf-buffer-queue-private.h',
-  'gdk-pixbuf-marshal.h',
-  'gdk-pixbuf-private.h',
-  'gdk-pixbuf-scaled-anim.h',
-  'io-ani-animation.h',
-  'io-gdip-animation.h',
-  'io-gdip-native.h',
-  'io-gdip-propertytags.h',
-  'io-gdip-utils.h',
-  'io-gif-animation.h',
-  'xpm-color-table.h',
-  'test-images.h',
-  'lzw.h',
+toml_conf = configuration_data()
+toml_conf.set('VERSION', meson.project_version())
+pixbuf_toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf)
+pixdata_toml = configure_file(input: 'gdk-pixdata.toml.in', output: 'gdk-pixdata.toml', configuration: toml_conf)
+
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
+
+docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference'
+
+expand_content_md_files = [
+  'scaling-compositing.md',
 ]
 
+build_docs = get_option('gtk_doc')
 if get_option('docs')
-  warning('The "docs" build option is deprecated; please use "gtk_doc=true"')
+  warning('The docs option is deprecated; use -Dgtk_doc=true')
+  build_docs = true
 endif
 
-if get_option('gtk_doc') or get_option('docs')
-  gnome.gtkdoc('gdk-pixbuf',
-               main_xml: 'gdk-pixbuf.xml',
-               src_dir: [ gdk_pixbuf_inc ],
-               dependencies: gdkpixbuf_dep,
-               gobject_typesfile: 'gdk-pixbuf.types',
-               scan_args: [
-                 '--rebuild-types',
-                 '--deprecated-guards="GDK_PIXBUF_ENABLE_BROKEN|GDK_PIXBUF_DISABLE_DEPRECATED"',
-                 '--ignore-headers=' + ' '.join(private_headers),
-               ],
-               fixxref_args: [
-                 '--html-dir=@0@'.format(docpath),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-               ],
-               html_assets: [
-                 'composite.png',
-               ],
-               content_files: [
-                 'gdk-pixbuf-from-drawables.xml',
-                 'gdk-pixbuf-rendering.xml',
-                 'gdk-pixbuf.xml',
-                 'gdk-pixbuf-csource.xml',
-                 'gdk-pixbuf-query-loaders.xml',
-               ],
-               install: true)
+if build_docs
+  custom_target('gdk-pixbuf-doc',
+    input: [ pixbuf_toml, gdkpixbuf_gir[0] ],
+    output: 'gdk-pixbuf',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../gdk-pixbuf'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    depend_files: [ expand_content_md_files ],
+    build_by_default: true,
+    install: true,
+    install_dir: docs_dir,
+  )
+
+  custom_target('gdk-pixdata-doc',
+    input: [ pixdata_toml, gdkpixdata_gir[0] ],
+    output: 'gdk-pixdata',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../gdk-pixbuf'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    build_by_default: true,
+    install: true,
+    install_dir: docs_dir,
+  )
 endif
 
 xsltproc = find_program('xsltproc', required: false)
diff --git a/docs/scaling-compositing.md b/docs/scaling-compositing.md
new file mode 100644
index 000000000..3abc75e73
--- /dev/null
+++ b/docs/scaling-compositing.md
@@ -0,0 +1,44 @@
+Title: Scaling and compositing
+
+----
+
+The `GdkPixBuf` class contains methods to scale pixbufs, to scale
+pixbufs and alpha blend against an existing image, and to scale
+pixbufs and alpha blend against a solid color or checkerboard.
+Alpha blending a checkerboard is a common way to show an image with
+an alpha channel in image-viewing and editing software.
+
+Note that in these functions, the terms ‘alpha blending’ and ‘compositing’
+are used synonymously.
+
+Since the full-featured functions [method@GdkPixbuf.Pixbuf.scale],
+[method@GdkPixbuf.Pixbuf.composite], and [`method@GdkPixbuf.Pixbuf.composite_color`]
+are rather complex to use and have many arguments, two simple
+convenience functions are provided, [`method@GdkPixbuf.Pixbuf.scale_simple`]
+and [`method@GdkPixbuf.Pixbuf.composite_color_simple`] which create a new
+pixbuf of a given size, scale an original image to fit, and then return it.
+
+If the destination pixbuf was created from a read only source, these
+operations will force a copy into a mutable buffer.
+
+Scaling and alpha blending functions take advantage of MMX hardware
+acceleration on systems where MMX is supported. If `GdkPixbuf` is built
+with the Sun mediaLib library, these functions are instead accelerated
+using mediaLib, which provides hardware acceleration on Intel, AMD,
+and Sparc chipsets. If desired, mediaLib support can be turned off by
+setting the `GDK_DISABLE_MEDIALIB` environment variable.
+
+The alpha blending function used is:
+
+```
+Cd = Cs·As + Cd(1-As)
+```
+
+where `Cd` is the destination pixel color, `Cs` is the source pixel color,
+and `As` is the source pixel alpha.
+
+**NOTE**: It is recommended to use [Cairo][cairo] for scaling and
+compositing, by using the contents of a `GdkPixbuf` pixel buffer as the
+data for a Cairo image surface.
+
+[cairo]: https://www.cairographics.org
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 000000000..caaee10f0
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ],
+    [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ],
+    [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+    [ 'GdkPixbuf', 'https://gnome.pages.gitlab.gnome.org/gdk-pixbuf/' ],
+]
diff --git a/docs/version.xml.in b/docs/version.xml.in
deleted file mode 100644
index 90ff08b2b..000000000
--- a/docs/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@GDK_PIXBUF_VERSION@
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c
index c8f2695e3..6f2c170b8 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.c
+++ b/gdk-pixbuf/gdk-pixbuf-animation.c
@@ -30,21 +30,30 @@
 #include <glib/gstdio.h>
 
 /**
- * SECTION:animation
- * @Short_description: Animated images.
- * @Title: Animations
- * @See_also: #GdkPixbufLoader.
+ * GdkPixbufAnimation:
+ *
+ * An opaque object representing an animation.
  *
  * The GdkPixBuf library provides a simple mechanism to load and
  * represent animations. An animation is conceptually a series of
- * frames to be displayed over time. The animation may not be
- * represented as a series of frames internally; for example, it may
- * be stored as a sprite and instructions for moving the sprite around
- * a background. To display an animation you don't need to understand
- * its representation, however; you just ask GdkPixBuf what should
+ * frames to be displayed over time.
+ *
+ * The animation may not be represented as a series of frames
+ * internally; for example, it may be stored as a sprite and
+ * instructions for moving the sprite around a background.
+ *
+ * To display an animation you don't need to understand its
+ * representation, however; you just ask `GdkPixbuf` what should
  * be displayed at a given point in time.
  */
 
+/**
+ * GdkPixbufAnimationIter:
+ *
+ * An opaque object representing an iterator which points to a
+ * certain position in an animation.
+ */
+
 typedef struct _GdkPixbufNonAnim GdkPixbufNonAnim;
 typedef struct _GdkPixbufNonAnimClass GdkPixbufNonAnimClass;
 
@@ -138,18 +147,19 @@ noop_updated_notify (GdkPixbuf *pixbuf,
 /**
  * gdk_pixbuf_animation_new_from_file:
  * @filename: (type filename): Name of file to load, in the GLib file
- *     name encoding
+ *   name encoding
  * @error: return location for error
  *
- * Creates a new animation by loading it from a file. The file format is
- * detected automatically. If the file's format does not support multi-frame
- * images, then an animation with a single frame will be created. Possible errors
- * are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
+ * Creates a new animation by loading it from a file.
  *
- * Return value: A newly-created animation with a reference count of 1, or %NULL
- * if any of several error conditions ocurred:  the file could not be opened,
- * there was no loader for the file's format, there was not enough memory to
- * allocate the image buffer, or the image file contained invalid data.
+ * The file format is detected automatically.
+ *
+ * If the file's format does not support multi-frame images, then an animation
+ * with a single frame will be created.
+ *
+ * Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains.
+ *
+ * Return value: (transfer full) (nullable): A newly-created animation
  */
 GdkPixbufAnimation *
 gdk_pixbuf_animation_new_from_file (const gchar  *filename,
@@ -320,7 +330,7 @@ fail_begin_load:
  *
  * Same as gdk_pixbuf_animation_new_from_file()
  *
- * Return value: A newly-created animation with a reference count of 1, or %NULL
+ * Return value: A newly-created animation with a reference count of 1, or `NULL`
  * if any of several error conditions ocurred:  the file could not be opened,
  * there was no loader for the file's format, there was not enough memory to
  * allocate the image buffer, or the image file contained invalid data.
@@ -335,24 +345,24 @@ gdk_pixbuf_animation_new_from_file_utf8 (const gchar  *filename,
 
 /**
  * gdk_pixbuf_animation_new_from_stream:
- * @stream:  a #GInputStream to load the pixbuf from
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @stream:  a `GInputStream` to load the pixbuf from
+ * @cancellable: (nullable): optional `GCancellable` object
  * @error: Return location for an error
  *
  * Creates a new animation by loading it from an input stream.
  *
- * The file format is detected automatically. If %NULL is returned, then
- * @error will be set. The @cancellable can be used to abort the operation
- * from another thread. If the operation was cancelled, the error
- * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in
- * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains.
+ * The file format is detected automatically.
+ *
+ * If `NULL` is returned, then @error will be set.
+ *
+ * The @cancellable can be used to abort the operation from another thread.
+ * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
+ * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
+ * `G_IO_ERROR` domains.
  *
  * The stream is not closed.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created animation
  *
  * Since: 2.28
  */
@@ -433,8 +443,8 @@ animation_new_from_stream_thread (GTask        *task,
 /**
  * gdk_pixbuf_animation_new_from_stream_async:
  * @stream: a #GInputStream from which to load the animation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded
+ * @cancellable: (nullable): optional #GCancellable object
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded
  * @user_data: the data to pass to the callback function
  *
  * Creates a new animation by asynchronously loading an image from an input stream.
@@ -442,7 +452,7 @@ animation_new_from_stream_thread (GTask        *task,
  * For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
  * version of this function.
  *
- * When the operation is finished, @callback will be called in the main thread.
+ * When the operation is finished, `callback` will be called in the main thread.
  * You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
  * result of the operation.
  *
@@ -469,13 +479,12 @@ gdk_pixbuf_animation_new_from_stream_async (GInputStream        *stream,
 /**
  * gdk_pixbuf_animation_new_from_stream_finish:
  * @async_result: a #GAsyncResult
- * @error: a #GError, or %NULL
+ * @error: a #GError, or `NULL`
  *
  * Finishes an asynchronous pixbuf animation creation operation started with
- * gdk_pixbuf_animation_new_from_stream_async().
+ * [func@GdkPixbuf.PixbufAnimation.new_from_stream_async].
  *
- * Return value: a #GdkPixbufAnimation or %NULL on error. Free the returned
- * object with g_object_unref().
+ * Return value: (transfer full) (nullable): the newly created animation
  *
  * Since: 2.28
  **/
@@ -499,13 +508,10 @@ gdk_pixbuf_animation_new_from_stream_finish (GAsyncResult  *async_result,
  *
  * Creates a new pixbuf animation by loading an image from an resource.
  *
- * The file format is detected automatically. If %NULL is returned, then
+ * The file format is detected automatically. If `NULL` is returned, then
  * @error will be set.
  *
- * Return value: A newly-created animation, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created animation
  *
  * Since: 2.28
  */
@@ -567,12 +573,14 @@ gdk_pixbuf_animation_unref (GdkPixbufAnimation *animation)
  * gdk_pixbuf_animation_is_static_image:
  * @animation: a #GdkPixbufAnimation
  *
+ * Checks whether the animation is a static image.
+ *
  * If you load a file with gdk_pixbuf_animation_new_from_file() and it
  * turns out to be a plain, unanimated image, then this function will
- * return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve
+ * return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
  * the image.
  *
- * Return value: %TRUE if the "animation" was really just an image
+ * Return value: `TRUE` if the "animation" was really just an image
  */
 gboolean
 gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
@@ -586,12 +594,17 @@ gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
  * gdk_pixbuf_animation_get_static_image:
  * @animation: a #GdkPixbufAnimation
  *
+ * Retrieves a static image for the animation.
+ *
  * If an animation is really just a plain image (has only one frame),
- * this function returns that image. If the animation is an animation,
- * this function returns a reasonable thing to display as a static
- * unanimated image, which might be the first frame, or something more
- * sophisticated. If an animation hasn't loaded any frames yet, this
- * function will return %NULL.
+ * this function returns that image.
+ *
+ * If the animation is an animation, this function returns a reasonable
+ * image to use as a static unanimated image, which might be the first
+ * frame, or something more sophisticated depending on the file format.
+ *
+ * If an animation hasn't loaded any frames yet, this function will
+ * return `NULL`.
  *
  * Return value: (transfer none): unanimated image representing the animation
  */
@@ -653,9 +666,10 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * @animation: a #GdkPixbufAnimation
  * @start_time: (allow-none): time when the animation starts playing
  *
- * Get an iterator for displaying an animation. The iterator provides
- * the frames that should be displayed at a given time. It should be
- * freed after use with g_object_unref().
+ * Get an iterator for displaying an animation.
+ *
+ * The iterator provides the frames that should be displayed at a
+ * given time.
  *
  * @start_time would normally come from g_get_current_time(), and marks
  * the beginning of animation playback. After creating an iterator, you
@@ -667,7 +681,7 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * the image is updated, you should reinstall the timeout with the new,
  * possibly-changed delay time.
  *
- * As a shortcut, if @start_time is %NULL, the result of
+ * As a shortcut, if @start_time is `NULL`, the result of
  * g_get_current_time() will be used automatically.
  *
  * To update the image (i.e. possibly change the result of
@@ -678,14 +692,14 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * after the delay time, you should also update it whenever you
  * receive the area_updated signal and
  * gdk_pixbuf_animation_iter_on_currently_loading_frame() returns
- * %TRUE. In this case, the frame currently being fed into the loader
+ * `TRUE`. In this case, the frame currently being fed into the loader
  * has received new data, so needs to be refreshed. The delay time for
  * a frame may also be modified after an area_updated signal, for
  * example if the delay time for a frame is encoded in the data after
  * the frame itself. So your timeout should be reinstalled after any
  * area_updated signal.
  *
- * A delay time of -1 is possible, indicating "infinite."
+ * A delay time of -1 is possible, indicating "infinite".
  *
  * Return value: (transfer full): an iterator to move over the animation
  */
@@ -723,9 +737,10 @@ gdk_pixbuf_animation_iter_init (GdkPixbufAnimationIter *iter)
  * @iter: an animation iterator
  *
  * Gets the number of milliseconds the current pixbuf should be displayed,
- * or -1 if the current pixbuf should be displayed forever. g_timeout_add()
- * conveniently takes a timeout in milliseconds, so you can use a timeout
- * to schedule the next update.
+ * or -1 if the current pixbuf should be displayed forever.
+ *
+ * The `g_timeout_add()` function conveniently takes a timeout in milliseconds,
+ * so you can use a timeout to schedule the next update.
  *
  * Note that some formats, like GIF, might clamp the timeout values in the
  * image file to avoid updates that are just too quick. The minimum timeout
@@ -746,17 +761,21 @@ gdk_pixbuf_animation_iter_get_delay_time (GdkPixbufAnimationIter *iter)
  * gdk_pixbuf_animation_iter_get_pixbuf:
  * @iter: an animation iterator
  *
- * Gets the current pixbuf which should be displayed; the pixbuf might not
- * be the same size as the animation itself
+ * Gets the current pixbuf which should be displayed.
+ *
+ * The pixbuf might not be the same size as the animation itself
  * (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()).
- * This pixbuf should be displayed for
- * gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller
- * of this function does not own a reference to the returned pixbuf;
- * the returned pixbuf will become invalid when the iterator advances
- * to the next frame, which may happen anytime you call
- * gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it
- * (don't just add a reference), as it may get recycled as you advance
- * the iterator.
+ *
+ * This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time()
+ * milliseconds.
+ *
+ * The caller of this function does not own a reference to the returned
+ * pixbuf; the returned pixbuf will become invalid when the iterator
+ * advances to the next frame, which may happen anytime you call
+ * gdk_pixbuf_animation_iter_advance().
+ *
+ * Copy the pixbuf to keep it (don't just add a reference), as it may get
+ * recycled as you advance the iterator.
  *
  * Return value: (transfer none): the pixbuf to be displayed
  */
@@ -774,12 +793,13 @@ gdk_pixbuf_animation_iter_get_pixbuf (GdkPixbufAnimationIter *iter)
  * @iter: a #GdkPixbufAnimationIter
  *
  * Used to determine how to respond to the area_updated signal on
- * #GdkPixbufLoader when loading an animation. area_updated is emitted
- * for an area of the frame currently streaming in to the loader. So if
- * you're on the currently loading frame, you need to redraw the screen for
- * the updated area.
+ * #GdkPixbufLoader when loading an animation.
+ *
+ * The `::area_updated` signal is emitted for an area of the frame currently
+ * streaming in to the loader. So if you're on the currently loading frame,
+ * you will need to redraw the screen for the updated area.
  *
- * Return value: %TRUE if the frame we're on is partially loaded, or the last frame
+ * Return value: `TRUE` if the frame we're on is partially loaded, or the last frame
  */
 gboolean
 gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *iter)
@@ -795,8 +815,10 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
  * @iter: a #GdkPixbufAnimationIter
  * @current_time: (allow-none): current time
  *
- * Possibly advances an animation to a new frame. Chooses the frame based
- * on the start time passed to gdk_pixbuf_animation_get_iter().
+ * Possibly advances an animation to a new frame.
+ *
+ * Chooses the frame based on the start time passed to
+ * gdk_pixbuf_animation_get_iter().
  *
  * @current_time would normally come from g_get_current_time(), and
  * must be greater than or equal to the time passed to
@@ -805,17 +827,17 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
  * called. That is, you can't go backward in time; animations only
  * play forward.
  *
- * As a shortcut, pass %NULL for the current time and g_get_current_time()
+ * As a shortcut, pass `NULL` for the current time and g_get_current_time()
  * will be invoked on your behalf. So you only need to explicitly pass
  * @current_time if you're doing something odd like playing the animation
  * at double speed.
  *
- * If this function returns %FALSE, there's no need to update the animation
+ * If this function returns `FALSE`, there's no need to update the animation
  * display, assuming the display had been rendered prior to advancing;
- * if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
+ * if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
  * and update the display with the new pixbuf.
  *
- * Returns: %TRUE if the image may need updating
+ * Returns: `TRUE` if the image may need updating
  */
 gboolean
 gdk_pixbuf_animation_iter_advance (GdkPixbufAnimationIter *iter,
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.h b/gdk-pixbuf/gdk-pixbuf-animation.h
index ad0c39c3b..cae551edd 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.h
+++ b/gdk-pixbuf/gdk-pixbuf-animation.h
@@ -36,20 +36,9 @@ G_BEGIN_DECLS
 
 /* Animation support */
 
-/**
- * GdkPixbufAnimation:
- *
- * An opaque struct representing an animation.
- */
 typedef struct _GdkPixbufAnimation GdkPixbufAnimation;
 
 
-/**
- * GdkPixbufAnimationIter:
- *
- * An opaque struct representing an iterator which points to a
- * certain position in an animation.
- */
 typedef struct _GdkPixbufAnimationIter GdkPixbufAnimationIter;
 
 #define GDK_TYPE_PIXBUF_ANIMATION              (gdk_pixbuf_animation_get_type ())
diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h
index 9e6ba6fab..4b8c9b9b2 100644
--- a/gdk-pixbuf/gdk-pixbuf-core.h
+++ b/gdk-pixbuf/gdk-pixbuf-core.h
@@ -44,17 +44,23 @@ G_BEGIN_DECLS
  *  considered fully opaque.
  * @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
  *  In the future it will do full alpha compositing.
- * 
- * These values can be passed to
- * gdk_pixbuf_xlib_render_to_drawable_alpha() to control how the alpha
- * channel of an image should be handled.  This function can create a
- * bilevel clipping mask (black and white) and use it while painting
- * the image.  In the future, when the X Window System gets an alpha
- * channel extension, it will be possible to do full alpha
- * compositing onto arbitrary drawables.  For now both cases fall
- * back to a bilevel clipping mask.
  *
- * Deprecated: it is unused since 2.42.
+ * Control the alpha channel for drawables.
+ *
+ * These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha()
+ * in gdk-pixbuf-xlib to control how the alpha channel of an image should
+ * be handled.
+ *
+ * This function can create a bilevel clipping mask (black and white) and use
+ * it while painting the image.
+ *
+ * In the future, when the X Window System gets an alpha channel extension,
+ * it will be possible to do full alpha compositing onto arbitrary drawables.
+ * For now both cases fall back to a bilevel clipping mask.
+ *
+ * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode in GdkPixbuf,
+ *   and the Xlib utility functions have been split out to their own
+ *   library, gdk-pixbuf-xlib
  */
 typedef enum
 {
@@ -67,7 +73,9 @@ typedef enum
  * @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
  * 
  * This enumeration defines the color spaces that are supported by
- * the gdk-pixbuf library.  Currently only RGB is supported.
+ * the gdk-pixbuf library.
+ *
+ * Currently only RGB is supported.
  */
 /* Note that these values are encoded in inline pixbufs
  * as ints, so don't reorder them
@@ -78,15 +86,6 @@ typedef enum {
 
 /* All of these are opaque structures */
 
-/**
- * GdkPixbuf:
- * 
- * This is the main structure in the gdk-pixbuf library.  It is
- * used to represent images.  It contains information about the
- * image's pixel data, its color space, bits per sample, width and
- * height, and the rowstride (the number of bytes between the start of
- * one row and the start of the next). 
- */
 typedef struct _GdkPixbuf GdkPixbuf;
 
 #define GDK_TYPE_PIXBUF              (gdk_pixbuf_get_type ())
@@ -101,20 +100,23 @@ typedef struct _GdkPixbuf GdkPixbuf;
  * @data: (closure): User closure data.
  * 
  * A function of this type is responsible for freeing the pixel array
- * of a pixbuf.  The gdk_pixbuf_new_from_data() function lets you
- * pass in a pre-allocated pixel array so that a pixbuf can be
- * created from it; in this case you will need to pass in a function
- * of #GdkPixbufDestroyNotify so that the pixel data can be freed
- * when the pixbuf is finalized.
+ * of a pixbuf.
+ *
+ * The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated
+ * pixel array so that a pixbuf can be created from it; in this case you
+ * will need to pass in a function of type `GdkPixbufDestroyNotify` so that
+ * the pixel data can be freed when the pixbuf is finalized.
  */
 typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
 
 /**
  * GDK_PIXBUF_ERROR:
  * 
- * Error domain used for pixbuf operations. Indicates that the error code
- * will be in the #GdkPixbufError enumeration. See #GError for
- * information on error domains and error codes.
+ * Error domain used for pixbuf operations.
+ *
+ * Indicates that the error code will be in the `GdkPixbufError` enumeration.
+ *
+ * See the `GError` for information on error domains and error codes.
  */
 #define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
 
@@ -129,9 +131,10 @@ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
  * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
  * @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded.
  * 
- * An error code in the #GDK_PIXBUF_ERROR domain. Many gdk-pixbuf
- * operations can cause errors in this domain, or in the #G_FILE_ERROR
- * domain.
+ * An error code in the `GDK_PIXBUF_ERROR` domain.
+ *
+ * Many gdk-pixbuf operations can cause errors in this domain, or in
+ * the `G_FILE_ERROR` domain.
  */
 typedef enum {
         /* image data hosed */
@@ -347,15 +350,18 @@ gboolean gdk_pixbuf_savev_utf8     (GdkPixbuf  *pixbuf,
  * @error: (out): A location to return an error.
  * @data: (closure): user data passed to gdk_pixbuf_save_to_callback(). 
  * 
- * Specifies the type of the function passed to
- * gdk_pixbuf_save_to_callback().  It is called once for each block of
- * bytes that is "written" by gdk_pixbuf_save_to_callback().  If
- * successful it should return %TRUE.  If an error occurs it should set
- * @error and return %FALSE, in which case gdk_pixbuf_save_to_callback()
+ * Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback].
+ *
+ * This function is called once for each block of bytes that is "written"
+ * by `gdk_pixbuf_save_to_callback()`.
+ *
+ * If successful it should return `TRUE`; if an error occurs it should set
+ * `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()`
  * will fail with the same error.
+ *
+ * Returns: `TRUE` if successful, `FALSE` otherwise
  * 
  * Since: 2.4
- * Returns: %TRUE if successful, %FALSE (with @error set) if failed.
  */
 
 typedef gboolean (*GdkPixbufSaveFunc)   (const gchar *buf,
diff --git a/gdk-pixbuf/gdk-pixbuf-data.c b/gdk-pixbuf/gdk-pixbuf-data.c
index cd968d4ae..958bcb73f 100644
--- a/gdk-pixbuf/gdk-pixbuf-data.c
+++ b/gdk-pixbuf/gdk-pixbuf-data.c
@@ -39,23 +39,30 @@
  * drops to zero, or %NULL if the data should not be freed
  * @destroy_fn_data: (closure): Closure data to pass to the destroy notification function
  * 
- * Creates a new #GdkPixbuf out of in-memory image data.  Currently only RGB
- * images with 8 bits per sample are supported.
+ * Creates a new #GdkPixbuf out of in-memory image data.
+ *
+ * Currently only RGB images with 8 bits per sample are supported.
  *
  * Since you are providing a pre-allocated pixel buffer, you must also
  * specify a way to free that data.  This is done with a function of
- * type #GdkPixbufDestroyNotify.  When a pixbuf created with is
+ * type `GdkPixbufDestroyNotify`.  When a pixbuf created with is
  * finalized, your destroy notification function will be called, and
  * it is its responsibility to free the pixel array.
  *
- * See also gdk_pixbuf_new_from_bytes().
+ * See also: [ctor@GdkPixbuf.Pixbuf.new_from_bytes]
  *
- * Return value: (transfer full): A newly-created #GdkPixbuf structure with a reference count of 1.
+ * Return value: (transfer full): A newly-created pixbuf
  **/
 GdkPixbuf *
-gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean has_alpha,
-			  int bits_per_sample, int width, int height, int rowstride,
-	  GdkPixbufDestroyNotify destroy_fn, gpointer destroy_fn_data)
+gdk_pixbuf_new_from_data (const guchar           *data,
+                          GdkColorspace           colorspace,
+                          gboolean                has_alpha,
+			  int                     bits_per_sample,
+                          int                     width,
+                          int                     height,
+                          int                     rowstride,
+	                  GdkPixbufDestroyNotify  destroy_fn,
+                          gpointer                destroy_fn_data)
 {
 	GdkPixbuf *pixbuf;
 
@@ -95,15 +102,24 @@ gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean
  * @rowstride: Distance in bytes between row starts
  * 
  * Creates a new #GdkPixbuf out of in-memory readonly image data.
+ *
  * Currently only RGB images with 8 bits per sample are supported.
- * This is the #GBytes variant of gdk_pixbuf_new_from_data().
  *
- * Return value: (transfer full): A newly-created #GdkPixbuf structure with a reference count of 1.
+ * This is the `GBytes` variant of gdk_pixbuf_new_from_data(), useful
+ * for language bindings.
+ *
+ * Return value: (transfer full): A newly-created pixbuf
+ *
  * Since: 2.32
  **/
 GdkPixbuf *
-gdk_pixbuf_new_from_bytes (GBytes *data, GdkColorspace colorspace, gboolean has_alpha,
-			   int bits_per_sample, int width, int height, int rowstride)
+gdk_pixbuf_new_from_bytes (GBytes        *data,
+                           GdkColorspace  colorspace,
+                           gboolean       has_alpha,
+			   int            bits_per_sample,
+                           int            width,
+                           int            height,
+                           int            rowstride)
 {
 	g_return_val_if_fail (data != NULL, NULL);
 	g_return_val_if_fail (colorspace == GDK_COLORSPACE_RGB, NULL);
@@ -112,14 +128,14 @@ gdk_pixbuf_new_from_bytes (GBytes *data, GdkColorspace colorspace, gboolean has_
 	g_return_val_if_fail (height > 0, NULL);
 	g_return_val_if_fail (g_bytes_get_size (data) >= width * height * (has_alpha ? 4 : 3), NULL);
 
-	return (GdkPixbuf*) g_object_new (GDK_TYPE_PIXBUF, 
-					  "pixel-bytes", data,
-					  "colorspace", colorspace,
-					  "n-channels", has_alpha ? 4 : 3,
-					  "bits-per-sample", bits_per_sample,
-					  "has-alpha", has_alpha ? TRUE : FALSE,
-					  "width", width,
-					  "height", height,
-					  "rowstride", rowstride,
-					  NULL);
+	return g_object_new (GDK_TYPE_PIXBUF,
+                             "pixel-bytes", data,
+                             "colorspace", colorspace,
+                             "n-channels", has_alpha ? 4 : 3,
+                             "bits-per-sample", bits_per_sample,
+                             "has-alpha", has_alpha ? TRUE : FALSE,
+                             "width", width,
+                             "height", height,
+                             "rowstride", rowstride,
+                             NULL);
 }
diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in
index 4fdb6bffa..600d03220 100644
--- a/gdk-pixbuf/gdk-pixbuf-features.h.in
+++ b/gdk-pixbuf/gdk-pixbuf-features.h.in
@@ -1,22 +1,13 @@
+#ifndef __GDK_PIXBUF_FEATURES_H__
+#define __GDK_PIXBUF_FEATURES_H__
+
 #if defined(GDK_PIXBUF_DISABLE_SINGLE_INCLUDES) && !defined (GDK_PIXBUF_H_INSIDE) && !defined (GDK_PIXBUF_COMPILATION)
 #error "Only <gdk-pixbuf/gdk-pixbuf.h> can be included directly."
 #endif
 
-#ifndef GDK_PIXBUF_FEATURES_H
-#define GDK_PIXBUF_FEATURES_H 1
-
 #include <glib.h>
 
 /**
- * SECTION:initialization_versions
- * @Short_description: Library version numbers.
- * @Title: Initialization and Versions
- * 
- * These macros and variables let you check the version of gdk-pixbuf
- * you're linking against.
- */
-
-/**
  * GDK_PIXBUF_MAJOR:
  * 
  * Major version of gdk-pixbuf library, that is the "0" in
@@ -37,9 +28,10 @@
 /**
  * GDK_PIXBUF_VERSION:
  * 
- * Contains the full version of the gdk-pixbuf header as a string.
+ * Contains the full version of GdkPixbuf as a string.
+ *
  * This is the version being compiled against; contrast with
- * #gdk_pixbuf_version.
+ * `gdk_pixbuf_version`.
  */
 
 #define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@)
@@ -81,7 +73,7 @@
  * 
  * This variable is in the library, so represents the
  * gdk-pixbuf library you have linked against. Contrast with the
- * #GDK_PIXBUF_MAJOR macro, which represents the major version of the
+ * `GDK_PIXBUF_MAJOR` macro, which represents the major version of the
  * gdk-pixbuf headers you have included.
  */
 /**
@@ -93,7 +85,7 @@
  * 
  * This variable is in the library, so represents the
  * gdk-pixbuf library you have linked against. Contrast with the
- * #GDK_PIXBUF_MINOR macro, which represents the minor version of the
+ * `GDK_PIXBUF_MINOR` macro, which represents the minor version of the
  * gdk-pixbuf headers you have included.
  */
 /**
@@ -105,7 +97,7 @@
  * 
  * This variable is in the library, so represents the
  * gdk-pixbuf library you have linked against. Contrast with the
- * #GDK_PIXBUF_MICRO macro, which represents the micro version of the
+ * `GDK_PIXBUF_MICRO` macro, which represents the micro version of the
  * gdk-pixbuf headers you have included.
  */
 /**
@@ -120,4 +112,4 @@ GDK_PIXBUF_VAR const guint gdk_pixbuf_minor_version;
 GDK_PIXBUF_VAR const guint gdk_pixbuf_micro_version;
 GDK_PIXBUF_VAR const char *gdk_pixbuf_version;
 
-#endif /* GDK_PIXBUF_FEATURES_H */
+#endif /* __GDK_PIXBUF_FEATURES_H__ */
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 2dc2ea6da..eb442e3bc 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -48,80 +48,69 @@
 #endif
 
 /**
- * SECTION:file-loading
- * @Short_description: Loading a pixbuf from a file.
- * @Title: File Loading
- * @See_also: #GdkPixbufLoader.
+ * GdkPixbufModule:
+ * @module_name: the name of the module, usually the same as the
+ *  usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
+ * @module_path: the path from which the module is loaded.
+ * @module: the loaded `GModule`.
+ * @info: a `GdkPixbufFormat` holding information about the module.
+ * @load: loads an image from a file.
+ * @load_xpm_data: loads an image from data in memory.
+ * @begin_load: begins an incremental load.
+ * @stop_load: stops an incremental load.
+ * @load_increment: continues an incremental load.
+ * @load_animation: loads an animation from a file.
+ * @save: saves a `GdkPixbuf` to a file.
+ * @save_to_callback: saves a `GdkPixbuf` by calling the given `GdkPixbufSaveFunc`.
+ * @is_save_option_supported: returns whether a save option key is supported by the module
  * 
- * The GdkPixBuf library provides a simple mechanism for loading
- * an image from a file in synchronous fashion.  This means that the
- * library takes control of the application while the file is being
- * loaded; from the user's point of view, the application will block
- * until the image is done loading.
+ * A `GdkPixbufModule` contains the necessary functions to load and save
+ * images in a certain file format.
  * 
+ * If `GdkPixbuf` has been compiled with `GModule` support, it can be extended
+ * by modules which can load (and perhaps also save) new image and animation
+ * formats.
+ *
+ * ## Implementing modules
  * 
- * This interface can be used by applications in which blocking is
- * acceptable while an image is being loaded.  It can also be used to
- * load small images in general.  Applications that need progressive
- * loading can use the #GdkPixbufLoader functionality instead.
- */
-
-/**
- * SECTION:file-saving
- * @Short_description: Saving a pixbuf to a file.
- * @Title: File saving
- * 
- * These functions allow to save a #GdkPixbuf in a number of 
- * file formats. The formatted data can be written to a file
- * or to a memory buffer. GdkPixBuf can also call a user-defined
- * callback on the data, which allows to e.g. write the image 
- * to a socket or store it in a database.
- */
-
-/**
- * SECTION:module_interface
- * @Short_description: Extending GdkPixBuf
- * @Title: Module Interface
- * 
- * If GdkPixBuf has been compiled with GModule support, it can be extended by
- * modules which can load (and perhaps also save) new image and animation
- * formats. Each loadable module must export a
- * #GdkPixbufModuleFillInfoFunc function named `fill_info` and
- * a #GdkPixbufModuleFillVtableFunc function named
- * `fill_vtable`.
+ * The `GdkPixbuf` interfaces needed for implementing modules are contained in
+ * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
+ * animations). They are not covered by the same stability guarantees as the
+ * regular GdkPixbuf API. To underline this fact, they are protected by the
+ * `GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol.
+ *
+ * Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function
+ * named `fill_vtable`, which will get called when the module
+ * is loaded and must set the function pointers of the `GdkPixbufModule`.
  * 
  * In order to make format-checking work before actually loading the modules
- * (which may require dlopening image libraries), modules export their 
- * signatures (and other information) via the `fill_info` function. An
- * external utility, gdk-pixbuf-query-loaders, uses this to create a text
+ * (which may require calling `dlopen` to load image libraries), modules export
+ * their signatures (and other information) via the `fill_info` function. An
+ * external utility, `gdk-pixbuf-query-loaders`, uses this to create a text
  * file containing a list of all available loaders and  their signatures.
- * This file is then read at runtime by GdkPixBuf to obtain the list of
+ * This file is then read at runtime by `GdkPixbuf` to obtain the list of
  * available loaders and their signatures. 
  * 
  * Modules may only implement a subset of the functionality available via
- * #GdkPixbufModule. If a particular functionality is not implemented, the
+ * `GdkPixbufModule`. If a particular functionality is not implemented, the
  * `fill_vtable` function will simply not set the corresponding
- * function pointers of the #GdkPixbufModule structure. If a module supports
- * incremental loading (i.e. provides #begin_load, #stop_load and
- * #load_increment), it doesn't have to implement #load, since GdkPixBuf can
- * supply a generic #load implementation wrapping the incremental loading. 
+ * function pointers of the `GdkPixbufModule` structure. If a module supports
+ * incremental loading (i.e. provides `begin_load`, `stop_load` and
+ * `load_increment`), it doesn't have to implement `load`, since `GdkPixbuf`
+ * can supply a generic `load` implementation wrapping the incremental loading.
+ *
+ * ## Installing modules
  * 
  * Installing a module is a two-step process:
- * - copy the module file(s) to the loader directory (normally
- *   `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
- *   environment variable `GDK_PIXBUF_MODULEDIR`) 
- * - call gdk-pixbuf-query-loaders to update the module file (normally
- *   `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the
- *   environment variable `GDK_PIXBUF_MODULE_FILE`)
- * 
- * The GdkPixBuf interfaces needed for implementing modules are contained in
- * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
- * animations). They are not covered by the same stability guarantees as the
- * regular  GdkPixBuf API. To underline this fact, they are protected by
- * `#ifdef GDK_PIXBUF_ENABLE_BACKEND`.
+ *
+ *  - copy the module file(s) to the loader directory (normally
+ *    `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
+ *    environment variable `GDK_PIXBUF_MODULEDIR`)
+ *  - call `gdk-pixbuf-query-loaders` to update the module file (normally
+ *    `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden
+ *    by the environment variable `GDK_PIXBUF_MODULE_FILE`)
  */
 
-
 static gint 
 format_check (GdkPixbufModule *module, guchar *buffer, int size)
 {
@@ -568,10 +557,10 @@ gdk_pixbuf_io_init_modules (const char  *filename,
 
 /**
  * gdk_pixbuf_init_modules:
- * @path: Path to directory where the loaders.cache is installed
- * @error: return location for a #GError
+ * @path: Path to directory where the `loaders.cache` is installed
+ * @error: return location for a `GError`
  *
- * Initalizes the gdk-pixbuf loader modules referenced by the loaders.cache
+ * Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache`
  * file present inside that directory.
  *
  * This is to be used by applications that want to ship certain loaders
@@ -1091,20 +1080,26 @@ _gdk_pixbuf_generic_image_load (GdkPixbufModule *module, FILE *f, GError **error
 }
 
 /**
- * gdk_pixbuf_new_from_file:
+ * gdk_pixbuf_new_from_file: (constructor)
  * @filename: (type filename): Name of file to load, in the GLib file
- *     name encoding
- * @error: Return location for an error
+ *   name encoding
+ * @error: (out): Return location for an error
  *
- * Creates a new pixbuf by loading an image from a file.  The file format is
- * detected automatically. If %NULL is returned, then @error will be set.
- * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
+ * Creates a new pixbuf by loading an image from a file.
  *
- * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if
- * any of several error conditions occurred:  the file could not be opened,
- * there was no loader for the file's format, there was not enough memory to
- * allocate the image buffer, or the image file contained invalid data.
- **/
+ * The file format is detected automatically.
+ *
+ * If `NULL` is returned, then @error will be set. Possible errors are:
+ *
+ *  - the file could not be opened
+ *  - there is no loader for the file's format
+ *  - there is not enough memory to allocate the image buffer
+ *  - the image buffer contains invalid data
+ *
+ * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
+ *
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
+ */
 GdkPixbuf *
 gdk_pixbuf_new_from_file (const char *filename,
                           GError    **error)
@@ -1190,7 +1185,7 @@ gdk_pixbuf_new_from_file (const char *filename,
  *
  * Same as gdk_pixbuf_new_from_file()
  *
- * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if
+ * Return value: A newly-created pixbuf with a reference count of 1, or `NULL` if
  * any of several error conditions occurred:  the file could not be opened,
  * there was no loader for the file's format, there was not enough memory to
  * allocate the image buffer, or the image file contained invalid data.
@@ -1206,29 +1201,33 @@ gdk_pixbuf_new_from_file_utf8 (const char *filename,
 
 
 /**
- * gdk_pixbuf_new_from_file_at_size:
+ * gdk_pixbuf_new_from_file_at_size: (constructor)
  * @filename: (type filename): Name of file to load, in the GLib file
  *     name encoding
  * @width: The width the image should have or -1 to not constrain the width
  * @height: The height the image should have or -1 to not constrain the height
- * @error: Return location for an error
+ * @error: (out): Return location for an error
+ *
+ * Creates a new pixbuf by loading an image from a file.
+ *
+ * The file format is detected automatically.
  *
- * Creates a new pixbuf by loading an image from a file.  
- * The file format is detected automatically. If %NULL is returned, then 
- * @error will be set. Possible errors are in the #GDK_PIXBUF_ERROR and 
- * #G_FILE_ERROR domains.
+ * If `NULL` is returned, then @error will be set. Possible errors are:
+ *
+ *  - the file could not be opened
+ *  - there is no loader for the file's format
+ *  - there is not enough memory to allocate the image buffer
+ *  - the image buffer contains invalid data
+ *
+ * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
  *
  * The image will be scaled to fit in the requested size, preserving
  * the image's aspect ratio. Note that the returned pixbuf may be smaller
- * than @width x @height, if the aspect ratio requires it. To load
+ * than `width` x `height`, if the aspect ratio requires it. To load
  * and image at the requested size, regardless of aspect ratio, use
- * gdk_pixbuf_new_from_file_at_scale().
+ * [ctor@GdkPixbuf.Pixbuf.new_from_file_at_scale].
  *
- * Return value: A newly-created pixbuf with a reference count of 1, or 
- * %NULL if any of several error conditions occurred:  the file could not 
- * be opened, there was no loader for the file's format, there was not 
- * enough memory to allocate the image buffer, or the image file contained 
- * invalid data.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.4
  **/
@@ -1255,7 +1254,7 @@ gdk_pixbuf_new_from_file_at_size (const char *filename,
  * Same as gdk_pixbuf_new_from_file_at_size()
  *
  * Return value: A newly-created pixbuf with a reference count of 1, or
- * %NULL if any of several error conditions occurred:  the file could not
+ * `NULL` if any of several error conditions occurred:  the file could not
  * be opened, there was no loader for the file's format, there was not
  * enough memory to allocate the image buffer, or the image file contained
  * invalid data.
@@ -1329,31 +1328,38 @@ at_scale_size_prepared_cb (GdkPixbufLoader *loader,
 }
 
 /**
- * gdk_pixbuf_new_from_file_at_scale:
+ * gdk_pixbuf_new_from_file_at_scale: (constructor)
  * @filename: (type filename): Name of file to load, in the GLib file
  *     name encoding
  * @width: The width the image should have or -1 to not constrain the width
  * @height: The height the image should have or -1 to not constrain the height
- * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio
+ * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio
  * @error: Return location for an error
  *
- * Creates a new pixbuf by loading an image from a file.  The file format is
- * detected automatically. If %NULL is returned, then @error will be set.
- * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
+ * Creates a new pixbuf by loading an image from a file.
+ *
+ * The file format is detected automatically.
+ *
+ * If `NULL` is returned, then @error will be set. Possible errors are:
+ *
+ *  - the file could not be opened
+ *  - there is no loader for the file's format
+ *  - there is not enough memory to allocate the image buffer
+ *  - the image buffer contains invalid data
+ *
+ * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
+ *
  * The image will be scaled to fit in the requested size, optionally preserving
  * the image's aspect ratio. 
  *
- * When preserving the aspect ratio, a @width of -1 will cause the image
- * to be scaled to the exact given height, and a @height of -1 will cause
+ * When preserving the aspect ratio, a `width` of -1 will cause the image
+ * to be scaled to the exact given height, and a `height` of -1 will cause
  * the image to be scaled to the exact given width. When not preserving
- * aspect ratio, a @width or @height of -1 means to not scale the image 
- * at all in that dimension. Negative values for @width and @height are 
+ * aspect ratio, a `width` or `height` of -1 means to not scale the image
+ * at all in that dimension. Negative values for `width` and `height` are
  * allowed since 2.8.
  *
- * Return value: A newly-created pixbuf with a reference count of 1, or %NULL 
- * if any of several error conditions occurred:  the file could not be opened,
- * there was no loader for the file's format, there was not enough memory to
- * allocate the image buffer, or the image file contained invalid data.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.6
  **/
@@ -1458,12 +1464,12 @@ gdk_pixbuf_new_from_file_at_scale (const char *filename,
  * @filename: (type filename): Name of file to load, in the GLib file name encoding
  * @width: The width the image should have or -1 to not constrain the width
  * @height: The height the image should have or -1 to not constrain the height
- * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio
+ * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio
  * @error: Return location for an error
  *
  * Same as gdk_pixbuf_new_from_file_at_scale().
  *
- * Return value: A newly-created pixbuf with a reference count of 1, or %NULL
+ * Return value: A newly-created pixbuf with a reference count of 1, or `NULL`
  * if any of several error conditions occurred:  the file could not be opened,
  * there was no loader for the file's format, there was not enough memory to
  * allocate the image buffer, or the image file contained invalid data.
@@ -1528,40 +1534,37 @@ load_from_stream (GdkPixbufLoader  *loader,
 
 
 /**
- * gdk_pixbuf_new_from_stream_at_scale:
- * @stream:  a #GInputStream to load the pixbuf from
+ * gdk_pixbuf_new_from_stream_at_scale: (constructor)
+ * @stream:  a `GInputStream` to load the pixbuf from
  * @width: The width the image should have or -1 to not constrain the width
  * @height: The height the image should have or -1 to not constrain the height
- * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
  * @error: Return location for an error
  *
  * Creates a new pixbuf by loading an image from an input stream.  
  *
- * The file format is detected automatically. If %NULL is returned, then 
+ * The file format is detected automatically. If `NULL` is returned, then
  * @error will be set. The @cancellable can be used to abort the operation
  * from another thread. If the operation was cancelled, the error 
- * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in 
- * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. 
+ * `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in
+ * the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains.
  *
  * The image will be scaled to fit in the requested size, optionally 
  * preserving the image's aspect ratio.
  *
- * When preserving the aspect ratio, a @width of -1 will cause the image to be
- * scaled to the exact given height, and a @height of -1 will cause the image
- * to be scaled to the exact given width. If both @width and @height are
+ * When preserving the aspect ratio, a `width` of -1 will cause the image to be
+ * scaled to the exact given height, and a `height` of -1 will cause the image
+ * to be scaled to the exact given width. If both `width` and `height` are
  * given, this function will behave as if the smaller of the two values
  * is passed as -1.
  *
- * When not preserving aspect ratio, a @width or @height of -1 means to not
+ * When not preserving aspect ratio, a `width` or `height` of -1 means to not
  * scale the image at all in that dimension.
  *
  * The stream is not closed.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error 
- * conditions occurred: the file could not be opened, the image format is 
- * not supported, there was not enough memory to allocate the image buffer, 
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.14
  */
@@ -1644,12 +1647,12 @@ out:
 
 /**
  * gdk_pixbuf_new_from_stream_at_scale_async:
- * @stream: a #GInputStream from which to load the pixbuf
+ * @stream: a `GInputStream` from which to load the pixbuf
  * @width: the width the image should have or -1 to not constrain the width
  * @height: the height the image should have or -1 to not constrain the height
- * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded
+ * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded
  * @user_data: the data to pass to the callback function
  *
  * Creates a new pixbuf by asynchronously loading an image from an input stream.
@@ -1705,25 +1708,25 @@ gdk_pixbuf_new_from_stream_at_scale_async (GInputStream        *stream,
 }
 
 /**
- * gdk_pixbuf_new_from_stream:
- * @stream:  a #GInputStream to load the pixbuf from
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * gdk_pixbuf_new_from_stream: (constructor)
+ * @stream:  a `GInputStream` to load the pixbuf from
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
  * @error: Return location for an error
  *
  * Creates a new pixbuf by loading an image from an input stream.  
  *
- * The file format is detected automatically. If %NULL is returned, then 
- * @error will be set. The @cancellable can be used to abort the operation
- * from another thread. If the operation was cancelled, the error 
- * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in 
- * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. 
+ * The file format is detected automatically.
+ *
+ * If `NULL` is returned, then `error` will be set.
+ *
+ * The `cancellable` can be used to abort the operation from another thread.
+ * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
+ * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
+ * `G_IO_ERROR` domains.
  *
  * The stream is not closed.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error 
- * conditions occurred: the file could not be opened, the image format is 
- * not supported, there was not enough memory to allocate the image buffer, 
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.14
  **/
@@ -1781,19 +1784,16 @@ G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 /**
- * gdk_pixbuf_new_from_resource:
+ * gdk_pixbuf_new_from_resource: (constructor)
  * @resource_path: the path of the resource file
  * @error: Return location for an error
  *
  * Creates a new pixbuf by loading an image from an resource.
  *
- * The file format is detected automatically. If %NULL is returned, then
+ * The file format is detected automatically. If `NULL` is returned, then
  * @error will be set.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.26
  **/
@@ -1818,16 +1818,16 @@ gdk_pixbuf_new_from_resource (const gchar  *resource_path,
 }
 
 /**
- * gdk_pixbuf_new_from_resource_at_scale:
+ * gdk_pixbuf_new_from_resource_at_scale: (constructor)
  * @resource_path: the path of the resource file
  * @width: The width the image should have or -1 to not constrain the width
  * @height: The height the image should have or -1 to not constrain the height
- * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio
+ * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio
  * @error: Return location for an error
  *
  * Creates a new pixbuf by loading an image from an resource.
  *
- * The file format is detected automatically. If %NULL is returned, then
+ * The file format is detected automatically. If `NULL` is returned, then
  * @error will be set.
  *
  * The image will be scaled to fit in the requested size, optionally
@@ -1839,10 +1839,7 @@ gdk_pixbuf_new_from_resource (const gchar  *resource_path,
  *
  * The stream is not closed.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.26
  */
@@ -1867,9 +1864,9 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path,
 
 /**
  * gdk_pixbuf_new_from_stream_async:
- * @stream: a #GInputStream from which to load the pixbuf
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded
+ * @stream: a `GInputStream` from which to load the pixbuf
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded
  * @user_data: the data to pass to the callback function
  *
  * Creates a new pixbuf by asynchronously loading an image from an input stream.
@@ -1878,7 +1875,8 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path,
  * version of this function.
  *
  * When the operation is finished, @callback will be called in the main thread.
- * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation.
+ * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of
+ * the operation.
  *
  * Since: 2.24
  **/
@@ -1908,14 +1906,13 @@ gdk_pixbuf_new_from_stream_async (GInputStream        *stream,
 
 /**
  * gdk_pixbuf_new_from_stream_finish:
- * @async_result: a #GAsyncResult
- * @error: a #GError, or %NULL
+ * @async_result: a `GAsyncResult`
+ * @error: a `GError`, or `NULL`
  *
  * Finishes an asynchronous pixbuf creation operation started with
  * gdk_pixbuf_new_from_stream_async().
  *
- * Return value: a #GdkPixbuf or %NULL on error. Free the returned
- * object with g_object_unref().
+ * Return value: (transfer full) (nullable): the newly created pixbuf
  *
  * Since: 2.24
  **/
@@ -1960,17 +1957,13 @@ info_cb (GdkPixbufLoader *loader,
 /**
  * gdk_pixbuf_get_file_info:
  * @filename: (type filename): The name of the file to identify.
- * @width: (optional) (out): Return location for the width of the
- *     image, or %NULL
- * @height: (optional) (out): Return location for the height of the
- *     image, or %NULL
+ * @width: (optional) (out): Return location for the width of the image
+ * @height: (optional) (out): Return location for the height of the image
  * 
  * Parses an image file far enough to determine its format and size.
  * 
- * Returns: (nullable) (transfer none): A #GdkPixbufFormat describing
- *    the image format of the file or %NULL if the image format wasn't
- *    recognized. The return value is owned by #GdkPixbuf and should
- *    not be freed.
+ * Returns: (nullable) (transfer none): A `GdkPixbufFormat` describing
+ *   the image format of the file
  *
  * Since: 2.4
  **/
@@ -2062,8 +2055,8 @@ get_file_info_thread (GTask                *task,
 /**
  * gdk_pixbuf_get_file_info_async:
  * @filename: (type filename): The name of the file to identify
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the file info is available
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @callback: a `GAsyncReadyCallback` to call when the file info is available
  * @user_data: the data to pass to the callback function
  *
  * Asynchronously parses an image file far enough to determine its
@@ -2104,18 +2097,16 @@ gdk_pixbuf_get_file_info_async  (const gchar          *filename,
 
 /**
  * gdk_pixbuf_get_file_info_finish:
- * @async_result: a #GAsyncResult
- * @width: (out): Return location for the width of the image, or %NULL
- * @height: (out): Return location for the height of the image, or %NULL
- * @error: a #GError, or %NULL
+ * @async_result: a `GAsyncResult`
+ * @width: (out): Return location for the width of the image, or `NULL`
+ * @height: (out): Return location for the height of the image, or `NULL`
+ * @error: a `GError`, or `NULL`
  *
  * Finishes an asynchronous pixbuf parsing operation started with
  * gdk_pixbuf_get_file_info_async().
  *
- * Returns: (transfer none): A #GdkPixbufFormat describing the image
- *    format of the file or %NULL if the image format wasn't
- *    recognized. The return value is owned by GdkPixbuf and should
- *    not be freed.
+ * Returns: (transfer none) (nullable): A `GdkPixbufFormat` describing the
+ *   image format of the file
  *
  * Since: 2.32
  **/
@@ -2151,10 +2142,12 @@ gdk_pixbuf_get_file_info_finish (GAsyncResult         *async_result,
  * gdk_pixbuf_new_from_xpm_data:
  * @data: (array zero-terminated=1): Pointer to inline XPM data.
  *
- * Creates a new pixbuf by parsing XPM data in memory.  This data is commonly
- * the result of including an XPM file into a program's C source.
+ * Creates a new pixbuf by parsing XPM data in memory.
  *
- * Return value: A newly-created pixbuf with a reference count of 1.
+ * This data is commonly the result of including an XPM file into a
+ * program's C source.
+ *
+ * Return value: A newly-created pixbuf
  **/
 GdkPixbuf *
 gdk_pixbuf_new_from_xpm_data (const char **data)
@@ -2415,18 +2408,18 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  
 /**
  * gdk_pixbuf_save:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @filename: (type filename): name of file to save.
  * @type: name of file format.
- * @error: (allow-none): return location for error, or %NULL
- * @...: list of key-value save options, followed by %NULL
+ * @error: (nullable): return location for error
+ * @...: list of key-value save options, followed by `NULL`
  *
  * Saves pixbuf to a file in format @type. By default, "jpeg", "png", "ico" 
  * and "bmp" are possible file formats to save in, but more formats may be
  * installed. The list of all writable formats can be determined in the 
  * following way:
  *
- * |[
+ * ```c
  * void add_if_writable (GdkPixbufFormat *data, GSList **list)
  * {
  *   if (gdk_pixbuf_format_is_writable (data))
@@ -2437,55 +2430,63 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  * GSList *writable_formats = NULL;
  * g_slist_foreach (formats, add_if_writable, &writable_formats);
  * g_slist_free (formats);
- * ]|
+ * ```
  *
- * If @error is set, %FALSE will be returned. Possible errors include 
- * those in the #GDK_PIXBUF_ERROR domain and those in the #G_FILE_ERROR domain.
+ * If `error` is set, `FALSE` will be returned. Possible errors include
+ * those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR`
+ * domain.
  *
- * The variable argument list should be %NULL-terminated; if not empty,
+ * The variable argument list should be `NULL`-terminated; if not empty,
  * it should contain pairs of strings that modify the save
  * parameters. For example:
- * |[
+ *
+ * ```c
  * gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL);
- * ]|
+ * ```
  *
- * Currently only few parameters exist. JPEG images can be saved with a
- * "quality" parameter; its value should be in the range [0,100]. JPEG
- * and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters
- * to the appropriate values in dots per inch.
+ * Currently only few parameters exist.
+ *
+ * JPEG images can be saved with a "quality" parameter; its value should be
+ * in the range `[0, 100]`. JPEG and PNG density can be set by setting the
+ * "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch.
  *
  * Text chunks can be attached to PNG images by specifying parameters of
  * the form "tEXt::key", where key is an ASCII string of length 1-79.
  * The values are UTF-8 encoded strings. The PNG compression level can
  * be specified using the "compression" parameter; it's value is in an
- * integer in the range of [0,9].
+ * integer in the range of `[0, 9]`.
  *
  * ICC color profiles can also be embedded into PNG, JPEG and TIFF images.
  * The "icc-profile" value should be the complete ICC profile encoded
  * into base64.
  *
- * |[
- * gchar *contents;
- * gchar *contents_encode;
+ * ```c
+ * char *contents;
  * gsize length;
- * g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL);
- * contents_encode = g_base64_encode ((const guchar *) contents, length);
+ *
+ * // icm_path is set elsewhere
+ * g_file_get_contents (icm_path, &contents, &length, NULL);
+ *
+ * char *contents_encode = g_base64_encode ((const guchar *) contents, length);
+ *
  * gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL);
- * ]|
+ * ```
+ *
+ * TIFF images recognize:
  *
- * TIFF images recognize: (1) a "bits-per-sample" option (integer) which
- * can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving
- * 8-bits per sample; (2) a "compression" option (integer) which can be
- * 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for
- * DEFLATE (see the libtiff documentation and tiff.h for all supported
- * codec values); (3) an "icc-profile" option (zero-terminated string)
- * containing a base64 encoded ICC color profile.
+ *  1. a "bits-per-sample" option (integer) which can be either 1 for saving
+ *     bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample
+ *  2. a "compression" option (integer) which can be 1 for no compression,
+ *     2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff
+ *     documentation and tiff.h for all supported codec values)
+ *  3. an "icc-profile" option (zero-terminated string) containing a base64
+ *     encoded ICC color profile.
  *
  * ICO images can be saved in depth 16, 24, or 32, by using the "depth"
  * parameter. When the ICO saver is given "x_hot" and "y_hot" parameters,
  * it produces a CUR instead of an ICO.
  *
- * Return value: whether an error was set
+ * Return value: `TRUE` on success, and `FALSE` otherwise
  **/
 gboolean
 gdk_pixbuf_save (GdkPixbuf  *pixbuf, 
@@ -2519,16 +2520,20 @@ gdk_pixbuf_save (GdkPixbuf  *pixbuf,
 
 /**
  * gdk_pixbuf_savev:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @filename: (type filename): name of file to save.
  * @type: name of file format.
- * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1): values for named options
- * @error: (allow-none): return location for error, or %NULL
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @error: (allow-none): return location for error, or `NULL`
+ *
+ * Vector version of `gdk_pixbuf_save()`.
  *
- * Saves pixbuf to a file in @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp".
- * If @error is set, %FALSE will be returned. 
- * See gdk_pixbuf_save () for more details.
+ * Saves pixbuf to a file in `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp".
+ *
+ * If @error is set, `FALSE` will be returned.
+ *
+ * See [method@GdkPixbuf.Pixbuf.save] for more details.
  *
  * Return value: whether an error was set
  **/
@@ -2600,12 +2605,12 @@ gdk_pixbuf_savev (GdkPixbuf  *pixbuf,
 
 /**
  * gdk_pixbuf_savev_utf8:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @filename: name of file to save.
  * @type: name of file format.
- * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1): values for named options
- * @error: (allow-none): return location for error, or %NULL
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @error: (allow-none): return location for error, or `NULL`
  *
  * Same as gdk_pixbuf_savev()
  *
@@ -2627,22 +2632,25 @@ gdk_pixbuf_savev_utf8 (GdkPixbuf  *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_callback:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @save_func: (scope call): a function that is called to save each block of data that
  *   the save routine generates.
  * @user_data: user data to pass to the save function.
  * @type: name of file format.
- * @error: (allow-none): return location for error, or %NULL
+ * @error: (allow-none): return location for error, or `NULL`
  * @...: list of key-value save options
  *
- * Saves pixbuf in format @type by feeding the produced data to a 
- * callback. Can be used when you want to store the image to something 
- * other than a file, such as an in-memory buffer or a socket.  
- * If @error is set, %FALSE will be returned. Possible errors
- * include those in the #GDK_PIXBUF_ERROR domain and whatever the save
+ * Saves pixbuf in format `type` by feeding the produced data to a
+ * callback.
+ *
+ * This function can be used when you want to store the image to something
+ * other than a file, such as an in-memory buffer or a socket.
+ *
+ * If @error is set, `FALSE` will be returned. Possible errors
+ * include those in the `GDK_PIXBUF_ERROR` domain and whatever the save
  * function generates.
  *
- * See gdk_pixbuf_save() for more details.
+ * See [method@GdkPixbuf.Pixbuf.save] for more details.
  *
  * Return value: whether an error was set
  *
@@ -2681,18 +2689,23 @@ gdk_pixbuf_save_to_callback    (GdkPixbuf  *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_callbackv:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @save_func: (scope call): a function that is called to save each block of data that
  *   the save routine generates.
  * @user_data: (closure): user data to pass to the save function.
  * @type: name of file format.
- * @option_keys: (array zero-terminated=1) (element-type utf8): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1) (element-type utf8): values for named options
- * @error: (allow-none): return location for error, or %NULL
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @error: (allow-none): return location for error, or `NULL`
+ *
+ * Vector version of `gdk_pixbuf_save_to_callback()`.
  *
  * Saves pixbuf to a callback in format @type, which is currently "jpeg",
- * "png", "tiff", "ico" or "bmp".  If @error is set, %FALSE will be returned. See
- * gdk_pixbuf_save_to_callback () for more details.
+ * "png", "tiff", "ico" or "bmp".
+ *
+ * If @error is set, `FALSE` will be returned.
+ *
+ * See [method@GdkPixbuf.Pixbuf.save_to_callback] for more details.
  *
  * Return value: whether an error was set
  *
@@ -2732,23 +2745,28 @@ gdk_pixbuf_save_to_callbackv   (GdkPixbuf  *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_buffer:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @buffer: (array length=buffer_size) (out) (element-type guint8): location to receive a pointer
  *   to the new buffer.
  * @buffer_size: location to receive the size of the new buffer.
  * @type: name of file format.
- * @error: (allow-none): return location for error, or %NULL
+ * @error: (allow-none): return location for error, or `NULL`
  * @...: list of key-value save options
  *
- * Saves pixbuf to a new buffer in format @type, which is currently "jpeg",
- * "png", "tiff", "ico" or "bmp".  This is a convenience function that uses
- * gdk_pixbuf_save_to_callback() to do the real work. Note that the buffer 
- * is not nul-terminated and may contain embedded  nuls.
- * If @error is set, %FALSE will be returned and @buffer will be set to
- * %NULL. Possible errors include those in the #GDK_PIXBUF_ERROR
+ * Saves pixbuf to a new buffer in format `type`, which is currently "jpeg",
+ * "png", "tiff", "ico" or "bmp".
+ *
+ * This is a convenience function that uses `gdk_pixbuf_save_to_callback()`
+ * to do the real work.
+ *
+ * Note that the buffer is not `NUL`-terminated and may contain embedded `NUL`
+ * characters.
+ *
+ * If @error is set, `FALSE` will be returned and @buffer will be set to
+ * `NULL`. Possible errors include those in the `GDK_PIXBUF_ERROR`
  * domain.
  *
- * See gdk_pixbuf_save() for more details.
+ * See `gdk_pixbuf_save()` for more details.
  *
  * Return value: whether an error was set
  *
@@ -2820,18 +2838,21 @@ save_to_buffer_callback (const gchar *data,
 
 /**
  * gdk_pixbuf_save_to_bufferv:
- * @pixbuf: a #GdkPixbuf.
+ * @pixbuf: a `GdkPixbuf`.
  * @buffer: (array length=buffer_size) (out) (element-type guint8):
  *   location to receive a pointer to the new buffer.
  * @buffer_size: location to receive the size of the new buffer.
  * @type: name of file format.
- * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1): values for named options
- * @error: (allow-none): return location for error, or %NULL
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @error: (allow-none): return location for error, or `NULL`
+ *
+ * Vector version of `gdk_pixbuf_save_to_buffer()`.
  *
  * Saves pixbuf to a new buffer in format @type, which is currently "jpeg",
- * "tiff", "png", "ico" or "bmp".  See gdk_pixbuf_save_to_buffer() 
- * for more details.
+ * "tiff", "png", "ico" or "bmp".
+ *
+ * See [method@GdkPixbuf.Pixbuf.save_to_buffer] for more details.
  *
  * Return value: whether an error was set
  *
@@ -2919,21 +2940,23 @@ save_to_stream (const gchar  *buffer,
 
 /**
  * gdk_pixbuf_save_to_streamv:
- * @pixbuf: a #GdkPixbuf
- * @stream: a #GOutputStream to save the pixbuf to
+ * @pixbuf: a `GdkPixbuf`
+ * @stream: a `GOutputStream` to save the pixbuf to
  * @type: name of file format
- * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1): values for named options
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: (allow-none): return location for error, or %NULL
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @cancellable: (nullable): optional `GCancellable` object, `NULL` to ignore
+ * @error: return location for error
  *
- * Saves @pixbuf to an output stream.
+ * Saves `pixbuf` to an output stream.
  *
  * Supported file formats are currently "jpeg", "tiff", "png", "ico" or
- * "bmp". See gdk_pixbuf_save_to_stream() for more details.
+ * "bmp".
  *
- * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an
- *     error was set.
+ * See [method@GdkPixbuf.Pixbuf.save_to_stream] for more details.
+ *
+ * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an
+ *   error was set.
  *
  * Since: 2.36
  */
@@ -2959,27 +2982,27 @@ gdk_pixbuf_save_to_streamv (GdkPixbuf      *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_stream:
- * @pixbuf: a #GdkPixbuf
- * @stream: a #GOutputStream to save the pixbuf to
+ * @pixbuf: a `GdkPixbuf`
+ * @stream: a `GOutputStream` to save the pixbuf to
  * @type: name of file format
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: (allow-none): return location for error, or %NULL
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @error: (allow-none): return location for error, or `NULL`
  * @...: list of key-value save options
  *
- * Saves @pixbuf to an output stream.
+ * Saves `pixbuf` to an output stream.
  *
  * Supported file formats are currently "jpeg", "tiff", "png", "ico" or 
- * "bmp". See gdk_pixbuf_save_to_buffer() for more details.
+ * "bmp". See `gdk_pixbuf_save_to_buffer()` for more details.
  *
- * The @cancellable can be used to abort the operation from another 
- * thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED 
- * will be returned. Other possible errors are in the #GDK_PIXBUF_ERROR 
- * and %G_IO_ERROR domains. 
+ * The `cancellable` can be used to abort the operation from another
+ * thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED`
+ * will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR`
+ * and `G_IO_ERROR` domains.
  *
- * The stream is not closed.
+ * The stream is not closed at the end of this call.
  *
- * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an
- *     error was set.
+ * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an
+ *   error was set.
  *
  * Since: 2.14
  */
@@ -3055,22 +3078,24 @@ save_to_stream_thread (GTask                 *task,
 
 /**
  * gdk_pixbuf_save_to_streamv_async:
- * @pixbuf: a #GdkPixbuf
- * @stream: a #GOutputStream to which to save the pixbuf
+ * @pixbuf: a `GdkPixbuf`
+ * @stream: a `GOutputStream` to which to save the pixbuf
  * @type: name of file format
- * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
- * @option_values: (array zero-terminated=1): values for named options
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved
+ * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set
+ * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved
  * @user_data: the data to pass to the callback function
  *
- * Saves @pixbuf to an output stream asynchronously.
+ * Saves `pixbuf` to an output stream asynchronously.
  *
  * For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous
  * version of this function.
  *
- * When the operation is finished, @callback will be called in the main thread.
- * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation.
+ * When the operation is finished, `callback` will be called in the main thread.
+ *
+ * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of
+ * the operation.
  *
  * Since: 2.36
  **/
@@ -3111,21 +3136,23 @@ gdk_pixbuf_save_to_streamv_async (GdkPixbuf           *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_stream_async:
- * @pixbuf: a #GdkPixbuf
- * @stream: a #GOutputStream to which to save the pixbuf
+ * @pixbuf: a `GdkPixbuf`
+ * @stream: a `GOutputStream` to which to save the pixbuf
  * @type: name of file format
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved
+ * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved
  * @user_data: the data to pass to the callback function
  * @...: list of key-value save options
  *
- * Saves @pixbuf to an output stream asynchronously.
+ * Saves `pixbuf` to an output stream asynchronously.
  *
  * For more details see gdk_pixbuf_save_to_stream(), which is the synchronous
  * version of this function.
  *
- * When the operation is finished, @callback will be called in the main thread.
- * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation.
+ * When the operation is finished, `callback` will be called in the main thread.
+ *
+ * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of
+ * the operation.
  *
  * Since: 2.24
  **/
@@ -3164,13 +3191,13 @@ gdk_pixbuf_save_to_stream_async (GdkPixbuf           *pixbuf,
 
 /**
  * gdk_pixbuf_save_to_stream_finish:
- * @async_result: a #GAsyncResult
- * @error: a #GError, or %NULL
+ * @async_result: a `GAsyncResult`
+ * @error: a `GError`, or `NULL`
  *
  * Finishes an asynchronous pixbuf save operation started with
  * gdk_pixbuf_save_to_stream_async().
  *
- * Return value: %TRUE if the pixbuf was saved successfully, %FALSE if an error was set.
+ * Return value: `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set.
  *
  * Since: 2.24
  **/
@@ -3196,7 +3223,7 @@ gdk_pixbuf_save_to_stream_finish (GAsyncResult  *async_result,
 
 /**
  * gdk_pixbuf_format_get_name:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
  * Returns the name of the format.
  * 
@@ -3214,7 +3241,7 @@ gdk_pixbuf_format_get_name (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_get_description:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
  * Returns a description of the format.
  * 
@@ -3240,12 +3267,11 @@ gdk_pixbuf_format_get_description (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_get_mime_types:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
  * Returns the mime types supported by the format.
  * 
- * Return value: (transfer full): a %NULL-terminated array of mime types which must be freed with 
- * g_strfreev() when it is no longer needed.
+ * Return value: (transfer full) (array zero-terminated=1): an array of mime types
  *
  * Since: 2.2
  */
@@ -3259,13 +3285,13 @@ gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_get_extensions:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
  * Returns the filename extensions typically used for files in the 
  * given format.
  * 
- * Return value: (transfer full): a %NULL-terminated array of filename extensions which must be
- * freed with g_strfreev() when it is no longer needed.
+ * Return value: (transfer full) (array zero-terminated=1): an array of
+ *   filename extensions
  *
  * Since: 2.2
  */
@@ -3279,7 +3305,7 @@ gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_is_writable:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
  * Returns whether pixbufs can be saved in the given format.
  * 
@@ -3297,12 +3323,13 @@ gdk_pixbuf_format_is_writable (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_is_scalable:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
+ *
+ * Returns whether this image format is scalable.
  *
- * Returns whether this image format is scalable. If a file is in a 
- * scalable format, it is preferable to load it at the desired size, 
- * rather than loading it at the default size and scaling the 
- * resulting pixbuf to the desired size.
+ * If a file is in a scalable format, it is preferable to load it at
+ * the desired size, rather than loading it at the default size and
+ * scaling the resulting pixbuf to the desired size.
  * 
  * Return value: whether this image format is scalable.
  *
@@ -3318,10 +3345,11 @@ gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_is_disabled:
- * @format: a #GdkPixbufFormat
+ * @format: a `GdkPixbufFormat`
  *
- * Returns whether this image format is disabled. See
- * gdk_pixbuf_format_set_disabled().
+ * Returns whether this image format is disabled.
+ *
+ * See gdk_pixbuf_format_set_disabled().
  * 
  * Return value: whether this image format is disabled.
  *
@@ -3337,13 +3365,16 @@ gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_set_disabled:
- * @format: a #GdkPixbufFormat
- * @disabled: %TRUE to disable the format @format
+ * @format: a `GdkPixbufFormat`
+ * @disabled: `TRUE` to disable the format @format
+ *
+ * Disables or enables an image format.
+ *
+ * If a format is disabled, GdkPixbuf won't use the image loader for
+ * this format to load images.
  *
- * Disables or enables an image format. If a format is disabled, 
- * gdk-pixbuf won't use the image loader for this format to load 
- * images. Applications can use this to avoid using image loaders 
- * with an inappropriate license, see gdk_pixbuf_format_get_license().
+ * Applications can use this to avoid using image loaders with an
+ * inappropriate license, see gdk_pixbuf_format_get_license().
  *
  * Since: 2.6
  */
@@ -3358,14 +3389,14 @@ gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format,
 
 /**
  * gdk_pixbuf_format_get_license:
- * @format: a #GdkPixbufFormat
+ * @format: a pixbuf format
  *
- * Returns information about the license of the image loader for the format. The
- * returned string should be a shorthand for a wellknown license, e.g. "LGPL",
- * "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license.  This
- * string should be freed with g_free() when it's no longer needed.
+ * Returns information about the license of the image loader for the format.
  *
- * Returns: a string describing the license of @format. 
+ * The returned string should be a shorthand for a well known license, e.g.
+ * "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license.
+ *
+ * Returns: (transfer full): a string describing the license of the pixbuf format
  *
  * Since: 2.6
  */
@@ -3392,9 +3423,7 @@ _gdk_pixbuf_get_format (GdkPixbufModule *module)
  * by GdkPixbuf.
  *
  * Returns: (transfer container) (element-type GdkPixbufFormat): A list of
- * #GdkPixbufFormats describing the supported image formats. The list should
- * be freed when it is no longer needed, but the structures themselves are
- * owned by #GdkPixbuf and should not be freed.
+ *   support image formats.
  *
  * Since: 2.2
  */
@@ -3415,11 +3444,11 @@ gdk_pixbuf_get_formats (void)
 
 /**
  * gdk_pixbuf_format_copy:
- * @format: a #GdkPixbufFormat
+ * @format: a pixbuf format
  *
- * Creates a copy of @format
+ * Creates a copy of `format`.
  *
- * Return value: the newly allocated copy of a #GdkPixbufFormat. Use
+ * Return value: the newly allocated copy of a `GdkPixbufFormat`. Use
  *   gdk_pixbuf_format_free() to free the resources when done
  *
  * Since: 2.22
@@ -3435,9 +3464,9 @@ gdk_pixbuf_format_copy (const GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_free:
- * @format: a #GdkPixbufFormat
+ * @format: a pixbuf format
  *
- * Frees the resources allocated when copying a #GdkPixbufFormat
+ * Frees the resources allocated when copying a `GdkPixbufFormat`
  * using gdk_pixbuf_format_copy()
  *
  * Since: 2.22
@@ -3451,14 +3480,15 @@ gdk_pixbuf_format_free (GdkPixbufFormat *format)
 
 /**
  * gdk_pixbuf_format_is_save_option_supported:
- * @format: a #GdkPixbufFormat
+ * @format: a pixbuf format
  * @option_key: the name of an option
  *
- * Returns %TRUE if the save option specified by @option_key is supported when
+ * Returns `TRUE` if the save option specified by @option_key is supported when
  * saving a pixbuf using the module implementing @format.
+ *
  * See gdk_pixbuf_save() for more information about option keys.
  *
- * Returns: %TRUE if the specified option is supported
+ * Returns: `TRUE` if the specified option is supported
  *
  * Since: 2.36
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-io.h b/gdk-pixbuf/gdk-pixbuf-io.h
index 89b0830e1..f8270f52c 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.h
+++ b/gdk-pixbuf/gdk-pixbuf-io.h
@@ -173,34 +173,37 @@ typedef void (* GdkPixbufModuleUpdatedFunc)  (GdkPixbuf *pixbuf,
  * @mask: mask containing bytes which modify how the prefix is matched against
  *  test data
  * @relevance: relevance of this pattern
+ *
+ * The signature prefix for a module.
  * 
  * The signature of a module is a set of prefixes. Prefixes are encoded as
  * pairs of ordinary strings, where the second string, called the mask, if 
- * not %NULL, must be of the same length as the first one and may contain 
+ * not `NULL`, must be of the same length as the first one and may contain
  * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, 
- * not matched, "don't-care"-bytes, zeros and non-zeros. 
+ * not matched, "don't-care"-bytes, zeros and non-zeros, respectively.
+ *
  * Each prefix has an associated integer that describes the relevance of 
  * the prefix, with 0 meaning a mismatch and 100 a "perfect match".
  * 
  * Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*', 
  * indicating an unanchored pattern that matches not only at the beginning, 
  * but also in the middle. Versions prior to 2.8 will interpret the '*'
- * like an 'x'. 
+ * like an 'x'.
  * 
  * The signature of a module is stored as an array of 
- * #GdkPixbufModulePatterns. The array is terminated by a pattern
- * where the @prefix is %NULL.
- * 
+ * `GdkPixbufModulePatterns`. The array is terminated by a pattern
+ * where the `prefix` is `NULL`.
  * 
- * <informalexample><programlisting>
+ * ```c
  * GdkPixbufModulePattern *signature[] = {
  *   { "abcdx", " !x z", 100 },
  *   { "bla", NULL,  90 },
  *   { NULL, NULL, 0 }
  * };
- * </programlisting>
- * The example matches e.g. "auud\0" with relevance 100, and "blau" with 
- * relevance 90.</informalexample>
+ * ```
+ *
+ * In the example above, the signature matches e.g. "auud\0" with
+ * relevance 100, and "blau" with relevance 90.
  * 
  * Since: 2.2
  */
@@ -211,31 +214,6 @@ struct _GdkPixbufModulePattern {
 	int relevance;
 };
 
-/**
- * GdkPixbufModule:
- * @module_name: the name of the module, usually the same as the
- *  usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
- * @module_path: the path from which the module is loaded.
- * @module: the loaded #GModule.
- * @info: a #GdkPixbufFormat holding information about the module.
- * @load: loads an image from a file.
- * @load_xpm_data: loads an image from data in memory.
- * @begin_load: begins an incremental load.
- * @stop_load: stops an incremental load.
- * @load_increment: continues an incremental load.
- * @load_animation: loads an animation from a file.
- * @save: saves a #GdkPixbuf to a file.
- * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
- * @is_save_option_supported: returns whether a save option key is supported by the module
- * 
- * A #GdkPixbufModule contains the necessary functions to load and save 
- * images in a certain file format. 
- * 
- * A #GdkPixbufModule can be loaded dynamically from a #GModule.
- * Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function 
- * named <function>fill_vtable</function>, which will get called when the module
- * is loaded and must set the function pointers of the #GdkPixbufModule. 
- */
 typedef struct _GdkPixbufModule GdkPixbufModule;
 struct _GdkPixbufModule {
 	char *module_name;
@@ -332,21 +310,23 @@ typedef enum /*< skip >*/
 
 /**
  * GdkPixbufFormat:
- * @name: the name of the image format.
- * @signature: the signature of the module.
- * @domain: the message domain for the @description.
- * @description: a description of the image format.
- * @mime_types: a %NULL-terminated array of MIME types for the image format.
- * @extensions: a %NULL-terminated array of typical filename extensions for the
- *  image format.
- * @flags: a combination of #GdkPixbufFormatFlags.
- * @disabled: a boolean determining whether the loader is disabled.
+ * @name: the name of the image format
+ * @signature: the signature of the module
+ * @domain: the message domain for the `description`
+ * @description: a description of the image format
+ * @mime_types: (array zero-terminated=1): the MIME types for the image format
+ * @extensions: (array zero-terminated=1): typical filename extensions for the
+ *   image format
+ * @flags: a combination of `GdkPixbufFormatFlags`
+ * @disabled: a boolean determining whether the loader is disabled`
  * @license: a string containing license information, typically set to 
- *  shorthands like "GPL", "LGPL", etc.
+ *   shorthands like "GPL", "LGPL", etc.
  * 
- * A #GdkPixbufFormat contains information about the image format accepted by a
- * module. Only modules should access the fields directly, applications should
- * use the <function>gdk_pixbuf_format_*</function> functions.
+ * A `GdkPixbufFormat` contains information about the image format accepted
+ * by a module.
+ *
+ * Only modules should access the fields directly, applications should
+ * use the `gdk_pixbuf_format_*` family of functions.
  * 
  * Since: 2.2
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 81c5afb75..51202b6f1 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -32,52 +32,53 @@
 #include "gdk-pixbuf-marshal.h"
 
 /**
- * SECTION:gdk-pixbuf-loader
- * @Short_description: Application-driven progressive image loading.
- * @Title: GdkPixbufLoader
- * @See_also: gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file()
+ * GdkPixbufLoader:
+ *
+ * Incremental image loader.
  * 
- * #GdkPixbufLoader provides a way for applications to drive the
+ * `GdkPixbufLoader` provides a way for applications to drive the
  * process of loading an image, by letting them send the image data
  * directly to the loader instead of having the loader read the data
- * from a file.  Applications can use this functionality instead of
- * gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() 
- * when they need to parse image data in
- * small chunks.  For example, it should be used when reading an
- * image from a (potentially) slow network connection, or when
- * loading an extremely large file.
- * 
- * 
- * To use #GdkPixbufLoader to load an image, just create a new one, and
- * call gdk_pixbuf_loader_write() to send the data to it.  When done,
- * gdk_pixbuf_loader_close() should be called to end the stream and
- * finalize everything. The loader will emit three important signals
- * throughout the process. The first, #GdkPixbufLoader::size-prepared,
- * will be emitted as soon as the image has enough information to
- * determine the size of the image to be used. If you want to scale
- * the image while loading it, you can call gdk_pixbuf_loader_set_size()
- * in response to this signal.
- * 
- * 
- * The second signal, #GdkPixbufLoader::area-prepared, will be emitted as
- * soon as the pixbuf of the desired has been allocated. You can obtain it
- * by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply
- * ref it. You can also call gdk_pixbuf_loader_get_pixbuf() later and get
- * the same pixbuf.
- * 
- * The last signal, #GdkPixbufLoader::area-updated, gets emitted every time
- * a region is updated. This way you can update a partially completed image.
- * Note that you do not know anything about the completeness of an image
- * from the updated area. For example, in an interlaced image, you need to
- * make several passes before the image is done loading.
+ * from a file. Applications can use this functionality instead of
+ * `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()`
+ * when they need to parse image data in small chunks. For example,
+ * it should be used when reading an image from a (potentially) slow
+ * network connection, or when loading an extremely large file.
+ *
+ * To use `GdkPixbufLoader` to load an image, create a new instance,
+ * and call [method@GdkPixbuf.PixbufLoader.write] to send the data
+ * to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be
+ * called to end the stream and finalize everything.
+ *
+ * The loader will emit three important signals throughout the process:
+ *
+ *  - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as
+ *    soon as the image has enough information to determine the size of
+ *    the image to be used. If you want to scale the image while loading
+ *    it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in
+ *    response to this signal.
+ *  - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as
+ *    soon as the pixbuf of the desired has been allocated. You can obtain
+ *    the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf].
+ *    If you want to use it, simply acquire a reference to it. You can
+ *    also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
+ *    pixbuf.
+ *  - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every
+ *    time a region is updated. This way you can update a partially
+ *    completed image. Note that you do not know anything about the
+ *    completeness of an image from the updated area. For example, in an
+ *    interlaced image you will need to make several passes before the
+ *    image is done loading.
  * 
- * # Loading an animation 
+ * ## Loading an animation
  *
- * Loading an animation is almost as easy as loading an image. Once the first
- * #GdkPixbufLoader::area-prepared signal has been emitted, you can call
- * gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct
- * and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for
- * displaying it. 
+ * Loading an animation is almost as easy as loading an image. Once the
+ * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+ * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to
+ * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call
+ * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a
+ * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the
+ * desired time stamp.
  */
 
 
@@ -133,9 +134,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          *
          * This signal is emitted when the pixbuf loader has been fed the
          * initial amount of data that is required to figure out the size
-         * of the image that it will create.  Applications can call  
-         * gdk_pixbuf_loader_set_size() in response to this signal to set
-         * the desired size to which the image should be scaled.
+         * of the image that it will create.
+         *
+         * Applications can call gdk_pixbuf_loader_set_size() in response
+         * to this signal to set the desired size to which the image
+         * should be scaled.
          */
         pixbuf_loader_signals[SIZE_PREPARED] =
                 g_signal_new ("size-prepared",
@@ -153,9 +156,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @loader: the object which received the signal.
          *
          * This signal is emitted when the pixbuf loader has allocated the 
-         * pixbuf in the desired size.  After this signal is emitted, 
-         * applications can call gdk_pixbuf_loader_get_pixbuf() to fetch 
-         * the partially-loaded pixbuf.
+         * pixbuf in the desired size.
+         *
+         * After this signal is emitted, applications can call
+         * gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
+         * pixbuf.
          */
         pixbuf_loader_signals[AREA_PREPARED] =
                 g_signal_new ("area-prepared",
@@ -175,9 +180,12 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @height: Height of updated area.
          *
          * This signal is emitted when a significant area of the image being
-         * loaded has been updated.  Normally it means that a complete
-         * scanline has been read in, but it could be a different area as
-         * well.  Applications can use this signal to know when to repaint
+         * loaded has been updated.
+         *
+         * Normally it means that a complete scanline has been read in, but
+         * it could be a different area as well.
+         *
+         * Applications can use this signal to know when to repaint
          * areas of an image that is being loaded.
          */
         pixbuf_loader_signals[AREA_UPDATED] =
@@ -198,6 +206,7 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @loader: the object which received the signal.
          *
          * This signal is emitted when gdk_pixbuf_loader_close() is called.
+         *
          * It can be used by different parts of an application to receive
          * notification when an image loader is closed by the code that
          * drives it.
@@ -254,9 +263,10 @@ gdk_pixbuf_loader_finalize (GObject *object)
  * @width: The desired width of the image being loaded.
  * @height: The desired height of the image being loaded.
  *
- * Causes the image to be scaled while it is loaded. The desired
- * image size can be determined relative to the original size of
- * the image by calling gdk_pixbuf_loader_set_size() from a
+ * Causes the image to be scaled while it is loaded.
+ *
+ * The desired image size can be determined relative to the original
+ * size of the image by calling gdk_pixbuf_loader_set_size() from a
  * signal handler for the ::size-prepared signal.
  *
  * Attempts to set the desired image size  are ignored after the 
@@ -500,15 +510,10 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader,
  * @count: Length of the @buf buffer in bytes.
  * @error: return location for errors
  *
- * This will cause a pixbuf loader to parse the next @count bytes of
- * an image.  It will return %TRUE if the data was loaded successfully,
- * and %FALSE if an error occurred.  In the latter case, the loader
- * will be closed, and will not accept further writes. If %FALSE is
- * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR
- * or #G_FILE_ERROR domains.
+ * Parses the next `count` bytes in the given image buffer.
  *
- * Return value: %TRUE if the write was successful, or %FALSE if the loader
- * cannot parse the buffer.
+ * Return value: `TRUE` if the write was successful, or
+ *   `FALSE` if the loader cannot parse the buffer
  **/
 gboolean
 gdk_pixbuf_loader_write (GdkPixbufLoader *loader,
@@ -562,20 +567,13 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader,
 /**
  * gdk_pixbuf_loader_write_bytes:
  * @loader: A pixbuf loader.
- * @buffer: The image data as a #GBytes
+ * @buffer: The image data as a `GBytes` buffer.
  * @error: return location for errors
  *
- * This will cause a pixbuf loader to parse a buffer inside a #GBytes
- * for an image.  It will return %TRUE if the data was loaded successfully,
- * and %FALSE if an error occurred.  In the latter case, the loader
- * will be closed, and will not accept further writes. If %FALSE is
- * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR
- * or #G_FILE_ERROR domains.
- *
- * See also: gdk_pixbuf_loader_write()
+ * Parses the next contents of the given image buffer.
  *
- * Return value: %TRUE if the write was successful, or %FALSE if the loader
- * cannot parse the buffer.
+ * Return value: `TRUE` if the write was successful, or `FALSE` if
+ *   the loader cannot parse the buffer
  *
  * Since: 2.30
  */
@@ -611,14 +609,16 @@ gdk_pixbuf_loader_new (void)
 /**
  * gdk_pixbuf_loader_new_with_type:
  * @image_type: name of the image format to be loaded with the image
- * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
  * image data as if it were an image of type @image_type, instead of
- * identifying the type automatically. Useful if you want an error if
- * the image isn't the expected type, for loading image formats
- * that can't be reliably identified by looking at the data, or if
- * the user manually forces a specific type.
+ * identifying the type automatically.
+ *
+ * This function is useful if you want an error if the image isn't the
+ * expected type; for loading image formats that can't be reliably
+ * identified by looking at the data; or if the user manually forces
+ * a specific type.
  *
  * The list of supported image formats depends on what image loaders
  * are installed, but typically "png", "jpeg", "gif", "tiff" and 
@@ -654,14 +654,16 @@ gdk_pixbuf_loader_new_with_type (const char *image_type,
 /**
  * gdk_pixbuf_loader_new_with_mime_type:
  * @mime_type: the mime type to be loaded 
- * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
- * image data as if it were an image of mime type @mime_type, instead of
- * identifying the type automatically. Useful if you want an error if
- * the image isn't the expected mime type, for loading image formats
- * that can't be reliably identified by looking at the data, or if
- * the user manually forces a specific mime type.
+ * image data as if it were an image of MIME type @mime_type, instead of
+ * identifying the type automatically.
+ *
+ * This function is useful if you want an error if the image isn't the
+ * expected MIME type; for loading image formats that can't be reliably
+ * identified by looking at the data; or if the user manually forces a
+ * specific MIME type.
  *
  * The list of supported mime types depends on what image loaders
  * are installed, but typically "image/png", "image/jpeg", "image/gif", 
@@ -671,6 +673,7 @@ gdk_pixbuf_loader_new_with_type (const char *image_type,
  * structs returned by gdk_pixbuf_get_formats().
  *
  * Return value: A newly-created pixbuf loader.
+ *
  * Since: 2.4
  **/
 GdkPixbufLoader *
@@ -736,19 +739,23 @@ _gdk_pixbuf_loader_new_with_filename (const char *filename)
  * @loader: A pixbuf loader.
  *
  * Queries the #GdkPixbuf that a pixbuf loader is currently creating.
+ *
  * In general it only makes sense to call this function after the
- * "area-prepared" signal has been emitted by the loader; this means
- * that enough data has been read to know the size of the image that
- * will be allocated.  If the loader has not received enough data via
- * gdk_pixbuf_loader_write(), then this function returns %NULL.  The
- * returned pixbuf will be the same in all future calls to the loader,
- * so simply calling g_object_ref() should be sufficient to continue
- * using it.  Additionally, if the loader is an animation, it will
- * return the "static image" of the animation
- * (see gdk_pixbuf_animation_get_static_image()).
+ * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+ * emitted by the loader; this means that enough data has been read
+ * to know the size of the image that will be allocated.
+ *
+ * If the loader has not received enough data via gdk_pixbuf_loader_write(),
+ * then this function returns `NULL`.
+ *
+ * The returned pixbuf will be the same in all future calls to the loader,
+ * so if you want to keep using it, you should acquire a reference to it.
+ *
+ * Additionally, if the loader is an animation, it will return the "static
+ * image" of the animation (see gdk_pixbuf_animation_get_static_image()).
  * 
- * Return value: (transfer none): The #GdkPixbuf that the loader is creating, or %NULL if not
- * enough data has been read to determine how to create the image buffer.
+ * Return value: (transfer none) (nullable): The pixbuf that the loader is
+ *   creating
  **/
 GdkPixbuf *
 gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
@@ -770,14 +777,17 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
  * @loader: A pixbuf loader
  *
  * Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
- * In general it only makes sense to call this function after the "area-prepared"
- * signal has been emitted by the loader. If the loader doesn't have enough
- * bytes yet (hasn't emitted the "area-prepared" signal) this function will 
- * return %NULL.
- *
- * Return value: (transfer none): The #GdkPixbufAnimation that the loader is loading, or %NULL if
- * not enough data has been read to determine the information.
-**/
+ *
+ * In general it only makes sense to call this function after the
+ * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by
+ * the loader.
+ *
+ * If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared`
+ * signal, this function will return `NULL`.
+ *
+ * Return value: (transfer none) (nullable): The animation that the loader is
+ *   currently loading
+ */
 GdkPixbufAnimation *
 gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader)
 {
@@ -793,24 +803,27 @@ gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader)
 /**
  * gdk_pixbuf_loader_close:
  * @loader: A pixbuf loader.
- * @error: (allow-none): return location for a #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for a #GError, or `NULL` to ignore errors
  *
  * Informs a pixbuf loader that no further writes with
  * gdk_pixbuf_loader_write() will occur, so that it can free its
- * internal loading structures. Also, tries to parse any data that
- * hasn't yet been parsed; if the remaining data is partial or
- * corrupt, an error will be returned.  If %FALSE is returned, @error
- * will be set to an error from the #GDK_PIXBUF_ERROR or #G_FILE_ERROR
- * domains. If you're just cancelling a load rather than expecting it
- * to be finished, passing %NULL for @error to ignore it is
- * reasonable.
- *
- * Remember that this does not unref the loader, so if you plan not to
- * use it anymore, please g_object_unref() it.
- *
- * Returns: %TRUE if all image data written so far was successfully
-            passed out via the update_area signal
- **/
+ * internal loading structures.
+ *
+ * This function also tries to parse any data that hasn't yet been parsed;
+ * if the remaining data is partial or corrupt, an error will be returned.
+ *
+ * If `FALSE` is returned, `error` will be set to an error from the
+ * `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains.
+ *
+ * If you're just cancelling a load rather than expecting it to be finished,
+ * passing `NULL` for `error` to ignore it is reasonable.
+ *
+ * Remember that this function does not release a reference on the loader, so
+ * you will need to explicitly release any reference you hold.
+ *
+ * Returns: `TRUE` if all image data written so far was successfully
+ *   passed out via the update_area signal
+ */
 gboolean
 gdk_pixbuf_loader_close (GdkPixbufLoader *loader,
                          GError         **error)
@@ -882,9 +895,7 @@ gdk_pixbuf_loader_close (GdkPixbufLoader *loader,
  * Obtains the available information about the format of the 
  * currently loading image file.
  *
- * Returns: (nullable) (transfer none): A #GdkPixbufFormat or
- * %NULL. The return value is owned by GdkPixbuf and should not be
- * freed.
+ * Returns: (nullable) (transfer none): A #GdkPixbufFormat
  * 
  * Since: 2.2
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.h b/gdk-pixbuf/gdk-pixbuf-loader.h
index 83648205f..1cc34136b 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.h
+++ b/gdk-pixbuf/gdk-pixbuf-loader.h
@@ -43,18 +43,12 @@ G_BEGIN_DECLS
 #define GDK_IS_PIXBUF_LOADER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GDK_TYPE_PIXBUF_LOADER))
 #define GDK_PIXBUF_LOADER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GDK_TYPE_PIXBUF_LOADER, GdkPixbufLoaderClass))
 
-/**
- * GdkPixbufLoader:
- * 
- * The GdkPixbufLoader struct contains only private
- * fields. 
- */
 typedef struct _GdkPixbufLoader GdkPixbufLoader;
 struct _GdkPixbufLoader
 {
+  /*< private >*/
   GObject parent_instance;
   
-  /*< private >*/
   gpointer priv;
 };
 
diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c
index 84e8e10c3..82dfad77b 100644
--- a/gdk-pixbuf/gdk-pixbuf-scale.c
+++ b/gdk-pixbuf/gdk-pixbuf-scale.c
@@ -26,49 +26,6 @@
 #include "pixops/pixops.h"
 
 /**
- * SECTION:scaling
- * @Short_description: Scaling pixbufs and scaling and alpha blending pixbufs
- * @Title: Scaling
- * 
- * The GdkPixBuf contains functions to scale pixbufs, to scale
- * pixbufs and alpha blend against an existing image, and to scale
- * pixbufs and alpha blend against a solid color or checkerboard.
- * Alpha blending a checkerboard is a common way to show an image with
- * an alpha channel in image-viewing and editing software.
- * 
- * Note that in these functions, the terms ‘alpha blending’ and ‘compositing’
- * are used synonymously.
- * 
- * Since the full-featured functions (gdk_pixbuf_scale(),
- * gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
- * rather complex to use and have many arguments, two simple
- * convenience functions are provided, gdk_pixbuf_scale_simple() and
- * gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
- * given size, scale an original image to fit, and then return the
- * new pixbuf.
- * 
- * If the destination pixbuf was created from a readonly source, these
- * operations will force a copy into a mutable buffer.
- * 
- * Scaling and alpha blending functions take advantage of MMX hardware
- * acceleration on systems where MMX is supported.  If gdk-pixbuf is built
- * with the Sun mediaLib library, these functions are instead accelerated
- * using mediaLib, which provides hardware acceleration on Intel, AMD,
- * and Sparc chipsets.  If desired, mediaLib support can be turned off by
- * setting the `GDK_DISABLE_MEDIALIB` environment variable.  
- * 
- * The alpha blending function used is:
- *
- * |[<!-- language="plain" -->
- * Cd = Cs·As + Cd(1-As)
- * ]|
- *
- * where `Cd` is the destination pixel color, `Cs` is the source pixel color,
- * and `As` is the source pixel alpha.
- */
-
-
-/**
  * gdk_pixbuf_scale:
  * @src: a #GdkPixbuf
  * @dest: the #GdkPixbuf into which to render the results
@@ -88,8 +45,8 @@
  * @dest_height) of the resulting image onto the destination image
  * replacing the previous contents.
  *
- * Try to use gdk_pixbuf_scale_simple() first, this function is
- * the industrial-strength power tool you can fall back to if
+ * Try to use gdk_pixbuf_scale_simple() first; this function is
+ * the industrial-strength power tool you can fall back to, if
  * gdk_pixbuf_scale_simple() isn't powerful enough.
  *
  * If the source rectangle overlaps the destination rectangle on the
@@ -148,6 +105,7 @@ gdk_pixbuf_scale (const GdkPixbuf *src,
  * 
  * Creates a transformation of the source image @src by scaling by
  * @scale_x and @scale_y then translating by @offset_x and @offset_y.
+ *
  * This gives an image in the coordinates of the destination pixbuf.
  * The rectangle (@dest_x, @dest_y, @dest_width, @dest_height)
  * is then alpha blended onto the corresponding rectangle of the
@@ -229,7 +187,6 @@ gdk_pixbuf_composite (const GdkPixbuf *src,
  *
  * See gdk_pixbuf_composite_color_simple() for a simpler variant of this
  * function suitable for many tasks.
- * 
  **/
 void
 gdk_pixbuf_composite_color (const GdkPixbuf *src,
@@ -283,24 +240,26 @@ gdk_pixbuf_composite_color (const GdkPixbuf *src,
  * @dest_height: the height of destination image
  * @interp_type: the interpolation type for the transformation.
  *
- * Create a new #GdkPixbuf containing a copy of @src scaled to
- * @dest_width x @dest_height. Leaves @src unaffected.  @interp_type
- * should be #GDK_INTERP_NEAREST if you want maximum speed (but when
- * scaling down #GDK_INTERP_NEAREST is usually unusably ugly).  The
- * default @interp_type should be #GDK_INTERP_BILINEAR which offers
- * reasonable quality and speed.
+ * Create a new pixbuf containing a copy of `src` scaled to
+ * `dest_width` x `dest_height`.
+ *
+ * This function leaves `src` unaffected.
+ *
+ * The `interp_type` should be `GDK_INTERP_NEAREST` if you want maximum
+ * speed (but when scaling down `GDK_INTERP_NEAREST` is usually unusably
+ * ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which
+ * offers reasonable quality and speed.
  *
- * You can scale a sub-portion of @src by creating a sub-pixbuf
- * pointing into @src; see gdk_pixbuf_new_subpixbuf().
+ * You can scale a sub-portion of `src` by creating a sub-pixbuf
+ * pointing into `src`; see [method@GdkPixbuf.Pixbuf.new_subpixbuf].
  *
- * If @dest_width and @dest_height are equal to the @src width and height, a
- * copy of @src is returned, avoiding any scaling.
+ * If `dest_width` and `dest_height` are equal to the width and height of
+ * `src`, this function will return an unscaled copy of `src`.
  *
- * For more complicated scaling/alpha blending see gdk_pixbuf_scale()
- * and gdk_pixbuf_composite().
+ * For more complicated scaling/alpha blending see [method@GdkPixbuf.Pixbuf.scale]
+ * and [method@GdkPixbuf.Pixbuf.composite].
  * 
- * Return value: (nullable) (transfer full): the new #GdkPixbuf, or %NULL if not enough memory could be
- * allocated for it.
+ * Return value: (nullable) (transfer full): the new pixbuf
  **/
 GdkPixbuf *
 gdk_pixbuf_scale_simple (const GdkPixbuf *src,
@@ -341,12 +300,11 @@ gdk_pixbuf_scale_simple (const GdkPixbuf *src,
  * @color1: the color of check at upper left
  * @color2: the color of the other check
  *
- * Creates a new #GdkPixbuf by scaling @src to @dest_width x
- * @dest_height and alpha blending the result with a checkboard of colors
- * @color1 and @color2.
+ * Creates a new pixbuf by scaling `src` to `dest_width` x `dest_height`
+ * and alpha blending the result with a checkboard of colors `color1`
+ * and `color2`.
  * 
- * Return value: (nullable) (transfer full): the new #GdkPixbuf, or %NULL if not enough memory could be
- * allocated for it.
+ * Return value: (nullable) (transfer full): the new pixbuf
  **/
 GdkPixbuf *
 gdk_pixbuf_composite_color_simple (const GdkPixbuf *src,
@@ -387,10 +345,9 @@ gdk_pixbuf_composite_color_simple (const GdkPixbuf *src,
  * Rotates a pixbuf by a multiple of 90 degrees, and returns the
  * result in a new pixbuf.
  *
- * If @angle is 0, a copy of @src is returned, avoiding any rotation.
+ * If `angle` is 0, this function will return a copy of `src`.
  *
- * Returns: (nullable) (transfer full): the new #GdkPixbuf, or %NULL
- * if not enough memory could be allocated for it.
+ * Returns: (nullable) (transfer full): the new pixbuf
  *
  * Since: 2.6
  */
@@ -489,13 +446,12 @@ gdk_pixbuf_rotate_simple (const GdkPixbuf   *src,
 /**
  * gdk_pixbuf_flip:
  * @src: a #GdkPixbuf
- * @horizontal: %TRUE to flip horizontally, %FALSE to flip vertically
+ * @horizontal: `TRUE` to flip horizontally, `FALSE` to flip vertically
  *
  * Flips a pixbuf horizontally or vertically and returns the
  * result in a new pixbuf.
  *
- * Returns: (nullable) (transfer full): the new #GdkPixbuf, or %NULL
- * if not enough memory could be allocated for it.
+ * Returns: (nullable) (transfer full): the new pixbuf
  *
  * Since: 2.6
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-transform.h b/gdk-pixbuf/gdk-pixbuf-transform.h
index 24e5ad5ae..2ba28c49f 100644
--- a/gdk-pixbuf/gdk-pixbuf-transform.h
+++ b/gdk-pixbuf/gdk-pixbuf-transform.h
@@ -59,12 +59,13 @@ G_BEGIN_DECLS
  *  **Deprecated**: this interpolation filter is deprecated, as in reality
  *  it has a lower quality than the @GDK_INTERP_BILINEAR filter
  *  (Since: 2.38)
- * 
- * This enumeration describes the different interpolation modes that
- * can be used with the scaling functions. @GDK_INTERP_NEAREST is
- * the fastest scaling method, but has horrible quality when
- * scaling down. @GDK_INTERP_BILINEAR is the best choice if you
- * aren't sure what to choose, it has a good speed/quality balance.
+ *
+ * Interpolation modes for scaling functions.
+ *
+ * The `GDK_INTERP_NEAREST` mode is the fastest scaling method, but has
+ * horrible quality when scaling down; `GDK_INTERP_BILINEAR` is the best
+ * choice if you aren't sure what to choose, it has a good speed/quality
+ * balance.
  * 
  * **Note**: Cubic filtering is missing from the list; hyperbolic
  * interpolation is just as fast and results in higher quality.
@@ -84,6 +85,7 @@ typedef enum {
  * @GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees.
  * 
  * The possible rotations which can be passed to gdk_pixbuf_rotate_simple().
+ *
  * To make them easier to use, their numerical values are the actual degrees.
  */
 typedef enum {
diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c
index db1562b76..0e80299f5 100644
--- a/gdk-pixbuf/gdk-pixbuf-util.c
+++ b/gdk-pixbuf/gdk-pixbuf-util.c
@@ -27,41 +27,35 @@
 #include "gdk-pixbuf-private.h"
 
 /**
- * SECTION:util
- * @Short_description: Utility and miscellaneous convenience functions.
- * @Title: Utilities
- * @See_also: #GdkPixbuf
- * 
- * These functions provide miscellaneous utilities for manipulating
- * pixbufs.  The pixel data in pixbufs may of course be manipulated
- * directly by applications, but several common operations can be
- * performed by these functions instead.
- */
-
-
-/**
  * gdk_pixbuf_add_alpha:
  * @pixbuf: A #GdkPixbuf.
- * @substitute_color: Whether to set a color to zero opacity.  If this
- * is %FALSE, then the (@r, @g, @b) arguments will be ignored.
+ * @substitute_color: Whether to set a color to zero opacity.
  * @r: Red value to substitute.
  * @g: Green value to substitute.
  * @b: Blue value to substitute.
  *
  * Takes an existing pixbuf and adds an alpha channel to it.
+ *
  * If the existing pixbuf already had an alpha channel, the channel
  * values are copied from the original; otherwise, the alpha channel
  * is initialized to 255 (full opacity).
  * 
- * If @substitute_color is %TRUE, then the color specified by (@r, @g, @b) will be
- * assigned zero opacity. That is, if you pass (255, 255, 255) for the
- * substitute color, all white pixels will become fully transparent.
+ * If `substitute_color` is `TRUE`, then the color specified by the
+ * (`r`, `g`, `b`) arguments will be assigned zero opacity. That is,
+ * if you pass `(255, 255, 255)` for the substitute color, all white
+ * pixels will become fully transparent.
+ *
+ * If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments
+ * will be ignored.
  *
- * Return value: (transfer full): A newly-created pixbuf with a reference count of 1.
+ * Return value: (transfer full): A newly-created pixbuf
  **/
 GdkPixbuf *
 gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf,
-		      gboolean substitute_color, guchar r, guchar g, guchar b)
+                      gboolean substitute_color,
+                      guchar r,
+                      guchar g,
+                      guchar b)
 {
 	GdkPixbuf *new_pixbuf;
 	int x, y;
@@ -135,8 +129,9 @@ gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf,
  * @dest_x: X coordinate within @dest_pixbuf.
  * @dest_y: Y coordinate within @dest_pixbuf.
  *
- * Copies a rectangular area from @src_pixbuf to @dest_pixbuf.  Conversion of
- * pixbuf formats is done automatically.
+ * Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`.
+ *
+ * Conversion of pixbuf formats is done automatically.
  *
  * If the source rectangle overlaps the destination rectangle on the
  * same pixbuf, it will be overwritten during the copy operation.
@@ -181,21 +176,27 @@ gdk_pixbuf_copy_area (const GdkPixbuf *src_pixbuf,
  * @saturation: saturation factor
  * @pixelate: whether to pixelate
  *
- * Modifies saturation and optionally pixelates @src, placing the result in
- * @dest. @src and @dest may be the same pixbuf with no ill effects.  If
- * @saturation is 1.0 then saturation is not changed. If it's less than 1.0,
- * saturation is reduced (the image turns toward grayscale); if greater than
- * 1.0, saturation is increased (the image gets more vivid colors). If @pixelate
- * is %TRUE, then pixels are faded in a checkerboard pattern to create a
- * pixelated image. @src and @dest must have the same image format, size, and
+ * Modifies saturation and optionally pixelates `src`, placing the result in
+ * `dest`.
+ *
+ * The `src` and `dest` pixbufs must have the same image format, size, and
  * rowstride.
+ *
+ * The `src` and `dest` arguments may be the same pixbuf with no ill effects.
+ *
+ * If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0,
+ * saturation is reduced (the image turns toward grayscale); if greater than
+ * 1.0, saturation is increased (the image gets more vivid colors).
+ *
+ * If `pixelate` is `TRUE`, then pixels are faded in a checkerboard pattern to
+ * create a pixelated image.
  * 
  **/
 void
-gdk_pixbuf_saturate_and_pixelate(const GdkPixbuf *src,
-                                 GdkPixbuf *dest,
-                                 gfloat saturation,
-                                 gboolean pixelate)
+gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src,
+                                  GdkPixbuf *dest,
+                                  gfloat saturation,
+                                  gboolean pixelate)
 {
         /* NOTE that src and dest MAY be the same pixbuf! */
   
@@ -271,20 +272,20 @@ gdk_pixbuf_saturate_and_pixelate(const GdkPixbuf *src,
 
 /**
  * gdk_pixbuf_apply_embedded_orientation:
- * @src: A #GdkPixbuf.
+ * @src: a pixbuf with an orientation option
  *
  * Takes an existing pixbuf and checks for the presence of an
- * associated "orientation" option, which may be provided by the 
- * jpeg loader (which reads the exif orientation tag) or the 
- * tiff loader (which reads the tiff orientation tag, and
- * compensates it for the partial transforms performed by 
- * libtiff). If an orientation option/tag is present, the
- * appropriate transform will be performed so that the pixbuf
- * is oriented correctly.
+ * associated "orientation" option.
+ *
+ * The orientation option may be provided by the JPEG loader (which
+ * reads the exif orientation tag) or the TIFF loader (which reads
+ * the TIFF orientation tag, and compensates it for the partial
+ * transforms performed by libtiff).
+ *
+ * If an orientation option/tag is present, the appropriate transform
+ * will be performed so that the pixbuf is oriented correctly.
  *
- * Return value: (transfer full): A newly-created pixbuf, %NULL if
- * not enough memory could be allocated for it, or a reference to the
- * input pixbuf (with an increased reference count).
+ * Return value: (transfer full) (nullable): A newly-created pixbuf
  *
  * Since: 2.12
  **/
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index 2594b99e9..01b53f088 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -21,152 +21,162 @@
  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "config.h"
-
-#include <math.h>
-#include <stdlib.h>
-#include <string.h>
-
-#define GDK_PIXBUF_C_COMPILATION
-#include "gdk-pixbuf-private.h"
-#include "gdk-pixbuf-features.h"
-#include "gdk-pixbuf-enum-types.h"
-
-/* Include the marshallers */
-#include <glib-object.h>
-#include <gio/gio.h>
-#include "gdk-pixbuf-marshal.h"
-
 /**
- * SECTION:creating
- * @Short_description: Creating a pixbuf from image data that is already in memory.
- * @Title: Image Data in Memory
- * @See_also: gdk_pixbuf_finalize().
+ * GdkPixbuf:
+ *
+ * A pixel buffer.
+ *
+ * `GdkPixbuf` contains information about an image's pixel data,
+ * its color space, bits per sample, width and height, and the
+ * rowstride (the number of bytes between the start of one row
+ * and the start of the next).
+ *
+ * ## Creating new `GdkPixbuf`
  * 
  * The most basic way to create a pixbuf is to wrap an existing pixel
- * buffer with a #GdkPixbuf structure.  You can use the
- * gdk_pixbuf_new_from_data() function to do this You need to specify
- * the destroy notification function that will be called when the
- * data buffer needs to be freed; this will happen when a #GdkPixbuf
- * is finalized by the reference counting functions If you have a
- * chunk of static data compiled into your application, you can pass
- * in %NULL as the destroy notification function so that the data
- * will not be freed.
+ * buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the
+ * [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this.
  * 
- * The gdk_pixbuf_new() function can be used as a convenience to
- * create a pixbuf with an empty buffer.  This is equivalent to
- * allocating a data buffer using malloc() and then wrapping it with
- * gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will
- * compute an optimal rowstride so that rendering can be performed
- * with an efficient algorithm.
+ * Every time you create a new `GdkPixbuf` instance for some data, you
+ * will need to specify the destroy notification function that will be
+ * called when the data buffer needs to be freed; this will happen when
+ * a `GdkPixbuf` is finalized by the reference counting functions. If
+ * you have a chunk of static data compiled into your application, you
+ * can pass in `NULL` as the destroy notification function so that the
+ * data will not be freed.
  * 
- * As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+ * The [`ctor@GdkPixbuf.Pixbuf.new`] constructor function can be used
+ * as a convenience to create a pixbuf with an empty buffer; this is
+ * equivalent to allocating a data buffer using `malloc()` and then
+ * wrapping it with `gdk_pixbuf_new_from_data()`. The `gdk_pixbuf_new()`
+ * function will compute an optimal rowstride so that rendering can be
+ * performed with an efficient algorithm.
+ *
+ * As a special case, you can use the [`ctor@GdkPixbuf.Pixbuf.new_from_xpm_data`]
  * function to create a pixbuf from inline XPM image data.
  * 
- * You can also copy an existing pixbuf with the gdk_pixbuf_copy()
- * function.  This is not the same as just doing a g_object_ref()
- * on the old pixbuf; the copy function will actually duplicate the
- * pixel data in memory and create a new #GdkPixbuf structure for it.
- */
-
-/**
- * SECTION:refcounting
- * @Short_description: Functions for reference counting and memory management on pixbufs.
- * @Title: Reference Counting and Memory Mangement
- * @See_also: #GdkPixbuf, gdk_pixbuf_new_from_data().
+ * You can also copy an existing pixbuf with the [method@Pixbuf.copy]
+ * function. This is not the same as just acquiring a reference to
+ * the old pixbuf instance: the copy function will actually duplicate
+ * the pixel data in memory and create a new [class@Pixbuf] instance
+ * for it.
+ *
+ * ## Reference counting
  * 
- * #GdkPixbuf structures are reference counted.  This means that an
+ * `GdkPixbuf` structures are reference counted. This means that an
  * application can share a single pixbuf among many parts of the
- * code.  When a piece of the program needs to keep a pointer to a
- * pixbuf, it should add a reference to it by calling g_object_ref().
- * When it no longer needs the pixbuf, it should subtract a reference
- * by calling g_object_unref().  The pixbuf will be destroyed when
- * its reference count drops to zero.  Newly-created #GdkPixbuf
- * structures start with a reference count of one.
- * 
- * > As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and
- * > gdk_pixbuf_unref() are deprecated in favour of g_object_ref()
- * > and g_object_unref() resp.
- * 
- * Finalizing a pixbuf means to free its pixel data and to free the
- * #GdkPixbuf structure itself.  Most of the library functions that
- * create #GdkPixbuf structures create the pixel data by themselves
- * and define the way it should be freed; you do not need to worry
- * about those.
- *
- * To provide preallocated pixel data, use
- * gdk_pixbuf_new_from_bytes().  The gdk_pixbuf_new_from_data() API is
- * an older variant that predates the existence of #GBytes.
- */
-
-/**
- * SECTION:gdk-pixbuf
- * @Short_description: Information that describes an image.
- * @Title: The GdkPixbuf Structure
+ * code. When a piece of the program needs to use a pixbuf, it should
+ * acquire a reference to it by calling `g_object_ref()`; when it no
+ * longer needs the pixbuf, it should release the reference it acquired
+ * by calling `g_object_unref()`. The resources associated with a
+ * `GdkPixbuf` will be freed when its reference count drops to zero.
+ * Newly-created `GdkPixbuf` instances start with a reference count
+ * of one.
  *
- * The #GdkPixbuf structure contains
- * information that describes an image in memory.
+ * ## Image Data
  *
- * ## Image Data ## {#image-data}
+ * Image data in a pixbuf is stored in memory in an uncompressed,
+ * packed format. Rows in the image are stored top to bottom, and
+ * in each row pixels are stored from left to right.
  *
- * Image data in a pixbuf is stored in memory in uncompressed,
- * packed format.  Rows in the image are stored top to bottom, and
- * in each row pixels are stored from left to right.  There may be
- * padding at the end of a row.  The "rowstride" value of a pixbuf,
- * as returned by gdk_pixbuf_get_rowstride(), indicates the number
- * of bytes between rows.
+ * There may be padding at the end of a row.
  *
- * ## put_pixel() Example ## {#put-pixel}
+ * The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`],
+ * indicates the number of bytes between rows.
  *
- * The following code illustrates a simple put_pixel()
+ * **NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the
+ * last row in the pixbuf may not be as wide as the full rowstride, but rather
+ * just as wide as the pixel data needs to be; that is: it is unsafe to do
+ * `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use
+ * [method@GdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the
+ * last row as:
+ *
+ * ```c
+ * last_row = width * ((n_channels * bits_per_sample + 7) / 8);
+ * ```
+ *
+ * The same rule applies when iterating over each row of a `GdkPixbuf` pixels
+ * array.
+ *
+ * The following code illustrates a simple `put_pixel()`
  * function for RGB pixbufs with 8 bits per channel with an alpha
- * channel.  It is not included in the gdk-pixbuf library for
- * performance reasons; rather than making several function calls
- * for each pixel, your own code can take shortcuts.
+ * channel.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
- * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
+ * put_pixel (GdkPixbuf *pixbuf,
+ *            int x,
+ * 	   int y,
+ * 	   guchar red,
+ * 	   guchar green,
+ * 	   guchar blue,
+ * 	   guchar alpha)
  * {
- *   int width, height, rowstride, n_channels;
- *   guchar *pixels, *p;
- *
- *   n_channels = gdk_pixbuf_get_n_channels (pixbuf);
+ *   int n_channels = gdk_pixbuf_get_n_channels (pixbuf);
  *
+ *   // Ensure that the pixbuf is valid
  *   g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
  *   g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
  *   g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
  *   g_assert (n_channels == 4);
  *
- *   width = gdk_pixbuf_get_width (pixbuf);
- *   height = gdk_pixbuf_get_height (pixbuf);
+ *   int width = gdk_pixbuf_get_width (pixbuf);
+ *   int height = gdk_pixbuf_get_height (pixbuf);
  *
+ *   // Ensure that the coordinates are in a valid range
  *   g_assert (x >= 0 && x < width);
  *   g_assert (y >= 0 && y < height);
  *
- *   rowstride = gdk_pixbuf_get_rowstride (pixbuf);
- *   pixels = gdk_pixbuf_get_pixels (pixbuf);
+ *   int rowstride = gdk_pixbuf_get_rowstride (pixbuf);
  *
- *   p = pixels + y * rowstride + x * n_channels;
+ *   // The pixel buffer in the GdkPixbuf instance
+ *   guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);
+ *
+ *   // The pixel we wish to modify
+ *   guchar *p = pixels + y * rowstride + x * n_channels;
  *   p[0] = red;
  *   p[1] = green;
  *   p[2] = blue;
  *   p[3] = alpha;
  * }
- * ]|
- *
- * This function will not work for pixbufs with images that are
- * other than 8 bits per sample or channel, but it will work for
- * most of the pixbufs that GTK+ uses.
- *
- * If you are doing memcpy() of raw pixbuf data, note that the last row
- * in the pixbuf may not be as wide as the full rowstride, but rather
- * just as wide as the pixel data needs to be. That is, it is unsafe to
- * do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf.
- * Use gdk_pixbuf_copy() instead, or compute the width in bytes of the
- * last row as `width * ((n_channels * bits_per_sample + 7) / 8)`.
+ * ```
+ *
+ * ## Loading images
+ *
+ * The `GdkPixBuf` class provides a simple mechanism for loading
+ * an image from a file in synchronous and asynchronous fashion.
+ *
+ * For GUI applications, it is recommended to use the asynchronous
+ * stream API to avoid blocking the control flow of the application.
+ *
+ * Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`]
+ * API for progressive image loading.
+ *
+ * ## Saving images
+ *
+ * The `GdkPixbuf` class provides methods for saving image data in
+ * a number of file formats. The formatted data can be written to a
+ * file or to a memory buffer. `GdkPixbuf` can also call a user-defined
+ * callback on the data, which allows to e.g. write the image
+ * to a socket or store it in a database.
  */
 
+#include "config.h"
+
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define GDK_PIXBUF_C_COMPILATION
+#include "gdk-pixbuf-private.h"
+#include "gdk-pixbuf-features.h"
+#include "gdk-pixbuf-enum-types.h"
+
+/* Include the marshallers */
+#include <glib-object.h>
+#include <gio/gio.h>
+#include "gdk-pixbuf-marshal.h"
+
 static void gdk_pixbuf_finalize     (GObject        *object);
 static void gdk_pixbuf_set_property (GObject        *object,
 				     guint           prop_id,
@@ -228,7 +238,8 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
         /**
          * GdkPixbuf:n-channels:
          *
-         * The number of samples per pixel. 
+         * The number of samples per pixel.
+         *
          * Currently, only 3 or 4 samples per pixel are supported.
          */
         g_object_class_install_property (object_class,
@@ -240,7 +251,13 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                            G_MAXINT,
                                                            3,
                                                            PIXBUF_PARAM_FLAGS));
-
+        /**
+         * GdkPixbuf:colorspace:
+         *
+         * The color space of the pixbuf.
+         *
+         * Currently, only `GDK_COLORSPACE_RGB` is supported.
+         */
         g_object_class_install_property (object_class,
                                          PROP_COLORSPACE,
                                          g_param_spec_enum ("colorspace",
@@ -249,7 +266,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                             GDK_TYPE_COLORSPACE,
                                                             GDK_COLORSPACE_RGB,
                                                             PIXBUF_PARAM_FLAGS));
-
+        /**
+         * GdkPixbuf:has-alpha:
+         *
+         * Whether the pixbuf has an alpha channel.
+         */
         g_object_class_install_property (object_class,
                                          PROP_HAS_ALPHA,
                                          g_param_spec_boolean ("has-alpha",
@@ -257,11 +278,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                                _("Whether the pixbuf has an alpha channel"),
                                                                FALSE,
                                                                PIXBUF_PARAM_FLAGS));
-
         /**
          * GdkPixbuf:bits-per-sample:
          *
          * The number of bits per sample. 
+         *
          * Currently only 8 bit per sample are supported.
          */
         g_object_class_install_property (object_class,
@@ -273,7 +294,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                            16,
                                                            8,
                                                            PIXBUF_PARAM_FLAGS));
-
+        /**
+         * GdkPixbuf:width:
+         *
+         * The number of columns of the pixbuf.
+         */
         g_object_class_install_property (object_class,
                                          PROP_WIDTH,
                                          g_param_spec_int ("width",
@@ -283,7 +308,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                            G_MAXINT,
                                                            1,
                                                            PIXBUF_PARAM_FLAGS));
-
+        /**
+         * GdkPixbuf:height:
+         *
+         * The number of rows of the pixbuf.
+         */
         g_object_class_install_property (object_class,
                                          PROP_HEIGHT,
                                          g_param_spec_int ("height",
@@ -293,13 +322,14 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                            G_MAXINT,
                                                            1,
                                                            PIXBUF_PARAM_FLAGS));
-
         /**
          * GdkPixbuf:rowstride:
          *
          * The number of bytes between the start of a row and 
-         * the start of the next row. This number must (obviously)
-         * be at least as large as the width of the pixbuf.
+         * the start of the next row.
+         *
+         * This number must (obviously) be at least as large as the
+         * width of the pixbuf.
          */
         g_object_class_install_property (object_class,
                                          PROP_ROWSTRIDE,
@@ -310,18 +340,22 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass)
                                                            G_MAXINT,
                                                            1,
                                                            PIXBUF_PARAM_FLAGS));
-
+        /**
+         * GdkPixbuf:pixels:
+         *
+         * A pointer to the pixel data of the pixbuf.
+         */
         g_object_class_install_property (object_class,
                                          PROP_PIXELS,
                                          g_param_spec_pointer ("pixels",
                                                                _("Pixels"),
                                                                _("A pointer to the pixel data of the pixbuf"),
                                                                PIXBUF_PARAM_FLAGS));
-
         /**
          * GdkPixbuf::pixel-bytes:
          *
          * If set, this pixbuf was created from read-only #GBytes.
+         *
          * Replaces GdkPixbuf::pixels.
          * 
          * Since: 2.32
@@ -529,8 +563,10 @@ free_buffer (guchar *pixels, gpointer data)
  * @height: Height of image in pixels, must be > 0
  *
  * Calculates the rowstride that an image created with those values would
- * have. This is useful for front-ends and backends that want to sanity
- * check image values without needing to create them.
+ * have.
+ *
+ * This function is useful for front-ends and backends that want to check
+ * image values without needing to create a `GdkPixbuf`.
  *
  * Return value: the rowstride for the given values, or -1 in case of error.
  *
@@ -568,12 +604,14 @@ gdk_pixbuf_calculate_rowstride (GdkColorspace colorspace,
  * @width: Width of image in pixels, must be > 0
  * @height: Height of image in pixels, must be > 0
  *
- * Creates a new #GdkPixbuf structure and allocates a buffer for it.  The 
- * buffer has an optimal rowstride.  Note that the buffer is not cleared;
+ * Creates a new `GdkPixbuf` structure and allocates a buffer for it.
+ *
+ * If the allocation of the buffer failed, this function will return `NULL`.
+ *
+ * The buffer has an optimal rowstride. Note that the buffer is not cleared;
  * you will have to fill it completely yourself.
  *
- * Return value: (nullable): A newly-created #GdkPixbuf with a reference count of 1, or
- * %NULL if not enough memory could be allocated for the image buffer.
+ * Return value: (transfer full) (nullable): A newly-created pixel buffer
  **/
 GdkPixbuf *
 gdk_pixbuf_new (GdkColorspace colorspace, 
@@ -606,12 +644,13 @@ gdk_pixbuf_new (GdkColorspace colorspace,
  * gdk_pixbuf_copy:
  * @pixbuf: A pixbuf.
  * 
- * Creates a new #GdkPixbuf with a copy of the information in the specified
- * @pixbuf. Note that this does not copy the options set on the original #GdkPixbuf,
+ * Creates a new `GdkPixbuf` with a copy of the information in the specified
+ * `pixbuf`.
+ *
+ * Note that this does not copy the options set on the original `GdkPixbuf`,
  * use gdk_pixbuf_copy_options() for this.
  * 
- * Return value: (nullable) (transfer full): A newly-created pixbuf with a reference count of 1, or %NULL if
- * not enough memory could be allocated.
+ * Return value: (nullable) (transfer full): A newly-created pixbuf
  **/
 GdkPixbuf *
 gdk_pixbuf_copy (const GdkPixbuf *pixbuf)
@@ -645,19 +684,20 @@ gdk_pixbuf_copy (const GdkPixbuf *pixbuf)
 
 /**
  * gdk_pixbuf_new_subpixbuf:
- * @src_pixbuf: a #GdkPixbuf
+ * @src_pixbuf: a `GdkPixbuf`
  * @src_x: X coord in @src_pixbuf
  * @src_y: Y coord in @src_pixbuf
  * @width: width of region in @src_pixbuf
  * @height: height of region in @src_pixbuf
  * 
- * Creates a new pixbuf which represents a sub-region of @src_pixbuf.
+ * Creates a new pixbuf which represents a sub-region of `src_pixbuf`.
+ *
  * The new pixbuf shares its pixels with the original pixbuf, so
  * writing to one affects both.  The new pixbuf holds a reference to
- * @src_pixbuf, so @src_pixbuf will not be finalized until the new
+ * `src_pixbuf`, so `src_pixbuf` will not be finalized until the new
  * pixbuf is finalized.
  *
- * Note that if @src_pixbuf is read-only, this function will force it
+ * Note that if `src_pixbuf` is read-only, this function will force it
  * to be mutable.
  *
  * Return value: (transfer full): a new pixbuf 
@@ -742,7 +782,7 @@ gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf)
  *
  * Queries whether a pixbuf has an alpha channel (opacity information).
  *
- * Return value: %TRUE if it has an alpha channel, %FALSE otherwise.
+ * Return value: `TRUE` if it has an alpha channel, `FALSE` otherwise.
  **/
 gboolean
 gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf)
@@ -774,12 +814,13 @@ gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf)
  *
  * Queries a pointer to the pixel data of a pixbuf.
  *
- * Return value: (array): A pointer to the pixbuf's pixel data.
- * Please see the section on [image data][image-data] for information
- * about how the pixel data is stored in memory.
- *
  * This function will cause an implicit copy of the pixbuf data if the
  * pixbuf was created from read-only data.
+ *
+ * Please see the section on [image data](#image-data) for information
+ * about how the pixel data is stored in memory.
+ *
+ * Return value: (array): A pointer to the pixbuf's pixel data.
  **/
 guchar *
 gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf)
@@ -820,13 +861,15 @@ downgrade_to_pixels (const GdkPixbuf *pixbuf)
  *
  * Queries a pointer to the pixel data of a pixbuf.
  *
- * Return value: (array length=length): A pointer to the pixbuf's
- * pixel data.  Please see the section on [image data][image-data]
- * for information about how the pixel data is stored in memory.
- *
  * This function will cause an implicit copy of the pixbuf data if the
  * pixbuf was created from read-only data.
  *
+ * Please see the section on [image data](#image-data) for information
+ * about how the pixel data is stored in memory.
+ *
+ * Return value: (array length=length): A pointer to the pixbuf's
+ * pixel data.
+ *
  * Since: 2.26
  */
 guchar *
@@ -848,10 +891,10 @@ gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf,
  * gdk_pixbuf_read_pixels:
  * @pixbuf: A pixbuf
  *
- * Provides a read-only pointer to the raw pixel data; must not be
- * modified.  This function allows skipping the implicit copy that
- * must be made if gdk_pixbuf_get_pixels() is called on a read-only
- * pixbuf.
+ * Provides a read-only pointer to the raw pixel data.
+ *
+ * This function allows skipping the implicit copy that must be made
+ * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf.
  *
  * Returns: a read-only pointer to the raw pixel data
  *
@@ -883,9 +926,10 @@ gdk_pixbuf_read_pixels (const GdkPixbuf  *pixbuf)
  * @pixbuf: A pixbuf
  *
  * Provides a #GBytes buffer containing the raw pixel data; the data
- * must not be modified.  This function allows skipping the implicit
- * copy that must be made if gdk_pixbuf_get_pixels() is called on a
- * read-only pixbuf.
+ * must not be modified.
+ *
+ * This function allows skipping the implicit copy that must be made
+ * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf.
  *
  * Returns: (transfer full): A new reference to a read-only copy of
  *   the pixel data.  Note that for mutable pixbufs, this function will
@@ -998,15 +1042,16 @@ gdk_pixbuf_error_quark (void)
 
 /**
  * gdk_pixbuf_fill:
- * @pixbuf: a #GdkPixbuf
- * @pixel: RGBA pixel to clear to
- *         (0xffffffff is opaque white, 0x00000000 transparent black)
+ * @pixbuf: a `GdkPixbuf`
+ * @pixel: RGBA pixel to used to clear (`0xffffffff` is opaque white,
+ *   `0x00000000` transparent black)
  *
  * Clears a pixbuf to the given RGBA value, converting the RGBA value into
- * the pixbuf's pixel format. The alpha will be ignored if the pixbuf
- * doesn't have an alpha channel.
- * 
- **/
+ * the pixbuf's pixel format.
+ *
+ * The alpha component will be ignored if the pixbuf doesn't have an alpha
+ * channel.
+ */
 void
 gdk_pixbuf_fill (GdkPixbuf *pixbuf,
                  guint32    pixel)
@@ -1065,7 +1110,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf,
 
 /**
  * gdk_pixbuf_get_option:
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  * @key: a nul-terminated string.
  * 
  * Looks up @key in the list of options that may have been attached to the
@@ -1084,8 +1129,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf,
  * Since 2.36.6, the JPEG loader sets the "comment" option with the comment
  * EXIF tag.
  * 
- * Return value: the value associated with @key. This is a nul-terminated 
- * string that should not be freed or %NULL if @key was not found.
+ * Return value: (transfer none) (nullable): the value associated with `key`
  **/
 const gchar *
 gdk_pixbuf_get_option (GdkPixbuf   *pixbuf,
@@ -1111,15 +1155,14 @@ gdk_pixbuf_get_option (GdkPixbuf   *pixbuf,
 
 /**
  * gdk_pixbuf_get_options:
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  *
- * Returns a #GHashTable with a list of all the options that may have been
- * attached to the @pixbuf when it was loaded, or that may have been
- * attached by another function using gdk_pixbuf_set_option().
+ * Returns a `GHashTable` with a list of all the options that may have been
+ * attached to the `pixbuf` when it was loaded, or that may have been
+ * attached by another function using [method@GdkPixbuf.Pixbuf.set_option].
  *
- * See gdk_pixbuf_get_option() for more details.
- *
- * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable of key/values
+ * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable
+ *   of key/values pairs
  *
  * Since: 2.32
  **/
@@ -1147,12 +1190,12 @@ gdk_pixbuf_get_options (GdkPixbuf *pixbuf)
 
 /**
  * gdk_pixbuf_remove_option:
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  * @key: a nul-terminated string representing the key to remove.
  *
- * Remove the key/value pair option attached to a #GdkPixbuf.
+ * Removes the key/value pair option attached to a `GdkPixbuf`.
  *
- * Return value: %TRUE if an option was removed, %FALSE if not.
+ * Return value: `TRUE` if an option was removed, `FALSE` if not.
  *
  * Since: 2.36
  **/
@@ -1213,15 +1256,16 @@ gdk_pixbuf_remove_option (GdkPixbuf   *pixbuf,
 
 /**
  * gdk_pixbuf_set_option:
- * @pixbuf: a #GdkPixbuf
+ * @pixbuf: a `GdkPixbuf`
  * @key: a nul-terminated string.
  * @value: a nul-terminated string.
  * 
- * Attaches a key/value pair as an option to a #GdkPixbuf. If @key already
- * exists in the list of options attached to @pixbuf, the new value is 
- * ignored and %FALSE is returned.
+ * Attaches a key/value pair as an option to a `GdkPixbuf`.
+ *
+ * If `key` already exists in the list of options attached to the `pixbuf`,
+ * the new value is ignored and `FALSE` is returned.
  *
- * Return value: %TRUE on success.
+ * Return value: `TRUE` on success
  *
  * Since: 2.2
  **/
@@ -1266,15 +1310,17 @@ gdk_pixbuf_set_option (GdkPixbuf   *pixbuf,
 
 /**
  * gdk_pixbuf_copy_options:
- * @src_pixbuf: a #GdkPixbuf to copy options from
- * @dest_pixbuf: the #GdkPixbuf to copy options to
+ * @src_pixbuf: the source pixbuf
+ * @dest_pixbuf: the destination pixbuf
+ *
+ * Copies the key/value pair options attached to a `GdkPixbuf` to another
+ * `GdkPixbuf`.
  *
- * Copy the key/value pair options attached to a #GdkPixbuf to another.
  * This is useful to keep original metadata after having manipulated
  * a file. However be careful to remove metadata which you've already
  * applied, such as the "orientation" option after rotating the image.
  *
- * Return value: %TRUE on success.
+ * Return value: `TRUE` on success.
  *
  * Since: 2.36
  **/
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index df1036a9a..621167611 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -23,19 +23,32 @@
 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 
 /**
- * SECTION:inline
- * @Short_description: Functions for inlined pixbuf handling.
- * @Title: Inline data
+ * GdkPixdata:
+ * @magic: magic number. A valid `GdkPixdata` structure must have
+ *   `GDK_PIXBUF_MAGIC_NUMBER` here
+ * @length: less than 1 to disable length checks, otherwise
+ *   `GDK_PIXDATA_HEADER_LENGTH` plus the length of `pixel_data`
+ * @pixdata_type: information about colorspace, sample width and
+ *   encoding, in a `GdkPixdataType`
+ * @rowstride: Distance in bytes between rows
+ * @width: Width of the image in pixels
+ * @height: Height of the image in pixels
+ * @pixel_data: (array) (element-type guint8): `width` x `height`
+ *   pixels, encoded according to `pixdata_type` and `rowstride`
+ *
+ * A pixel buffer suitable for serialization and streaming.
  * 
- * Using #GdkPixdata, images can be compiled into an application,
+ * Using `GdkPixdata`, images can be compiled into an application,
  * making it unnecessary to refer to external image files at runtime.
- * GdkPixBuf includes a utility named gdk-pixbuf-csource, which
- * can be used to convert image files into #GdkPixdata structures suitable
- * for inclusion in C sources. To convert the #GdkPixdata structures back 
- * into #GdkPixbufs, use gdk_pixbuf_from_pixdata.
  *
- * #GdkPixdata should not be used any more. #GResource should be used to save
- * the original compressed images inside the program's binary.
+ * `GdkPixbuf` includes a utility named `gdk-pixbuf-csource`, which
+ * can be used to convert image files into `GdkPixdata` structures suitable
+ * for inclusion in C sources. To convert the `GdkPixdata` structures back
+ * into a `GdkPixbuf`, use `gdk_pixbuf_from_pixdata()`.
+ *
+ * Deprecated: 2.32: `GdkPixdata` should not be used any more. `GResource`
+ *   should be used to save the original compressed images inside the
+ *   program's binary
  */
 
 #define APPEND g_string_append_printf
@@ -189,20 +202,24 @@ get_uint32 (const guint8 *stream, guint *result)
  * @stream_length: length of the stream used for deserialization.
  * @stream: (array length=stream_length): stream of bytes containing a
  *   serialized #GdkPixdata structure.
- * @error: #GError location to indicate failures (maybe %NULL to ignore errors).
+ * @error: #GError location to indicate failures (maybe `NULL` to ignore errors).
  *
  * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream.
+ *
  * The byte stream consists of a straightforward writeout of the
- * #GdkPixdata fields in network byte order, plus the @pixel_data
+ * `GdkPixdata` fields in network byte order, plus the `pixel_data`
  * bytes the structure points to.
- * The @pixdata contents are reconstructed byte by byte and are checked
- * for validity. This function may fail with %GDK_PIXBUF_ERROR_CORRUPT_IMAGE
- * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE.
  *
- * Return value: Upon successful deserialization %TRUE is returned,
- * %FALSE otherwise.
+ * The `pixdata` contents are reconstructed byte by byte and are checked
+ * for validity.
  *
- * Deprecated: 2.32: Use #GResource instead.
+ * This function may fail with `GDK_PIXBUF_ERROR_CORRUPT_IMAGE`
+ * or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`.
+ *
+ * Return value: Upon successful deserialization `TRUE` is returned,
+ * `FALSE` otherwise.
+ *
+ * Deprecated: 2.32: Use `GResource` instead.
  **/
 gboolean
 gdk_pixdata_deserialize (GdkPixdata   *pixdata,
@@ -320,17 +337,18 @@ free_buffer (guchar *pixels, gpointer data)
 
 /**
  * gdk_pixdata_from_pixbuf: (skip)
- * @pixdata: a #GdkPixdata to fill.
- * @pixbuf: the data to fill @pixdata with.
+ * @pixdata: a `GdkPixdata` to fill.
+ * @pixbuf: the data to fill `pixdata` with.
  * @use_rle: whether to use run-length encoding for the pixel data.
  *
- * Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the
- * pixel data is run-length encoded into newly-allocated memory and a 
- * pointer to that memory is returned. 
+ * Converts a `GdkPixbuf` to a `GdkPixdata`.
+ *
+ * If `use_rle` is `TRUE`, the pixel data is run-length encoded into
+ * newly-allocated memory and a pointer to that memory is returned. 
  *
- * Returns: (nullable): If @use_rle is %TRUE, a pointer to the
- *   newly-allocated memory for the run-length encoded pixel data,
- *   otherwise %NULL.
+ * Returns: (nullable) (array) (element-type guint8): If `use_rle` is
+ *   `TRUE`, a pointer to the newly-allocated memory for the run-length
+ *   encoded pixel data, otherwise `NULL`.
  *
  * Deprecated: 2.32: Use #GResource instead.
  **/
@@ -419,17 +437,20 @@ gdk_pixdata_from_pixbuf (GdkPixdata      *pixdata,
 
 /**
  * gdk_pixbuf_from_pixdata:
- * @pixdata: a #GdkPixdata to convert into a #GdkPixbuf.
+ * @pixdata: a #GdkPixdata to convert into a `GdkPixbuf`.
  * @copy_pixels: whether to copy raw pixel data; run-length encoded
- *     pixel data is always copied.
+ *   pixel data is always copied.
  * @error: location to store possible errors.
  * 
- * Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or
- * if the pixel data is run-length-encoded, the pixel data is copied into
- * newly-allocated memory; otherwise it is reused.
+ * Converts a `GdkPixdata` to a `GdkPixbuf`.
  *
- * Returns: (transfer full): a new #GdkPixbuf.
- * Deprecated: 2.32: Use #GResource instead.
+ * If `copy_pixels` is `TRUE` or if the pixel data is run-length-encoded,
+ * the pixel data is copied into newly-allocated memory; otherwise it is
+ * reused.
+ *
+ * Returns: (transfer full): a new pixbuf
+ *
+ * Deprecated: 2.32: Use `GResource` instead.
  **/
 GdkPixbuf*
 gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
@@ -689,20 +710,19 @@ save_rle_decoder (GString     *gstring,
 
 /**
  * gdk_pixdata_to_csource:
- * @pixdata: a #GdkPixdata to convert to C source.
- * @name: used for naming generated data structures or macros.
- * @dump_type: a #GdkPixdataDumpType determining the kind of C
- *   source to be generated.
+ * @pixdata: a `GdkPixdata` to convert to C source
+ * @name: used for naming generated data structures or macros
+ * @dump_type: the kind of C source to be generated
  *
  * Generates C source code suitable for compiling images directly 
  * into programs. 
  *
- * gdk-pixbuf ships with a program called
- * [gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command
- * line interface to this function.
+ * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which offers
+ * a command line interface to this function.
+ *
+ * Returns: (transfer full): a newly-allocated string buffer containing
+ *   the C source form of `pixdata`.
  *
- * Returns: a newly-allocated string containing the C source form
- *   of @pixdata.
  * Deprecated: 2.32: Use #GResource instead.
  **/
 GString*
@@ -930,49 +950,51 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
 
 /**
  * gdk_pixbuf_new_from_inline:
- * @data_length: Length in bytes of the @data argument or -1 to 
- *    disable length checks
+ * @data_length: Length in bytes of the `data` argument or -1 to 
+ *   disable length checks
  * @data: (array length=data_length): Byte data containing a
- *    serialized #GdkPixdata structure
+ *   serialized `GdkPixdata` structure
  * @copy_pixels: Whether to copy the pixel data, or use direct pointers
- *               @data for the resulting pixbuf
- * @error: #GError return location, may be %NULL to ignore errors
+ *   `data` for the resulting pixbuf
+ * @error: #GError return location, may be `NULL` to ignore errors
  *
- * Create a #GdkPixbuf from a flat representation that is suitable for
- * storing as inline data in a program. This is useful if you want to
- * ship a program with images, but don't want to depend on any
- * external files.
+ * Creates a `GdkPixbuf` from a flat representation that is suitable for
+ * storing as inline data in a program.
+ *
+ * This is useful if you want to ship a program with images, but don't want
+ * to depend on any external files.
+ *
+ * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which allows
+ * for conversion of `GdkPixbuf`s into such a inline representation.
  *
- * gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource],
- * which allows for conversion of #GdkPixbufs into such a inline representation.
  * In almost all cases, you should pass the `--raw` option to
  * `gdk-pixbuf-csource`. A sample invocation would be:
  *
- * |[
- *  gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
- * ]|
+ * ```
+ * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
+ * ```
  * 
  * For the typical case where the inline pixbuf is read-only static data,
  * you don't need to copy the pixel data unless you intend to write to
- * it, so you can pass %FALSE for @copy_pixels.  (If you pass `--rle` to
- * `gdk-pixbuf-csource`, a copy will be made even if @copy_pixels is %FALSE,
- * so using this option is generally a bad idea.)
+ * it, so you can pass `FALSE` for `copy_pixels`. If you pass `--rle` to
+ * `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`,
+ * so using this option is generally a bad idea.
  *
  * If you create a pixbuf from const inline data compiled into your
  * program, it's probably safe to ignore errors and disable length checks, 
  * since things will always succeed:
- * |[
+ *
+ * ```c
  * pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);
- * ]|
+ * ```
  *
  * For non-const inline data, you could get out of memory. For untrusted 
  * inline data located at runtime, you could have corrupt inline data in 
  * addition.
  *
- * Return value: A newly-created #GdkPixbuf structure with a reference,
- *   count of 1, or %NULL if an error occurred.
+ * Return value: A newly-created pixbuf
  *
- * Deprecated: 2.32: Use #GResource instead.
+ * Deprecated: 2.32: Use `GResource` instead.
  **/
 GdkPixbuf*
 gdk_pixbuf_new_from_inline (gint          data_length,
diff --git a/gdk-pixbuf/gdk-pixdata.h b/gdk-pixbuf/gdk-pixdata.h
index 0aa2a2550..4c25698a2 100644
--- a/gdk-pixbuf/gdk-pixdata.h
+++ b/gdk-pixbuf/gdk-pixdata.h
@@ -47,7 +47,9 @@ G_BEGIN_DECLS
  *
  * An enumeration containing three sets of flags for a #GdkPixdata struct: 
  * one for the used colorspace, one for the width of the samples and one 
- * for the encoding of the pixel data.  
+ * for the encoding of the pixel data.
+ *
+ * Deprecated: 2.32
  **/
 typedef enum
 {
@@ -64,23 +66,6 @@ typedef enum
   GDK_PIXDATA_ENCODING_MASK     = 0x0f << 24
 } GdkPixdataType;
 
-/**
- * GdkPixdata:
- * @magic: magic number. A valid #GdkPixdata structure must have 
- *    #GDK_PIXBUF_MAGIC_NUMBER here.
- * @length: less than 1 to disable length checks, otherwise 
- *    #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. 
- * @pixdata_type: information about colorspace, sample width and 
- *    encoding, in a #GdkPixdataType. 
- * @rowstride: Distance in bytes between rows.
- * @width: Width of the image in pixels.
- * @height: Height of the image in pixels.
- * @pixel_data: (array) (element-type guint8): @width x @height pixels, encoded according to @pixdata_type
- *   and @rowstride.
- *
- * A #GdkPixdata contains pixbuf information in a form suitable for 
- * serialization and streaming.
- **/
 typedef struct _GdkPixdata GdkPixdata;
 struct _GdkPixdata
 {
@@ -99,6 +84,8 @@ struct _GdkPixdata
  * GDK_PIXDATA_HEADER_LENGTH:
  *
  * The length of a #GdkPixdata structure without the @pixel_data pointer.
+ *
+ * Deprecated: 2.32
  **/
 #define	GDK_PIXDATA_HEADER_LENGTH	(4 + 4 + 4 + 4 + 4 + 4)
 
@@ -145,7 +132,9 @@ GdkPixbuf*	gdk_pixbuf_from_pixdata	(const GdkPixdata	*pixdata,
  * @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT
  * and @GDK_PIXDATA_DUMP_MACROS are mutually exclusive, as are
  * @GDK_PIXBUF_DUMP_GTYPES and @GDK_PIXBUF_DUMP_CTYPES. The remaining
- * elements are optional flags that can be freely added. 
+ * elements are optional flags that can be freely added.
+ *
+ * Deprecated: 2.32
  **/
 typedef enum
 {
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 000000000..e9c78c1e7
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/ebassi/gi-docgen.git
+push-url=ssh://git@gitlab.gnome.org:ebassi/gi-docgen.git
+revision=main
+depth=1