Merge branch 'gi-docs' into 'master'

Gi docs

See merge request GNOME/pango!281

98 files changed, 6184 insertions, 7608 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 06cd1b57..ed21f97e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -119,9 +119,14 @@ reference:
     EXTRA_MESON_FLAGS: ""
   script:
     - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} -Dgtk_doc=true _build
-    - ninja -C _build pango-doc
+    - ninja -C _build
     - mkdir -p _reference/
-    - mv _build/docs/html/ _reference/
+    - mv _build/docs/Pango/ _reference/
+    - mv _build/docs/PangoCairo/ _reference/
+    - mv _build/docs/PangoFc/ _reference/
+    - mv _build/docs/PangoFT2/ _reference/
+    - mv _build/docs/PangoOT/ _reference/
+    - mv _build/docs/PangoXft/ _reference/
   artifacts:
     paths:
       - _reference
diff --git a/docs/check.docs b/docs/check.docs
deleted file mode 100755
index 8eb5fe1c..00000000
--- a/docs/check.docs
+++ /dev/null
@@ -1,57 +0,0 @@
-#!/bin/sh
-
-LC_ALL=C
-export LC_ALL
-
-if test -z "$DOC_MODULE"; then
-	# extract from Makefile
-	eval `grep '^DOC_MODULE' Makefile | sed 's/ //g'`
-	if test -z "$DOC_MODULE"; then
-		echo Failed extracting DOC_MODULE from Makefile 1>&2
-		echo Try setting DOC_MODULE env var manually 1>&2
-		exit 1
-	fi
-fi
-
-if test -n "$REPORT_FILES"; then
-	$MAKE $REPORT_FILES || exit 1
-fi
-
-test -z "$srcdir" && srcdir=.
-stat=0
-
-if test -f "$DOC_MODULE-undeclared.txt"; then
-	undeclared=`cat "$DOC_MODULE-undeclared.txt"`
-	if test -n "$undeclared"; then
-		echo Undeclared documentation symbols: 1>&2
-		cat "$DOC_MODULE-undeclared.txt" 1>&2
-		stat=1
-	fi
-fi >&2
-if test -f "$DOC_MODULE-unused.txt"; then
-	unused=`cat "$DOC_MODULE-unused.txt"`
-	if test -n "$unused"; then
-		echo Unused documentated symbols: 1>&2
-		cat "$DOC_MODULE-unused.txt" 1>&2
-		stat=1
-	fi
-fi >&2
-if test -f "$DOC_MODULE-undocumented.txt"; then
-	if grep '^0 symbols incomplete' "$DOC_MODULE-undocumented.txt" >/dev/null &&
-	   grep '^0 not documented'     "$DOC_MODULE-undocumented.txt" >/dev/null; then
-		:
-	else
-		echo Incomplete or undocumented symbols: 1>&2
-		cat "$DOC_MODULE-undocumented.txt" 1>&2
-		stat=1
-	fi
-fi >&2
-
-# Make failure non-critical for now since this is broken
-if test $stat == 1; then
-    echo "**********************************************"
-    echo "checks.docs failed, but we ignore this for now"
-    echo "**********************************************"
-fi
-# exit $stat
-
diff --git a/docs/meson.build b/docs/meson.build
index e847a34f..14a7a5cd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,97 +1,163 @@
-subdir('xml')
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
-version_xml_conf = configuration_data()
-version_xml_conf.set('PANGO_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in',
-               output: 'version.xml',
-               configuration: version_xml_conf)
-
-private_headers = [
-  'pangocairo-private.h',
-  'pangocairo-fc-private.h',
-  'pangocairo-fc.h',
-  'pangocairo-win32.h',
-  'pangocairo-atsui.h',
-  'pango-coverage-private.h',
-  'pango-color-table.h',
-  'pango-emoji-private.h',
-  'pango-font-private.h',
-  'pango-fontmap-private.h',
-  'pango-fontset-private.h',
-  'pango-impl-utils.h',
-  'pango-glyph-item-private.h',
-  'pango-layout-private.h',
-  'pango-script-table.h',
-  'pango-script-private.h',
-  'pango-utils-private.h',
-  'pangofc-private.h',
-  'pangofc-fontmap-private.h',
-  'pangoft2-private.h',
-  'pangowin32-private.h',
-  'pangoatsui-private.h',
-  'pangoxft-private.h',
-  'pango-ot-private.h',
-  'pango-script-lang-table.h',
-  'pango-language-sample-table.h',
-  'pangocoretext-private.h',
-]
-
-content_files = [
-  'pango_markup.sgml',
-  'version.xml',
-]
-
-html_images = [
+pango_content_files = [
+  'pango_rendering.md',
+  'pango_markup.md',
+  'pango_fonts.md',
+  'pango_bidi.md',
+  'pango-name.png',
   'layout.png',
   'pipeline.png',
-  'rotated-text.png',
   'rects1.png',
   'rects2.png',
+  'rects3.png',
 ]
 
-docdeps = [ libpango_dep ]
+doc_conf = configuration_data()
+doc_conf.set('PANGO_VERSION', meson.project_version())
+
+pango_toml = configure_file(input: 'pango.toml.in',
+                            output: 'pango.toml',
+                            configuration: doc_conf)
+
+custom_target('pango-doc',
+  input: pango_gir[0],
+  output: 'Pango',
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+    '--config', pango_toml,
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ pango_toml, pango_content_files],
+  build_by_default: true,
+)
 
 if build_pangoft2
-  docdeps += libpangoft2_dep
+  pangoft2_toml = configure_file(input: 'pangoft2.toml.in',
+                                 output: 'pangoft2.toml',
+                                 configuration: doc_conf)
+
+  custom_target('pangoft-doc',
+    input: pangoft2_gir[0],
+    output: 'PangoFT2',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+      '--config', pangoft2_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ pangoft2_toml, 'pango-name.png' ],
+    build_by_default: true,
+  )
 endif
 
 if xft_dep.found() and fontconfig_dep.found()
-  docdeps += libpangoxft_dep
+  pangoxft_toml = configure_file(input: 'pangoxft.toml.in',
+                                 output: 'pangoxft.toml',
+                                 configuration: doc_conf)
+
+  custom_target('pangoxft-doc',
+    input: pangoxft_gir[0],
+    output: 'PangoXft',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+      '--config', pangoxft_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ pangoxft_toml, 'pango-name.png' ],
+    build_by_default: true,
+  )
 endif
 
 if cairo_dep.found()
-  docdeps += libpangocairo_dep
+  pangocairo_content_files = [
+    'pango_cairo.md',
+    'pango-name.png',
+    'rotated-text.png',
+  ]
+
+  pangocairo_toml = configure_file(input: 'pangocairo.toml.in',
+                                   output: 'pangocairo.toml',
+                                   configuration: doc_conf)
+
+  custom_target('pangocairo-doc',
+    input: pangocairo_gir[0],
+    output: 'PangoCairo',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+      '--config', pangocairo_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ pangocairo_toml, pangocairo_content_files ],
+    build_by_default: true,
+  )
 endif
 
-glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
-glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
-cairo_prefix = dependency('cairo').get_pkgconfig_variable('prefix')
-cairo_docpath = join_paths(cairo_prefix, 'share', 'gtk-doc', 'html')
-docpath = join_paths(pango_datadir, 'gtk-doc', 'html')
+pangoot_toml = configure_file(input: 'pangoot.toml.in',
+                              output: 'pangoot.toml',
+                              configuration: doc_conf)
 
-gnome.gtkdoc('pango',
-             main_xml: 'pango-docs.sgml',
-             src_dir: [
-               pango_inc,
-             ],
-             dependencies: docdeps,
-             gobject_typesfile: configure_file(input: 'pango.types.in',
-                                               output: 'pango.types',
-                                               configuration: pango_conf),
-             scan_args: [
-               '--deprecated-guards=PANGO_DISABLE_DEPRECATED',
-               '--ignore-decorators=_PANGO_EXTERN',
-               '--ignore-headers=' + ' '.join(private_headers),
-             ],
-             mkdb_args: [
-               '--sgml-mode',
-               '--output-format=xml',
-             ],
-             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(cairo_docpath, 'cairo')),
-             ],
-             html_assets: html_images,
-             install: true)
+custom_target('pangoot-doc',
+  input: pangoot_gir[0],
+  output: 'PangoOT',
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+    '--config', pangoot_toml,
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ pangoot_toml, 'pango-name.png' ],
+  build_by_default: true,
+)
+
+if fontconfig_dep.found()
+  pangofc_toml = configure_file(input: 'pangofc.toml.in',
+                                output: 'pangofc.toml',
+                                configuration: doc_conf)
+
+  custom_target('pangofc-doc',
+    input: pangofc_gir[0],
+    output: 'PangoFc',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
+      '--config', pangofc_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ pangofc_toml, 'pango-name.png' ],
+    build_by_default: true,
+  )
+endif
diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
deleted file mode 100644
index 2ac4f6df..00000000
--- a/docs/pango-docs.sgml
+++ /dev/null
@@ -1,167 +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>Pango Reference Manual</title>
-    <abstract>Internationalized text layout and rendering</abstract>
-    <releaseinfo>for Pango &version;.
-      Online at
-      <ulink role="online-location" url="https://developer.gnome.org/pango/">https://developer.gnome.org/pango/</ulink>
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter id="pango">
-    <title>Basic Pango Interfaces</title>
-    <xi:include href="xml/main.xml"/>
-    <xi:include href="xml/fonts.xml"/>
-    <xi:include href="xml/glyphs.xml"/>
-    <xi:include href="xml/text-attributes.xml"/>
-    <xi:include href="xml/markup.xml"/>
-    <xi:include href="xml/layout.xml"/>
-    <xi:include href="xml/scripts.xml"/>
-    <xi:include href="xml/bidi.xml"/>
-    <xi:include href="xml/vertical.xml"/>
-  </chapter>
-
-  <chapter id="rendering">
-    <title>Rendering with Pango</title>
-    <xi:include href="xml/pangocairo.xml"/>
-    <xi:include href="xml/win32-fonts.xml"/>
-    <xi:include href="xml/coretext-fonts.xml"/>
-    <xi:include href="xml/freetype-fonts.xml"/>
-    <xi:include href="xml/xft-fonts.xml"/>
-  </chapter>
-
-  <chapter id="lowlevel">
-    <title>Low Level Functionality</title>
-    <xi:include href="xml/context.xml"/>
-    <xi:include href="xml/tab-stops.xml"/>
-    <xi:include href="xml/coverage-maps.xml"/>
-    <xi:include href="xml/pango-renderer.xml"/>
-    <xi:include href="xml/pangofc-fontmap.xml"/>
-    <xi:include href="xml/pangofc-font.xml"/>
-    <xi:include href="xml/pangofc-decoder.xml"/>
-    <xi:include href="xml/utils.xml"/>
-    <xi:include href="xml/pango-version.xml"/>
-    </chapter>
-
-  <chapter id="deprecated">
-    <title>Deprecated APIs</title>
-    <xi:include href="xml/opentype.xml"/>
-    <xi:include href="xml/engines.xml"/>
-    <xi:include href="xml/pango-engine-lang.xml"/>
-    <xi:include href="xml/pango-engine-shape.xml"/>
-    <xi:include href="xml/modules.xml"/>
-  </chapter>
-
-  <chapter id="pango-hierarchy">
-    <title>Object Hierarchy</title>
-    <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-
-  <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">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-2">
-    <title>Index of new symbols in 1.2</title>
-    <xi:include href="xml/api-index-1.2.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-4">
-    <title>Index of new symbols in 1.4</title>
-    <xi:include href="xml/api-index-1.4.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-6">
-    <title>Index of new symbols in 1.6</title>
-    <xi:include href="xml/api-index-1.6.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-8">
-    <title>Index of new symbols in 1.8</title>
-    <xi:include href="xml/api-index-1.8.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-10">
-    <title>Index of new symbols in 1.10</title>
-    <xi:include href="xml/api-index-1.10.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-12">
-    <title>Index of new symbols in 1.12</title>
-    <xi:include href="xml/api-index-1.12.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-14">
-    <title>Index of new symbols in 1.14</title>
-    <xi:include href="xml/api-index-1.14.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-16">
-    <title>Index of new symbols in 1.16</title>
-    <xi:include href="xml/api-index-1.16.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-18">
-    <title>Index of new symbols in 1.18</title>
-    <xi:include href="xml/api-index-1.18.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-20">
-    <title>Index of new symbols in 1.20</title>
-    <xi:include href="xml/api-index-1.20.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-22">
-    <title>Index of new symbols in 1.22</title>
-    <xi:include href="xml/api-index-1.22.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-24">
-    <title>Index of new symbols in 1.24</title>
-    <xi:include href="xml/api-index-1.24.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-26">
-    <title>Index of new symbols in 1.26</title>
-    <xi:include href="xml/api-index-1.26.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-30">
-    <title>Index of new symbols in 1.30</title>
-    <xi:include href="xml/api-index-1.30.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-31-0">
-    <title>Index of new symbols in 1.31</title>
-    <xi:include href="xml/api-index-1.31.0.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-32">
-    <title>Index of new symbols in 1.32</title>
-    <xi:include href="xml/api-index-1.32.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-32-4">
-    <title>Index of new symbols in 1.32.4</title>
-    <xi:include href="xml/api-index-1.32.4.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-34">
-    <title>Index of new symbols in 1.34</title>
-    <xi:include href="xml/api-index-1.34.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-38">
-    <title>Index of new symbols in 1.38</title>
-    <xi:include href="xml/api-index-1.38.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-42">
-    <title>Index of new symbols in 1.42</title>
-    <xi:include href="xml/api-index-1.42.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-44">
-    <title>Index of new symbols in 1.44</title>
-    <xi:include href="xml/api-index-1.44.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-1-46">
-    <title>Index of new symbols in 1.46</title>
-    <xi:include href="xml/api-index-1.46.xml"><xi:fallback /></xi:include>
-  </index>
-
-</book>
diff --git a/docs/pango-name-black.png b/docs/pango-name-black.png
new file mode 100644
index 00000000..00025b68
--- /dev/null
+++ b/docs/pango-name-black.png
diff --git a/docs/pango-name-solid.png b/docs/pango-name-solid.png
new file mode 100644
index 00000000..630c5142
--- /dev/null
+++ b/docs/pango-name-solid.png
diff --git a/docs/pango-name-white.png b/docs/pango-name-white.png
new file mode 100644
index 00000000..2240573a
--- /dev/null
+++ b/docs/pango-name-white.png
diff --git a/docs/pango-name.png b/docs/pango-name.png
new file mode 100644
index 00000000..2240573a
--- /dev/null
+++ b/docs/pango-name.png
diff --git a/docs/pango-overrides.txt b/docs/pango-overrides.txt
deleted file mode 100644
index e69de29b..00000000
--- a/docs/pango-overrides.txt
+++ /dev/null
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
deleted file mode 100644
index 358f5bbf..00000000
--- a/docs/pango-sections.txt
+++ /dev/null
@@ -1,1276 +0,0 @@
-<SECTION>
-<TITLE>Text Processing</TITLE>
-<FILE>main</FILE>
-<SUBSECTION>
-PangoItem
-PangoAnalysis
-PANGO_ANALYSIS_FLAG_CENTERED_BASELINE
-PANGO_ANALYSIS_FLAG_IS_ELLIPSIS
-PANGO_ANALYSIS_FLAG_NEED_HYPHEN
-
-<SUBSECTION>
-pango_itemize
-pango_itemize_with_base_dir
-pango_item_free
-pango_item_copy
-pango_item_new
-pango_item_split
-pango_item_apply_attrs
-pango_reorder_items
-
-<SUBSECTION>
-pango_break
-pango_get_log_attrs
-pango_find_paragraph_boundary
-pango_default_break
-pango_tailor_break
-PangoLogAttr
-
-<SUBSECTION>
-pango_shape
-pango_shape_full
-PangoShapeFlags
-pango_shape_with_flags
-
-<SUBSECTION Standard>
-PANGO_TYPE_DIRECTION
-PANGO_TYPE_ITEM
-
-<SUBSECTION Private>
-pango_item_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Contexts</TITLE>
-<FILE>context</FILE>
-PangoContext
-pango_context_new
-pango_context_changed
-pango_context_get_serial
-pango_context_set_font_map
-pango_context_get_font_map
-pango_context_get_font_description
-pango_context_set_font_description
-pango_context_get_language
-pango_context_set_language
-pango_context_get_base_dir
-pango_context_set_base_dir
-pango_context_get_base_gravity
-pango_context_set_base_gravity
-pango_context_get_gravity
-pango_context_get_gravity_hint
-pango_context_set_gravity_hint
-pango_context_get_matrix
-pango_context_set_matrix
-pango_context_get_round_glyph_positions
-pango_context_set_round_glyph_positions
-pango_context_load_font
-pango_context_load_fontset
-pango_context_get_metrics
-pango_context_list_families
-
-<SUBSECTION Standard>
-PANGO_TYPE_CONTEXT
-PangoContextClass
-PANGO_CONTEXT
-PANGO_CONTEXT_CLASS
-PANGO_IS_CONTEXT
-PANGO_IS_CONTEXT_CLASS
-PANGO_CONTEXT_GET_CLASS
-PANGO_TYPE_ITEM
-
-<SUBSECTION Private>
-pango_context_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Glyph Storage</TITLE>
-<FILE>glyphs</FILE>
-PANGO_SCALE
-PANGO_PIXELS
-PANGO_PIXELS_FLOOR
-PANGO_PIXELS_CEIL
-PANGO_UNITS_ROUND
-pango_units_to_double
-pango_units_from_double
-PangoRectangle
-PANGO_ASCENT
-PANGO_DESCENT
-PANGO_LBEARING
-PANGO_RBEARING
-pango_extents_to_pixels
-PangoMatrix
-PANGO_MATRIX_INIT
-pango_matrix_copy
-pango_matrix_free
-pango_matrix_translate
-pango_matrix_scale
-pango_matrix_rotate
-pango_matrix_concat
-pango_matrix_transform_point
-pango_matrix_transform_distance
-pango_matrix_transform_rectangle
-pango_matrix_transform_pixel_rectangle
-pango_matrix_get_font_scale_factor
-pango_matrix_get_font_scale_factors
-PangoGlyph
-PANGO_GLYPH_EMPTY
-PANGO_GLYPH_INVALID_INPUT
-PANGO_GLYPH_UNKNOWN_FLAG
-PANGO_GET_UNKNOWN_GLYPH
-PangoGlyphInfo
-PangoGlyphGeometry
-PangoGlyphUnit
-PangoGlyphVisAttr
-PangoGlyphString
-PangoGlyphItem
-PangoGlyphItemIter
-pango_glyph_string_new
-pango_glyph_string_copy
-pango_glyph_string_set_size
-pango_glyph_string_free
-pango_glyph_string_extents
-pango_glyph_string_extents_range
-pango_glyph_string_get_width
-pango_glyph_string_index_to_x
-pango_glyph_string_x_to_index
-pango_glyph_string_get_logical_widths
-pango_glyph_item_copy
-pango_glyph_item_free
-pango_glyph_item_split
-pango_glyph_item_apply_attrs
-pango_glyph_item_letter_space
-pango_glyph_item_get_logical_widths
-pango_glyph_item_iter_copy
-pango_glyph_item_iter_free
-pango_glyph_item_iter_init_start
-pango_glyph_item_iter_init_end
-pango_glyph_item_iter_next_cluster
-pango_glyph_item_iter_prev_cluster
-
-PANGO_TYPE_GLYPH_STRING
-<SUBSECTION Private>
-PANGO_TYPE_GLYPH_ITEM
-PANGO_TYPE_GLYPH_ITEM_ITER
-PANGO_TYPE_MATRIX
-pango_glyph_string_get_type
-pango_glyph_item_get_type
-pango_glyph_item_iter_get_type
-pango_matrix_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Coverage Maps</TITLE>
-<FILE>coverage-maps</FILE>
-PangoCoverageLevel
-PANGO_TYPE_COVERAGE_LEVEL
-PangoCoverage
-<SUBSECTION>
-pango_coverage_new
-pango_coverage_ref
-pango_coverage_unref
-pango_coverage_copy
-pango_coverage_get
-pango_coverage_max
-pango_coverage_set
-pango_coverage_to_bytes
-pango_coverage_from_bytes
-
-<SUBSECTION Private>
-pango_coverage_level_get_type
-pango_coverage_get_type
-PANGO_COVERAGE
-PANGO_COVERAGE_CLASS
-PANGO_COVERAGE_GET_CLASS
-PANGO_IS_COVERAGE
-PANGO_IS_COVERAGE_CLASS
-PANGO_TYPE_COVERAGE
-PangoCoverageClass
-PangoCoveragePrivate
-</SECTION>
-
-<SECTION>
-<TITLE>Fonts</TITLE>
-<FILE>fonts</FILE>
-PangoFontDescription
-PangoStyle
-PangoWeight
-PangoVariant
-PangoStretch
-PangoFontMask
-pango_font_description_new
-pango_font_description_copy
-pango_font_description_copy_static
-pango_font_description_hash
-pango_font_description_equal
-pango_font_description_free
-pango_font_descriptions_free
-pango_font_description_set_family
-pango_font_description_set_family_static
-pango_font_description_get_family
-pango_font_description_set_style
-pango_font_description_get_style
-pango_font_description_set_variant
-pango_font_description_get_variant
-pango_font_description_set_weight
-pango_font_description_get_weight
-pango_font_description_set_stretch
-pango_font_description_get_stretch
-pango_font_description_set_size
-pango_font_description_get_size
-pango_font_description_set_absolute_size
-pango_font_description_get_size_is_absolute
-pango_font_description_set_gravity
-pango_font_description_get_gravity
-pango_font_description_set_variations
-pango_font_description_set_variations_static
-pango_font_description_get_variations
-pango_font_description_get_set_fields
-pango_font_description_unset_fields
-pango_font_description_merge
-pango_font_description_merge_static
-pango_font_description_better_match
-pango_font_description_from_string
-pango_font_description_to_string
-pango_font_description_to_filename
-<SUBSECTION>
-PangoFontMetrics
-pango_font_metrics_ref
-pango_font_metrics_unref
-pango_font_metrics_get_ascent
-pango_font_metrics_get_descent
-pango_font_metrics_get_height
-pango_font_metrics_get_approximate_char_width
-pango_font_metrics_get_approximate_digit_width
-pango_font_metrics_get_underline_thickness
-pango_font_metrics_get_underline_position
-pango_font_metrics_get_strikethrough_thickness
-pango_font_metrics_get_strikethrough_position
-<SUBSECTION>
-PangoFont
-pango_font_find_shaper
-pango_font_describe
-pango_font_describe_with_absolute_size
-pango_font_get_face
-pango_font_get_coverage
-pango_font_has_char
-pango_font_get_glyph_extents
-pango_font_get_metrics
-pango_font_get_font_map
-pango_font_get_features
-pango_font_get_hb_font
-<SUBSECTION>
-PangoFontFamily
-pango_font_family_get_name
-pango_font_family_is_monospace
-pango_font_family_is_variable
-pango_font_family_list_faces
-pango_font_family_get_face
-<SUBSECTION>
-PangoFontFace
-pango_font_face_get_face_name
-pango_font_face_list_sizes
-pango_font_face_describe
-pango_font_face_is_synthesized
-pango_font_face_get_family
-<SUBSECTION>
-PangoFontMap
-PangoFontMapClass
-pango_font_map_create_context
-pango_font_map_load_font
-pango_font_map_load_fontset
-pango_font_map_list_families
-pango_font_map_get_family
-pango_font_map_get_serial
-pango_font_map_changed
-<SUBSECTION>
-PangoFontset
-PangoFontsetClass
-pango_fontset_get_font
-pango_fontset_get_metrics
-PangoFontsetForeachFunc
-pango_fontset_foreach
-
-<SUBSECTION Standard>
-PANGO_TYPE_FONTSET
-PANGO_TYPE_FONT_MAP
-PANGO_FONT_MAP
-PANGO_IS_FONT_MAP
-PANGO_FONT_MAP_CLASS
-PANGO_IS_FONT_MAP_CLASS
-PANGO_FONT_MAP_GET_CLASS
-PANGO_TYPE_FONT_FAMILY
-PANGO_FONT_FAMILY
-PANGO_IS_FONT_FAMILY
-PANGO_TYPE_FONT_FACE
-PANGO_FONT_FACE
-PANGO_IS_FONT_FACE
-PANGO_TYPE_FONT_METRICS
-PANGO_TYPE_FONT
-PANGO_FONT
-PANGO_IS_FONT
-PANGO_TYPE_FONT_DESCRIPTION
-PANGO_TYPE_STYLE
-PANGO_TYPE_WEIGHT
-PANGO_TYPE_VARIANT
-PANGO_TYPE_STRETCH
-PANGO_TYPE_FONT_MASK
-PANGO_FONT_FACE_CLASS
-PANGO_IS_FONT_CLASS
-PANGO_FONT_FACE_GET_CLASS
-PangoFontFamilyClass
-PangoFontFaceClass
-PANGO_FONT_GET_CLASS
-PANGO_FONT_CLASS
-PANGO_IS_FONT_FAMILY_CLASS
-PangoFontClass
-PANGO_FONT_FAMILY_GET_CLASS
-PANGO_FONT_FAMILY_CLASS
-PANGO_IS_FONT_FACE_CLASS
-PANGO_FONTSET
-PANGO_IS_FONTSET
-PANGO_FONTSET_CLASS
-PANGO_IS_FONTSET_CLASS
-PANGO_FONTSET_GET_CLASS
-PANGO_FONTSET_SIMPLE
-PANGO_IS_FONTSET_SIMPLE
-PangoFontsetSimpleClass
-
-<SUBSECTION Private>
-pango_font_metrics_new
-pango_font_get_type
-pango_stretch_get_type
-pango_style_get_type
-pango_variant_get_type
-pango_weight_get_type
-pango_font_mask_get_type
-pango_font_description_get_type
-pango_font_map_get_type
-pango_font_face_get_type
-pango_font_family_get_type
-pango_font_metrics_get_type
-pango_fontset_get_type
-pango_fontset_simple_get_type
-PANGO_UNKNOWN_GLYPH_WIDTH
-PANGO_UNKNOWN_GLYPH_HEIGHT
-</SECTION>
-
-<SECTION>
-<TITLE>Text Attributes</TITLE>
-<FILE>text-attributes</FILE>
-PangoAttrType
-PangoAttrClass
-PangoAttribute
-PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
-PANGO_ATTR_INDEX_TO_TEXT_END
-PangoAttrString
-PangoAttrLanguage
-PangoAttrColor
-PangoAttrInt
-PangoAttrFloat
-PangoAttrFontDesc
-PangoAttrShape
-PangoAttrSize
-PangoAttrFontFeatures
-pango_attr_type_register
-pango_attr_type_get_name
-pango_attribute_init
-pango_attribute_copy
-pango_attribute_equal
-pango_attribute_destroy
-<SUBSECTION>
-pango_attr_language_new
-pango_attr_family_new
-pango_attr_style_new
-pango_attr_variant_new
-pango_attr_stretch_new
-pango_attr_weight_new
-pango_attr_size_new
-pango_attr_size_new_absolute
-pango_attr_font_desc_new
-pango_attr_foreground_new
-pango_attr_background_new
-pango_attr_strikethrough_new
-pango_attr_strikethrough_color_new
-pango_attr_underline_new
-pango_attr_underline_color_new
-PangoUnderline
-pango_attr_overline_new
-pango_attr_overline_color_new
-PangoOverline
-pango_attr_shape_new
-pango_attr_shape_new_with_data
-PangoAttrDataCopyFunc
-pango_attr_scale_new
-PANGO_SCALE_XX_SMALL
-PANGO_SCALE_X_SMALL
-PANGO_SCALE_SMALL
-PANGO_SCALE_MEDIUM
-PANGO_SCALE_LARGE
-PANGO_SCALE_X_LARGE
-PANGO_SCALE_XX_LARGE
-pango_attr_rise_new
-pango_attr_letter_spacing_new
-pango_attr_fallback_new
-pango_attr_gravity_new
-pango_attr_gravity_hint_new
-pango_attr_font_features_new
-pango_attr_foreground_alpha_new
-pango_attr_background_alpha_new
-pango_attr_allow_breaks_new
-pango_attr_insert_hyphens_new
-PangoShowFlags
-pango_attr_show_new
-PangoColor
-pango_color_parse
-pango_color_parse_with_alpha
-pango_color_copy
-pango_color_free
-pango_color_to_string
-<SUBSECTION>
-PangoAttrList
-pango_attr_list_new
-pango_attr_list_ref
-pango_attr_list_unref
-pango_attr_list_copy
-pango_attr_list_insert
-pango_attr_list_insert_before
-pango_attr_list_change
-pango_attr_list_splice
-pango_attr_list_filter
-pango_attr_list_update
-PangoAttrFilterFunc
-pango_attr_list_get_attributes
-pango_attr_list_equal
-pango_attr_list_get_iterator
-PangoAttrIterator
-pango_attr_iterator_copy
-pango_attr_iterator_next
-pango_attr_iterator_range
-pango_attr_iterator_get
-pango_attr_iterator_get_font
-pango_attr_iterator_get_attrs
-pango_attr_iterator_destroy
-
-<SUBSECTION Private>
-PANGO_TYPE_ATTR_TYPE
-PANGO_TYPE_UNDERLINE
-PANGO_TYPE_COLOR
-PANGO_TYPE_ATTR_LIST
-pango_attr_type_get_type
-pango_attr_list_get_type
-pango_underline_get_type
-pango_color_get_type
-pango_attribute_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Markup</TITLE>
-<FILE>markup</FILE>
-pango_parse_markup
-pango_markup_parser_new
-pango_markup_parser_finish
-</SECTION>
-
-<SECTION>
-<TITLE>Tab Stops</TITLE>
-<FILE>tab-stops</FILE>
-PangoTabArray
-PangoTabAlign
-pango_tab_array_new
-pango_tab_array_new_with_positions
-pango_tab_array_copy
-pango_tab_array_free
-pango_tab_array_get_size
-pango_tab_array_resize
-pango_tab_array_set_tab
-pango_tab_array_get_tab
-pango_tab_array_get_tabs
-pango_tab_array_get_positions_in_pixels
-
-<SUBSECTION Private>
-PANGO_TYPE_TAB_ARRAY
-PANGO_TYPE_TAB_ALIGN
-pango_tab_align_get_type
-pango_tab_array_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Layout Objects</TITLE>
-<FILE>layout</FILE>
-PangoLayout
-PangoLayoutIter
-pango_layout_new
-pango_layout_copy
-
-pango_layout_get_context
-pango_layout_context_changed
-pango_layout_get_serial
-
-pango_layout_set_text
-pango_layout_get_text
-pango_layout_get_character_count
-pango_layout_set_markup
-pango_layout_set_markup_with_accel
-pango_layout_set_attributes
-pango_layout_get_attributes
-pango_layout_set_font_description
-pango_layout_get_font_description
-pango_layout_set_width
-pango_layout_get_width
-pango_layout_set_height
-pango_layout_get_height
-pango_layout_set_wrap
-pango_layout_get_wrap
-pango_layout_is_wrapped
-PangoWrapMode
-pango_layout_set_ellipsize
-pango_layout_get_ellipsize
-pango_layout_is_ellipsized
-PangoEllipsizeMode
-pango_layout_set_indent
-pango_layout_get_indent
-pango_layout_get_spacing
-pango_layout_set_spacing
-pango_layout_set_line_spacing
-pango_layout_get_line_spacing
-pango_layout_set_justify
-pango_layout_get_justify
-pango_layout_set_auto_dir
-pango_layout_get_auto_dir
-pango_layout_get_direction
-pango_layout_set_alignment
-pango_layout_get_alignment
-pango_layout_set_tabs
-pango_layout_get_tabs
-pango_layout_set_single_paragraph_mode
-pango_layout_get_single_paragraph_mode
-PangoAlignment
-
-pango_layout_get_unknown_glyphs_count
-pango_layout_get_log_attrs
-pango_layout_get_log_attrs_readonly
-
-pango_layout_index_to_pos
-pango_layout_index_to_line_x
-pango_layout_xy_to_index
-pango_layout_get_cursor_pos
-pango_layout_move_cursor_visually
-
-pango_layout_get_extents
-pango_layout_get_pixel_extents
-pango_layout_get_size
-pango_layout_get_pixel_size
-pango_layout_get_baseline
-pango_layout_get_line_count
-pango_layout_get_line
-pango_layout_get_line_readonly
-pango_layout_get_lines
-pango_layout_get_lines_readonly
-
-pango_layout_get_iter
-pango_layout_iter_copy
-pango_layout_iter_free
-pango_layout_iter_next_run
-pango_layout_iter_next_char
-pango_layout_iter_next_cluster
-pango_layout_iter_next_line
-pango_layout_iter_at_last_line
-pango_layout_iter_get_index
-pango_layout_iter_get_baseline
-pango_layout_iter_get_run
-pango_layout_iter_get_run_readonly
-pango_layout_iter_get_line
-pango_layout_iter_get_line_readonly
-pango_layout_iter_get_layout
-pango_layout_iter_get_char_extents
-pango_layout_iter_get_cluster_extents
-pango_layout_iter_get_run_extents
-pango_layout_iter_get_line_yrange
-pango_layout_iter_get_line_extents
-pango_layout_iter_get_layout_extents
-
-<SUBSECTION>
-PangoLayoutLine
-PangoLayoutRun
-
-pango_layout_line_ref
-pango_layout_line_unref
-pango_layout_line_get_extents
-pango_layout_line_get_pixel_extents
-pango_layout_line_index_to_x
-pango_layout_line_x_to_index
-pango_layout_line_get_x_ranges
-pango_layout_line_get_height
-
-<SUBSECTION Standard>
-PANGO_TYPE_WRAP_MODE
-PANGO_TYPE_ELLIPSIZE_MODE
-PANGO_TYPE_ALIGNMENT
-PANGO_TYPE_LAYOUT
-PangoLayoutClass
-PANGO_LAYOUT
-PANGO_IS_LAYOUT
-PANGO_LAYOUT_CLASS
-PANGO_IS_LAYOUT_CLASS
-PANGO_LAYOUT_GET_CLASS
-PANGO_TYPE_LAYOUT_ITER
-PANGO_TYPE_LAYOUT_LINE
-
-<SUBSECTION Private>
-pango_layout_get_type
-pango_layout_iter_get_type
-pango_layout_line_get_type
-pango_alignment_get_type
-pango_wrap_mode_get_type
-pango_ellipsize_mode_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Scripts and Languages</TITLE>
-<FILE>scripts</FILE>
-PangoScript
-PangoScriptIter
-pango_script_for_unichar
-pango_script_get_sample_language
-pango_script_iter_new
-pango_script_iter_get_range
-pango_script_iter_next
-pango_script_iter_free
-PangoLanguage
-pango_language_from_string
-pango_language_to_string
-pango_language_matches
-pango_language_includes_script
-pango_language_get_scripts
-pango_language_get_default
-pango_language_get_preferred
-pango_language_get_sample_string
-
-<SUBSECTION Private>
-PANGO_TYPE_LANGUAGE
-PANGO_TYPE_SCRIPT
-pango_script_get_type
-pango_language_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Engines</TITLE>
-<FILE>engines</FILE>
-PangoEngineInfo
-PangoEngineScriptInfo
-PangoEngine
-PangoEngineClass
-script_engine_list
-script_engine_init
-script_engine_exit
-script_engine_create
-<SUBSECTION Standard>
-PANGO_ENGINE
-PANGO_IS_ENGINE
-PANGO_TYPE_ENGINE
-PANGO_ENGINE_CLASS
-PANGO_IS_ENGINE_CLASS
-PANGO_ENGINE_GET_CLASS
-<SUBSECTION Private>
-pango_engine_get_type
-PANGO_MODULE_ENTRY
-PANGO_ENGINE_DEFINE_TYPE
-</SECTION>
-
-<SECTION>
-<TITLE>PangoEngineLang</TITLE>
-<FILE>pango-engine-lang</FILE>
-PangoEngineLang
-PangoEngineLangClass
-PANGO_ENGINE_TYPE_LANG
-PANGO_ENGINE_LANG_DEFINE_TYPE
-<SUBSECTION Standard>
-PANGO_ENGINE_LANG
-PANGO_IS_ENGINE_LANG
-PANGO_TYPE_ENGINE_LANG
-PANGO_ENGINE_LANG_CLASS
-PANGO_IS_ENGINE_LANG_CLASS
-PANGO_ENGINE_LANG_GET_CLASS
-<SUBSECTION Private>
-pango_engine_lang_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>PangoEngineShape</TITLE>
-<FILE>pango-engine-shape</FILE>
-PangoEngineShape
-PangoEngineShapeClass
-PANGO_ENGINE_TYPE_SHAPE
-PANGO_ENGINE_SHAPE_DEFINE_TYPE
-<SUBSECTION Standard>
-PANGO_ENGINE_SHAPE
-PANGO_IS_ENGINE_SHAPE
-PANGO_TYPE_ENGINE_SHAPE
-PANGO_ENGINE_SHAPE_CLASS
-PANGO_IS_ENGINE_SHAPE_CLASS
-PANGO_ENGINE_SHAPE_GET_CLASS
-<SUBSECTION Private>
-pango_engine_shape_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Modules</TITLE>
-<FILE>modules</FILE>
-PangoIncludedModule
-PangoMap
-PangoMapEntry
-pango_find_map
-pango_map_get_engine
-pango_map_get_engines
-pango_module_register
-</SECTION>
-
-<SECTION>
-<FILE>pango-renderer</FILE>
-PangoRenderer
-PangoRenderPart
-PANGO_TYPE_RENDER_PART
-PangoRendererClass
-<TITLE>PangoRenderer</TITLE>
-pango_renderer_draw_layout
-pango_renderer_draw_layout_line
-pango_renderer_draw_glyphs
-pango_renderer_draw_glyph_item
-pango_renderer_draw_rectangle
-pango_renderer_draw_error_underline
-pango_renderer_draw_trapezoid
-pango_renderer_draw_glyph
-pango_renderer_activate
-pango_renderer_deactivate
-pango_renderer_part_changed
-pango_renderer_set_color
-pango_renderer_get_color
-pango_renderer_set_alpha
-pango_renderer_get_alpha
-pango_renderer_set_matrix
-pango_renderer_get_matrix
-pango_renderer_get_layout
-pango_renderer_get_layout_line
-<SUBSECTION Standard>
-PANGO_RENDERER
-PANGO_IS_RENDERER
-PANGO_TYPE_RENDERER
-pango_renderer_get_type
-PANGO_RENDERER_CLASS
-PANGO_IS_RENDERER_CLASS
-PANGO_RENDERER_GET_CLASS
-<SUBSECTION Private>
-pango_render_part_get_type
-PangoRendererPrivate
-</SECTION>
-
-<SECTION>
-<TITLE>Win32 Fonts and Rendering</TITLE>
-<FILE>win32-fonts</FILE>
-pango_win32_get_context
-pango_win32_render
-pango_win32_render_transformed
-pango_win32_render_layout_line
-pango_win32_render_layout
-pango_win32_get_unknown_glyph
-pango_win32_font_get_glyph_index
-pango_win32_font_select_font
-pango_win32_font_done_font
-pango_win32_font_get_metrics_factor
-pango_win32_get_debug_flag
-pango_win32_get_dc
-PangoWin32FontCache
-pango_win32_font_cache_new
-pango_win32_font_cache_free
-pango_win32_font_cache_load
-pango_win32_font_cache_loadw
-pango_win32_font_cache_unload
-pango_win32_font_map_for_display
-pango_win32_shutdown_display
-pango_win32_font_map_get_font_cache
-pango_win32_font_logfont
-pango_win32_font_logfontw
-pango_win32_font_description_from_logfont
-pango_win32_font_description_from_logfontw
-
-<SUBSECTION Private>
-STRICT
-</SECTION>
-
-<SECTION>
-<TITLE>FreeType Fonts and Rendering</TITLE>
-<FILE>freetype-fonts</FILE>
-PangoFT2FontMap
-pango_ft2_font_map_new
-pango_ft2_font_map_set_resolution
-pango_ft2_font_map_create_context
-PangoFT2SubstituteFunc
-pango_ft2_font_map_set_default_substitute
-pango_ft2_font_map_substitute_changed
-pango_ft2_get_context
-pango_ft2_render
-pango_ft2_render_transformed
-pango_ft2_render_layout_line
-pango_ft2_render_layout_line_subpixel
-pango_ft2_render_layout
-pango_ft2_render_layout_subpixel
-pango_ft2_get_unknown_glyph
-pango_ft2_font_get_kerning
-pango_ft2_font_get_face
-pango_ft2_font_get_coverage
-pango_ft2_font_map_for_display
-pango_ft2_shutdown_display
-<SUBSECTION Standard>
-PANGO_TYPE_FT2_FONT_MAP
-PANGO_FT2_FONT_MAP
-PANGO_FT2_IS_FONT_MAP
-<SUBSECTION Private>
-pango_ft2_font_map_get_type
-STRICT
-</SECTION>
-
-<SECTION>
-<TITLE>Xft Fonts and Rendering</TITLE>
-<FILE>xft-fonts</FILE>
-PangoXftFont
-PangoXftFontMap
-pango_xft_get_context
-pango_xft_get_font_map
-pango_xft_set_default_substitute
-PangoXftSubstituteFunc
-pango_xft_substitute_changed
-pango_xft_shutdown_display
-pango_xft_font_get_font
-pango_xft_font_get_display
-pango_xft_font_has_char
-pango_xft_font_lock_face
-pango_xft_font_unlock_face
-pango_xft_font_get_glyph
-pango_xft_font_get_unknown_glyph
-PangoXftRenderer
-PangoXftRendererClass
-
-pango_xft_renderer_new
-pango_xft_renderer_set_draw
-pango_xft_renderer_set_default_color
-pango_xft_render
-pango_xft_picture_render
-pango_xft_render_transformed
-pango_xft_render_layout_line
-pango_xft_render_layout
-<SUBSECTION Standard>
-PANGO_TYPE_XFT_FONT
-PANGO_XFT_FONT
-PANGO_XFT_IS_FONT
-PANGO_TYPE_XFT_FONT_MAP
-PANGO_XFT_FONT_MAP
-PANGO_XFT_IS_FONT_MAP
-PANGO_XFT_RENDERER
-PANGO_IS_XFT_RENDERER
-PANGO_TYPE_XFT_RENDERER
-PANGO_XFT_RENDERER_CLASS
-PANGO_IS_XFT_RENDERER_CLASS
-PANGO_XFT_RENDERER_GET_CLASS
-
-<SUBSECTION Private>
-PangoXftRendererPrivate
-pango_xft_font_get_type
-pango_xft_font_map_get_type
-pango_xft_renderer_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Cairo Rendering</TITLE>
-<FILE>pangocairo</FILE>
-PangoCairoFont
-PangoCairoFontMap
-pango_cairo_font_map_get_default
-pango_cairo_font_map_set_default
-pango_cairo_font_map_new
-pango_cairo_font_map_new_for_font_type
-pango_cairo_font_map_get_font_type
-pango_cairo_font_map_set_resolution
-pango_cairo_font_map_get_resolution
-pango_cairo_font_map_create_context
-pango_cairo_font_get_scaled_font
-pango_cairo_context_set_resolution
-pango_cairo_context_get_resolution
-pango_cairo_context_set_font_options
-pango_cairo_context_get_font_options
-PangoCairoShapeRendererFunc
-pango_cairo_context_set_shape_renderer
-pango_cairo_context_get_shape_renderer
-pango_cairo_create_context
-pango_cairo_update_context
-pango_cairo_create_layout
-pango_cairo_update_layout
-pango_cairo_show_glyph_string
-pango_cairo_show_glyph_item
-pango_cairo_show_layout_line
-pango_cairo_show_layout
-pango_cairo_show_error_underline
-pango_cairo_glyph_string_path
-pango_cairo_layout_line_path
-pango_cairo_layout_path
-pango_cairo_error_underline_path
-<SUBSECTION Standard>
-PANGO_CAIRO_FONT
-PANGO_CAIRO_FONT_MAP
-PANGO_IS_CAIRO_FONT
-PANGO_IS_CAIRO_FONT_MAP
-PANGO_TYPE_CAIRO_FONT
-PANGO_TYPE_CAIRO_FONT_MAP
-pango_cairo_font_get_type
-pango_cairo_font_map_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>CoreText Fonts</TITLE>
-<FILE>coretext-fonts</FILE>
-pango_core_text_font_get_ctfont
-<SUBSECTION Standard>
-PANGO_CAIRO_CORE_TEXT_FONT
-PANGO_CAIRO_CORE_TEXT_FONT_CLASS
-PANGO_CAIRO_CORE_TEXT_FONT_GET_CLASS
-PANGO_CAIRO_CORE_TEXT_FONT_MAP
-PANGO_CORE_TEXT_FONT
-PANGO_CORE_TEXT_FONT_CLASS
-PANGO_CORE_TEXT_FONT_GET_CLASS
-PANGO_CORE_TEXT_FONT_MAP
-PANGO_CORE_TEXT_FONT_MAP_CLASS
-PANGO_CORE_TEXT_FONT_MAP_GET_CLASS
-PANGO_CORE_TEXT_IS_FONT_MAP
-PANGO_IS_CAIRO_CORE_TEXT_FONT_CLASS
-PANGO_IS_CAIRO_CORE_TEXT_FONT_MAP
-PANGO_IS_CORE_TEXT_FONT
-PANGO_IS_CORE_TEXT_FONT_CLASS
-PANGO_IS_CORE_TEXT_FONT_MAP_CLASS
-PANGO_TYPE_CAIRO_CORE_TEXT_FONT
-PANGO_TYPE_CAIRO_CORE_TEXT_FONT_MAP
-PANGO_TYPE_CORE_TEXT_FONT
-PANGO_TYPE_CORE_TEXT_FONT_MAP
-PangoCairoCoreTextFont
-PangoCairoCoreTextFontClass
-PangoCairoCoreTextFontMap
-PangoCoreTextFace
-PangoCoreTextFamily
-PangoCoreTextFont
-PangoCoreTextFontClass
-PangoCoreTextFontMap
-PangoCoreTextFontMapClass
-PangoCoreTextFontPrivate
-pango_cairo_core_text_font_get_type
-pango_cairo_core_text_font_map_get_type
-pango_core_text_font_get_type
-pango_core_text_font_map_get_type
-</SECTION>
-
-<SECTION>
-<FILE>pangofc-fontmap</FILE>
-<TITLE>PangoFcFontMap</TITLE>
-PangoFcFontMap
-PangoFcFontMapClass
-pango_fc_font_map_create_context
-PangoFcDecoderFindFunc
-pango_fc_font_map_add_decoder_find_func
-pango_fc_font_map_find_decoder
-pango_fc_font_map_cache_clear
-pango_fc_font_map_config_changed
-pango_fc_font_map_shutdown
-pango_fc_font_map_set_config
-pango_fc_font_map_get_config
-PangoFcSubstituteFunc
-pango_fc_font_map_set_default_substitute
-pango_fc_font_map_substitute_changed
-pango_fc_font_description_from_pattern
-PANGO_FC_FONT_FEATURES
-PANGO_FC_GRAVITY
-PANGO_FC_VERSION
-PANGO_FC_PRGNAME
-PANGO_FC_FONT_VARIATIONS
-<SUBSECTION Standard>
-PANGO_FC_FONT_MAP
-PANGO_IS_FC_FONT_MAP
-PANGO_TYPE_FC_FONT_MAP
-PANGO_FC_FONT_MAP_CLASS
-PANGO_IS_FC_FONT_MAP_CLASS
-PANGO_FC_FONT_MAP_GET_CLASS
-
-<SUBSECTION Private>
-PangoFcFontMapPrivate
-pango_fc_font_map_get_type
-</SECTION>
-
-
-<SECTION>
-<FILE>pangofc-font</FILE>
-<TITLE>PangoFcFont</TITLE>
-PangoFcFont
-PangoFcFontClass
-pango_fc_font_lock_face
-pango_fc_font_unlock_face
-pango_fc_font_has_char
-pango_fc_font_get_glyph
-pango_fc_font_get_unknown_glyph
-pango_fc_font_kern_glyphs
-pango_fc_font_get_languages
-pango_fc_font_get_pattern
-<SUBSECTION Standard>
-PANGO_FC_FONT
-PANGO_IS_FC_FONT
-PANGO_TYPE_FC_FONT
-PANGO_FC_FONT_CLASS
-PANGO_IS_FC_FONT_CLASS
-PANGO_FC_FONT_GET_CLASS
-<SUBSECTION Private>
-pango_fc_font_get_type
-</SECTION>
-
-<SECTION>
-<FILE>pangofc-decoder</FILE>
-<TITLE>PangoFcDecoder</TITLE>
-PangoFcDecoder
-PangoFcDecoderClass
-pango_fc_decoder_get_charset
-pango_fc_decoder_get_glyph
-<SUBSECTION Standard>
-PANGO_FC_DECODER
-PANGO_IS_FC_DECODER
-PANGO_TYPE_FC_DECODER
-pango_fc_decoder_get_type
-PANGO_FC_DECODER_CLASS
-PANGO_IS_FC_DECODER_CLASS
-PANGO_FC_DECODER_GET_CLASS
-</SECTION>
-
-<SECTION>
-<TITLE>OpenType Font Handling</TITLE>
-<FILE>opentype</FILE>
-PangoOTTag
-PangoOTInfo
-PangoOTBuffer
-PangoOTGlyph
-PangoOTRuleset
-PangoOTRulesetDescription
-PangoOTTableType
-PangoOTFeatureMap
-PANGO_OT_TAG_MAKE
-PANGO_OT_TAG_MAKE_FROM_STRING
-PANGO_OT_ALL_GLYPHS
-PANGO_OT_NO_FEATURE
-PANGO_OT_NO_SCRIPT
-PANGO_OT_DEFAULT_LANGUAGE
-PANGO_OT_TAG_DEFAULT_LANGUAGE
-PANGO_OT_TAG_DEFAULT_SCRIPT
-pango_ot_info_get
-pango_ot_info_find_script
-pango_ot_info_find_language
-pango_ot_info_find_feature
-pango_ot_info_list_scripts
-pango_ot_info_list_languages
-pango_ot_info_list_features
-pango_ot_buffer_new
-pango_ot_buffer_destroy
-pango_ot_buffer_clear
-pango_ot_buffer_add_glyph
-pango_ot_buffer_set_rtl
-pango_ot_buffer_set_zero_width_marks
-pango_ot_buffer_get_glyphs
-pango_ot_buffer_output
-pango_ot_ruleset_get_for_description
-pango_ot_ruleset_new
-pango_ot_ruleset_new_for
-pango_ot_ruleset_new_from_description
-pango_ot_ruleset_add_feature
-pango_ot_ruleset_maybe_add_feature
-pango_ot_ruleset_maybe_add_features
-pango_ot_ruleset_get_feature_count
-pango_ot_ruleset_substitute
-pango_ot_ruleset_position
-pango_ot_ruleset_description_copy
-pango_ot_ruleset_description_equal
-pango_ot_ruleset_description_free
-pango_ot_ruleset_description_hash
-pango_ot_tag_from_language
-pango_ot_tag_from_script
-pango_ot_tag_to_language
-pango_ot_tag_to_script
-
-<SUBSECTION Standard>
-PANGO_IS_OT_INFO
-PANGO_IS_OT_RULESET
-PANGO_OT_INFO
-PANGO_OT_RULESET
-PANGO_TYPE_OT_INFO
-PANGO_TYPE_OT_RULESET
-pango_ot_info_get_type
-pango_ot_ruleset_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Miscellaneous Utilities</TITLE>
-<FILE>utils</FILE>
-pango_split_file_list
-pango_trim_string
-pango_read_line
-pango_skip_space
-pango_scan_word
-pango_scan_string
-pango_scan_int
-pango_parse_enum
-pango_parse_style
-pango_parse_variant
-pango_parse_weight
-pango_parse_stretch
-pango_log2vis_get_embedding_levels
-pango_is_zero_width
-pango_quantize_line_geometry
-</SECTION>
-
-<SECTION>
-<TITLE>Version Checking</TITLE>
-<FILE>pango-version</FILE>
-PANGO_VERSION_ENCODE
-PANGO_VERSION
-PANGO_VERSION_MAJOR
-PANGO_VERSION_MINOR
-PANGO_VERSION_MICRO
-PANGO_VERSION_STRING
-PANGO_VERSION_CHECK
-pango_version
-pango_version_string
-pango_version_check
-PANGO_VERSION_1_2
-PANGO_VERSION_1_4
-PANGO_VERSION_1_6
-PANGO_VERSION_1_8
-PANGO_VERSION_1_10
-PANGO_VERSION_1_12
-PANGO_VERSION_1_14
-PANGO_VERSION_1_16
-PANGO_VERSION_1_18
-PANGO_VERSION_1_20
-PANGO_VERSION_1_22
-PANGO_VERSION_1_24
-PANGO_VERSION_1_26
-PANGO_VERSION_1_28
-PANGO_VERSION_1_30
-PANGO_VERSION_1_32
-PANGO_VERSION_1_34
-PANGO_VERSION_1_36
-PANGO_VERSION_1_38
-PANGO_VERSION_1_40
-PANGO_VERSION_1_42
-PANGO_VERSION_1_44
-PANGO_VERSION_MIN_REQUIRED
-PANGO_VERSION_MAX_ALLOWED
-<SUBSECTION Private>
-PANGO_UNAVAILABLE
-PANGO_AVAILABLE_IN_ALL
-PANGO_VERSION_CUR_STABLE
-PANGO_VERSION_PREV_STABLE
-PANGO_AVAILABLE_IN_1_2
-PANGO_AVAILABLE_IN_1_4
-PANGO_AVAILABLE_IN_1_6
-PANGO_AVAILABLE_IN_1_8
-PANGO_AVAILABLE_IN_1_10
-PANGO_AVAILABLE_IN_1_12
-PANGO_AVAILABLE_IN_1_14
-PANGO_AVAILABLE_IN_1_16
-PANGO_AVAILABLE_IN_1_18
-PANGO_AVAILABLE_IN_1_20
-PANGO_AVAILABLE_IN_1_22
-PANGO_AVAILABLE_IN_1_24
-PANGO_AVAILABLE_IN_1_26
-PANGO_AVAILABLE_IN_1_28
-PANGO_AVAILABLE_IN_1_30
-PANGO_AVAILABLE_IN_1_32
-PANGO_AVAILABLE_IN_1_34
-PANGO_AVAILABLE_IN_1_36
-PANGO_AVAILABLE_IN_1_38
-PANGO_AVAILABLE_IN_1_40
-PANGO_AVAILABLE_IN_1_42
-PANGO_AVAILABLE_IN_1_44
-PANGO_DEPRECATED
-PANGO_DEPRECATED_FOR
-PANGO_DEPRECATED_IN_1_2
-PANGO_DEPRECATED_IN_1_2_FOR
-PANGO_DEPRECATED_IN_1_4
-PANGO_DEPRECATED_IN_1_4_FOR
-PANGO_DEPRECATED_IN_1_6
-PANGO_DEPRECATED_IN_1_6_FOR
-PANGO_DEPRECATED_IN_1_8
-PANGO_DEPRECATED_IN_1_8_FOR
-PANGO_DEPRECATED_IN_1_10
-PANGO_DEPRECATED_IN_1_10_FOR
-PANGO_DEPRECATED_IN_1_12
-PANGO_DEPRECATED_IN_1_12_FOR
-PANGO_DEPRECATED_IN_1_14
-PANGO_DEPRECATED_IN_1_14_FOR
-PANGO_DEPRECATED_IN_1_16
-PANGO_DEPRECATED_IN_1_16_FOR
-PANGO_DEPRECATED_IN_1_18
-PANGO_DEPRECATED_IN_1_18_FOR
-PANGO_DEPRECATED_IN_1_20
-PANGO_DEPRECATED_IN_1_20_FOR
-PANGO_DEPRECATED_IN_1_22
-PANGO_DEPRECATED_IN_1_22_FOR
-PANGO_DEPRECATED_IN_1_24
-PANGO_DEPRECATED_IN_1_24_FOR
-PANGO_DEPRECATED_IN_1_26
-PANGO_DEPRECATED_IN_1_26_FOR
-PANGO_DEPRECATED_IN_1_28
-PANGO_DEPRECATED_IN_1_28_FOR
-PANGO_DEPRECATED_IN_1_30
-PANGO_DEPRECATED_IN_1_30_FOR
-PANGO_DEPRECATED_IN_1_32
-PANGO_DEPRECATED_IN_1_32_FOR
-PANGO_DEPRECATED_IN_1_34
-PANGO_DEPRECATED_IN_1_34_FOR
-PANGO_DEPRECATED_IN_1_36
-PANGO_DEPRECATED_IN_1_36_FOR
-PANGO_DEPRECATED_IN_1_38
-PANGO_DEPRECATED_IN_1_38_FOR
-PANGO_DEPRECATED_IN_1_40
-PANGO_DEPRECATED_IN_1_40_FOR
-PANGO_DEPRECATED_IN_1_42
-PANGO_DEPRECATED_IN_1_42_FOR
-PANGO_DEPRECATED_IN_1_44
-PANGO_DEPRECATED_IN_1_44_FOR
-</SECTION>
-
-<SECTION>
-<TITLE>Vertical Text</TITLE>
-<FILE>vertical</FILE>
-PangoGravity
-PangoGravityHint
-PANGO_GRAVITY_IS_IMPROPER
-PANGO_GRAVITY_IS_VERTICAL
-pango_gravity_get_for_matrix
-pango_gravity_get_for_script
-pango_gravity_get_for_script_and_width
-pango_gravity_to_rotation
-<SUBSECTION Standard>
-PANGO_TYPE_GRAVITY
-PANGO_TYPE_GRAVITY_HINT
-<SUBSECTION Private>
-pango_gravity_get_type
-pango_gravity_hint_get_type
-</SECTION>
-
-<SECTION>
-<TITLE>Bidirectional Text</TITLE>
-<FILE>bidi</FILE>
-PangoDirection
-pango_unichar_direction
-pango_find_base_dir
-pango_get_mirror_char
-PangoBidiType
-pango_bidi_type_for_unichar
-<SUBSECTION Standard>
-PANGO_TYPE_BIDI_TYPE
-<SUBSECTION Private>
-pango_bidi_type_get_type
-pango_direction_get_type
-</SECTION>
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
new file mode 100644
index 00000000..3b7c9a0b
--- /dev/null
+++ b/docs/pango.toml.in
@@ -0,0 +1,73 @@
+[library]
+namespace = "Pango"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "Internationalized text layout and rendering"
+dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "PangoCairo-1.0",
+                 "PangoFc-1.0", "PangoFT2-1.0", "PangoOT-1.0",
+                 "PangoXft-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies."HarfBuzz-0.0"]
+  name = "HarfBuzz"
+  description = "A text shaping library"
+  docs_url = "https://harfbuzz.github.io/"
+
+  [dependencies."PangoCairo-1.0"]
+  name = "PangoCairo"
+  description = "Cairo support for Pango"
+  docs_url = "../PangoCairo/"
+
+  [dependencies."PangoFc-1.0"]
+  name = "PangoFc"
+  description = "Fontconfig support for Pango"
+  docs_url = "../PangoFc/"
+
+  [dependencies."PangoFT2-1.0"]
+  name = "PangoFT2"
+  description = "Freetype support for Pango"
+  docs_url = "../PangoFT2/"
+
+  [dependencies."PangoOT-1.0"]
+  name = "PangoOT"
+  description = "OpenType support for Pango"
+  docs_url = "../PangoOT/"
+
+  [dependencies."PangoXft-1.0"]
+  name = "PangoXft"
+  description = "Xft support for Pango"
+  docs_url = "../PangoXft/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+content_files = [
+  "pango_rendering.md",
+  "pango_markup.md",
+  "pango_fonts.md",
+  "pango_bidi.md",
+]
+
+content_images = [
+  "pango-name.png",
+  "layout.png",
+  "pipeline.png",
+  "rects1.png",
+  "rects2.png"
+]
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
new file mode 100644
index 00000000..27005caa
--- /dev/null
+++ b/docs/pango_bidi.md
@@ -0,0 +1,58 @@
+---
+Title: Bidirectional and Vertical Text
+---
+
+# Bidirectional Text
+
+Pango supports bidirectional text (like Arabic and Hebrew) automatically.
+Some applications however, need some help to correctly handle bidirectional text.
+
+The [enum@Pango.Direction] type can be used with [method@Pango.Context.set_base_dir]
+to instruct Pango about direction of text, though in most cases Pango detects
+that correctly and automatically. For application that need more direct
+control over bidirectional setting of text, Pango provides APIs such as
+[func@unichar_direction], [func@find_base_dir], [func@get_mirror_char]
+or [type_func@Pango.BidiType.for_unichar].
+
+# Vertical Text
+
+Pango is not only capable of vertical text layout, it can handle mixed vertical
+and non-vertical text correctly. This section describes the types used for setting
+vertical text parameters.
+
+The way this is implemented is through the concept of *gravity*. Gravity of
+normal Latin text is south. A gravity value of east means that glyphs will be
+rotated ninety degrees counterclockwise. So, to render vertical text one needs
+to set the gravity and rotate the layout using the matrix machinery already
+in place. This has the huge advantage that most algorithms working on a
+[class@Pango.Layout] do not need any change as the assumption that lines run
+in the X direction and stack in the Y direction holds even for vertical text
+layouts.
+
+Applications should only need to set base gravity on [class@Pango.Context] in use,
+and let Pango decide the gravity assigned to each run of text. This automatically
+handles text with mixed scripts. A very common use is to set the context base
+gravity to auto using [method@Pango.Context.set_base_gravity] and rotate the layout
+normally. Pango will make sure that Asian languages take the right form, while
+other scripts are rotated normally.
+
+The correct way to set gravity on a layout is to set it on the context associated
+with it using [method@Pango.Context.set_base_gravity]. The context of a layout can
+be accessed using [method@Pango.Layout.get_context]. The currently set base gravity
+of the context can be accessed using [method@Pango.Context.get_base_gravity] and the
+*resolved* gravity of it using [method@Pango.Context.get_gravity]. The resolved
+gravity is the same as the base gravity for the most part, except that if the base
+gravity is set to `PANGO_GRAVITY_AUTO`, the resolved gravity will depend on the
+current matrix set on context, and is derived using [type_func@Pango.Gravity.get_for_matrix].
+
+The next thing an application may want to set on the context is the *gravity hint*.
+A [enum@Pango.GravityHint] instructs how different scripts should react to the set
+base gravity.
+
+Font descriptions have a gravity property too, that can be set using
+[method@Pango.FontDescription.set_gravity] and accessed using
+[method@Pango.FontDescription.get_gravity]. However, those are rarely useful
+from application code and are mainly used by `PangoLayout` internally.
+
+Last but not least, one can create `PangoAttributes` for gravity and gravity
+hint using [func@attr_gravity_new] and [func@attr_gravity_hint_new].
diff --git a/docs/pango_cairo.md b/docs/pango_cairo.md
new file mode 100644
index 00000000..2edd8ba8
--- /dev/null
+++ b/docs/pango_cairo.md
@@ -0,0 +1,129 @@
+---
+Title: Rendering with Cairo
+---
+
+# Rendering with Cairo
+
+The Cairo library is a vector graphics library with a powerful rendering model.
+It has such features as anti-aliased primitives, alpha-compositing, and gradients.
+Multiple backends for Cairo are available, to allow rendering to images, to PDF
+files, and to the screen on X and on other windowing systems. The functions in
+this section allow using Pango to render to Cairo surfaces.
+
+Using Pango with Cairo is straightforward. A `PangoContext` created with
+pango_cairo_font_map_create_context() can be used on any Cairo context (`cairo_t`),
+but needs to be updated to match the current transformation matrix and target
+surface of the Cairo context using pango_cairo_update_context(). The convenience
+functions pango_cairo_create_layout() and pango_cairo_update_layout() handle
+the common case where the program doesn't need to manipulate the properties of
+the `PangoContext`.
+
+When you get the metrics of a layout or of a piece of a layout using functions
+such as pango_layout_get_extents(), the reported metrics are in user-space
+coordinates. If a piece of text is 10 units long, and you call
+`cairo_scale (cr, 2.0)`, it still is more-or-less 10 units long. However, the
+results will be affected by hinting (that is, the process of adjusting the text
+to look good on the pixel grid), so you shouldn't assume they are completely
+independent of the current transformation matrix. Note that the basic metrics
+functions in Pango report results in integer Pango units. To get to the floating
+point units used in Cairo divide by `PANGO_SCALE`.
+
+## Using Pango with Cairo
+
+```
+#include <math.h>
+#include <pango/pangocairo.h>
+
+#define RADIUS 150
+#define N_WORDS 10
+#define FONT "Sans Bold 27"
+
+static void
+draw_text (cairo_t *cr)
+{
+  PangoLayout *layout;
+  PangoFontDescription *desc;
+  int i;
+
+  /* Center coordinates on the middle of the region we are drawing */
+  cairo_translate (cr, RADIUS, RADIUS);
+
+  /* Create a PangoLayout, set the font and text */
+  layout = pango_cairo_create_layout (cr);
+
+  pango_layout_set_text (layout, "Text", -1);
+  desc = pango_font_description_from_string (FONT);
+  pango_layout_set_font_description (layout, desc);
+  pango_font_description_free (desc);
+
+  /* Draw the layout N_WORDS times in a circle */
+  for (i = 0; i < N_WORDS; i++)
+    {
+      int width, height;
+      double angle = (360. * i) / N_WORDS;
+      double red;
+
+      cairo_save (cr);
+
+      /* Gradient from red at angle == 60 to blue at angle == 240 */
+      red   = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
+      cairo_set_source_rgb (cr, red, 0, 1.0 - red);
+
+      cairo_rotate (cr, angle * G_PI / 180.);
+
+      /* Inform Pango to re-layout the text with the new transformation */
+      pango_cairo_update_layout (cr, layout);
+
+      pango_layout_get_size (layout, &width, &height);
+      cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
+      pango_cairo_show_layout (cr, layout);
+
+      cairo_restore (cr);
+    }
+
+  /* free the layout object */
+  g_object_unref (layout);
+}
+
+int
+main (int argc, char **argv)
+{
+  cairo_t *cr;
+  char *filename;
+  cairo_status_t status;
+  cairo_surface_t *surface;
+
+  if (argc != 2)
+    {
+      g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
+      return 1;
+    }
+
+  filename = argv[1];
+
+  surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+                                        2 * RADIUS, 2 * RADIUS);
+  cr = cairo_create (surface);
+
+  cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
+  cairo_paint (cr);
+  draw_text (cr);
+  cairo_destroy (cr);
+
+  status = cairo_surface_write_to_png (surface, filename);
+  cairo_surface_destroy (surface);
+
+  if (status != CAIRO_STATUS_SUCCESS)
+    {
+      g_printerr ("Could not save png to '%s'\n", filename);
+      return 1;
+    }
+
+  return 0;
+}
+```
+
+Once you build and run the example code above, you should see the
+following result:
+
+![Output of rotated-example](rotated-text.png)
diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md
new file mode 100644
index 00000000..776dba71
--- /dev/null
+++ b/docs/pango_fonts.md
@@ -0,0 +1,65 @@
+---
+Title: Fonts and Glyphs
+---
+
+# Fonts
+
+Pango supports a flexible architecture where a particular rendering architecture
+can supply an implementation of fonts. The `PangoFont` structure represents an
+abstract rendering-system-independent font. Pango provides routines to list
+available fonts, and to load a font matching a given description.
+
+Conceptually, Pango groups fonts into faces and families which are identified
+by a name. A *font face* provides the different sizes of a single font style.
+A *font family* provides the available styles of a font.
+
+As an example, "Helvetica" is a family, "Helvetica Bold" is a face of this
+family, and "Helvetica Bold 12pt" is a concrete font of this face.
+
+# Font Enumeration
+
+The central object for dealing with the available fonts on a system and caching
+loaded fonts is a [class@Pango.FontMap]. An application typically uses a single
+font map.
+
+Since the font map depends on the rendering architecture in use, you'll need to
+use the backend function pango_cairo_font_map_get_default() to obtain the default
+fontmap. Depending on the platform, it will return a `PangoCairoFcFontMap`, a
+`PangoCairoWin32FontMap` or a `PangoCairoCoreTextFontMap`.
+
+Once you have a fontmap, you can enumerate the available font families with
+[method@Pango.FontMap.list_families]. To enumerate the faces of a font family,
+use [method@Pango.FontFamily.list_faces].
+
+# Font Descriptions
+
+Since loading fonts uses system resources, Pango provides a way to describe
+a font without loading it. A [struct@Pango.FontDescription] is a struct that
+contains enough information to load a concrete font with
+[method@Pango.FontMap.load_font] or [method@Pango.Context.load_font]. You can
+obtain a font description from a font face using [method@Pango.FontFace.describe],
+or by parsing a string such as
+
+    Helvetica Bold 12pt
+
+with [type_func@Pango.FontDescription.from_string].
+
+# Glyphs
+
+A font provides information about glyphs and how to position and render them.
+The Pango rendering pipeline uses this information to create a
+[struct@Pango.GlyphString], which contains the glyphs corresponding to the
+characters in the text and related information such as glyph positions and sizes,
+and clustering information (i.e. which glyphs correspond to which characters).
+
+![A glyph string](rects3.png)
+
+A glyph is identified by a [alias@Pango.Glyph], which is a numeric ID. Note that
+glyph IDs are font-specific: the same character can be represented by diffferent
+glyph IDs in different fonts.
+
+The mapping between characters and glyphs is in general neither 1-1 nor a map:
+a single glyph may represent multiple characters (as is the case with ligatures),
+a single character may be represented by multiple glyphs (for example, when
+combining accents and base character), and in complex scripts, multiple characters
+may form clusters that get rearranged and represented by multiple glyphs.
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
new file mode 100644
index 00000000..dc6047d3
--- /dev/null
+++ b/docs/pango_markup.md
@@ -0,0 +1,184 @@
+---
+Title: Text Attributes and Markup
+---
+
+# Text Attributes
+
+Attributed text is used in a number of places in Pango. It is used as the
+input to the itemization process and also when creating a [class@Pango.Layout].
+
+Attributes can influence the various stages of the rendering pipeline. For example,
+font or size attributes will influence the font selection that is happening during
+itemization, font features and letterspacing attributes will influence shaping, and
+color or underline attributes will be used for rendering.
+
+Pango uses a simple structs for individual attributes, such as
+[struct@Pango.AttrColor] or [struct@Pango.AttrFontDesc]. Each attribute has a type,
+and a start and end index that determine the range of characters that the attribute
+applies to. See the [enum@Pango.AttrType] enumeration for all the possible
+attribute types.
+
+Attributes rarely come alone. Pango uses the [struct@Pango.AttrList] structure
+to hold all attributes that apply to a piece of text.
+
+# Pango Markup
+
+Frequently, you want to display some text to the user with attributes applied to
+part of the text (for example, you might want bold or italicized words). With the
+base Pango interfaces, you could create a [struct@Pango.AttrList] and apply it to
+the text; the problem is that you'd need to apply attributes to some numeric range
+of characters, for example "characters 12-17." This is broken from an
+internationalization standpoint; once the text is translated, the word you wanted
+to italicize could be in a different position.
+
+The solution is to include the text attributes in the string to be translated.
+Pango provides this feature with a small markup language. You can parse a marked-up
+string into the string text plus a [struct@Pango.AttrList] using either of
+[func@parse_markup] or [func@markup_parser_new].
+
+A simple example of a marked-up string might be:
+
+```
+<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"
+```
+
+Pango uses GMarkup to parse this language, which means that XML features
+such as numeric character entities such as `&#169;` for © can be used too.
+
+The root tag of a marked-up document is `<markup>`, but pango_parse_markup()
+allows you to omit this tag, so you will most likely never need to use it.
+The most general markup tag is `<span>`, then there are some convenience
+tags.
+
+## The `<span>` Attributes
+
+font
+font_desc
+: A font description string, such as "Sans Italic 12". See
+  pango_font_description_from_string() for a description of the format of
+  the string representation. Note that any other span attributes will override
+  this description. So if you have "Sans Italic" and also a style="normal"
+  attribute, you will get Sans normal, not italic.
+
+font_family
+face
+: A font family name.
+
+font_size
+size
+: Font size in 1024ths of a point, or one of the absolute sizes 'xx-small',
+  'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the
+  relative sizes 'smaller' or 'larger'. If you want to specify a absolute size,
+  it's usually easier to take advantage of the ability to specify a partial font
+  description using 'font'; you can use font='12.5' rather than size='12800'.
+
+font_style
+style
+: One of 'normal', 'oblique', 'italic'.
+
+font_weight
+weight
+: One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a
+  numeric weight.
+
+font_variant
+variant
+: One of 'normal' or 'smallcaps'.
+
+font_stretch
+stretch
+: One of 'ultracondensed', 'extracondensed',
+  'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded',
+  'extraexpanded', 'ultraexpanded'.
+
+font_features
+: A comma-separated list of OpenType font feature settings, in the same syntax as
+  accepted by CSS. E.g: `font_features='dlig=1, -kern, afrc on'`.
+
+foreground
+fgcolor
+color
+: An RGB color specification such as '#00FF00' or a color name such as 'red'.
+  Since 1.38, an RGBA color specification such as '#00FF007F' will be interpreted
+  as specifying both a foreground color and foreground alpha.
+
+background
+bgcolor
+: An RGB color specification such as '#00FF00' or a color name such as 'red'.
+  Since 1.38, an RGBA color specification such as '#00FF007F' will be interpreted
+  as specifying both a background color and background alpha.
+
+alpha
+fgalpha
+: An alpha value for the foreground color, either a plain integer between 1 and
+  65536 or a percentage value like '50%'.
+
+background_alpha
+bgalpha
+: An alpha value for the background color, either a plain integer between 1 and
+  65536 or a percentage value like '50%'.
+
+underline
+: One of 'none', 'single', 'double', 'low', 'error'.
+
+underline_color
+: The color of underlines; an RGB color specification such as '#00FF00' or a color
+  name such as 'red'.
+
+rise
+: Vertical displacement, in Pango units. Can be negative for subscript, positive
+  for superscript.
+
+strikethrough
+: 'true' or 'false' whether to strike through the text.
+
+strikethrough_color
+: The color of strikethrough lines; an RGB color specification such as '#00FF00'
+  or a color name such as 'red'.
+
+fallback
+: 'true' or 'false' whether to enable fallback. If disabled, then characters will
+  only be used from the closest matching font on the system. No fallback will be
+  done to other fonts on the system that might contain the characters in the text.
+  Fallback is enabled by default. Most applications should not disable fallback.
+
+lang
+: A language code, indicating the text language.
+
+letter_spacing
+: Inter-letter spacing in 1024ths of a point.
+
+gravity
+: One of 'south', 'east', 'north', 'west', 'auto'.
+
+gravity_hint
+: One of 'natural', 'strong', 'line'.
+
+## Convenience Tags
+
+`<b>`
+: Bold
+
+`<big>`
+: Makes font relatively larger, equivalent to `<span size="larger">`
+
+`<i>`
+: Italic
+
+`<s>`
+: Strikethrough
+
+`<sub>`
+: Subscript
+
+`<sup>`
+: Superscript
+
+`<small>`
+: Makes font relatively smaller, equivalent to `<span size="smaller">`
+
+`<tt>`
+: Monospace font
+
+`<u>`
+: Underline
diff --git a/docs/pango_markup.sgml b/docs/pango_markup.sgml
deleted file mode 100644
index c2ba377c..00000000
--- a/docs/pango_markup.sgml
+++ /dev/null
@@ -1,301 +0,0 @@
-<refentry id="PangoMarkupFormat" revision="11 Dec 2002">
-<refmeta>
-<refentrytitle>Text Attribute Markup</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Pango Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Text Attribute Markup</refname><refpurpose>Simple
-markup language to encode text with attributes</refpurpose>
-</refnamediv>
-
-<refsect1 id="PangoMarkupFormatLanguage">
-<title>Pango Text Attribute Markup Language</title>
-
-<para>
-Frequently, you want to display some text to the user with attributes
-applied to part of the text (for example, you might want bold or
-italicized words). With the base Pango interfaces, you could create a
-<link linkend="PangoAttrList">PangoAttrList</link> and apply it to the
-text; the problem is that you'd need to apply attributes to some
-numeric range of characters, for example "characters 12-17." This is
-broken from an internationalization standpoint; once the text is
-translated, the word you wanted to italicize could be in a different
-position.
-</para>
-
-<para>
-The solution is to include the text attributes in the string to be
-translated. Pango provides this feature with a small markup language.
-You can parse a marked-up string into the string text plus a
-<link linkend="PangoAttrList">PangoAttrList</link> using either of
-<link linkend="pango-parse-markup">pango_parse_markup()</link> or
-<link linkend="pango-markup-parser-new">pango_markup_parser_new()</link>.
-</para>
-
-<para>
-A simple example of a marked-up string might be:
-<literal>"&lt;span foreground="blue" size="x-large"&gt;Blue text&lt;/span&gt; is &lt;i&gt;cool&lt;/i&gt;!"</literal>
-</para>
-
-<para>
-Pango uses #GMarkup to parse this language, which means that XML features
-such as numeric character entities such as &amp;#169; for &#169; can
-be used too.
-</para>
-
-<para>
-The root tag of a marked-up document is &lt;markup&gt;, but <link
-linkend="pango-parse-markup">pango_parse_markup()</link> allows you to
-omit this tag, so you will most likely never need to use it. The most
-general markup tag is &lt;span&gt;, then there are some convenience
-tags. &lt;span&gt; has the following attributes:
-<variablelist><title>&lt;span&gt; attributes</title>
-
-<varlistentry>
-<term>font<footnote id='since_1_21'><para>Since 1.21</para></footnote></term>
-<term>font_desc</term>
-<listitem><para>
-A font description string, such as "Sans Italic 12". See
-<link linkend="pango-font-description-from-string">pango_font_description_from_string()</link>
-for a description of the format of the string representation . Note that any 
-other span attributes will override this description. So if you have 
-"Sans Italic" and also a style="normal" attribute, you will get Sans normal, 
-not italic.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_family</term>
-<term>face</term>
-<listitem><para>
-A font family name
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_size<footnoteref linkend='since_1_21'/></term>
-<term>size</term>
-<listitem><para>
-Font size in 1024ths of a point, or one of the absolute sizes 
-'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
-'xx-large', or one of the relative sizes 'smaller' or 'larger'.
-If you want to specify a absolute size, it's usually easier
-to take advantage of the ability to specify a partial
-font description using 'font'; you can use
-<literal>font='12.5'</literal> rather than
-<literal>size='12800'</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_style<footnoteref linkend='since_1_21'/></term>
-<term>style</term>
-<listitem><para>
-One of 'normal', 'oblique', 'italic'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_weight<footnoteref linkend='since_1_21'/></term>
-<term>weight</term>
-<listitem><para>
-One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy',
-or a numeric weight
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_variant<footnoteref linkend='since_1_21'/></term>
-<term>variant</term>
-<listitem><para>
-One of 'normal' or 'smallcaps'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_stretch<footnoteref linkend='since_1_21'/></term>
-<term>stretch</term>
-<listitem><para>
-One of 'ultracondensed', 'extracondensed', 'condensed',
-'semicondensed', 'normal', 'semiexpanded', 'expanded',
-'extraexpanded', 'ultraexpanded'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_features<footnote id='since_1_38'><para>Since 1.38</para></footnote></term>
-<listitem><para>
-A comma separated list of OpenType font feature settings, in the same
-syntax as accepted by CSS. E.g: <literal>font_features='dlig=1, -kern, afrc on'</literal>
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>foreground</term>
-<term>fgcolor<footnoteref linkend='since_1_21'/></term>
-<term>color</term>
-<listitem><para>
-An RGB color specification such as '#00FF00' or a color name such as
-'red'.
-Since 1.38, an RGBA color specification such as '#00FF007F' will
-be interpreted as specifying both a foreground color and foreground alpha.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>background</term>
-<term>bgcolor<footnoteref linkend='since_1_21'/></term>
-<listitem><para>
-An RGB color specification such as '#00FF00' or a color name such as
-'red'.
-Since 1.38, an RGBA color specification such as '#00FF007F' will
-be interpreted as specifying both a background color and background alpha.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>alpha</term>
-<term>fgalpha<footnoteref linkend='since_1_38'/></term>
-<listitem><para>
-An alpha value for the foreground color, either a plain integer between 1 and 65536
-or a percentage value like '50%'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>background_alpha</term>
-<term>bgalpha<footnoteref linkend='since_1_38'/></term>
-<listitem><para>
-An alpha value for the background color, either a plain integer between 1 and 65536
-or a percentage value like '50%'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>underline</term>
-<listitem><para>
-One of 'none', 'single', 'double', 'low', 'error'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>underline_color</term>
-<listitem><para>
-The color of underlines; an RGB color specification such as '#00FF00'
-or a color name such as 'red'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>rise</term>
-<listitem><para>
-Vertical displacement, in Pango units. Can be negative for 
-subscript, positive for superscript.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>strikethrough</term>
-<listitem><para>
-'true' or 'false' whether to strike through the text
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>strikethrough_color</term>
-<listitem><para>
-The color of strikethrough lines; an RGB color specification such as
-'#00FF00' or a color name such as 'red'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>fallback</term>
-<listitem><para>
-'true' or 'false' whether to enable fallback. If disabled, then characters
-will only be used from the closest matching font on the system. No fallback
-will be done to other fonts on the system that might contain the characters
-in the text.  Fallback is enabled by default. Most applications should not
-disable fallback.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>lang</term>
-<listitem><para>
-A language code, indicating the text language
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>letter_spacing</term>
-<listitem><para>
-Inter-letter spacing in 1024ths of a point.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>gravity</term>
-<listitem><para>
-One of 'south', 'east', 'north', 'west', 'auto'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>gravity_hint</term>
-<listitem><para>
-One of 'natural', 'strong', 'line'.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</para>
-
-<para>
-The following convenience tags are provided:
-
-<variablelist><title>Convenience tags</title>
-<varlistentry><term>b</term>
-<listitem><para>
-Bold
-</para></listitem>
-</varlistentry>
-<varlistentry><term>big</term>
-<listitem><para>
-Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
-</para></listitem>
-</varlistentry>
-<varlistentry><term>i</term>
-<listitem><para>
-Italic
-</para></listitem>
-</varlistentry>
-<varlistentry><term>s</term>
-<listitem><para>
-Strikethrough
-</para></listitem>
-</varlistentry>
-<varlistentry><term>sub</term>
-<listitem><para>
-Subscript
-</para></listitem>
-</varlistentry>
-<varlistentry><term>sup</term>
-<listitem><para>
-Superscript
-</para></listitem>
-</varlistentry>
-<varlistentry><term>small</term>
-<listitem><para>
-Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
-</para></listitem>
-</varlistentry>
-<varlistentry><term>tt</term>
-<listitem><para>
-Monospace font
-</para></listitem>
-</varlistentry>
-<varlistentry><term>u</term>
-<listitem><para>
-Underline
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-</para>
-
-</refsect1>
-
-</refentry>
diff --git a/docs/pango_rendering.md b/docs/pango_rendering.md
new file mode 100644
index 00000000..2fd61e93
--- /dev/null
+++ b/docs/pango_rendering.md
@@ -0,0 +1,35 @@
+---
+Title: The Rendering Pipeline
+---
+
+# The Rendering Pipeline
+
+The Pango rendering pipeline takes a string of Unicode characters, converts them
+it into glyphs, and renders them on some output medium. This section describes the
+various stages of this pipeline and the APIs that implement them.
+
+![Pango Rendering Pipeline](pipeline.png)
+
+Itemization
+: breaks a piece of text into segments with consistent direction and shaping
+  properies. Among other things, this determines which font to use for each
+  character. Use pango_itemize() or pango_itemize_with_base_dir() to itemize text.
+
+Shaping
+: converts characters into glyphs. Use pango_shape(), pango_shape_full() or
+  pango_shape_with_flags() to shape text.
+
+Line Breaking
+: determines where line breaks should be inserted into a sequence of glyphs.
+  The function pango_break() determines possible line breaks. The actual line
+  breaking is done by [class@Pango.Layout].
+
+Justification
+: adjusts inter-word spacing to form lines of even length. This is done by
+  [class@Pango.Layout].
+
+Rendering
+: takes a string of positioned glyphs, and renders them onto a surface. This is
+  accomplished by a [class@Pango.Renderer] object. The functions
+  pango_cairo_show_glyph_string() and pango_cairo_show_layout() use a
+  [class@Pango.Renderer] to draw text onto a cairo surface.
diff --git a/docs/pango_xft.md b/docs/pango_xft.md
new file mode 100644
index 00000000..340506d2
--- /dev/null
+++ b/docs/pango_xft.md
@@ -0,0 +1,26 @@
+Title: Xft Fonts and Rendering
+
+The Xft library is a library for displaying fonts on the X window
+system; internally it uses the fontconfig library to locate font
+files, and the FreeType library to load and render fonts. The
+Xft backend is the recommended Pango font backend for screen
+display with X. (The Cairo back end is another possibility.)
+
+Using the Xft backend is generally straightforward;
+[func@PangoXft.get_context] creates a context for a specified display
+and screen. You can then create a [class@Pango.Layout] with that context
+and render it with [func@PangoXft.render_layout]. At a more advanced
+level, the low-level fontconfig options used for rendering fonts
+can be affected using [func@PangoXft.set_default_substitute], and
+[func@PangoXft.substitute_changed].
+
+A range of functions for drawing pieces of a layout, such as individual
+layout lines and glyphs strings are provided.  You can also directly
+create a [class@PangoXft.Renderer]. Finally, in some advanced cases,
+it is useful to derive from [class@PangoXft.Renderer]. Deriving from
+[class@PangoXft.Renderer] is useful for two reasons. One reason is be
+to support custom attributes by overriding `PangoRendererClass` virtual
+functions like 'prepare_run' or 'draw_shape'. The other reason is to
+customize exactly how the final bits are drawn to the destination by
+overriding the `PangoXftRendererClass` virtual functions
+'composite_glyphs' and 'composite_trapezoids'.
diff --git a/docs/pangocairo.toml.in b/docs/pangocairo.toml.in
new file mode 100644
index 00000000..3d41b82f
--- /dev/null
+++ b/docs/pangocairo.toml.in
@@ -0,0 +1,40 @@
+[library]
+namespace = "PangoCairo"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "Cairo support for Pango"
+dependencies = [ "Pango-1.0", "cairo-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "A library for layout out and rendering of text"
+  docs_url = "../Pango/"
+
+  [dependencies."cairo-1.0"]
+  name = "Cairo"
+  description = "A vector graphics library"
+  docs_url = "https://www.cairographics.org/manual/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+content_files = [
+  "pango_cairo.md",
+]
+
+content_images = [
+  "pango-name.png",
+  "rotated-text.png"
+]
diff --git a/docs/pangofc.toml.in b/docs/pangofc.toml.in
new file mode 100644
index 00000000..061ff072
--- /dev/null
+++ b/docs/pangofc.toml.in
@@ -0,0 +1,36 @@
+[library]
+namespace = "PangoFc"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "Fontconfig support for Pango"
+dependencies = [ "Pango-1.0", "fontconfig-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "A library for layout out and rendering of text"
+  docs_url = "../Pango/"
+
+  [dependencies."fontconfig-2.0"]
+  name = "Fontconfig"
+  description = "A font configuration and enumeration library"
+  docs_url = "https://www.fontconfig.org"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+
+content_images = [
+  "pango-name.png"
+]
diff --git a/docs/pangoft2.toml.in b/docs/pangoft2.toml.in
new file mode 100644
index 00000000..c44dfe7f
--- /dev/null
+++ b/docs/pangoft2.toml.in
@@ -0,0 +1,36 @@
+[library]
+namespace = "PangoFT2"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "Freetype support for Pango"
+dependencies = [ "Pango-1.0", "freetype2-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "A library for layout out and rendering of text"
+  docs_url = "../Pango/"
+
+  [dependencies."freetype2-2.0"]
+  name = "Freetype"
+  description = "A font loading and rendering library"
+  docs_url = "https://www.freetype.org"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+
+content_images = [
+  "pango-name.png"
+]
diff --git a/docs/pangoot.toml.in b/docs/pangoot.toml.in
new file mode 100644
index 00000000..531cd640
--- /dev/null
+++ b/docs/pangoot.toml.in
@@ -0,0 +1,31 @@
+[library]
+namespace = "PangoOT"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "OpenType support for Pango"
+dependencies = [ "Pango-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "A library for layout out and rendering of text"
+  docs_url = "../Pango/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+
+content_images = [
+  "pango-name.png"
+]
diff --git a/docs/pangoxft.toml.in b/docs/pangoxft.toml.in
new file mode 100644
index 00000000..d117b388
--- /dev/null
+++ b/docs/pangoxft.toml.in
@@ -0,0 +1,39 @@
+[library]
+namespace = "PangoXft"
+version = "@PANGO_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
+website_url = "https://www.pango.org"
+authors = "Owen Taylor, Behdad Esfahbod"
+logo_url = "pango-name.png"
+license = "GPL-2.1-or-later"
+description = "Xft support for Pango"
+dependencies = [ "Pango-1.0", "xft-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "A library for layout out and rendering of text"
+  docs_url = "../Pango/"
+
+  [dependencies."xft-2.0"]
+  name = "Xft"
+  description = "X11 client-side font rendering library"
+  docs_url = "https://x.org"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
+
+[extra]
+content_files = [
+  "pango_xft.md"
+]
+
+content_images = [
+  "pango-name.png"
+]
diff --git a/docs/rects3.png b/docs/rects3.png
new file mode 100644
index 00000000..4817b7af
--- /dev/null
+++ b/docs/rects3.png
diff --git a/docs/version.xml.in b/docs/version.xml.in
deleted file mode 100644
index 8f556477..00000000
--- a/docs/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@PANGO_VERSION@
diff --git a/docs/xml/gtkdocentities.ent.in b/docs/xml/gtkdocentities.ent.in
deleted file mode 100644
index f12c9ff7..00000000
--- a/docs/xml/gtkdocentities.ent.in
+++ /dev/null
@@ -1,8 +0,0 @@
-<!ENTITY package "@PACKAGE@">
-<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
-<!ENTITY package_name "@PACKAGE_NAME@">
-<!ENTITY package_string "@PACKAGE_STRING@">
-<!ENTITY package_tarname "@PACKAGE_TARNAME@">
-<!ENTITY package_url "@PACKAGE_URL@">
-<!ENTITY package_version "@PACKAGE_VERSION@">
-<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
diff --git a/docs/xml/meson.build b/docs/xml/meson.build
deleted file mode 100644
index 2a4cf4b7..00000000
--- a/docs/xml/meson.build
+++ /dev/null
@@ -1,10 +0,0 @@
-ent_conf = configuration_data()
-ent_conf.set('PACKAGE', meson.project_name())
-ent_conf.set('PACKAGE_BUGREPORT', 'https://bugzilla.gnome.org/enter_bug.cgi?product=pango')
-ent_conf.set('PACKAGE_NAME', meson.project_name())
-ent_conf.set('PACKAGE_STRING', meson.project_name())
-ent_conf.set('PACKAGE_TARNAME', '@0@-@1@'.format(meson.project_name(), meson.project_version()))
-ent_conf.set('PACKAGE_URL', 'https://developer.gnome.org/pango/stable')
-ent_conf.set('PACKAGE_VERSION', meson.project_version())
-ent_conf.set('PACKAGE_API_VERSION', pango_api_version)
-configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
diff --git a/meson.build b/meson.build
index 28d9c9ba..f9e63347 100644
--- a/meson.build
+++ b/meson.build
@@ -585,6 +585,10 @@ libsysprof_capture_dep = dependency('sysprof-capture-4',
 pango_conf.set('HAVE_SYSPROF', libsysprof_capture_dep.found())
 pango_deps += libsysprof_capture_dep
 
+gidocgen_dep = dependency('gi-docgen', version: '>= 2021.1',
+                          fallback: ['gi-docgen', 'dummy_dep'],
+                          required: get_option('gtk_doc'))
+
 gnome = import('gnome')
 pkgconfig = import('pkgconfig')
 
diff --git a/pango/break.c b/pango/break.c
index 58bf2f90..35b947c0 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -147,8 +147,9 @@ typedef enum
  * @attrs: logical attributes to fill in
  * @attrs_len: size of the array passed as @attrs
  *
- * This is the default break algorithm. It applies Unicode
- * rules without language-specific tailoring, therefore
+ * This is the default break algorithm.
+ *
+ * It applies Unicode rules without language-specific tailoring, therefore
  * the @analyis argument is unused and can be %NULL.
  *
  * See pango_tailor_break() for language-specific breaks.
@@ -1612,8 +1613,9 @@ tailor_break (const char    *text,
  *             information in
  * @attrs_len: size of the array passed as @attrs
  *
- * Determines possible line, word, and character breaks
- * for a string of Unicode text with a single analysis.
+ * Determines possible line, word, and character breaks for a string of
+ * Unicode text with a single analysis.
+ *
  * For most purposes you may want to use pango_get_log_attrs().
  *
  * Deprecated: 1.44: Use pango_default_break() and pango_tailor_break()
@@ -1641,17 +1643,18 @@ pango_break (const gchar   *text,
  * @next_paragraph_start: (out): return location for start of next
  *   paragraph
  *
- * Locates a paragraph boundary in @text. A boundary is caused by
- * delimiter characters, such as a newline, carriage return, carriage
- * return-newline pair, or Unicode paragraph separator character.  The
- * index of the run of delimiters is returned in
- * @paragraph_delimiter_index. The index of the start of the paragraph
- * (index after all delimiters) is stored in @next_paragraph_start.
+ * Locates a paragraph boundary in @text.
+ *
+ * A boundary is caused by delimiter characters, such as a newline, carriage
+ * return, carriage return-newline pair, or Unicode paragraph separator character.
+ * The index of the run of delimiters is returned in @paragraph_delimiter_index.
+ * The index of the start of the paragrap (index after all delimiters) is stored
+ * in @next_paragraph_start.
  *
  * If no delimiters are found, both @paragraph_delimiter_index and
  * @next_paragraph_start are filled with the length of @text (an index one
  * off the end).
- **/
+ */
 void
 pango_find_paragraph_boundary (const gchar *text,
 			       gint         length,
@@ -1736,16 +1739,16 @@ pango_find_paragraph_boundary (const gchar *text,
  * pango_tailor_break:
  * @text: text to process. Must be valid UTF-8
  * @length: length in bytes of @text
- * @analysis:  #PangoAnalysis structure from pango_itemize() for @text
+ * @analysis: `PangoAnalysis` structure from [func@itemize] for @text
  * @offset: Byte offset of @text from the beginning of the
  *     paragraph, or -1 to ignore attributes from @analysis
- * @log_attrs: (array length=log_attrs_len): array with one #PangoLogAttr
+ * @log_attrs: (array length=log_attrs_len): array with one `PangoLogAttr`
  *   per character in @text, plus one extra, to be filled in
  * @log_attrs_len: length of @log_attrs array
  *
- * Apply language-specific tailoring to the breaks in
- * @log_attrs, which are assumed to have been produced
- * by pango_default_break().
+ * Apply language-specific tailoring to the breaks in @log_attrs.
+ *
+ * The line breaks are assumed to have been produced by [func@default_break].
  *
  * If @offset is not -1, it is used to apply attributes
  * from @analysis that are relevant to line breaking.
@@ -1805,17 +1808,17 @@ tailor_segment (const char      *range_start,
  * @length: length in bytes of @text
  * @level: embedding level, or -1 if unknown
  * @language: language tag
- * @log_attrs: (array length=attrs_len): array with one #PangoLogAttr
+ * @log_attrs: (array length=attrs_len): array with one `PangoLogAttr`
  *   per character in @text, plus one extra, to be filled in
  * @attrs_len: length of @log_attrs array
  *
- * Computes a #PangoLogAttr for each character in @text. The @log_attrs
- * array must have one #PangoLogAttr for each position in @text; if
- * @text contains N characters, it has N+1 positions, including the
- * last position at the end of the text. @text should be an entire
- * paragraph; logical attributes can't be computed without context
- * (for example you need to see spaces on either side of a word to know
- * the word is a word).
+ * Computes a `PangoLogAttr` for each character in @text.
+ *
+ * The @log_attrs array must have one `PangoLogAttr` for each position in @text;
+ * if @text contains N characters, it has N+1 positions, including the last
+ * position at the end of the text. @text should be an entire paragraph; logical
+ * attributes can't be computed without context (for example you need to see
+ * spaces on either side of a word to know the word is a word).
  */
 void
 pango_get_log_attrs (const char    *text,
diff --git a/pango/fonts.c b/pango/fonts.c
index 0b76d9dd..b199e785 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -19,19 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:fonts
- * @short_description:Structures representing abstract fonts
- * @title: Fonts
- *
- * Pango supports a flexible architecture where a
- * particular rendering architecture can supply an
- * implementation of fonts. The #PangoFont structure
- * represents an abstract rendering-system-independent font.
- * Pango provides routines to list available fonts, and
- * to load a font matching a given description.
- */
-
 #include "config.h"
 #include <stdlib.h>
 #include <math.h>
@@ -69,21 +56,21 @@ G_DEFINE_BOXED_TYPE (PangoFontDescription, pango_font_description,
                      pango_font_description_free);
 
 static const PangoFontDescription pfd_defaults = {
-  NULL,			/* family_name */
+  NULL,                 /* family_name */
 
-  PANGO_STYLE_NORMAL,	/* style */
-  PANGO_VARIANT_NORMAL,	/* variant */
-  PANGO_WEIGHT_NORMAL,	/* weight */
-  PANGO_STRETCH_NORMAL,	/* stretch */
+  PANGO_STYLE_NORMAL,   /* style */
+  PANGO_VARIANT_NORMAL, /* variant */
+  PANGO_WEIGHT_NORMAL,  /* weight */
+  PANGO_STRETCH_NORMAL, /* stretch */
   PANGO_GRAVITY_SOUTH,  /* gravity */
   NULL,                 /* variations */
 
-  0,			/* mask */
-  0,			/* static_family */
-  0,			/* static_variations*/
-  0,    		/* size_is_absolute */
+  0,                    /* mask */
+  0,                    /* static_family */
+  0,                    /* static_variations*/
+  0,                    /* size_is_absolute */
 
-  0,			/* size */
+  0,                    /* size */
 };
 
 /**
@@ -91,9 +78,9 @@ static const PangoFontDescription pfd_defaults = {
  *
  * Creates a new font description structure with all fields unset.
  *
- * Return value: the newly allocated #PangoFontDescription, which
- *               should be freed using pango_font_description_free().
- **/
+ * Return value: the newly allocated `PangoFontDescription`, which
+ *   should be freed using [method@Pango.FontDescription.free].
+ */
 PangoFontDescription *
 pango_font_description_new (void)
 {
@@ -106,18 +93,20 @@ pango_font_description_new (void)
 
 /**
  * pango_font_description_set_family:
- * @desc: a #PangoFontDescription.
+ * @desc: a `PangoFontDescription`.
  * @family: a string representing the family name.
  *
- * Sets the family name field of a font description. The family
+ * Sets the family name field of a font description.
+ *
+ * The family
  * name represents a family of related font styles, and will
- * resolve to a particular #PangoFontFamily. In some uses of
- * #PangoFontDescription, it is also possible to use a comma
+ * resolve to a particular `PangoFontFamily`. In some uses of
+ * `PangoFontDescription`, it is also possible to use a comma
  * separated list of family names for this field.
- **/
+ */
 void
 pango_font_description_set_family (PangoFontDescription *desc,
-				   const char           *family)
+                                   const char           *family)
 {
   g_return_if_fail (desc != NULL);
 
@@ -128,19 +117,20 @@ pango_font_description_set_family (PangoFontDescription *desc,
 
 /**
  * pango_font_description_set_family_static:
- * @desc: a #PangoFontDescription
- * @family: a string representing the family name.
+ * @desc: a `PangoFontDescription`
+ * @family: a string representing the family name
  *
- * Like pango_font_description_set_family(), except that no
+ * Sets the family name field of a font description, without copying the string.
+ *
+ * This is like [method@Pango.FontDescription.set_family], except that no
  * copy of @family is made. The caller must make sure that the
- * string passed in stays around until @desc has been freed
- * or the name is set again. This function can be used if
- * @family is a static string such as a C string literal, or
- * if @desc is only needed temporarily.
- **/
+ * string passed in stays around until @desc has been freed or the
+ * name is set again. This function can be used if @family is a static
+ * string such as a C string literal, or if @desc is only needed temporarily.
+ */
 void
 pango_font_description_set_family_static (PangoFontDescription *desc,
-					  const char           *family)
+                                          const char           *family)
 {
   g_return_if_fail (desc != NULL);
 
@@ -166,16 +156,16 @@ pango_font_description_set_family_static (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_family:
- * @desc: a #PangoFontDescription.
+ * @desc: a `PangoFontDescription`.
+ *
+ * Gets the family name field of a font description.
  *
- * Gets the family name field of a font description. See
- * pango_font_description_set_family().
+ * See [method@Pango.FontDescription.set_family].
  *
  * Return value: (nullable): the family name field for the font
- *               description, or %NULL if not previously set.  This
- *               has the same life-time as the font description itself
- *               and should not be freed.
- **/
+ *   description, or %NULL if not previously set. This has the same
+ *   life-time as the font description itself and should not be freed.
+ */
 const char *
 pango_font_description_get_family (const PangoFontDescription *desc)
 {
@@ -186,21 +176,23 @@ pango_font_description_get_family (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_style:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @style: the style for the font description
  *
- * Sets the style field of a #PangoFontDescription. The
- * #PangoStyle enumeration describes whether the font is slanted and
- * the manner in which it is slanted; it can be either
+ * Sets the style field of a `PangoFontDescription`.
+ *
+ * The [enum@Pango.Style] enumeration describes whether the font is
+ * slanted and the manner in which it is slanted; it can be either
  * #PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE.
- * Most fonts will either have a italic style or an oblique
- * style, but not both, and font matching in Pango will
- * match italic specifications with oblique fonts and vice-versa
- * if an exact match is not found.
- **/
+ *
+ * Most fonts will either have a italic style or an oblique style,
+ * but not both, and font matching in Pango will match italic
+ * specifications with oblique fonts and vice-versa if an exact
+ * match is not found.
+ */
 void
 pango_font_description_set_style (PangoFontDescription *desc,
-				  PangoStyle            style)
+                                  PangoStyle            style)
 {
   g_return_if_fail (desc != NULL);
 
@@ -210,15 +202,16 @@ pango_font_description_set_style (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_style:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Gets the style field of a `PangoFontDescription`.
  *
- * Gets the style field of a #PangoFontDescription. See
- * pango_font_description_set_style().
+ * See [method@Pango.FontDescription.set_style].
  *
  * Return value: the style field for the font description.
- *   Use pango_font_description_get_set_fields() to find out if
- *   the field was explicitly set or not.
- **/
+ *   Use [method@Pango.FontDescription.get_set_fields] to
+ *   find out if the field was explicitly set or not.
+ */
 PangoStyle
 pango_font_description_get_style (const PangoFontDescription *desc)
 {
@@ -229,15 +222,17 @@ pango_font_description_get_style (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_variant:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @variant: the variant type for the font description.
  *
- * Sets the variant field of a font description. The #PangoVariant
- * can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS.
- **/
+ * Sets the variant field of a font description.
+ *
+ * The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL
+ * or %PANGO_VARIANT_SMALL_CAPS.
+ */
 void
 pango_font_description_set_variant (PangoFontDescription *desc,
-				    PangoVariant          variant)
+                                    PangoVariant          variant)
 {
   g_return_if_fail (desc != NULL);
 
@@ -247,15 +242,16 @@ pango_font_description_set_variant (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_variant:
- * @desc: a #PangoFontDescription.
+ * @desc: a `PangoFontDescription`.
+ *
+ * Gets the variant field of a `PangoFontDescription`.
  *
- * Gets the variant field of a #PangoFontDescription. See
- * pango_font_description_set_variant().
+ * See [method@Pango.FontDescription.set_variant].
  *
- * Return value: the variant field for the font description. Use
- *   pango_font_description_get_set_fields() to find out if
- *   the field was explicitly set or not.
- **/
+ * Return value: the variant field for the font description.
+ *   Use [method@Pango.FontDescription.get_set_fields] to find
+ *   out if the field was explicitly set or not.
+ */
 PangoVariant
 pango_font_description_get_variant (const PangoFontDescription *desc)
 {
@@ -266,17 +262,19 @@ pango_font_description_get_variant (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_weight:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @weight: the weight for the font description.
  *
- * Sets the weight field of a font description. The weight field
+ * Sets the weight field of a font description.
+ *
+ * The weight field
  * specifies how bold or light the font should be. In addition
- * to the values of the #PangoWeight enumeration, other intermediate
- * numeric values are possible.
- **/
+ * to the values of the [enum@Pango.Weight] enumeration, other
+ * intermediate numeric values are possible.
+ */
 void
 pango_font_description_set_weight (PangoFontDescription *desc,
-				   PangoWeight          weight)
+                                   PangoWeight          weight)
 {
   g_return_if_fail (desc != NULL);
 
@@ -286,15 +284,16 @@ pango_font_description_set_weight (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_weight:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Gets the weight field of a font description.
  *
- * Gets the weight field of a font description. See
- * pango_font_description_set_weight().
+ * See [method@Pango.FontDescription.set_weight].
  *
- * Return value: the weight field for the font description. Use
- *   pango_font_description_get_set_fields() to find out if
- *   the field was explicitly set or not.
- **/
+ * Return value: the weight field for the font description.
+ *   Use [method@Pango.FontDescription.get_set_fields] to find
+ *   out if the field was explicitly set or not.
+ */
 PangoWeight
 pango_font_description_get_weight (const PangoFontDescription *desc)
 {
@@ -305,15 +304,17 @@ pango_font_description_get_weight (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_stretch:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @stretch: the stretch for the font description
  *
- * Sets the stretch field of a font description. The stretch field
- * specifies how narrow or wide the font should be.
- **/
+ * Sets the stretch field of a font description.
+ *
+ * The [enum@Pango.Stretch] field specifies how narrow or
+ * wide the font should be.
+ */
 void
 pango_font_description_set_stretch (PangoFontDescription *desc,
-				    PangoStretch          stretch)
+                                    PangoStretch          stretch)
 {
   g_return_if_fail (desc != NULL);
 
@@ -323,15 +324,16 @@ pango_font_description_set_stretch (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_stretch:
- * @desc: a #PangoFontDescription.
+ * @desc: a `PangoFontDescription`.
  *
  * Gets the stretch field of a font description.
- * See pango_font_description_set_stretch().
  *
- * Return value: the stretch field for the font description. Use
- *   pango_font_description_get_set_fields() to find out if
- *   the field was explicitly set or not.
- **/
+ * See [method@Pango.FontDescription.set_stretch].
+ *
+ * Return value: the stretch field for the font description.
+ *   Use [method@Pango.FontDescription.get_set_fields] to find
+ *   out if the field was explicitly set or not.
+ */
 PangoStretch
 pango_font_description_get_stretch (const PangoFontDescription *desc)
 {
@@ -342,21 +344,24 @@ pango_font_description_get_stretch (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_size:
- * @desc: a #PangoFontDescription
- * @size: the size of the font in points, scaled by PANGO_SCALE. (That is,
- *        a @size value of 10 * PANGO_SCALE is a 10 point font. The conversion
- *        factor between points and device units depends on system configuration
- *        and the output device. For screen display, a logical DPI of 96 is
- *        common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3
- *        pixel font. Use pango_font_description_set_absolute_size() if you need
- *        a particular size in device units.
- *
- * Sets the size field of a font description in fractional points. This is mutually
- * exclusive with pango_font_description_set_absolute_size().
- **/
+ * @desc: a `PangoFontDescription`
+ * @size: the size of the font in points, scaled by %PANGO_SCALE.
+ *   (That is, a @size value of 10 * PANGO_SCALE is a 10 point font.
+ *   The conversion factor between points and device units depends on
+ *   system configuration and the output device. For screen display, a
+ *   logical DPI of 96 is common, in which case a 10 point font corresponds
+ *   to a 10 * (96 / 72) = 13.3 pixel font.
+ *   Use [method@Pango.FontDescription.set_absolute_size] if you need
+ *   a particular size in device units.
+ *
+ * Sets the size field of a font description in fractional points.
+ *
+ * This is mutually exclusive with
+ * [method@Pango.FontDescription.set_absolute_size].
+ */
 void
 pango_font_description_set_size (PangoFontDescription *desc,
-				 gint                  size)
+                                 gint                  size)
 {
   g_return_if_fail (desc != NULL);
   g_return_if_fail (size >= 0);
@@ -368,18 +373,20 @@ pango_font_description_set_size (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_size:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
  * Gets the size field of a font description.
- * See pango_font_description_set_size().
  *
- * Return value: the size field for the font description in points or device units.
- *   You must call pango_font_description_get_size_is_absolute()
- *   to find out which is the case. Returns 0 if the size field has not
- *   previously been set or it has been set to 0 explicitly.
- *   Use pango_font_description_get_set_fields() to
- *   find out if the field was explicitly set or not.
- **/
+ * See [method@Pango.FontDescription.set_size].
+ *
+ * Return value: the size field for the font description in points
+ *   or device units. You must call
+ *   [method@Pango.FontDescription.get_size_is_absolute] to find out
+ *   which is the case. Returns 0 if the size field has not previously
+ *   been set or it has been set to 0 explicitly.
+ *   Use [method@Pango.FontDescription.get_set_fields] to find out
+ *   if the field was explicitly set or not.
+ */
 gint
 pango_font_description_get_size (const PangoFontDescription *desc)
 {
@@ -390,20 +397,21 @@ pango_font_description_get_size (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_absolute_size:
- * @desc: a #PangoFontDescription
- * @size: the new size, in Pango units. There are %PANGO_SCALE Pango units in one
- *   device unit. For an output backend where a device unit is a pixel, a @size
- *   value of 10 * PANGO_SCALE gives a 10 pixel font.
+ * @desc: a `PangoFontDescription`
+ * @size: the new size, in Pango units. There are %PANGO_SCALE Pango units
+ *   in one device unit. For an output backend where a device unit is a pixel,
+ *   a @size value of 10 * PANGO_SCALE gives a 10 pixel font.
+ *
+ * Sets the size field of a font description, in device units.
  *
- * Sets the size field of a font description, in device units. This is mutually
- * exclusive with pango_font_description_set_size() which sets the font size
- * in points.
+ * This is mutually exclusive with [method@Pango.FontDescription.set_size]
+ * which sets the font size in points.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_font_description_set_absolute_size (PangoFontDescription *desc,
-					  double                size)
+                                          double                size)
 {
   g_return_if_fail (desc != NULL);
   g_return_if_fail (size >= 0);
@@ -415,17 +423,21 @@ pango_font_description_set_absolute_size (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_size_is_absolute:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Determines whether the size of the font is in points (not absolute)
+ * or device units (absolute).
  *
- * Determines whether the size of the font is in points (not absolute) or device units (absolute).
- * See pango_font_description_set_size() and pango_font_description_set_absolute_size().
+ * See [method@Pango.FontDescription.set_size]
+ * and [method@Pango.FontDescription.set_absolute_size].
  *
  * Return value: whether the size for the font description is in
- *   points or device units.  Use pango_font_description_get_set_fields() to
- *   find out if the size field of the font description was explicitly set or not.
+ *   points or device units. Use [method@Pango.FontDescription.get_set_fields]
+ *   to find out if the size field of the font description was explicitly
+ *   set or not.
  *
  * Since: 1.8
- **/
+ */
 gboolean
 pango_font_description_get_size_is_absolute (const PangoFontDescription *desc)
 {
@@ -436,22 +448,24 @@ pango_font_description_get_size_is_absolute (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_gravity:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @gravity: the gravity for the font description.
  *
- * Sets the gravity field of a font description. The gravity field
- * specifies how the glyphs should be rotated.  If @gravity is
+ * Sets the gravity field of a font description.
+ *
+ * The gravity field
+ * specifies how the glyphs should be rotated. If @gravity is
  * %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on
  * the font description.
  *
- * This function is seldom useful to the user.  Gravity should normally
- * be set on a #PangoContext.
+ * This function is seldom useful to the user. Gravity should normally
+ * be set on a `PangoContext`.
  *
  * Since: 1.16
- **/
+ */
 void
 pango_font_description_set_gravity (PangoFontDescription *desc,
-				    PangoGravity          gravity)
+                                    PangoGravity          gravity)
 {
   g_return_if_fail (desc != NULL);
 
@@ -467,17 +481,18 @@ pango_font_description_set_gravity (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_gravity:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
- * Gets the gravity field of a font description. See
- * pango_font_description_set_gravity().
+ * Gets the gravity field of a font description.
  *
- * Return value: the gravity field for the font description. Use
- *   pango_font_description_get_set_fields() to find out if
- *   the field was explicitly set or not.
+ * See [method@Pango.FontDescription.set_gravity].
+ *
+ * Return value: the gravity field for the font description.
+ *   Use [method@Pango.FontDescription.get_set_fields] to find out
+ *   if the field was explicitly set or not.
  *
  * Since: 1.16
- **/
+ */
 PangoGravity
 pango_font_description_get_gravity (const PangoFontDescription *desc)
 {
@@ -488,18 +503,20 @@ pango_font_description_get_gravity (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_variations_static:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @variations: a string representing the variations
  *
- * Like pango_font_description_set_variations(), except that no
- * copy of @variations is made. The caller must make sure that the
- * string passed in stays around until @desc has been freed
+ * Sets the variations field of a font description.
+ *
+ * This is like [method@Pango.FontDescription.set_variations], except
+ * that no copy of @variations is made. The caller must make sure that
+ * the string passed in stays around until @desc has been freed
  * or the name is set again. This function can be used if
- * @variations is a static string such as a C string literal, or
- * if @desc is only needed temporarily.
+ * @variations is a static string such as a C string literal,
+ * or if @desc is only needed temporarily.
  *
  * Since: 1.42
- **/
+ */
 void
 pango_font_description_set_variations_static (PangoFontDescription *desc,
                                               const char           *variations)
@@ -528,14 +545,18 @@ pango_font_description_set_variations_static (PangoFontDescription *desc,
 
 /**
  * pango_font_description_set_variations:
- * @desc: a #PangoFontDescription.
+ * @desc: a `PangoFontDescription`.
  * @variations: a string representing the variations
  *
- * Sets the variations field of a font description. OpenType
- * font variations allow to select a font instance by specifying
- * values for a number of axes, such as width or weight.
+ * Sets the variations field of a font description.
+ *
+ * OpenType font variations allow to select a font instance by
+ * specifying values for a number of axes, such as width or weight.
+ *
+ * The format of the variations string is
+ *
+ *     AXIS1=VALUE,AXIS2=VALUE...
  *
- * The format of the variations string is AXIS1=VALUE,AXIS2=VALUE...,
  * with each AXIS a 4 character tag that identifies a font axis,
  * and each VALUE a floating point number. Unknown axes are ignored,
  * and values are clamped to their allowed range.
@@ -544,7 +565,7 @@ pango_font_description_set_variations_static (PangoFontDescription *desc,
  * a font. Both harfbuzz or freetype have API for this.
  *
  * Since: 1.42
- **/
+ */
 void
 pango_font_description_set_variations (PangoFontDescription *desc,
                                        const char           *variations)
@@ -558,18 +579,18 @@ pango_font_description_set_variations (PangoFontDescription *desc,
 
 /**
  * pango_font_description_get_variations:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Gets the variations field of a font description.
  *
- * Gets the variations field of a font description. See
- * pango_font_description_set_variations().
+ * See [method@Pango.FontDescription.set_variations].
  *
- * Return value: (nullable): the varitions field for the font
- *               description, or %NULL if not previously set.  This
- *               has the same life-time as the font description itself
- *               and should not be freed.
+ * Return value: (nullable): the variations field for the font
+ *   description, or %NULL if not previously set. This has the same
+ *   life-time as the font description itself and should not be freed.
  *
  * Since: 1.42
- **/
+ */
 const char *
 pango_font_description_get_variations (const PangoFontDescription *desc)
 {
@@ -580,13 +601,13 @@ pango_font_description_get_variations (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_get_set_fields:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
  * Determines which fields in a font description have been set.
  *
  * Return value: a bitmask with bits set corresponding to the
  *   fields in @desc that have been set.
- **/
+ */
 PangoFontMask
 pango_font_description_get_set_fields (const PangoFontDescription *desc)
 {
@@ -597,15 +618,16 @@ pango_font_description_get_set_fields (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_unset_fields:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @to_unset: bitmask of fields in the @desc to unset.
  *
- * Unsets some of the fields in a #PangoFontDescription.  The unset
- * fields will get back to their default values.
- **/
+ * Unsets some of the fields in a `PangoFontDescription`.
+ *
+ * The unset fields will get back to their default values.
+ */
 void
 pango_font_description_unset_fields (PangoFontDescription *desc,
-				     PangoFontMask         to_unset)
+                                     PangoFontMask         to_unset)
 {
   PangoFontDescription unset_desc;
 
@@ -621,23 +643,26 @@ pango_font_description_unset_fields (PangoFontDescription *desc,
 
 /**
  * pango_font_description_merge:
- * @desc: a #PangoFontDescription
- * @desc_to_merge: (allow-none): the #PangoFontDescription to merge from, or %NULL
+ * @desc: a `PangoFontDescription`
+ * @desc_to_merge: (allow-none): the `PangoFontDescription` to merge from,
+ *   or %NULL
  * @replace_existing: if %TRUE, replace fields in @desc with the
  *   corresponding values from @desc_to_merge, even if they
  *   are already exist.
  *
  * Merges the fields that are set in @desc_to_merge into the fields in
- * @desc.  If @replace_existing is %FALSE, only fields in @desc that
+ * @desc.
+ *
+ * If @replace_existing is %FALSE, only fields in @desc that
  * are not already set are affected. If %TRUE, then fields that are
  * already set will be replaced as well.
  *
  * If @desc_to_merge is %NULL, this function performs nothing.
- **/
+ */
 void
 pango_font_description_merge (PangoFontDescription       *desc,
-			      const PangoFontDescription *desc_to_merge,
-			      gboolean                    replace_existing)
+                              const PangoFontDescription *desc_to_merge,
+                              gboolean                    replace_existing)
 {
   gboolean family_merged;
   gboolean variations_merged;
@@ -667,21 +692,24 @@ pango_font_description_merge (PangoFontDescription       *desc,
 
 /**
  * pango_font_description_merge_static:
- * @desc: a #PangoFontDescription
- * @desc_to_merge: the #PangoFontDescription to merge from
+ * @desc: a `PangoFontDescription`
+ * @desc_to_merge: the `PangoFontDescription` to merge from
  * @replace_existing: if %TRUE, replace fields in @desc with the
  *   corresponding values from @desc_to_merge, even if they
  *   are already exist.
  *
- * Like pango_font_description_merge(), but only a shallow copy is made
- * of the family name and other allocated fields. @desc can only be
- * used until @desc_to_merge is modified or freed. This is meant
- * to be used when the merged font description is only needed temporarily.
- **/
+ * Merges the fields that are set in @desc_to_merge into the fields in
+ * @desc, without copying allocated fields.
+ *
+ * This is like [method@Pango.FontDescription.merge], but only a shallow copy
+ * is made of the family name and other allocated fields. @desc can only
+ * be used until @desc_to_merge is modified or freed. This is meant to
+ * be used when the merged font description is only needed temporarily.
+ */
 void
 pango_font_description_merge_static (PangoFontDescription       *desc,
-				     const PangoFontDescription *desc_to_merge,
-				     gboolean                    replace_existing)
+                                     const PangoFontDescription *desc_to_merge,
+                                     gboolean                    replace_existing)
 {
   PangoFontMask new_mask;
 
@@ -718,14 +746,14 @@ pango_font_description_merge_static (PangoFontDescription       *desc,
 
 static gint
 compute_distance (const PangoFontDescription *a,
-		  const PangoFontDescription *b)
+                  const PangoFontDescription *b)
 {
   if (a->style == b->style)
     {
       return abs((int)(a->weight) - (int)(b->weight));
     }
   else if (a->style != PANGO_STYLE_NORMAL &&
-	   b->style != PANGO_STYLE_NORMAL)
+           b->style != PANGO_STYLE_NORMAL)
     {
       /* Equate oblique and italic, but with a big penalty
        */
@@ -737,28 +765,28 @@ compute_distance (const PangoFontDescription *a,
 
 /**
  * pango_font_description_better_match:
- * @desc: a #PangoFontDescription
- * @old_match: (allow-none): a #PangoFontDescription, or %NULL
- * @new_match: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ * @old_match: (allow-none): a `PangoFontDescription`, or %NULL
+ * @new_match: a `PangoFontDescription`
  *
  * Determines if the style attributes of @new_match are a closer match
  * for @desc than those of @old_match are, or if @old_match is %NULL,
  * determines if @new_match is a match at all.
- * Approximate matching is done for
- * weight and style; other style attributes must match exactly.
- * Style attributes are all attributes other than family and size-related
- * attributes.  Approximate matching for style considers PANGO_STYLE_OBLIQUE
- * and PANGO_STYLE_ITALIC as matches, but not as good a match as when the
- * styles are equal.
+ *
+ * Approximate matching is done for weight and style; other style attributes
+ * must match exactly. Style attributes are all attributes other than family
+ * and size-related attributes. Approximate matching for style considers
+ * %PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good
+ * a match as when the styles are equal.
  *
  * Note that @old_match must match @desc.
  *
  * Return value: %TRUE if @new_match is a better match
- **/
+ */
 gboolean
 pango_font_description_better_match (const PangoFontDescription *desc,
-				     const PangoFontDescription *old_match,
-				     const PangoFontDescription *new_match)
+                                     const PangoFontDescription *old_match,
+                                     const PangoFontDescription *new_match)
 {
   g_return_val_if_fail (desc != NULL, G_MAXINT);
   g_return_val_if_fail (new_match != NULL, G_MAXINT);
@@ -771,7 +799,7 @@ pango_font_description_better_match (const PangoFontDescription *desc,
       int new_distance = compute_distance (desc, new_match);
 
       if (new_distance < old_distance)
-	return TRUE;
+        return TRUE;
     }
 
   return FALSE;
@@ -779,17 +807,16 @@ pango_font_description_better_match (const PangoFontDescription *desc,
 
 /**
  * pango_font_description_copy:
- * @desc: (nullable): a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a `PangoFontDescription`, may be %NULL
  *
- * Make a copy of a #PangoFontDescription.
+ * Make a copy of a `PangoFontDescription`.
  *
- * Return value: (nullable): the newly allocated
- *               #PangoFontDescription, which should be freed with
- *               pango_font_description_free(), or %NULL if @desc was
- *               %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoFontDescription`,
+ *   which should be freed with [method@Pango.FontDescription.free],
+ *   or %NULL if @desc was %NULL.
+ */
 PangoFontDescription *
-pango_font_description_copy  (const PangoFontDescription  *desc)
+pango_font_description_copy (const PangoFontDescription *desc)
 {
   PangoFontDescription *result;
 
@@ -814,18 +841,20 @@ pango_font_description_copy  (const PangoFontDescription  *desc)
 
 /**
  * pango_font_description_copy_static:
- * @desc: (nullable): a #PangoFontDescription, may be %NULL
- *
- * Like pango_font_description_copy(), but only a shallow copy is made
- * of the family name and other allocated fields. The result can only
- * be used until @desc is modified or freed. This is meant to be used
- * when the copy is only needed temporarily.
- *
- * Return value: (nullable): the newly allocated
- *               #PangoFontDescription, which should be freed with
- *               pango_font_description_free(), or %NULL if @desc was
- *               %NULL.
- **/
+ * @desc: (nullable): a `PangoFontDescription`, may be %NULL
+ *
+ * Make a copy of a `PangoFontDescription`, but don't duplicate
+ * allocated fields.
+ *
+ * This is like [method@Pango.FontDescription.copy], but only a shallow
+ * copy is made of the family name and other allocated fields. The result
+ * can only be used until @desc is modified or freed. This is meant
+ * to be used when the copy is only needed temporarily.
+ *
+ * Return value: (nullable): the newly allocated `PangoFontDescription`,
+ *   which should be freed with [method@Pango.FontDescription.free],
+ *   or %NULL if @desc was %NULL.
+ */
 PangoFontDescription *
 pango_font_description_copy_static (const PangoFontDescription *desc)
 {
@@ -849,34 +878,35 @@ pango_font_description_copy_static (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_equal:
- * @desc1: a #PangoFontDescription
- * @desc2: another #PangoFontDescription
+ * @desc1: a `PangoFontDescription`
+ * @desc2: another `PangoFontDescription`
  *
- * Compares two font descriptions for equality. Two font descriptions
- * are considered equal if the fonts they describe are provably identical.
- * This means that their masks do not have to match, as long as other fields
- * are all the same. (Two font descriptions may result in identical fonts
- * being loaded, but still compare %FALSE.)
+ * Compares two font descriptions for equality.
+ *
+ * Two font descriptions are considered equal if the fonts they describe
+ * are provably identical. This means that their masks do not have to match,
+ * as long as other fields are all the same. (Two font descriptions may
+ * result in identical fonts being loaded, but still compare %FALSE.)
  *
  * Return value: %TRUE if the two font descriptions are identical,
- *		 %FALSE otherwise.
- **/
+ *   %FALSE otherwise.
+ */
 gboolean
-pango_font_description_equal (const PangoFontDescription  *desc1,
-			      const PangoFontDescription  *desc2)
+pango_font_description_equal (const PangoFontDescription *desc1,
+                              const PangoFontDescription *desc2)
 {
   g_return_val_if_fail (desc1 != NULL, FALSE);
   g_return_val_if_fail (desc2 != NULL, FALSE);
 
   return desc1->style == desc2->style &&
-	 desc1->variant == desc2->variant &&
-	 desc1->weight == desc2->weight &&
-	 desc1->stretch == desc2->stretch &&
-	 desc1->size == desc2->size &&
-	 desc1->size_is_absolute == desc2->size_is_absolute &&
-	 desc1->gravity == desc2->gravity &&
-	 (desc1->family_name == desc2->family_name ||
-	  (desc1->family_name && desc2->family_name && g_ascii_strcasecmp (desc1->family_name, desc2->family_name) == 0)) &&
+         desc1->variant == desc2->variant &&
+         desc1->weight == desc2->weight &&
+         desc1->stretch == desc2->stretch &&
+         desc1->size == desc2->size &&
+         desc1->size_is_absolute == desc2->size_is_absolute &&
+         desc1->gravity == desc2->gravity &&
+         (desc1->family_name == desc2->family_name ||
+          (desc1->family_name && desc2->family_name && g_ascii_strcasecmp (desc1->family_name, desc2->family_name) == 0)) &&
          (g_strcmp0 (desc1->variations, desc2->variations) == 0);
 }
 
@@ -892,7 +922,7 @@ case_insensitive_hash (const char *key)
   if (h)
     {
       for (p += 1; *p != '\0'; p++)
-	h = (h << 5) - h + TOLOWER (*p);
+        h = (h << 5) - h + TOLOWER (*p);
     }
 
   return h;
@@ -900,14 +930,15 @@ case_insensitive_hash (const char *key)
 
 /**
  * pango_font_description_hash:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Computes a hash of a `PangoFontDescription` structure.
  *
- * Computes a hash of a #PangoFontDescription structure suitable
- * to be used, for example, as an argument to g_hash_table_new().
- * The hash value is independent of @desc->mask.
+ * This is suitable to be used, for example, as an argument
+ * to g_hash_table_new(). The hash value is independent of @desc->mask.
  *
  * Return value: the hash value.
- **/
+ */
 guint
 pango_font_description_hash (const PangoFontDescription *desc)
 {
@@ -932,12 +963,12 @@ pango_font_description_hash (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_free:
- * @desc: (nullable): a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a `PangoFontDescription`, may be %NULL
  *
  * Frees a font description.
- **/
+ */
 void
-pango_font_description_free  (PangoFontDescription  *desc)
+pango_font_description_free (PangoFontDescription *desc)
 {
   if (desc == NULL)
     return;
@@ -954,14 +985,14 @@ pango_font_description_free  (PangoFontDescription  *desc)
 /**
  * pango_font_descriptions_free:
  * @descs: (allow-none) (array length=n_descs) (transfer full): a pointer
- * to an array of #PangoFontDescription, may be %NULL
+ *   to an array of `PangoFontDescription`, may be %NULL
  * @n_descs: number of font descriptions in @descs
  *
  * Frees an array of font descriptions.
- **/
+ */
 void
 pango_font_descriptions_free (PangoFontDescription **descs,
-			      int                    n_descs)
+                              int                    n_descs)
 {
   int i;
 
@@ -1040,8 +1071,8 @@ static const FieldMap gravity_map[] = {
 
 static gboolean
 field_matches (const gchar *s1,
-	       const gchar *s2,
-	       gsize n)
+               const gchar *s2,
+               gsize n)
 {
   gint c1, c2;
 
@@ -1054,10 +1085,10 @@ field_matches (const gchar *s1,
       c2 = (gint)(guchar) TOLOWER (*s2);
       if (c1 != c2) {
         if (c1 == '-') {
-	  s1++;
-	  continue;
-	}
-	return FALSE;
+          s1++;
+          continue;
+        }
+        return FALSE;
       }
       s1++; s2++;
       n--;
@@ -1068,8 +1099,8 @@ field_matches (const gchar *s1,
 
 static gboolean
 parse_int (const char *word,
-	   size_t      wordlen,
-	   int        *out)
+           size_t      wordlen,
+           int        *out)
 {
   char *end;
   long val = strtol (word, &end, 10);
@@ -1088,11 +1119,11 @@ parse_int (const char *word,
 
 static gboolean
 find_field (const char *what,
-	    const FieldMap *map,
-	    int n_elements,
-	    const char *str,
-	    int len,
-	    int *val)
+            const FieldMap *map,
+            int n_elements,
+            const char *str,
+            int len,
+            int *val)
 {
   int i;
   gboolean had_prefix = FALSE;
@@ -1101,21 +1132,21 @@ find_field (const char *what,
     {
       i = strlen (what);
       if (len > i && 0 == strncmp (what, str, i) && str[i] == '=')
-	{
-	  str += i + 1;
-	  len -= i + 1;
-	  had_prefix = TRUE;
-	}
+        {
+          str += i + 1;
+          len -= i + 1;
+          had_prefix = TRUE;
+        }
     }
 
   for (i=0; i<n_elements; i++)
     {
       if (map[i].str[0] && field_matches (map[i].str, str, len))
-	{
-	  if (val)
-	    *val = map[i].value;
-	  return TRUE;
-	}
+        {
+          if (val)
+            *val = map[i].value;
+          return TRUE;
+        }
     }
 
   if (!what || had_prefix)
@@ -1133,10 +1164,10 @@ find_field_any (const char *str, int len, PangoFontDescription *desc)
 #define FIELD(NAME, MASK) \
   G_STMT_START { \
   if (find_field (G_STRINGIFY (NAME), NAME##_map, G_N_ELEMENTS (NAME##_map), str, len, \
-		  desc ? (int *)(void *)&desc->NAME : NULL)) \
+                  desc ? (int *)(void *)&desc->NAME : NULL)) \
     { \
       if (desc) \
-	desc->mask |= MASK; \
+        desc->mask |= MASK; \
       return TRUE; \
     } \
   } G_STMT_END
@@ -1171,9 +1202,9 @@ getword (const char *str, const char *last, size_t *wordlen, const char *stop)
 
 static gboolean
 parse_size (const char *word,
-	    size_t      wordlen,
-	    int        *pango_size,
-	    gboolean   *size_is_absolute)
+            size_t      wordlen,
+            int        *pango_size,
+            gboolean   *size_is_absolute)
 {
   char *end;
   double size = g_ascii_strtod (word, &end);
@@ -1184,10 +1215,10 @@ parse_size (const char *word,
       ) && size >= 0 && size <= 1000000) /* word is a valid float */
     {
       if (pango_size)
-	*pango_size = (int)(size * PANGO_SCALE + 0.5);
+        *pango_size = (int)(size * PANGO_SCALE + 0.5);
 
       if (size_is_absolute)
-	*size_is_absolute = end < word + wordlen;
+        *size_is_absolute = end < word + wordlen;
 
       return TRUE;
     }
@@ -1216,10 +1247,11 @@ parse_variations (const char  *word,
  * pango_font_description_from_string:
  * @str: string representation of a font description.
  *
- * Creates a new font description from a string representation in the
- * form
+ * Creates a new font description from a string representation.
+ *
+ * The string must have the form
  *
- * "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]",
+ *     "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]",
  *
  * where FAMILY-LIST is a comma-separated list of families optionally
  * terminated by a comma, STYLE_OPTIONS is a whitespace-separated list
@@ -1257,10 +1289,10 @@ parse_variations (const char  *word,
  *
  * A typical example:
  *
- * "Cantarell Italic Light 15 \@wght=200"
+ *     "Cantarell Italic Light 15 \@wght=200"
  *
- * Return value: a new #PangoFontDescription.
- **/
+ * Return value: a new `PangoFontDescription`.
+ */
 PangoFontDescription *
 pango_font_description_from_string (const char *str)
 {
@@ -1273,9 +1305,9 @@ pango_font_description_from_string (const char *str)
   desc = pango_font_description_new ();
 
   desc->mask = PANGO_FONT_MASK_STYLE |
-	       PANGO_FONT_MASK_WEIGHT |
-	       PANGO_FONT_MASK_VARIANT |
-	       PANGO_FONT_MASK_STRETCH;
+               PANGO_FONT_MASK_WEIGHT |
+               PANGO_FONT_MASK_VARIANT |
+               PANGO_FONT_MASK_STRETCH;
 
   len = strlen (str);
   last = str + len;
@@ -1285,8 +1317,8 @@ pango_font_description_from_string (const char *str)
     {
       if (parse_variations (p, wordlen, &desc->variations))
         {
-	  desc->mask |= PANGO_FONT_MASK_VARIATIONS;
-	  last = p;
+          desc->mask |= PANGO_FONT_MASK_VARIATIONS;
+          last = p;
         }
     }
 
@@ -1296,11 +1328,11 @@ pango_font_description_from_string (const char *str)
     {
       gboolean size_is_absolute;
       if (parse_size (p, wordlen, &desc->size, &size_is_absolute))
-	{
-	  desc->size_is_absolute = size_is_absolute;
-	  desc->mask |= PANGO_FONT_MASK_SIZE;
-	  last = p;
-	}
+        {
+          desc->size_is_absolute = size_is_absolute;
+          desc->mask |= PANGO_FONT_MASK_SIZE;
+          last = p;
+        }
     }
 
   /* Now parse style words
@@ -1309,12 +1341,12 @@ pango_font_description_from_string (const char *str)
   while (wordlen != 0)
     {
       if (!find_field_any (p, wordlen, desc))
-	break;
+        break;
       else
-	{
-	  last = p;
-	  p = getword (str, last, &wordlen, ",");
-	}
+        {
+          last = p;
+          p = getword (str, last, &wordlen, ",");
+        }
     }
 
   /* Remainder (str => p) is family list. Trim off trailing commas and leading and trailing white space
@@ -1345,7 +1377,7 @@ pango_font_description_from_string (const char *str)
       families = g_strsplit (desc->family_name, ",", -1);
 
       for (i = 0; families[i]; i++)
-	g_strstrip (families[i]);
+        g_strstrip (families[i]);
 
       g_free (desc->family_name);
       desc->family_name = g_strjoinv (",", families);
@@ -1367,11 +1399,11 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element
         continue;
 
       if (G_LIKELY (map[i].str[0]))
-	{
-	  if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' '))
-	    g_string_append_c (str, ' ');
-	  g_string_append (str, map[i].str);
-	}
+        {
+          if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' '))
+            g_string_append_c (str, ' ');
+          g_string_append (str, map[i].str);
+        }
       return;
     }
 
@@ -1382,18 +1414,19 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element
 
 /**
  * pango_font_description_to_string:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
- * Creates a string representation of a font description. See
- * pango_font_description_from_string() for a description of the
- * format of the string representation. The family list in the
- * string description will only have a terminating comma if the
- * last word of the list is a valid style option.
+ * Creates a string representation of a font description.
+ *
+ * See [type_func@Pango.FontDescription.from_string] for a description
+ * of the format of the string representation. The family list in
+ * the string description will only have a terminating comma if
+ * the last word of the list is a valid style option.
  *
  * Return value: a new string that must be freed with g_free().
- **/
+ */
 char *
-pango_font_description_to_string (const PangoFontDescription  *desc)
+pango_font_description_to_string (const PangoFontDescription *desc)
 {
   GString *result;
 
@@ -1414,14 +1447,14 @@ pango_font_description_to_string (const PangoFontDescription  *desc)
        */
       p = getword (desc->family_name, desc->family_name + strlen(desc->family_name), &wordlen, ",");
       if (wordlen != 0 &&
-	  (find_field_any (p, wordlen, NULL) ||
-	   (parse_size (p, wordlen, NULL, NULL) &&
-	    desc->weight == PANGO_WEIGHT_NORMAL &&
-	    desc->style == PANGO_STYLE_NORMAL &&
-	    desc->stretch == PANGO_STRETCH_NORMAL &&
-	    desc->variant == PANGO_VARIANT_NORMAL &&
-	    (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0)))
-	g_string_append_c (result, ',');
+          (find_field_any (p, wordlen, NULL) ||
+           (parse_size (p, wordlen, NULL, NULL) &&
+            desc->weight == PANGO_WEIGHT_NORMAL &&
+            desc->style == PANGO_STYLE_NORMAL &&
+            desc->stretch == PANGO_STRETCH_NORMAL &&
+            desc->variant == PANGO_VARIANT_NORMAL &&
+            (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0)))
+        g_string_append_c (result, ',');
     }
 
 #define FIELD(NAME, MASK) \
@@ -1444,13 +1477,13 @@ pango_font_description_to_string (const PangoFontDescription  *desc)
       char buf[G_ASCII_DTOSTR_BUF_SIZE];
 
       if (result->len > 0 || result->str[result->len -1] != ' ')
-	g_string_append_c (result, ' ');
+        g_string_append_c (result, ' ');
 
       g_ascii_dtostr (buf, sizeof (buf), (double)desc->size / PANGO_SCALE);
       g_string_append (result, buf);
 
       if (desc->size_is_absolute)
-	g_string_append (result, "px");
+        g_string_append (result, "px");
     }
 
   if (desc->variations && desc->mask & PANGO_FONT_MASK_VARIATIONS)
@@ -1464,17 +1497,19 @@ pango_font_description_to_string (const PangoFontDescription  *desc)
 
 /**
  * pango_font_description_to_filename:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ *
+ * Creates a filename representation of a font description.
  *
- * Creates a filename representation of a font description. The
- * filename is identical to the result from calling
- * pango_font_description_to_string(), but with underscores instead of
- * characters that are untypical in filenames, and in lower case only.
+ * The filename is identical to the result from calling
+ * [method@Pango.FontDescription.to_string], but with underscores
+ * instead of characters that are untypical in filenames, and in
+ * lower case only.
  *
  * Return value: a new string that must be freed with g_free().
- **/
+ */
 char *
-pango_font_description_to_filename (const PangoFontDescription  *desc)
+pango_font_description_to_filename (const PangoFontDescription *desc)
 {
   char *result;
   char *p;
@@ -1489,23 +1524,22 @@ pango_font_description_to_filename (const PangoFontDescription  *desc)
       if (G_UNLIKELY ((guchar) *p >= 128))
         /* skip over non-ASCII chars */;
       else if (strchr ("-+_.", *p) == NULL && !g_ascii_isalnum (*p))
-	*p = '_';
+        *p = '_';
       else
-	*p = g_ascii_tolower (*p);
+        *p = g_ascii_tolower (*p);
       p++;
     }
 
   return result;
 }
 
-
 static gboolean
 parse_field (const char *what,
-	     const FieldMap *map,
-	     int n_elements,
-	     const char *str,
-	     int *val,
-	     gboolean warn)
+             const FieldMap *map,
+             int n_elements,
+             const char *str,
+             int *val,
+             gboolean warn)
 {
   gboolean found;
   int len = strlen (str);
@@ -1520,10 +1554,10 @@ parse_field (const char *what,
 
       for (i = 0; i < n_elements; i++)
         if (map[i].str[0] == '\0')
-	  {
-	    *val = map[i].value;
-	    return TRUE;
-	  }
+          {
+            *val = map[i].value;
+            return TRUE;
+          }
 
       *val = 0;
       return TRUE;
@@ -1533,21 +1567,21 @@ parse_field (const char *what,
 
   if (!found && warn)
     {
-	int i;
-	GString *s = g_string_new (NULL);
+        int i;
+        GString *s = g_string_new (NULL);
 
-	for (i = 0; i < n_elements; i++)
-	  {
-	    if (i)
-	      g_string_append_c (s, '/');
-	    g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str);
-	  }
+        for (i = 0; i < n_elements; i++)
+          {
+            if (i)
+              g_string_append_c (s, '/');
+            g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str);
+          }
 
-	g_warning ("%s must be one of %s or a number",
-		   what,
-		   s->str);
+        g_warning ("%s must be one of %s or a number",
+                   what,
+                   s->str);
 
-	g_string_free (s, TRUE);
+        g_string_free (s, TRUE);
     }
 
   return found;
@@ -1559,20 +1593,21 @@ parse_field (const char *what,
 /**
  * pango_parse_style:
  * @str: a string to parse.
- * @style: (out): a #PangoStyle to store the result
- *   in.
+ * @style: (out): a `PangoStyle` to store the result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
- * Parses a font style. The allowed values are "normal",
- * "italic" and "oblique", case variations being
+ * Parses a font style.
+ *
+ * The allowed values are "normal", "italic" and "oblique", case
+ * variations being
  * ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
- **/
+ */
 gboolean
 pango_parse_style (const char *str,
-		   PangoStyle *style,
-		   gboolean    warn)
+                   PangoStyle *style,
+                   gboolean    warn)
 {
   return FIELD (style,   PANGO_FONT_MASK_STYLE);
 }
@@ -1580,20 +1615,20 @@ pango_parse_style (const char *str,
 /**
  * pango_parse_variant:
  * @str: a string to parse.
- * @variant: (out): a #PangoVariant to store the
- *   result in.
+ * @variant: (out): a `PangoVariant` to store the result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
- * Parses a font variant. The allowed values are "normal"
- * and "smallcaps" or "small_caps", case variations being
- * ignored.
+ * Parses a font variant.
+ *
+ * The allowed values are "normal" and "smallcaps" or "small_caps",
+ * case variations being ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
- **/
+ */
 gboolean
 pango_parse_variant (const char   *str,
-		     PangoVariant *variant,
-		     gboolean	   warn)
+                     PangoVariant *variant,
+                     gboolean      warn)
 {
   return FIELD (variant, PANGO_FONT_MASK_VARIANT);
 }
@@ -1601,20 +1636,21 @@ pango_parse_variant (const char   *str,
 /**
  * pango_parse_weight:
  * @str: a string to parse.
- * @weight: (out): a #PangoWeight to store the result
- *   in.
+ * @weight: (out): a `PangoWeight` to store the result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
- * Parses a font weight. The allowed values are "heavy",
+ * Parses a font weight.
+ *
+ * The allowed values are "heavy",
  * "ultrabold", "bold", "normal", "light", "ultraleight"
  * and integers. Case variations are ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
- **/
+ */
 gboolean
 pango_parse_weight (const char  *str,
-		    PangoWeight *weight,
-		    gboolean     warn)
+                    PangoWeight *weight,
+                    gboolean     warn)
 {
   return FIELD (weight,  PANGO_FONT_MASK_WEIGHT);
 }
@@ -1622,29 +1658,28 @@ pango_parse_weight (const char  *str,
 /**
  * pango_parse_stretch:
  * @str: a string to parse.
- * @stretch: (out): a #PangoStretch to store the
- *   result in.
+ * @stretch: (out): a `PangoStretch` to store the result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
- * Parses a font stretch. The allowed values are
+ * Parses a font stretch.
+ *
+ * The allowed values are
  * "ultra_condensed", "extra_condensed", "condensed",
  * "semi_condensed", "normal", "semi_expanded", "expanded",
  * "extra_expanded" and "ultra_expanded". Case variations are
  * ignored and the '_' characters may be omitted.
  *
  * Return value: %TRUE if @str was successfully parsed.
- **/
+ */
 gboolean
 pango_parse_stretch (const char   *str,
-		     PangoStretch *stretch,
-		     gboolean	   warn)
+                     PangoStretch *stretch,
+                     gboolean      warn)
 {
   return FIELD (stretch, PANGO_FONT_MASK_STRETCH);
 }
 
 
-
-
 /*
  * PangoFont
  */
@@ -1681,16 +1716,17 @@ pango_font_init (PangoFont *font G_GNUC_UNUSED)
 
 /**
  * pango_font_describe:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
  * Returns a description of the font, with font size set in points.
- * Use pango_font_describe_with_absolute_size() if you want the font
- * size in device units.
  *
- * Return value: a newly-allocated #PangoFontDescription object.
- **/
+ * Use [method@Pango.Font.describe_with_absolute_size] if you want
+ * the font size in device units.
+ *
+ * Return value: a newly-allocated `PangoFontDescription` object.
+ */
 PangoFontDescription *
-pango_font_describe (PangoFont      *font)
+pango_font_describe (PangoFont *font)
 {
   g_return_val_if_fail (font != NULL, NULL);
 
@@ -1699,18 +1735,19 @@ pango_font_describe (PangoFont      *font)
 
 /**
  * pango_font_describe_with_absolute_size:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
  * Returns a description of the font, with absolute font size set
- * (in device units). Use pango_font_describe() if you want the font
- * size in points.
+ * in device units.
  *
- * Return value: a newly-allocated #PangoFontDescription object.
+ * Use [method@Pango.Font.describe] if you want the font size in points.
+ *
+ * Return value: a newly-allocated `PangoFontDescription` object.
  *
  * Since: 1.14
- **/
+ */
 PangoFontDescription *
-pango_font_describe_with_absolute_size (PangoFont      *font)
+pango_font_describe_with_absolute_size (PangoFont *font)
 {
   g_return_val_if_fail (font != NULL, NULL);
 
@@ -1725,17 +1762,17 @@ pango_font_describe_with_absolute_size (PangoFont      *font)
 
 /**
  * pango_font_get_coverage:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @language: the language tag
  *
  * Computes the coverage map for a given font and language tag.
  *
- * Return value: (transfer full): a newly-allocated #PangoCoverage
+ * Return value: (transfer full): a newly-allocated `PangoCoverage`
  *   object.
- **/
+ */
 PangoCoverage *
 pango_font_get_coverage (PangoFont     *font,
-			 PangoLanguage *language)
+                         PangoLanguage *language)
 {
   g_return_val_if_fail (font != NULL, NULL);
 
@@ -1744,7 +1781,7 @@ pango_font_get_coverage (PangoFont     *font,
 
 /**
  * pango_font_find_shaper:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @language: the language tag
  * @ch: a Unicode character.
  *
@@ -1753,26 +1790,27 @@ pango_font_get_coverage (PangoFont     *font,
  *
  * Return value: (transfer none): the best matching shaper.
  * Deprecated: Shape engines are no longer used
- **/
+ */
 PangoEngineShape *
 pango_font_find_shaper (PangoFont     *font,
-			PangoLanguage *language,
-			guint32        ch)
+                        PangoLanguage *language,
+                        guint32        ch)
 {
   return NULL;
 }
 
 /**
  * pango_font_get_glyph_extents:
- * @font: (nullable): a #PangoFont
+ * @font: (nullable): a `PangoFont`
  * @glyph: the glyph index
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph
  *            as drawn or %NULL to indicate that the result is not needed.
  * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of
  *            the glyph or %NULL to indicate that the result is not needed.
  *
- * Gets the logical and ink extents of a glyph within a font. The
- * coordinate system for each rectangle has its origin at the
+ * Gets the logical and ink extents of a glyph within a font.
+ *
+ * The coordinate system for each rectangle has its origin at the
  * base line and horizontal origin of the character with increasing
  * coordinates extending to the right and down. The macros PANGO_ASCENT(),
  * PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
@@ -1781,29 +1819,29 @@ pango_font_find_shaper (PangoFont     *font,
  *
  * If @font is %NULL, this function gracefully sets some sane values in the
  * output variables and returns.
- **/
+ */
 void
 pango_font_get_glyph_extents  (PangoFont      *font,
-			       PangoGlyph      glyph,
-			       PangoRectangle *ink_rect,
-			       PangoRectangle *logical_rect)
+                               PangoGlyph      glyph,
+                               PangoRectangle *ink_rect,
+                               PangoRectangle *logical_rect)
 {
   if (G_UNLIKELY (!font))
     {
       if (ink_rect)
-	{
-	  ink_rect->x = PANGO_SCALE;
-	  ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE;
-	  ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE;
-	  ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE;
-	}
+        {
+          ink_rect->x = PANGO_SCALE;
+          ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE;
+          ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE;
+          ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE;
+        }
       if (logical_rect)
-	{
-	  logical_rect->x = 0;
-	  logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
-	  logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
-	  logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE;
-	}
+        {
+          logical_rect->x = 0;
+          logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
+          logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
+          logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE;
+        }
       return;
     }
 
@@ -1812,24 +1850,26 @@ pango_font_get_glyph_extents  (PangoFont      *font,
 
 /**
  * pango_font_get_metrics:
- * @font: (nullable): a #PangoFont
- * @language: (allow-none): language tag used to determine which script to get the metrics
- *            for, or %NULL to indicate to get the metrics for the entire font.
+ * @font: (nullable): a `PangoFont`
+ * @language: (allow-none): language tag used to determine which script
+ *   to get the metrics for, or %NULL to indicate to get the metrics for
+ *   the entire font.
+ *
+ * Gets overall metric information for a font.
  *
- * Gets overall metric information for a font. Since the metrics may be
- * substantially different for different scripts, a language tag can
- * be provided to indicate that the metrics should be retrieved that
- * correspond to the script(s) used by that language.
+ * Since the metrics may be substantially different for different scripts,
+ * a language tag can be provided to indicate that the metrics should be
+ * retrieved that correspond to the script(s) used by that language.
  *
  * If @font is %NULL, this function gracefully sets some sane values in the
  * output variables and returns.
  *
- * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref()
- *   when finished using the object.
- **/
+ * Return value: a `PangoFontMetrics` object. The caller must call
+ *   [method@Pango.FontMetrics.unref] when finished using the object.
+ */
 PangoFontMetrics *
-pango_font_get_metrics (PangoFont        *font,
-			PangoLanguage    *language)
+pango_font_get_metrics (PangoFont     *font,
+                        PangoLanguage *language)
 {
   if (G_UNLIKELY (!font))
     {
@@ -1853,23 +1893,24 @@ pango_font_get_metrics (PangoFont        *font,
 
 /**
  * pango_font_get_font_map:
- * @font: (nullable): a #PangoFont, or %NULL
+ * @font: (nullable): a `PangoFont`, or %NULL
  *
  * Gets the font map for which the font was created.
  *
- * Note that the font maintains a <firstterm>weak</firstterm> reference
- * to the font map, so if all references to font map are dropped, the font
- * map will be finalized even if there are fonts created with the font
- * map that are still alive.  In that case this function will return %NULL.
+ * Note that the font maintains a *weak* reference to the font map, so if
+ * all references to font map are dropped, the font map will be finalized
+ * even if there are fonts created with the font map that are still alive.
+ * In that case this function will return %NULL.
+ *
  * It is the responsibility of the user to ensure that the font map is kept
- * alive.  In most uses this is not an issue as a #PangoContext holds
+ * alive. In most uses this is not an issue as a #PangoContext holds
  * a reference to the font map.
  *
- * Return value: (transfer none) (nullable): the #PangoFontMap for the
- *               font, or %NULL if @font is %NULL.
+ * Return value: (transfer none) (nullable): the `PangoFontMap` for the
+ *   font, or %NULL if @font is %NULL.
  *
  * Since: 1.10
- **/
+ */
 PangoFontMap *
 pango_font_get_font_map (PangoFont *font)
 {
@@ -1884,11 +1925,11 @@ pango_font_get_font_map (PangoFont *font)
 
 /**
  * pango_font_get_face:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Gets the #PangoFontFace to which @font belongs.
+ * Gets the `PangoFontFace` to which @font belongs.
  *
- * Returns: (transfer none): the #PangoFontFace
+ * Returns: (transfer none): the `PangoFontFace`
  *
  * Since: 1.46
  */
@@ -1902,16 +1943,15 @@ pango_font_get_face (PangoFont *font)
 
 /**
  * pango_font_get_hb_font: (skip)
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Get a hb_font_t object backing this font.
+ * Get a `hb_font_t` object backing this font.
  *
- * Note that the objects returned by this function
- * are cached and immutable. If you need to make
- * changes to the hb_font_t, use hb_font_create_sub_font().
+ * Note that the objects returned by this function are cached and immutable.
+ * If you need to make changes to the `hb_font_t`, use hb_font_create_sub_font().
  *
- * Returns: (transfer none) (nullable): the hb_font_t object backing the
- *          font, or %NULL if the font does not have one
+ * Returns: (transfer none) (nullable): the `hb_font_t` object backing the
+ *   font, or %NULL if the font does not have one
  *
  * Since: 1.44
  */
@@ -1939,13 +1979,14 @@ G_DEFINE_BOXED_TYPE (PangoFontMetrics, pango_font_metrics,
 /**
  * pango_font_metrics_new:
  *
- * Creates a new #PangoFontMetrics structure. This is only for
- * internal use by Pango backends and there is no public way
- * to set the fields of the structure.
+ * Creates a new `PangoFontMetrics` structure.
  *
- * Return value: a newly-created #PangoFontMetrics structure
+ * This is only for internal use by Pango backends and there is
+ * no public way to set the fields of the structure.
+ *
+ * Return value: a newly-created `PangoFontMetrics` structure
  *   with a reference count of 1.
- **/
+ */
 PangoFontMetrics *
 pango_font_metrics_new (void)
 {
@@ -1957,12 +1998,12 @@ pango_font_metrics_new (void)
 
 /**
  * pango_font_metrics_ref:
- * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL
  *
  * Increase the reference count of a font metrics structure by one.
  *
  * Return value: (nullable): @metrics
- **/
+ */
 PangoFontMetrics *
 pango_font_metrics_ref (PangoFontMetrics *metrics)
 {
@@ -1976,12 +2017,11 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_unref:
- * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL
  *
- * Decrease the reference count of a font metrics structure by one. If
- * the result is zero, frees the structure and any associated
- * memory.
- **/
+ * Decrease the reference count of a font metrics structure by one.
+ * If the result is zero, frees the structure and any associated memory.
+ */
 void
 pango_font_metrics_unref (PangoFontMetrics *metrics)
 {
@@ -1996,16 +2036,17 @@ pango_font_metrics_unref (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_ascent:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
+ *
+ * Gets the ascent from a font metrics structure.
  *
- * Gets the ascent from a font metrics structure. The ascent is
- * the distance from the baseline to the logical top of a line
- * of text. (The logical top may be above or below the top of the
- * actual drawn ink. It is necessary to lay out the text to figure
- * where the ink will be.)
+ * The ascent is the distance from the baseline to the logical top
+ * of a line of text. (The logical top may be above or below the top
+ * of the actual drawn ink. It is necessary to lay out the text to
+ * figure where the ink will be.)
  *
  * Return value: the ascent, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
 {
@@ -2016,16 +2057,17 @@ pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_descent:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
+ *
+ * Gets the descent from a font metrics structure.
  *
- * Gets the descent from a font metrics structure. The descent is
- * the distance from the baseline to the logical bottom of a line
- * of text. (The logical bottom may be above or below the bottom of the
- * actual drawn ink. It is necessary to lay out the text to figure
- * where the ink will be.)
+ * The descent is the distance from the baseline to the logical bottom
+ * of a line of text. (The logical bottom may be above or below the
+ * bottom of the actual drawn ink. It is necessary to lay out the text
+ * to figure where the ink will be.)
  *
  * Return value: the descent, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_descent (PangoFontMetrics *metrics)
 {
@@ -2036,10 +2078,11 @@ pango_font_metrics_get_descent (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_height:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
- * Gets the line height from a font metrics structure. The
- * line height is the distance between successive baselines
+ * Gets the line height from a font metrics structure.
+ *
+ * The line height is the distance between successive baselines
  * in wrapped text.
  *
  * If the line height is not available, 0 is returned.
@@ -2058,15 +2101,16 @@ pango_font_metrics_get_height (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_approximate_char_width:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the approximate character width for a font metrics structure.
+ *
  * This is merely a representative value useful, for example, for
  * determining the initial size for a window. Actual characters in
  * text will be wider and narrower than this.
  *
  * Return value: the character width, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
 {
@@ -2077,9 +2121,10 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_approximate_digit_width:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the approximate digit width for a font metrics structure.
+ *
  * This is merely a representative value useful, for example, for
  * determining the initial size for a window. Actual digits in
  * text can be wider or narrower than this, though this value
@@ -2087,7 +2132,7 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
  * pango_font_metrics_get_approximate_char_width() for digits.
  *
  * Return value: the digit width, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics)
 {
@@ -2098,18 +2143,18 @@ pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_underline_position:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested position to draw the underline.
- * The value returned is the distance <emphasis>above</emphasis> the
- * baseline of the top of the underline. Since most fonts have
- * underline positions beneath the baseline, this value is typically
- * negative.
+ *
+ * The value returned is the distance *above* the baseline of the top
+ * of the underline. Since most fonts have underline positions beneath
+ * the baseline, this value is typically negative.
  *
  * Return value: the suggested underline position, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_underline_position (PangoFontMetrics *metrics)
 {
@@ -2120,14 +2165,14 @@ pango_font_metrics_get_underline_position (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_underline_thickness:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested thickness to draw for the underline.
  *
  * Return value: the suggested underline thickness, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_underline_thickness (PangoFontMetrics *metrics)
 {
@@ -2138,16 +2183,17 @@ pango_font_metrics_get_underline_thickness (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_strikethrough_position:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested position to draw the strikethrough.
- * The value returned is the distance <emphasis>above</emphasis> the
+ *
+ * The value returned is the distance *above* the
  * baseline of the top of the strikethrough.
  *
  * Return value: the suggested strikethrough position, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_strikethrough_position (PangoFontMetrics *metrics)
 {
@@ -2158,14 +2204,14 @@ pango_font_metrics_get_strikethrough_position (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_strikethrough_thickness:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested thickness to draw for the strikethrough.
  *
  * Return value: the suggested strikethrough thickness, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_strikethrough_thickness (PangoFontMetrics *metrics)
 {
@@ -2243,15 +2289,17 @@ pango_font_family_init (PangoFontFamily *family G_GNUC_UNUSED)
 
 /**
  * pango_font_family_get_name:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  *
- * Gets the name of the family. The name is unique among all
- * fonts for the font backend and can be used in a #PangoFontDescription
- * to specify that a face from this family is desired.
+ * Gets the name of the family.
+ *
+ * The name is unique among all fonts for the font backend and can
+ * be used in a `PangoFontDescription` to specify that a face from
+ * this family is desired.
  *
  * Return value: the name of the family. This string is owned
  *   by the family object and must not be modified or freed.
- **/
+ */
 const char *
 pango_font_family_get_name (PangoFontFamily  *family)
 {
@@ -2262,21 +2310,22 @@ pango_font_family_get_name (PangoFontFamily  *family)
 
 /**
  * pango_font_family_list_faces:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  * @faces: (out) (allow-none) (array length=n_faces) (transfer container):
- *   location to store an array of pointers to #PangoFontFace objects,
+ *   location to store an array of pointers to `PangoFontFace` objects,
  *   or %NULL. This array should be freed with g_free() when it is no
  *   longer needed.
  * @n_faces: (out): location to store number of elements in @faces.
  *
- * Lists the different font faces that make up @family. The faces
- * in a family share a common design, but differ in slant, weight,
+ * Lists the different font faces that make up @family.
+ *
+ * The faces in a family share a common design, but differ in slant, weight,
  * width and other aspects.
- **/
+ */
 void
 pango_font_family_list_faces (PangoFontFamily  *family,
-			      PangoFontFace  ***faces,
-			      int              *n_faces)
+                              PangoFontFace  ***faces,
+                              int              *n_faces)
 {
   g_return_if_fail (PANGO_IS_FONT_FAMILY (family));
 
@@ -2318,14 +2367,14 @@ pango_font_family_real_get_face (PangoFontFamily *family,
 
 /**
  * pango_font_family_get_face:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  * @name: (nullable): the name of a face. If the name is %NULL,
  *     the family's default face (fontconfig calls it "Regular")
  *     will be returned.
  *
- * Gets the #PangoFontFace of @family with the given name.
+ * Gets the `PangoFontFace` of @family with the given name.
  *
- * Returns: (transfer none) (nullable): the #PangoFontFace,
+ * Returns: (transfer none) (nullable): the `PangoFontFace`,
  *     or %NULL if no face with the given name exists.
  *
  * Since: 1.46
@@ -2341,10 +2390,12 @@ pango_font_family_get_face (PangoFontFamily *family,
 
 /**
  * pango_font_family_is_monospace:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  *
  * A monospace font is a font designed for text display where the the
- * characters form a regular grid. For Western languages this would
+ * characters form a regular grid.
+ *
+ * For Western languages this would
  * mean that the advance width of all characters are the same, but
  * this categorization also includes Asian fonts which include
  * double-width characters: characters that occupy two grid cells.
@@ -2352,14 +2403,14 @@ pango_font_family_get_face (PangoFontFamily *family,
  * character is typically double-width in a monospace font.
  *
  * The best way to find out the grid-cell size is to call
- * pango_font_metrics_get_approximate_digit_width(), since the results
- * of pango_font_metrics_get_approximate_char_width() may be affected
- * by double-width characters.
+ * [method@Pango.FontMetrics.get_approximate_digit_width], since the
+ * results of [method@Pango.FontMetrics.get_approximate_char_width] may
+ * be affected by double-width characters.
  *
  * Return value: %TRUE if the family is monospace.
  *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_font_family_is_monospace (PangoFontFamily  *family)
 {
@@ -2373,7 +2424,7 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
 
 /**
  * pango_font_family_is_variable:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  *
  * A variable font is a font which has axes that can be modified to
  * produce different faces.
@@ -2381,7 +2432,7 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
  * Return value: %TRUE if the family is variable
  *
  * Since: 1.44
- **/
+ */
 gboolean
 pango_font_family_is_variable (PangoFontFamily  *family)
 {
@@ -2411,16 +2462,16 @@ pango_font_face_init (PangoFontFace *face G_GNUC_UNUSED)
 
 /**
  * pango_font_face_describe:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
  * Returns the family, style, variant, weight and stretch of
- * a #PangoFontFace. The size field of the resulting font description
+ * a `PangoFontFace`. The size field of the resulting font description
  * will be unset.
  *
- * Return value: a newly-created #PangoFontDescription structure
- *  holding the description of the face. Use pango_font_description_free()
- *  to free the result.
- **/
+ * Return value: a newly-created `PangoFontDescription` structure
+ *   holding the description of the face. Use [method@Pango.FontDescription.free]
+ *   to free the result.
+ */
 PangoFontDescription *
 pango_font_face_describe (PangoFontFace *face)
 {
@@ -2431,16 +2482,16 @@ pango_font_face_describe (PangoFontFace *face)
 
 /**
  * pango_font_face_is_synthesized:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
- * Returns whether a #PangoFontFace is synthesized by the underlying
+ * Returns whether a `PangoFontFace` is synthesized by the underlying
  * font rendering engine from another face, perhaps by shearing, emboldening,
  * or lightening it.
  *
  * Return value: whether @face is synthesized.
  *
  * Since: 1.18
- **/
+ */
 gboolean
 pango_font_face_is_synthesized (PangoFontFace  *face)
 {
@@ -2454,15 +2505,15 @@ pango_font_face_is_synthesized (PangoFontFace  *face)
 
 /**
  * pango_font_face_get_face_name:
- * @face: a #PangoFontFace.
+ * @face: a `PangoFontFace`.
  *
  * Gets a name representing the style of this face among the
- * different faces in the #PangoFontFamily for the face. The
+ * different faces in the `PangoFontFamily` for the face. The
  * name is suitable for displaying to users.
  *
  * Return value: the face name for the face. This string is
  *   owned by the face object and must not be modified or freed.
- **/
+ */
 const char *
 pango_font_face_get_face_name (PangoFontFace *face)
 {
@@ -2473,23 +2524,25 @@ pango_font_face_get_face_name (PangoFontFace *face)
 
 /**
  * pango_font_face_list_sizes:
- * @face: a #PangoFontFace.
+ * @face: a `PangoFontFace`.
  * @sizes: (out) (array length=n_sizes) (nullable) (optional):
  *         location to store a pointer to an array of int. This array
  *         should be freed with g_free().
  * @n_sizes: location to store the number of elements in @sizes
  *
- * List the available sizes for a font. This is only applicable to bitmap
- * fonts. For scalable fonts, stores %NULL at the location pointed to by
- * @sizes and 0 at the location pointed to by @n_sizes. The sizes returned
- * are in Pango units and are sorted in ascending order.
+ * List the available sizes for a font.
+ *
+ * This is only applicable to bitmap fonts. For scalable fonts, stores
+ * %NULL at the location pointed to by @sizes and 0 at the location pointed
+ * to by @n_sizes. The sizes returned are in Pango units and are sorted
+ * in ascending order.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_font_face_list_sizes (PangoFontFace  *face,
-			    int           **sizes,
-			    int            *n_sizes)
+                            int           **sizes,
+                            int            *n_sizes)
 {
   g_return_if_fail (PANGO_IS_FONT_FACE (face));
   g_return_if_fail (sizes == NULL || n_sizes != NULL);
@@ -2502,19 +2555,18 @@ pango_font_face_list_sizes (PangoFontFace  *face,
   else
     {
       if (sizes != NULL)
-	*sizes = NULL;
+        *sizes = NULL;
       *n_sizes = 0;
     }
 }
 
 /**
  * pango_font_face_get_family:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
- * Gets the #PangoFontFamily that @face
- * belongs to.
+ * Gets the `PangoFontFamily` that @face belongs to.
  *
- * Returns: (transfer none): the #PangoFontFamily
+ * Returns: (transfer none): the `PangoFontFamily`
  *
  * Since: 1.46
  */
@@ -2528,7 +2580,7 @@ pango_font_face_get_family (PangoFontFace *face)
 
 /**
  * pango_font_has_char:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @wc: a Unicode character
  *
  * Returns whether the font provides a glyph for this character.
@@ -2549,12 +2601,13 @@ pango_font_has_char (PangoFont *font,
 
 /**
  * pango_font_get_features:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @features: (out caller-allocates) (array length=len): Array to features in
  * @len: the length of @features
  * @num_features: (inout): the number of used items in @features
  *
  * Obtain the OpenType features that are provided by the font.
+ *
  * These are passed to the rendering system, together with features
  * that have been explicitly set via attributes.
  *
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 6c674e03..649e7758 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -28,10 +28,10 @@
 /**
  * pango_glyph_string_new:
  *
- * Create a new #PangoGlyphString.
+ * Create a new `PangoGlyphString`.
  *
- * Return value: the newly allocated #PangoGlyphString, which
- *               should be freed with pango_glyph_string_free().
+ * Return value: the newly allocated `PangoGlyphString`, which
+ *               should be freed with [method@Pango.GlyphString.free].
  */
 PangoGlyphString *
 pango_glyph_string_new (void)
@@ -48,7 +48,7 @@ pango_glyph_string_new (void)
 
 /**
  * pango_glyph_string_set_size:
- * @string:    a #PangoGlyphString.
+ * @string:    a `PangoGlyphString`.
  * @new_len:   the new length of the string.
  *
  * Resize a glyph string to the given length.
@@ -97,12 +97,12 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string,
 
 /**
  * pango_glyph_string_copy:
- * @string: (nullable): a #PangoGlyphString, may be %NULL
+ * @string: (nullable): a `PangoGlyphString`, may be %NULL
  *
  * Copy a glyph string and associated storage.
  *
- * Return value: (nullable): the newly allocated #PangoGlyphString,
- *               which should be freed with pango_glyph_string_free(),
+ * Return value: (nullable): the newly allocated `PangoGlyphString`,
+ *               which should be freed with [method@Pango.GlyphString.free],
  *               or %NULL if @string was %NULL.
  */
 PangoGlyphString *
@@ -127,7 +127,7 @@ pango_glyph_string_copy (PangoGlyphString *string)
 
 /**
  * pango_glyph_string_free:
- * @string: (nullable): a #PangoGlyphString, may be %NULL
+ * @string: (nullable): a `PangoGlyphString`, may be %NULL
  *
  * Free a glyph string and associated storage.
  */
@@ -144,11 +144,11 @@ pango_glyph_string_free (PangoGlyphString *string)
 
 /**
  * pango_glyph_string_extents_range:
- * @glyphs:   a #PangoGlyphString
+ * @glyphs:   a `PangoGlyphString`
  * @start:    start index
  * @end:      end index (the range is the set of bytes with
 	      indices such that start <= index < end)
- * @font:     a #PangoFont
+ * @font:     a `PangoFont`
  * @ink_rect: (out caller-allocates) (optional): rectangle used to
  *            store the extents of the glyph string range as drawn or
  *            %NULL to indicate that the result is not needed.
@@ -156,11 +156,12 @@ pango_glyph_string_free (PangoGlyphString *string)
  *            store the logical extents of the glyph string range or
  *            %NULL to indicate that the result is not needed.
  *
- * Computes the extents of a sub-portion of a glyph string. The extents are
- * relative to the start of the glyph string range (the origin of their
- * coordinate system is at the start of the range, not at the start of the entire
- * glyph string).
- **/
+ * Computes the extents of a sub-portion of a glyph string.
+ *
+ * The extents are relative to the start of the glyph string range
+ * (the origin of their coordinate system is at the start of the range,
+ * not at the start of the entire glyph string).
+ */
 void
 pango_glyph_string_extents_range (PangoGlyphString *glyphs,
 				  int               start,
@@ -261,16 +262,17 @@ pango_glyph_string_extents_range (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_extents:
- * @glyphs:   a #PangoGlyphString
- * @font:     a #PangoFont
+ * @glyphs:   a `PangoGlyphString`
+ * @font:     a `PangoFont`
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph string
  *            as drawn or %NULL to indicate that the result is not needed.
  * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of the
  *            glyph string or %NULL to indicate that the result is not needed.
  *
- * Compute the logical and ink extents of a glyph string. See the documentation
- * for pango_font_get_glyph_extents() for details about the interpretation
- * of the rectangles.
+ * Compute the logical and ink extents of a glyph string.
+ *
+ * See the documentation for [method@Pango.Font.get_glyph_extents] for details
+ * about the interpretation of the rectangles.
  *
  * Examples of logical (red) and ink (green) rects:
  *
@@ -288,12 +290,14 @@ pango_glyph_string_extents (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_get_width:
- * @glyphs:   a #PangoGlyphString
+ * @glyphs:  a `PangoGlyphString`
+ *
+ * Computes the logical width of the glyph string.
  *
- * Computes the logical width of the glyph string as can also be computed
- * using pango_glyph_string_extents().  However, since this only computes the
- * width, it's much faster.  This is in fact only a convenience function that
- * computes the sum of geometry.width for each glyph in the @glyphs.
+ * This can also be computed using [method@Pango.GlyphString.extents].
+ * However, since this only computes the width, it's much faster. This
+ * is in fact only a convenience function that computes the sum of
+ * @geometry.width for each glyph in the @glyphs.
  *
  * Return value: the logical width of the glyph string.
  *
@@ -313,7 +317,7 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs)
 
 /**
  * pango_glyph_string_get_logical_widths:
- * @glyphs: a #PangoGlyphString
+ * @glyphs: a `PangoGlyphString`
  * @text: the text corresponding to the glyphs
  * @length: the length of @text, in bytes
  * @embedding_level: the embedding level of the string
@@ -322,13 +326,14 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs)
  *                  length) unless text has NUL bytes) to be filled in
  *                  with the resulting character widths.
  *
- * Given a #PangoGlyphString resulting from pango_shape() and the corresponding
- * text, determine the screen width corresponding to each character. When
- * multiple characters compose a single cluster, the width of the entire
- * cluster is divided equally among the characters.
+ * Given a `PangoGlyphString` and corresponding text, determine the width
+ * corresponding to each character.
  *
- * See also pango_glyph_item_get_logical_widths().
- **/
+ * When multiple characters compose a single cluster, the width of the
+ * entire cluster is divided equally among the characters.
+ *
+ * See also [method@Pango.GlyphItem.get_logical_widths].
+ */
 void
 pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
 				       const char       *text,
@@ -358,18 +363,20 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_index_to_x:
- * @glyphs:    the glyphs return from pango_shape()
+ * @glyphs:    the glyphs return from [func@shape]
  * @text:      the text for the run
  * @length:    the number of bytes (not characters) in @text.
- * @analysis:  the analysis information return from pango_itemize()
+ * @analysis:  the analysis information return from [func@itemize]
  * @index_:    the byte index within @text
  * @trailing:  whether we should compute the result for the beginning (%FALSE)
  *             or end (%TRUE) of the character.
  * @x_pos:     (out): location to store result
  *
- * Converts from character position to x position. (X position
- * is measured from the left edge of the run). Character positions
- * are computed by dividing up each cluster into equal portions.
+ * Converts from character position to x position.
+ *
+ * The X position is measured from the left edge of the run.
+ * Character positions are computed by dividing up each cluster
+ * into equal portions.
  */
 
 void
@@ -486,21 +493,22 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_x_to_index:
- * @glyphs:    the glyphs returned from pango_shape()
+ * @glyphs:    the glyphs returned from [func@shape]
  * @text:      the text for the run
  * @length:    the number of bytes (not characters) in text.
- * @analysis:  the analysis information return from pango_itemize()
+ * @analysis:  the analysis information return from [func@itemize]
  * @x_pos:     the x offset (in Pango units)
  * @index_:    (out): location to store calculated byte index within @text
  * @trailing:  (out): location to store a boolean indicating
  *             whether the user clicked on the leading or trailing
  *             edge of the character.
  *
- * Convert from x offset to character position. Character positions
- * are computed by dividing up each cluster into equal portions.
- * In scripts where positioning within a cluster is not allowed
- * (such as Thai), the returned value may not be a valid cursor
- * position; the caller must combine the result with the logical
+ * Convert from x offset to character position.
+ *
+ * Character positions are computed by dividing up each cluster into
+ * equal portions. In scripts where positioning within a cluster is
+ * not allowed (such as Thai), the returned value may not be a valid
+ * cursor position; the caller must combine the result with the logical
  * attributes for the text to compute the valid cursor position.
  */
 void
diff --git a/pango/modules.c b/pango/modules.c
index 54f9db8f..b7ba105b 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -19,19 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:modules
- * @short_description:Support for loadable modules
- * @title:Modules
- *
- * Functions and macros in this section were used to support
- * loading dynamic modules that add engines to Pango at run time.
- *
- * That is no longer the case, and these APIs should not be
- * used anymore.
- *
- * Deprecated: 1.38
- */
 #include "config.h"
 
 #include "pango-modules.h"
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 8f23fe77..225dc654 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -19,17 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:text-attributes
- * @short_description:Font and other attributes for annotating text
- * @title:Attributes
- *
- * Attributed text is used in a number of places in Pango. It
- * is used as the input to the itemization process and also when
- * creating a #PangoLayout. The data types and functions in
- * this section are used to represent and manipulate sets
- * of attributes applied to a portion of text.
- */
 #include "config.h"
 #include <string.h>
 
@@ -38,17 +27,17 @@
 #include "pango-impl-utils.h"
 
 static PangoAttribute *pango_attr_color_new         (const PangoAttrClass *klass,
-						     guint16               red,
-						     guint16               green,
-						     guint16               blue);
+                                                     guint16               red,
+                                                     guint16               green,
+                                                     guint16               blue);
 static PangoAttribute *pango_attr_string_new        (const PangoAttrClass *klass,
-						     const char           *str);
+                                                     const char           *str);
 static PangoAttribute *pango_attr_int_new           (const PangoAttrClass *klass,
-						     int                   value);
+                                                     int                   value);
 static PangoAttribute *pango_attr_float_new         (const PangoAttrClass *klass,
-						     double                value);
+                                                     double                value);
 static PangoAttribute *pango_attr_size_new_internal (int                   size,
-						     gboolean              absolute);
+                                                     gboolean              absolute);
 
 
 G_LOCK_DEFINE_STATIC (attr_type);
@@ -58,11 +47,12 @@ static GHashTable *name_map = NULL; /* MT-safe */
  * pango_attr_type_register:
  * @name: an identifier for the type
  *
- * Allocate a new attribute type ID.  The attribute type name can be accessed
- * later by using pango_attr_type_get_name().
+ * Allocate a new attribute type ID.
+ *
+ * The attribute type name can be accessed later by using [type_func@Pango.AttrType.get_name].
  *
  * Return value: the new type ID.
- **/
+ */
 PangoAttrType
 pango_attr_type_register (const gchar *name)
 {
@@ -76,7 +66,7 @@ pango_attr_type_register (const gchar *name)
   if (name)
     {
       if (G_UNLIKELY (!name_map))
-	name_map = g_hash_table_new (NULL, NULL);
+        name_map = g_hash_table_new (NULL, NULL);
 
       g_hash_table_insert (name_map, GUINT_TO_POINTER (type), (gpointer) g_intern_string (name));
     }
@@ -90,17 +80,19 @@ pango_attr_type_register (const gchar *name)
  * pango_attr_type_get_name:
  * @type: an attribute type ID to fetch the name for
  *
- * Fetches the attribute type name passed in when registering the type using
- * pango_attr_type_register().
+ * Fetches the attribute type name.
+ *
+ * The attribute type name is the string passed in when registering the type
+ * using [type_func@attr_type_register].
  *
  * The returned value is an interned string (see g_intern_string() for what
  * that means) that should not be modified or freed.
  *
  * Return value: (nullable): the type ID name (which may be %NULL), or
- * %NULL if @type is a built-in Pango attribute type or invalid.
+ *   %NULL if @type is a built-in Pango attribute type or invalid.
  *
  * Since: 1.22
- **/
+ */
 const char *
 pango_attr_type_get_name (PangoAttrType type)
 {
@@ -118,20 +110,19 @@ pango_attr_type_get_name (PangoAttrType type)
 
 /**
  * pango_attribute_init:
- * @attr: a #PangoAttribute
- * @klass: a #PangoAttrClass
+ * @attr: a `PangoAttribute`
+ * @klass: a `PangoAttrClass`
  *
- * Initializes @attr's klass to @klass,
- * it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
- * and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END
- * such that the attribute applies
+ * Initializes @attr's klass to @klass, it's start_index to
+ * %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to
+ * %PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies
  * to the entire text by default.
  *
  * Since: 1.20
- **/
+ */
 void
 pango_attribute_init (PangoAttribute       *attr,
-		      const PangoAttrClass *klass)
+                      const PangoAttrClass *klass)
 {
   g_return_if_fail (attr != NULL);
   g_return_if_fail (klass != NULL);
@@ -143,13 +134,13 @@ pango_attribute_init (PangoAttribute       *attr,
 
 /**
  * pango_attribute_copy:
- * @attr: a #PangoAttribute
+ * @attr: a `PangoAttribute`
  *
  * Make a copy of an attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attribute_copy (const PangoAttribute *attr)
 {
@@ -166,10 +157,10 @@ pango_attribute_copy (const PangoAttribute *attr)
 
 /**
  * pango_attribute_destroy:
- * @attr: a #PangoAttribute.
+ * @attr: a `PangoAttribute`.
  *
- * Destroy a #PangoAttribute and free all associated memory.
- **/
+ * Destroy a `PangoAttribute` and free all associated memory.
+ */
 void
 pango_attribute_destroy (PangoAttribute *attr)
 {
@@ -184,18 +175,18 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute,
 
 /**
  * pango_attribute_equal:
- * @attr1: a #PangoAttribute
- * @attr2: another #PangoAttribute
+ * @attr1: a `PangoAttribute`
+ * @attr2: another `PangoAttribute`
  *
  * Compare two attributes for equality. This compares only the
  * actual value of the two attributes and not the ranges that the
  * attributes apply to.
  *
  * Return value: %TRUE if the two attributes have the same value.
- **/
+ */
 gboolean
 pango_attribute_equal (const PangoAttribute *attr1,
-		       const PangoAttribute *attr2)
+                       const PangoAttribute *attr2)
 {
   g_return_val_if_fail (attr1 != NULL, FALSE);
   g_return_val_if_fail (attr2 != NULL, FALSE);
@@ -223,14 +214,14 @@ pango_attr_string_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_string_equal (const PangoAttribute *attr1,
-			 const PangoAttribute *attr2)
+                         const PangoAttribute *attr2)
 {
   return strcmp (((PangoAttrString *)attr1)->value, ((PangoAttrString *)attr2)->value) == 0;
 }
 
 static PangoAttribute *
 pango_attr_string_new (const PangoAttrClass *klass,
-		       const char           *str)
+                       const char           *str)
 {
   PangoAttrString *result = g_slice_new (PangoAttrString);
   pango_attribute_init (&result->attr, klass);
@@ -245,9 +236,9 @@ pango_attr_string_new (const PangoAttrClass *klass,
  *
  * Create a new font family attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_family_new (const char *family)
 {
@@ -279,7 +270,7 @@ pango_attr_language_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_language_equal (const PangoAttribute *attr1,
-			   const PangoAttribute *attr2)
+                           const PangoAttribute *attr2)
 {
   return ((PangoAttrLanguage *)attr1)->value == ((PangoAttrLanguage *)attr2)->value;
 }
@@ -290,9 +281,9 @@ pango_attr_language_equal (const PangoAttribute *attr1,
  *
  * Create a new language tag attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_language_new (PangoLanguage *language)
 {
@@ -318,9 +309,9 @@ pango_attr_color_copy (const PangoAttribute *attr)
   const PangoAttrColor *color_attr = (PangoAttrColor *)attr;
 
   return pango_attr_color_new (attr->klass,
-			       color_attr->color.red,
-			       color_attr->color.green,
-			       color_attr->color.blue);
+                               color_attr->color.red,
+                               color_attr->color.green,
+                               color_attr->color.blue);
 }
 
 static void
@@ -333,21 +324,21 @@ pango_attr_color_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_color_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrColor *color_attr1 = (const PangoAttrColor *)attr1;
   const PangoAttrColor *color_attr2 = (const PangoAttrColor *)attr2;
 
   return (color_attr1->color.red == color_attr2->color.red &&
-	  color_attr1->color.blue == color_attr2->color.blue &&
-	  color_attr1->color.green == color_attr2->color.green);
+          color_attr1->color.blue == color_attr2->color.blue &&
+          color_attr1->color.green == color_attr2->color.green);
 }
 
 static PangoAttribute *
 pango_attr_color_new (const PangoAttrClass *klass,
-		      guint16               red,
-		      guint16               green,
-		      guint16               blue)
+                      guint16               red,
+                      guint16               green,
+                      guint16               blue)
 {
   PangoAttrColor *result = g_slice_new (PangoAttrColor);
   pango_attribute_init (&result->attr, klass);
@@ -366,13 +357,13 @@ pango_attr_color_new (const PangoAttrClass *klass,
  *
  * Create a new foreground color attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_foreground_new (guint16 red,
-			   guint16 green,
-			   guint16 blue)
+                           guint16 green,
+                           guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_FOREGROUND,
@@ -392,13 +383,13 @@ pango_attr_foreground_new (guint16 red,
  *
  * Create a new background color attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_background_new (guint16 red,
-			   guint16 green,
-			   guint16 blue)
+                           guint16 green,
+                           guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_BACKGROUND,
@@ -428,7 +419,7 @@ pango_attr_int_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_int_equal (const PangoAttribute *attr1,
-		      const PangoAttribute *attr2)
+                      const PangoAttribute *attr2)
 {
   const PangoAttrInt *int_attr1 = (const PangoAttrInt *)attr1;
   const PangoAttrInt *int_attr2 = (const PangoAttrInt *)attr2;
@@ -438,7 +429,7 @@ pango_attr_int_equal (const PangoAttribute *attr1,
 
 static PangoAttribute *
 pango_attr_int_new (const PangoAttrClass *klass,
-		    int                   value)
+                    int                   value)
 {
   PangoAttrInt *result = g_slice_new (PangoAttrInt);
   pango_attribute_init (&result->attr, klass);
@@ -465,7 +456,7 @@ pango_attr_float_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_float_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrFloat *float_attr1 = (const PangoAttrFloat *)attr1;
   const PangoAttrFloat *float_attr2 = (const PangoAttrFloat *)attr2;
@@ -475,7 +466,7 @@ pango_attr_float_equal (const PangoAttribute *attr1,
 
 static PangoAttribute*
 pango_attr_float_new  (const PangoAttrClass *klass,
-		       double                value)
+                       double                value)
 {
   PangoAttrFloat *result = g_slice_new (PangoAttrFloat);
   pango_attribute_init (&result->attr, klass);
@@ -505,7 +496,7 @@ pango_attr_size_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_size_equal (const PangoAttribute *attr1,
-		       const PangoAttribute *attr2)
+                       const PangoAttribute *attr2)
 {
   const PangoAttrSize *size_attr1 = (const PangoAttrSize *)attr1;
   const PangoAttrSize *size_attr2 = (const PangoAttrSize *)attr2;
@@ -515,7 +506,7 @@ pango_attr_size_equal (const PangoAttribute *attr1,
 
 static PangoAttribute *
 pango_attr_size_new_internal (int size,
-			      gboolean absolute)
+                              gboolean absolute)
 {
   PangoAttrSize *result;
 
@@ -546,9 +537,9 @@ pango_attr_size_new_internal (int size,
  *
  * Create a new font-size attribute in fractional points.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_size_new (int size)
 {
@@ -561,11 +552,11 @@ pango_attr_size_new (int size)
  *
  * Create a new font-size attribute in device units.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_size_new_absolute (int size)
 {
@@ -578,9 +569,9 @@ pango_attr_size_new_absolute (int size)
  *
  * Create a new font slant style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_style_new (PangoStyle style)
 {
@@ -600,9 +591,9 @@ pango_attr_style_new (PangoStyle style)
  *
  * Create a new font weight attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_weight_new (PangoWeight weight)
 {
@@ -620,11 +611,11 @@ pango_attr_weight_new (PangoWeight weight)
  * pango_attr_variant_new:
  * @variant: the variant
  *
- * Create a new font variant attribute (normal or small caps)
+ * Create a new font variant attribute (normal or small caps).
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_variant_new (PangoVariant variant)
 {
@@ -642,11 +633,11 @@ pango_attr_variant_new (PangoVariant variant)
  * pango_attr_stretch_new:
  * @stretch: the stretch
  *
- * Create a new font stretch attribute
+ * Create a new font stretch attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_stretch_new (PangoStretch  stretch)
 {
@@ -679,27 +670,28 @@ pango_attr_font_desc_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_font_desc_equal (const PangoAttribute *attr1,
-			    const PangoAttribute *attr2)
+                            const PangoAttribute *attr2)
 {
   const PangoAttrFontDesc *desc_attr1 = (const PangoAttrFontDesc *)attr1;
   const PangoAttrFontDesc *desc_attr2 = (const PangoAttrFontDesc *)attr2;
 
   return pango_font_description_get_set_fields (desc_attr1->desc) ==
          pango_font_description_get_set_fields (desc_attr2->desc) &&
-	 pango_font_description_equal (desc_attr1->desc, desc_attr2->desc);
+         pango_font_description_equal (desc_attr1->desc, desc_attr2->desc);
 }
 
 /**
  * pango_attr_font_desc_new:
  * @desc: the font description
  *
- * Create a new font description attribute. This attribute
- * allows setting family, style, weight, variant, stretch,
- * and size simultaneously.
+ * Create a new font description attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * This attribute allows setting family, style, weight, variant,
+ * stretch, and size simultaneously.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_font_desc_new (const PangoFontDescription *desc)
 {
@@ -724,9 +716,9 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
  *
  * Create a new underline-style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_underline_new (PangoUnderline underline)
 {
@@ -746,19 +738,20 @@ pango_attr_underline_new (PangoUnderline underline)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new underline color attribute. This attribute
- * modifies the color of underlines. If not set, underlines
+ * Create a new underline color attribute.
+ *
+ * This attribute modifies the color of underlines. If not set, underlines
  * will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_underline_color_new (guint16 red,
-				guint16 green,
-				guint16 blue)
+                                guint16 green,
+                                guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_UNDERLINE_COLOR,
@@ -776,9 +769,9 @@ pango_attr_underline_color_new (guint16 red,
  *
  * Create a new strike-through attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_strikethrough_new (gboolean strikethrough)
 {
@@ -798,19 +791,20 @@ pango_attr_strikethrough_new (gboolean strikethrough)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new strikethrough color attribute. This attribute
- * modifies the color of strikethrough lines. If not set, strikethrough
- * lines will use the foreground color.
+ * Create a new strikethrough color attribute.
+ *
+ * This attribute modifies the color of strikethrough lines. If not set,
+ * strikethrough lines will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_strikethrough_color_new (guint16 red,
-				    guint16 green,
-				    guint16 blue)
+                                    guint16 green,
+                                    guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_STRIKETHROUGH_COLOR,
@@ -825,13 +819,13 @@ pango_attr_strikethrough_color_new (guint16 red,
 /**
  * pango_attr_rise_new:
  * @rise: the amount that the text should be displaced vertically,
- *        in Pango units. Positive values displace the text upwards.
+ *   in Pango units. Positive values displace the text upwards.
  *
  * Create a new baseline displacement attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_rise_new (int rise)
 {
@@ -849,12 +843,14 @@ pango_attr_rise_new (int rise)
  * pango_attr_scale_new:
  * @scale_factor: factor to scale the font
  *
- * Create a new font size scale attribute. The base font for the
- * affected text will have its size multiplied by @scale_factor.
+ * Create a new font size scale attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * The base font for the affected text will have its size multiplied
+ * by @scale_factor.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute*
 pango_attr_scale_new (double scale_factor)
 {
@@ -871,7 +867,7 @@ pango_attr_scale_new (double scale_factor)
 /**
  * pango_attr_fallback_new:
  * @enable_fallback: %TRUE if we should fall back on other fonts
- *                   for characters the active font is missing.
+ *   for characters the active font is missing.
  *
  * Create a new font fallback attribute.
  *
@@ -880,11 +876,11 @@ pango_attr_scale_new (double scale_factor)
  * other fonts on the system that might contain the characters in the
  * text.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.4
- **/
+ */
 PangoAttribute *
 pango_attr_fallback_new (gboolean enable_fallback)
 {
@@ -905,11 +901,11 @@ pango_attr_fallback_new (gboolean enable_fallback)
  *
  * Create a new letter-spacing attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.6
- **/
+ */
 PangoAttribute *
 pango_attr_letter_spacing_new (int letter_spacing)
 {
@@ -935,7 +931,7 @@ pango_attr_shape_copy (const PangoAttribute *attr)
     data = shape_attr->data;
 
   return pango_attr_shape_new_with_data (&shape_attr->ink_rect, &shape_attr->logical_rect,
-					 data, shape_attr->copy_func, shape_attr->destroy_func);
+                                         data, shape_attr->copy_func, shape_attr->destroy_func);
 }
 
 static void
@@ -951,48 +947,48 @@ pango_attr_shape_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_shape_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrShape *shape_attr1 = (const PangoAttrShape *)attr1;
   const PangoAttrShape *shape_attr2 = (const PangoAttrShape *)attr2;
 
   return (shape_attr1->logical_rect.x == shape_attr2->logical_rect.x &&
-	  shape_attr1->logical_rect.y == shape_attr2->logical_rect.y &&
-	  shape_attr1->logical_rect.width == shape_attr2->logical_rect.width &&
-	  shape_attr1->logical_rect.height == shape_attr2->logical_rect.height &&
-	  shape_attr1->ink_rect.x == shape_attr2->ink_rect.x &&
-	  shape_attr1->ink_rect.y == shape_attr2->ink_rect.y &&
-	  shape_attr1->ink_rect.width == shape_attr2->ink_rect.width &&
-	  shape_attr1->ink_rect.height == shape_attr2->ink_rect.height &&
-	  shape_attr1->data == shape_attr2->data);
+          shape_attr1->logical_rect.y == shape_attr2->logical_rect.y &&
+          shape_attr1->logical_rect.width == shape_attr2->logical_rect.width &&
+          shape_attr1->logical_rect.height == shape_attr2->logical_rect.height &&
+          shape_attr1->ink_rect.x == shape_attr2->ink_rect.x &&
+          shape_attr1->ink_rect.y == shape_attr2->ink_rect.y &&
+          shape_attr1->ink_rect.width == shape_attr2->ink_rect.width &&
+          shape_attr1->ink_rect.height == shape_attr2->ink_rect.height &&
+          shape_attr1->data == shape_attr2->data);
 }
 
 /**
  * pango_attr_shape_new_with_data:
- * @ink_rect:     ink rectangle to assign to each character
+ * @ink_rect: ink rectangle to assign to each character
  * @logical_rect: logical rectangle to assign to each character
- * @data:         user data pointer
+ * @data: user data pointer
  * @copy_func: (allow-none): function to copy @data when the
- *                attribute is copied. If %NULL, @data is simply
- *                copied as a pointer.
+ *   attribute is copied. If %NULL, @data is simply copied as a pointer.
  * @destroy_func: (allow-none): function to free @data when the
- *                attribute is freed, or %NULL
+ *   attribute is freed, or %NULL
+ *
+ * Creates a new shape attribute.
  *
  * Like pango_attr_shape_new(), but a user data pointer is also
- * provided; this pointer can be accessed when later
- * rendering the glyph.
+ * provided; this pointer can be accessed when later rendering the glyph.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
-				const PangoRectangle  *logical_rect,
-				gpointer               data,
-				PangoAttrDataCopyFunc  copy_func,
-				GDestroyNotify         destroy_func)
+                                const PangoRectangle  *logical_rect,
+                                gpointer               data,
+                                PangoAttrDataCopyFunc  copy_func,
+                                GDestroyNotify         destroy_func)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_SHAPE,
@@ -1019,26 +1015,27 @@ pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
 
 /**
  * pango_attr_shape_new:
- * @ink_rect:     ink rectangle to assign to each character
+ * @ink_rect: ink rectangle to assign to each character
  * @logical_rect: logical rectangle to assign to each character
  *
- * Create a new shape attribute. A shape is used to impose a
- * particular ink and logical rectangle on the result of shaping a
- * particular glyph. This might be used, for instance, for
- * embedding a picture or a widget inside a #PangoLayout.
+ * Create a new shape attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * A shape is used to impose a particular ink and logical rectangle
+ * on the result of shaping a particular glyph. This might be used,
+ * for instance, for embedding a picture or a widget inside a `PangoLayout`.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_shape_new (const PangoRectangle *ink_rect,
-		      const PangoRectangle *logical_rect)
+                      const PangoRectangle *logical_rect)
 {
   g_return_val_if_fail (ink_rect != NULL, NULL);
   g_return_val_if_fail (logical_rect != NULL, NULL);
 
   return pango_attr_shape_new_with_data (ink_rect, logical_rect,
-					 NULL, NULL, NULL);
+                                         NULL, NULL, NULL);
 }
 
 /**
@@ -1047,11 +1044,11 @@ pango_attr_shape_new (const PangoRectangle *ink_rect,
  *
  * Create a new gravity attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.16
- **/
+ */
 PangoAttribute *
 pango_attr_gravity_new (PangoGravity gravity)
 {
@@ -1073,11 +1070,11 @@ pango_attr_gravity_new (PangoGravity gravity)
  *
  * Create a new gravity hint attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.16
- **/
+ */
 PangoAttribute *
 pango_attr_gravity_hint_new (PangoGravityHint hint)
 {
@@ -1097,11 +1094,11 @@ pango_attr_gravity_hint_new (PangoGravityHint hint)
  *
  * Create a new font features tag attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
- **/
+ */
 PangoAttribute *
 pango_attr_font_features_new (const gchar *features)
 {
@@ -1123,8 +1120,8 @@ pango_attr_font_features_new (const gchar *features)
  *
  * Create a new foreground alpha attribute.
  *
- * Return value: (transfer full): the new allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
  */
@@ -1147,8 +1144,8 @@ pango_attr_foreground_alpha_new (guint16 alpha)
  *
  * Create a new background alpha attribute.
  *
- * Return value: (transfer full): the new allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
  */
@@ -1174,8 +1171,8 @@ pango_attr_background_alpha_new (guint16 alpha)
  * If breaks are disabled, the range will be kept in a
  * single run, as far as possible.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy()
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  */
@@ -1201,8 +1198,8 @@ pango_attr_allow_breaks_new (gboolean allow_breaks)
  * Pango will insert hyphens when breaking lines in the middle
  * of a word. This attribute can be used to suppress the hyphen.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy()
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  */
@@ -1221,13 +1218,13 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens)
 
 /**
  * pango_attr_show_new:
- * @flags: #PangoShowFlags to apply
+ * @flags: `PangoShowFlags` to apply
  *
  * Create a new attribute that influences how invisible
  * characters are rendered.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  **/
@@ -1250,11 +1247,11 @@ pango_attr_show_new (PangoShowFlags flags)
  *
  * Create a new overline-style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.46
- **/
+ */
 PangoAttribute *
 pango_attr_overline_new (PangoOverline overline)
 {
@@ -1274,15 +1271,16 @@ pango_attr_overline_new (PangoOverline overline)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new overline color attribute. This attribute
- * modifies the color of overlines. If not set, overlines
+ * Create a new overline color attribute.
+ *
+ * This attribute modifies the color of overlines. If not set, overlines
  * will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.46
- **/
+ */
 PangoAttribute *
 pango_attr_overline_color_new (guint16 red,
                                guint16 green,
@@ -1318,9 +1316,9 @@ _pango_attr_list_init (PangoAttrList *list)
  *
  * Create a new empty attribute list with a reference count of one.
  *
- * Return value: (transfer full): the newly allocated #PangoAttrList,
- *               which should be freed with pango_attr_list_unref().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttrList`,
+ *   which should be freed with [method@Pango.AttrList.unref].
+ */
 PangoAttrList *
 pango_attr_list_new (void)
 {
@@ -1333,14 +1331,14 @@ pango_attr_list_new (void)
 
 /**
  * pango_attr_list_ref:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Increase the reference count of the given attribute list by one.
  *
  * Return value: The attribute list passed in
  *
  * Since: 1.10
- **/
+ */
 PangoAttrList *
 pango_attr_list_ref (PangoAttrList *list)
 {
@@ -1372,12 +1370,12 @@ _pango_attr_list_destroy (PangoAttrList *list)
 
 /**
  * pango_attr_list_unref:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Decrease the reference count of the given attribute list by one.
  * If the result is zero, free the attribute list and the attributes
  * it contains.
- **/
+ */
 void
 pango_attr_list_unref (PangoAttrList *list)
 {
@@ -1395,15 +1393,14 @@ pango_attr_list_unref (PangoAttrList *list)
 
 /**
  * pango_attr_list_copy:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Copy @list and return an identical new list.
  *
- * Return value: (nullable): the newly allocated #PangoAttrList, with a
- *               reference count of one, which should
- *               be freed with pango_attr_list_unref().
- *               Returns %NULL if @list was %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoAttrList`,
+ *   with a reference count of one, which should be freed with
+ *   [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL.
+ */
 PangoAttrList *
 pango_attr_list_copy (PangoAttrList *list)
 {
@@ -1423,8 +1420,8 @@ pango_attr_list_copy (PangoAttrList *list)
 
 static void
 pango_attr_list_insert_internal (PangoAttrList  *list,
-				 PangoAttribute *attr,
-				 gboolean        before)
+                                 PangoAttribute *attr,
+                                 gboolean        before)
 {
   const guint start_index = attr->start_index;
   PangoAttribute *last_attr;
@@ -1467,17 +1464,18 @@ pango_attr_list_insert_internal (PangoAttrList  *list,
 
 /**
  * pango_attr_list_insert:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * be inserted after all other attributes with a matching
- * @start_index.
- **/
+ * Insert the given attribute into the `PangoAttrList`.
+ *
+ * It will be inserted after all other attributes with a
+ * matching @start_index.
+ */
 void
 pango_attr_list_insert (PangoAttrList  *list,
-			PangoAttribute *attr)
+                        PangoAttribute *attr)
 {
   g_return_if_fail (list != NULL);
   g_return_if_fail (attr != NULL);
@@ -1487,17 +1485,18 @@ pango_attr_list_insert (PangoAttrList  *list,
 
 /**
  * pango_attr_list_insert_before:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * be inserted before all other attributes with a matching
- * @start_index.
- **/
+ * Insert the given attribute into the `PangoAttrList`.
+ *
+ * It will be inserted before all other attributes with a
+ * matching @start_index.
+ */
 void
 pango_attr_list_insert_before (PangoAttrList  *list,
-			       PangoAttribute *attr)
+                               PangoAttribute *attr)
 {
   g_return_if_fail (list != NULL);
   g_return_if_fail (attr != NULL);
@@ -1507,20 +1506,21 @@ pango_attr_list_insert_before (PangoAttrList  *list,
 
 /**
  * pango_attr_list_change:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
+ *
+ * Insert the given attribute into the `PangoAttrList`.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * replace any attributes of the same type on that segment
+ * It will replace any attributes of the same type on that segment
  * and be merged with any adjoining attributes that are identical.
  *
- * This function is slower than pango_attr_list_insert() for
- * creating an attribute list in order (potentially much slower
- * for large lists). However, pango_attr_list_insert() is not
- * suitable for continually changing a set of attributes
- * since it never removes or combines existing attributes.
- **/
+ * This function is slower than [method@Pango.AttrList.insert] for
+ * creating an attribute list in order (potentially much slower for
+ * large lists). However, [method@Pango.AttrList.insert] is not
+ * suitable for continually changing a set of attributes since it
+ * never removes or combines existing attributes.
+ */
 void
 pango_attr_list_change (PangoAttrList  *list,
                         PangoAttribute *attr)
@@ -1665,27 +1665,25 @@ pango_attr_list_change (PangoAttrList  *list,
 
 /**
  * pango_attr_list_update:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @pos: the position of the change
  * @remove: the number of removed bytes
  * @add: the number of added bytes
  *
- * Update indices of attributes in @list for
- * a change in the text they refer to.
+ * Update indices of attributes in @list for a change in the
+ * text they refer to.
  *
- * The change that this function applies is
- * removing @remove bytes at position @pos
- * and inserting @add bytes instead.
+ * The change that this function applies is removing @remove
+ * bytes at position @pos and inserting @add bytes instead.
  *
- * Attributes that fall entirely in the
- * (@pos, @pos + @remove) range are removed.
+ * Attributes that fall entirely in the (@pos, @pos + @remove)
+ * range are removed.
  *
- * Attributes that start or end inside the
- * (@pos, @pos + @remove) range are shortened to
- * reflect the removal.
+ * Attributes that start or end inside the (@pos, @pos + @remove)
+ * range are shortened to reflect the removal.
  *
- * Attributes start and end positions are updated
- * if they are behind @pos + @remove.
+ * Attributes start and end positions are updated if they are
+ * behind @pos + @remove.
  *
  * Since: 1.44
  */
@@ -1743,29 +1741,30 @@ pango_attr_list_update (PangoAttrList *list,
 
 /**
  * pango_attr_list_splice:
- * @list: a #PangoAttrList
- * @other: another #PangoAttrList
+ * @list: a `PangoAttrList`
+ * @other: another `PangoAttrList`
  * @pos: the position in @list at which to insert @other
  * @len: the length of the spliced segment. (Note that this
- *       must be specified since the attributes in @other
- *       may only be present at some subsection of this range)
+ *   must be specified since the attributes in @other may only
+ *   be present at some subsection of this range)
  *
- * This function opens up a hole in @list, fills it in with attributes from
- * the left, and then merges @other on top of the hole.
+ * This function opens up a hole in @list, fills it in with attributes
+ * from the left, and then merges @other on top of the hole.
  *
  * This operation is equivalent to stretching every attribute
  * that applies at position @pos in @list by an amount @len,
- * and then calling pango_attr_list_change() with a copy
- * of each attribute in @other in sequence (offset in position by @pos).
+ * and then calling [method@Pango.AttrList.change] with a copy
+ * of each attribute in @other in sequence (offset in position
+ * by @pos).
  *
  * This operation proves useful for, for instance, inserting
  * a pre-edit string in the middle of an edit buffer.
- **/
+ */
 void
 pango_attr_list_splice (PangoAttrList *list,
-			PangoAttrList *other,
-			gint           pos,
-			gint           len)
+                        PangoAttrList *other,
+                        gint           pos,
+                        gint           len)
 {
   guint i, p;
   guint upos, ulen;
@@ -1827,13 +1826,13 @@ pango_attr_list_splice (PangoAttrList *list,
 
 /**
  * pango_attr_list_get_attributes:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
  * Gets a list of all attributes in @list.
  *
  * Return value: (element-type Pango.Attribute) (transfer full):
  *   a list of all attributes in @list. To free this value, call
- *   pango_attribute_destroy() on each value and g_slist_free()
+ *   [mehod@Pango.Attribute.destroy] on each value and g_slist_free()
  *   on the list.
  *
  * Since: 1.44
@@ -1861,8 +1860,8 @@ pango_attr_list_get_attributes (PangoAttrList *list)
 
 /**
  * pango_attr_list_equal:
- * @list: a #PangoAttrList
- * @other_list: the other #PangoAttrList
+ * @list: a `PangoAttrList`
+ * @other_list: the other `PangoAttrList`
  *
  * Checks whether @list and @other_list contain the same attributes and
  * whether those attributes apply to the same ranges. Beware that this
@@ -1956,13 +1955,13 @@ _pango_attr_list_get_iterator (PangoAttrList     *list,
 
 /**
  * pango_attr_list_get_iterator:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
  * Create a iterator initialized to the beginning of the list.
  * @list must not be modified until this iterator is freed.
  *
- * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should
- *               be freed with pango_attr_iterator_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
+ *   which should be freed with [method@Pango.AttrIterator.destroy].
  **/
 PangoAttrIterator *
 pango_attr_list_get_iterator (PangoAttrList  *list)
@@ -1985,14 +1984,14 @@ pango_attr_list_get_iterator (PangoAttrList  *list)
  *
  * Get the range of the current segment. Note that the
  * stored return values are signed, not unsigned like
- * the values in #PangoAttribute. To deal with this API
+ * the values in `PangoAttribute`. To deal with this API
  * oversight, stored return values that wouldn't fit into
  * a signed integer are clamped to %G_MAXINT.
- **/
+ */
 void
 pango_attr_iterator_range (PangoAttrIterator *iterator,
-			   gint              *start,
-			   gint              *end)
+                           gint              *start,
+                           gint              *end)
 {
   g_return_if_fail (iterator != NULL);
 
@@ -2004,12 +2003,13 @@ pango_attr_iterator_range (PangoAttrIterator *iterator,
 
 /**
  * pango_attr_iterator_next:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a `PangoAttrIterator`
  *
  * Advance the iterator until the next change of style.
  *
- * Return value: %FALSE if the iterator is at the end of the list, otherwise %TRUE
- **/
+ * Return value: %FALSE if the iterator is at the end of the list,
+ *   otherwise %TRUE
+ */
 gboolean
 pango_attr_iterator_next (PangoAttrIterator *iterator)
 {
@@ -2074,14 +2074,13 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_copy:
- * @iterator: a #PangoAttrIterator.
+ * @iterator: a `PangoAttrIterator`
  *
- * Copy a #PangoAttrIterator
+ * Copy a `PangoAttrIterator`.
  *
- * Return value: (transfer full): the newly allocated
- *               #PangoAttrIterator, which should be freed with
- *               pango_attr_iterator_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
+ *   which should be freed with [method@Pango.AttrIterator.destroy].
+ */
 PangoAttrIterator *
 pango_attr_iterator_copy (PangoAttrIterator *iterator)
 {
@@ -2110,10 +2109,10 @@ _pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_destroy:
- * @iterator: a #PangoAttrIterator.
+ * @iterator: a `PangoAttrIterator`
  *
- * Destroy a #PangoAttrIterator and free all associated memory.
- **/
+ * Destroy a `PangoAttrIterator` and free all associated memory.
+ */
 void
 pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 {
@@ -2125,21 +2124,21 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_get:
- * @iterator: a #PangoAttrIterator
- * @type: the type of attribute to find.
+ * @iterator: a `PangoAttrIterator`
+ * @type: the type of attribute to find
  *
  * Find the current attribute of a particular type at the iterator
  * location. When multiple attributes of the same type overlap,
  * the attribute whose range starts closest to the current location
  * is used.
  *
- * Return value: (nullable) (transfer none): the current attribute of the given type,
- *               or %NULL if no attribute of that type applies to the
- *               current location.
- **/
+ * Return value: (nullable) (transfer none): the current attribute of
+ *   the given type, or %NULL if no attribute of that type applies to
+ *   the current location.
+ */
 PangoAttribute *
 pango_attr_iterator_get (PangoAttrIterator *iterator,
-			 PangoAttrType      type)
+                         PangoAttrType      type)
 {
   int i;
 
@@ -2161,29 +2160,28 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
 
 /**
  * pango_attr_iterator_get_font:
- * @iterator: a #PangoAttrIterator
- * @desc: a #PangoFontDescription to fill in with the current values.
- *        The family name in this structure will be set using
- *        pango_font_description_set_family_static() using values from
- *        an attribute in the #PangoAttrList associated with the iterator,
- *        so if you plan to keep it around, you must call:
- *        <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>.
- * @language: (allow-none): if non-%NULL, location to store language tag for item, or %NULL
- *            if none is found.
- * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): if non-%NULL,
- *           location in which to store a list of non-font
- *           attributes at the the current position; only the highest priority
- *           value of each attribute will be added to this list. In order
- *           to free this value, you must call pango_attribute_destroy() on
- *           each member.
+ * @iterator: a `PangoAttrIterator`
+ * @desc: a `PangoFontDescription` to fill in with the current values.
+ *   The family name in this structure will be set using
+ *   [method@Pango.FontDescription.set_family_static] using values from
+ *   an attribute in the `PangoAttrList` associated with the iterator,
+ *   so if you plan to keep it around, you must call:
+ *   pango_font_description_set_family (desc, pango_font_description_get_family (desc)).
+ * @language: (allow-none): if non-%NULL, location to store language tag
+ *   for item, or %NULL if none is found.
+ * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full):
+ *   if non-%NULL, location in which to store a list of non-font attributes
+ *   at the the current position; only the highest priority value of each
+ *   attribute will be added to this list. In order to free this value, you
+ *   must call [method@Pango.Attribute.destroy] on each member.
  *
  * Get the font and other attributes at the current iterator position.
- **/
+ */
 void
 pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
-			      PangoFontDescription  *desc,
-			      PangoLanguage        **language,
-			      GSList               **extra_attrs)
+                              PangoFontDescription  *desc,
+                              PangoLanguage        **language,
+                              GSList               **extra_attrs)
 {
   PangoFontMask mask = 0;
   gboolean have_language = FALSE;
@@ -2208,91 +2206,91 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
       const PangoAttribute *attr = g_ptr_array_index (iterator->attribute_stack, i);
 
       switch ((int) attr->klass->type)
-	{
-	case PANGO_ATTR_FONT_DESC:
-	  {
-	    PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask;
-	    mask |= new_mask;
-	    pango_font_description_unset_fields (desc, new_mask);
-	    pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE);
-
-	    break;
-	  }
-	case PANGO_ATTR_FAMILY:
-	  if (!(mask & PANGO_FONT_MASK_FAMILY))
-	    {
-	      mask |= PANGO_FONT_MASK_FAMILY;
-	      pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_STYLE:
-	  if (!(mask & PANGO_FONT_MASK_STYLE))
-	    {
-	      mask |= PANGO_FONT_MASK_STYLE;
-	      pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_VARIANT:
-	  if (!(mask & PANGO_FONT_MASK_VARIANT))
-	    {
-	      mask |= PANGO_FONT_MASK_VARIANT;
-	      pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_WEIGHT:
-	  if (!(mask & PANGO_FONT_MASK_WEIGHT))
-	    {
-	      mask |= PANGO_FONT_MASK_WEIGHT;
-	      pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_STRETCH:
-	  if (!(mask & PANGO_FONT_MASK_STRETCH))
-	    {
-	      mask |= PANGO_FONT_MASK_STRETCH;
-	      pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_SIZE:
-	  if (!(mask & PANGO_FONT_MASK_SIZE))
-	    {
-	      mask |= PANGO_FONT_MASK_SIZE;
-	      pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size);
-	    }
-	  break;
-	case PANGO_ATTR_ABSOLUTE_SIZE:
-	  if (!(mask & PANGO_FONT_MASK_SIZE))
-	    {
-	      mask |= PANGO_FONT_MASK_SIZE;
-	      pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size);
-	    }
-	  break;
-	case PANGO_ATTR_SCALE:
-	  if (!have_scale)
-	    {
-	      have_scale = TRUE;
-	      scale = ((PangoAttrFloat *)attr)->value;
-	    }
-	  break;
-	case PANGO_ATTR_LANGUAGE:
-	  if (language)
-	    {
-	      if (!have_language)
-		{
-		  have_language = TRUE;
-		  *language = ((PangoAttrLanguage *)attr)->value;
-		}
-	    }
-	  break;
-	default:
-	  if (extra_attrs)
-	    {
-	      gboolean found = FALSE;
-
-	      /* Hack: special-case FONT_FEATURES.  We don't want them to
-	       * override each other, so we never merge them.  This should
-	       * be fixed when we implement attr-merging. */
-	      if (attr->klass->type != PANGO_ATTR_FONT_FEATURES)
+        {
+        case PANGO_ATTR_FONT_DESC:
+          {
+            PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask;
+            mask |= new_mask;
+            pango_font_description_unset_fields (desc, new_mask);
+            pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE);
+
+            break;
+          }
+        case PANGO_ATTR_FAMILY:
+          if (!(mask & PANGO_FONT_MASK_FAMILY))
+            {
+              mask |= PANGO_FONT_MASK_FAMILY;
+              pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_STYLE:
+          if (!(mask & PANGO_FONT_MASK_STYLE))
+            {
+              mask |= PANGO_FONT_MASK_STYLE;
+              pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_VARIANT:
+          if (!(mask & PANGO_FONT_MASK_VARIANT))
+            {
+              mask |= PANGO_FONT_MASK_VARIANT;
+              pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_WEIGHT:
+          if (!(mask & PANGO_FONT_MASK_WEIGHT))
+            {
+              mask |= PANGO_FONT_MASK_WEIGHT;
+              pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_STRETCH:
+          if (!(mask & PANGO_FONT_MASK_STRETCH))
+            {
+              mask |= PANGO_FONT_MASK_STRETCH;
+              pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_SIZE:
+          if (!(mask & PANGO_FONT_MASK_SIZE))
+            {
+              mask |= PANGO_FONT_MASK_SIZE;
+              pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size);
+            }
+          break;
+        case PANGO_ATTR_ABSOLUTE_SIZE:
+          if (!(mask & PANGO_FONT_MASK_SIZE))
+            {
+              mask |= PANGO_FONT_MASK_SIZE;
+              pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size);
+            }
+          break;
+        case PANGO_ATTR_SCALE:
+          if (!have_scale)
+            {
+              have_scale = TRUE;
+              scale = ((PangoAttrFloat *)attr)->value;
+            }
+          break;
+        case PANGO_ATTR_LANGUAGE:
+          if (language)
+            {
+              if (!have_language)
+                {
+                  have_language = TRUE;
+                  *language = ((PangoAttrLanguage *)attr)->value;
+                }
+            }
+          break;
+        default:
+          if (extra_attrs)
+            {
+              gboolean found = FALSE;
+
+              /* Hack: special-case FONT_FEATURES.  We don't want them to
+               * override each other, so we never merge them.  This should
+               * be fixed when we implement attr-merging. */
+              if (attr->klass->type != PANGO_ATTR_FONT_FEATURES)
                 {
                   GSList *tmp_list = *extra_attrs;
                   while (tmp_list)
@@ -2308,10 +2306,10 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
                     }
                 }
 
-	      if (!found)
-		*extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr));
-	    }
-	}
+              if (!found)
+                *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr));
+            }
+        }
     }
 
   if (have_scale)
@@ -2325,24 +2323,23 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
 
 /**
  * pango_attr_list_filter:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @func: (scope call) (closure data): callback function; returns %TRUE
  *        if an attribute should be filtered out.
  * @data: (closure): Data to be passed to @func
  *
- * Given a #PangoAttrList and callback function, removes any elements
- * of @list for which @func returns %TRUE and inserts them into
- * a new list.
+ * Given a `PangoAttrList` and callback function, removes any elements
+ * of @list for which @func returns %TRUE and inserts them into a new list.
  *
- * Return value: (transfer full) (nullable): the new #PangoAttrList or
+ * Return value: (transfer full) (nullable): the new `PangoAttrList` or
  *  %NULL if no attributes of the given types were found.
  *
  * Since: 1.2
- **/
+ */
 PangoAttrList *
 pango_attr_list_filter (PangoAttrList       *list,
-			PangoAttrFilterFunc  func,
-			gpointer             data)
+                        PangoAttrFilterFunc  func,
+                        gpointer             data)
 
 {
   PangoAttrList *new = NULL;
@@ -2378,18 +2375,18 @@ pango_attr_list_filter (PangoAttrList       *list,
 
 /**
  * pango_attr_iterator_get_attrs:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a `PangoAttrIterator`
  *
  * Gets a list of all attributes at the current position of the
  * iterator.
  *
- * Return value: (element-type Pango.Attribute) (transfer full): a list of
- *   all attributes for the current range.
- *   To free this value, call pango_attribute_destroy() on
- *   each value and g_slist_free() on the list.
+ * Return value: (element-type Pango.Attribute) (transfer full):
+ *   a list of all attributes for the current range. To free this value,
+ *   call [method@Pango.Attribute.destroy] on each value and g_slist_free()
+ *   on the list.
  *
  * Since: 1.2
- **/
+ */
 GSList *
 pango_attr_iterator_get_attrs (PangoAttrIterator *iterator)
 {
@@ -2407,17 +2404,17 @@ pango_attr_iterator_get_attrs (PangoAttrIterator *iterator)
       gboolean found = FALSE;
 
       for (tmp_list2 = attrs; tmp_list2; tmp_list2 = tmp_list2->next)
-	{
-	  PangoAttribute *old_attr = tmp_list2->data;
+        {
+          PangoAttribute *old_attr = tmp_list2->data;
           if (attr->klass->type == old_attr->klass->type)
             {
               found = TRUE;
               break;
             }
-	}
+        }
 
       if (!found)
-	attrs = g_slist_prepend (attrs, pango_attribute_copy (attr));
+        attrs = g_slist_prepend (attrs, pango_attribute_copy (attr));
     }
 
   return attrs;
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index aecd1199..e20b6413 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -37,7 +37,7 @@ typedef struct _PangoColor PangoColor;
  * @green: value of green component
  * @blue: value of blue component
  *
- * The #PangoColor structure is used to
+ * The `PangoColor` structure is used to
  * represent a color in an uncalibrated RGB color-space.
  */
 struct _PangoColor
@@ -50,7 +50,7 @@ struct _PangoColor
 /**
  * PANGO_TYPE_COLOR:
  *
- * The #GObject type for #PangoColor.
+ * The `GObject` type for `PangoColor`.
  */
 #define PANGO_TYPE_COLOR pango_color_get_type ()
 PANGO_AVAILABLE_IN_ALL
@@ -93,33 +93,36 @@ typedef struct _PangoAttrFontFeatures PangoAttrFontFeatures;
 /**
  * PANGO_TYPE_ATTR_LIST:
  *
- * The #GObject type for #PangoAttrList.
+ * The `GObject` type for `PangoAttrList`.
  */
 #define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()
+
 /**
  * PangoAttrIterator:
  *
- * The #PangoAttrIterator structure is used to represent an
- * iterator through a #PangoAttrList. A new iterator is created
- * with pango_attr_list_get_iterator(). Once the iterator
- * is created, it can be advanced through the style changes
- * in the text using pango_attr_iterator_next(). At each
- * style change, the range of the current style segment and the
- * attributes currently in effect can be queried.
+ * A `PangoAttrIterator` is used to iterate through a `PangoAttrList`.
+ *
+ * A new iterator is created with [method@Pango.AttrList.get_iterator].
+ * Once the iterator is created, it can be advanced through the style
+ * changes in the text using [method@Pango.AttrIterator.next]. At each
+ * style change, the range of the current style segment and the attributes
+ * currently in effect can be queried.
  */
+
 /**
  * PangoAttrList:
  *
- * The #PangoAttrList structure represents a list of attributes
- * that apply to a section of text. The attributes are, in general,
- * allowed to overlap in an arbitrary fashion, however, if the
- * attributes are manipulated only through pango_attr_list_change(),
- * the overlap between properties will meet stricter criteria.
+ * A `PangoAttrList` represents a list of attributes that apply to a section
+ * of text.
+ *
+ * The attributes in a `PangoAttrList` are, in general, allowed to overlap in
+ * an arbitrary fashion. However, if the attributes are manipulated only through
+ * [method@Pango.AttrList.change], the overlap between properties will meet
+ * stricter criteria.
  *
- * Since the #PangoAttrList structure is stored as a linear list,
- * it is not suitable for storing attributes for large amounts
- * of text. In general, you should not use a single #PangoAttrList
- * for more than one paragraph of text.
+ * Since the `PangoAttrList` structure is stored as a linear list, it is not
+ * suitable for storing attributes for large amounts of text. In general, you
+ * should not use a single `PangoAttrList` for more than one paragraph of text.
  */
 typedef struct _PangoAttrList     PangoAttrList;
 typedef struct _PangoAttrIterator PangoAttrIterator;
@@ -127,43 +130,43 @@ typedef struct _PangoAttrIterator PangoAttrIterator;
 /**
  * PangoAttrType:
  * @PANGO_ATTR_INVALID: does not happen
- * @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
- * @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
- * @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
- * @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
- * @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
- * @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
- * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
- * @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
- * @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
- * @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
- * @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
- * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
- * @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
- * @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
- * @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
- * @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
- * @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
- * @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
- * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
- * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
- * @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt)
- * @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt)
- * @PANGO_ATTR_FONT_FEATURES: OpenType font features (#PangoAttrString). Since 1.38
- * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha (#PangoAttrInt). Since 1.38
- * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha (#PangoAttrInt). Since 1.38
- * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed (#PangoAttrInt). Since 1.44
- * @PANGO_ATTR_SHOW: how to render invisible characters (#PangoAttrInt). Since 1.44
- * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks (#PangoAttrInt). Since 1.44
- * @PANGO_ATTR_OVERLINE: whether the text has an overline (#PangoAttrInt). Since 1.46
- * @PANGO_ATTR_OVERLINE_COLOR: overline color (#PangoAttrColor). Since 1.46
- *
- * The #PangoAttrType
- * distinguishes between different types of attributes. Along with the
- * predefined values, it is possible to allocate additional values
- * for custom attributes using pango_attr_type_register(). The predefined
- * values are given below. The type of structure used to store the
- * attribute is listed in parentheses after the description.
+ * @PANGO_ATTR_LANGUAGE: language ([struct@Pango.AttrLanguage])
+ * @PANGO_ATTR_FAMILY: font family name list ([struct@Pango.AttrString])
+ * @PANGO_ATTR_STYLE: font slant style ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_WEIGHT: font weight ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_VARIANT: font variant (normal or small caps) ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_STRETCH: font stretch ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_FONT_DESC: font description ([struct@Pango.AttrFontDesc])
+ * @PANGO_ATTR_FOREGROUND: foreground color ([struct@Pango.AttrColor])
+ * @PANGO_ATTR_BACKGROUND: background color ([struct@Pango.AttrColor])
+ * @PANGO_ATTR_UNDERLINE: whether the text has an underline ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_RISE: baseline displacement ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_SHAPE: shape ([struct@Pango.AttrShape])
+ * @PANGO_ATTR_SCALE: font size scale factor ([struct@Pango.AttrFloat])
+ * @PANGO_ATTR_FALLBACK: whether fallback is enabled ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_LETTER_SPACING: letter spacing ([struct@PangoAttrInt])
+ * @PANGO_ATTR_UNDERLINE_COLOR: underline color ([struct@Pango.AttrColor])
+ * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color ([struct@Pango.AttrColor])
+ * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_GRAVITY: base text gravity ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_GRAVITY_HINT: gravity hint ([struct@Pango.AttrInt])
+ * @PANGO_ATTR_FONT_FEATURES: OpenType font features ([struct@Pango.AttrString]). Since 1.38
+ * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha ([struct@Pango.AttrInt]). Since 1.38
+ * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha ([struct@Pango.AttrInt]). Since 1.38
+ * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44
+ * @PANGO_ATTR_SHOW: how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44
+ * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44
+ * @PANGO_ATTR_OVERLINE: whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46
+ * @PANGO_ATTR_OVERLINE_COLOR: overline color ([struct@Pango.AttrColor]). Since 1.46
+ *
+ * The `PangoAttrType` distinguishes between different types of attributes.
+ *
+ * Along with the predefined values, it is possible to allocate additional
+ * values for custom attributes using [type_func@attr_type_register]. The predefined
+ * values are given below. The type of structure used to store the attribute is
+ * listed in parentheses after the description.
  */
 typedef enum
 {
@@ -226,9 +229,8 @@ typedef enum
  *     drawn continuously across multiple runs. This type
  *     of underlining is available since Pango 1.46.
  *
- * The #PangoUnderline enumeration is used to specify
- * whether text should be underlined, and if so, the type
- * of underlining.
+ * The `PangoUnderline` enumeration is used to specify whether text
+ * should be underlined, and if so, the type of underlining.
  */
 typedef enum {
   PANGO_UNDERLINE_NONE,
@@ -248,9 +250,8 @@ typedef enum {
  * @PANGO_OVERLINE_SINGLE: Draw a single line above the ink
  *     extents of the text being underlined.
  *
- * The #PangoOverline enumeration is used to specify
- * whether text should be overlined, and if so, the type
- * of line.
+ * The `PangoOverline` enumeration is used to specify whether text
+ * should be overlined, and if so, the type of line.
  *
  * Since: 1.46
  */
@@ -262,8 +263,8 @@ typedef enum {
 /**
  * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING:
  *
- * This value can be used to set the start_index member of a #PangoAttribute
- * such that the attribute covers from the beginning of the text.
+ * Value for @start_index in `PangoAttribute` that indicates
+ * the beginning of the text.
  *
  * Since: 1.24
  */
@@ -272,8 +273,8 @@ typedef enum {
 /**
  * PANGO_ATTR_INDEX_TO_TEXT_END: (value 4294967295)
  *
- * This value can be used to set the end_index member of a #PangoAttribute
- * such that the attribute covers to the end of the text.
+ * Value for @end_index in `PangoAttribute` that indicates
+ * the end of the text.
  *
  * Since: 1.24
  */
@@ -286,12 +287,14 @@ typedef enum {
  * @end_index: end index of the range (in bytes). The character at this index
  * is not included in the range.
  *
- * The #PangoAttribute structure represents the common portions of all
- * attributes. Particular types of attributes include this structure
- * as their initial portion. The common portion of the attribute holds
- * the range to which the value in the type-specific part of the attribute
- * applies and should be initialized using pango_attribute_init().
- * By default an attribute will have an all-inclusive range of [0,%G_MAXUINT].
+ * The `PangoAttribute` structure represents the common portions of all
+ * attributes.
+ *
+ * Particular types of attributes include this structure as their initial
+ * portion. The common portion of the attribute holds the range to which
+ * the value in the type-specific part of the attribute applies and should
+ * be initialized using [method@Pango.Attribute.init]. By default, an attribute
+ * will have an all-inclusive range of [0,%G_MAXUINT].
  */
 struct _PangoAttribute
 {
@@ -308,8 +311,8 @@ struct _PangoAttribute
  * Type of a function filtering a list of attributes.
  *
  * Return value: %TRUE if the attribute should be selected for
- * filtering, %FALSE otherwise.
- **/
+ *   filtering, %FALSE otherwise.
+ */
 typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
 					 gpointer        user_data);
 
@@ -326,14 +329,18 @@ typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
 /**
  * PangoAttrClass:
  * @type: the type ID for this attribute
- * @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
- * @destroy: function to free an attribute of this type (see pango_attribute_destroy())
- * @equal: function to check two attributes of this type for equality (see pango_attribute_equal())
- *
- * The #PangoAttrClass structure stores the type and operations for
- * a particular type of attribute. The functions in this structure should
- * not be called directly. Instead, one should use the wrapper functions
- * provided for #PangoAttribute.
+ * @copy: function to duplicate an attribute of this type
+ *   (see [method@Pango.Attribute.copy])
+ * @destroy: function to free an attribute of this type
+ *   (see [method@Pango.Attribute.destroy])
+ * @equal: function to check two attributes of this type for equality
+ *   (see [method@Pango.Attribute.equal])
+ *
+ * The `PangoAttrClass` structure stores the type and operations for
+ * a particular type of attribute.
+ *
+ * The functions in this structure should not be called directly. Instead,
+ * one should use the wrapper functions provided for `PangoAttribute`.
  */
 struct _PangoAttrClass
 {
@@ -349,7 +356,7 @@ struct _PangoAttrClass
  * @attr: the common portion of the attribute
  * @value: the string which is the value of the attribute
  *
- * The #PangoAttrString structure is used to represent attributes with
+ * The `PangoAttrString` structure is used to represent attributes with
  * a string value.
  */
 struct _PangoAttrString
@@ -360,9 +367,9 @@ struct _PangoAttrString
 /**
  * PangoAttrLanguage:
  * @attr: the common portion of the attribute
- * @value: the #PangoLanguage which is the value of the attribute
+ * @value: the `PangoLanguage` which is the value of the attribute
  *
- * The #PangoAttrLanguage structure is used to represent attributes that
+ * The `PangoAttrLanguage` structure is used to represent attributes that
  * are languages.
  */
 struct _PangoAttrLanguage
@@ -375,7 +382,7 @@ struct _PangoAttrLanguage
  * @attr: the common portion of the attribute
  * @value: the value of the attribute
  *
- * The #PangoAttrInt structure is used to represent attributes with
+ * The `PangoAttrInt` structure is used to represent attributes with
  * an integer or enumeration value.
  */
 struct _PangoAttrInt
@@ -388,7 +395,7 @@ struct _PangoAttrInt
  * @attr: the common portion of the attribute
  * @value: the value of the attribute
  *
- * The #PangoAttrFloat structure is used to represent attributes with
+ * The `PangoAttrFloat` structure is used to represent attributes with
  * a float or double value.
  */
 struct _PangoAttrFloat
@@ -399,9 +406,9 @@ struct _PangoAttrFloat
 /**
  * PangoAttrColor:
  * @attr: the common portion of the attribute
- * @color: the #PangoColor which is the value of the attribute
+ * @color: the `PangoColor` which is the value of the attribute
  *
- * The #PangoAttrColor structure is used to represent attributes that
+ * The `PangoAttrColor` structure is used to represent attributes that
  * are colors.
  */
 struct _PangoAttrColor
@@ -414,13 +421,13 @@ struct _PangoAttrColor
  * PangoAttrSize:
  * @attr: the common portion of the attribute
  * @size: size of font, in units of 1/%PANGO_SCALE of a point (for
- * %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE)
+ *   %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE)
  * @absolute: whether the font size is in device units or points.
- * This field is only present for compatibility with Pango-1.8.0
- * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
- * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
+ *   This field is only present for compatibility with Pango-1.8.0
+ *   (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
+ *   be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
  *
- * The #PangoAttrSize structure is used to represent attributes which
+ * The `PangoAttrSize` structure is used to represent attributes which
  * set font size.
  */
 struct _PangoAttrSize
@@ -435,11 +442,11 @@ struct _PangoAttrSize
  * @attr: the common portion of the attribute
  * @ink_rect: the ink rectangle to restrict to
  * @logical_rect: the logical rectangle to restrict to
- * @data: user data set (see pango_attr_shape_new_with_data())
+ * @data: user data set (see [type_func@Pango.AttrShape.new_with_data])
  * @copy_func: copy function for the user data
  * @destroy_func: destroy function for the user data
  *
- * The #PangoAttrShape structure is used to represent attributes which
+ * The `PangoAttrShape` structure is used to represent attributes which
  * impose shape restrictions.
  */
 struct _PangoAttrShape
@@ -458,7 +465,7 @@ struct _PangoAttrShape
  * @attr: the common portion of the attribute
  * @desc: the font description which is the value of this attribute
  *
- * The #PangoAttrFontDesc structure is used to store an attribute that
+ * The `PangoAttrFontDesc` structure is used to store an attribute that
  * sets all aspects of the font description at once.
  */
 struct _PangoAttrFontDesc
@@ -472,7 +479,7 @@ struct _PangoAttrFontDesc
  * @attr: the common portion of the attribute
  * @features: the featues, as a string in CSS syntax
  *
- * The #PangoAttrFontFeatures structure is used to represent OpenType
+ * The `PangoAttrFontFeatures` structure is used to represent OpenType
  * font features as an attribute.
  *
  * Since: 1.38
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index d4d84e03..b86affba 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -19,24 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:bidi
- * @short_description:Types and functions for bidirectional text
- * @title:Bidirectional Text
- * @see_also:
- * pango_context_get_base_dir(),
- * pango_context_set_base_dir(),
- * pango_itemize_with_base_dir()
- *
- * Pango supports bidirectional text (like Arabic and Hebrew) automatically.
- * Some applications however, need some help to correctly handle bidirectional text.
- *
- * The #PangoDirection type can be used with pango_context_set_base_dir() to
- * instruct Pango about direction of text, though in most cases Pango detects
- * that correctly and automatically.  The rest of the facilities in this section
- * are used internally by Pango already, and are provided to help applications
- * that need more direct control over bidirectional setting of text.
- */
 #include "config.h"
 
 #include <string.h>
@@ -56,11 +38,11 @@
  * pango_bidi_type_for_unichar:
  * @ch: a Unicode character
  *
- * Determines the normative bidirectional character type of a
- * character, as specified in the Unicode Character Database.
+ * Determines the bidirectional type of a character.
  *
- * A simplified version of this function is available as
- * pango_unichar_direction().
+ * The bidirectional type is specified in the Unicode Character Database.
+ *
+ * A simplified version of this function is available as [func@unichar_direction].
  *
  * Return value: the bidirectional character type, as used in the
  * Unicode bidirectional algorithm.
@@ -114,8 +96,10 @@ pango_bidi_type_for_unichar (gunichar ch)
  *             if @text is nul-terminated and the length should be calculated.
  * @pbase_dir: input base direction, and output resolved direction.
  *
- * This will return the bidirectional embedding levels of the input paragraph
- * as defined by the Unicode Bidirectional Algorithm available at:
+ * Return the bidirectional embedding levels of the input paragraph.
+ *
+ * The bidirectional embedding levels are defined by the Unicode Bidirectional
+ * Algorithm available at:
  *
  *   http://www.unicode.org/reports/tr9/
  *
@@ -123,7 +107,7 @@ pango_bidi_type_for_unichar (gunichar ch)
  * characters in the text will determine the final resolved direction.
  *
  * Return value: a newly allocated array of embedding levels, one item per
- *               character (not byte), that should be freed using g_free.
+ *   character (not byte), that should be freed using g_free().
  *
  * Since: 1.4
  */
@@ -282,14 +266,15 @@ resolved:
  * pango_unichar_direction:
  * @ch: a Unicode character
  *
- * Determines the inherent direction of a character; either
- * %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, or
- * %PANGO_DIRECTION_NEUTRAL.
+ * Determines the inherent direction of a character.
+ *
+ * The inherent direction is either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL,
+ * or %PANGO_DIRECTION_NEUTRAL.
  *
  * This function is useful to categorize characters into left-to-right
- * letters, right-to-left letters, and everything else.  If full
- * Unicode bidirectional type of a character is needed,
- * pango_bidi_type_for_unichar() can be used instead.
+ * letters, right-to-left letters, and everything else. If full Unicode
+ * bidirectional type of a character is needed, [type_func@Pango.BidiType.for_unichar]
+ * can be used instead.
  *
  * Return value: the direction of the character.
  */
@@ -316,9 +301,9 @@ pango_unichar_direction (gunichar ch)
  * @ch: a Unicode character
  * @mirrored_ch: location to store the mirrored character
  *
- * If @ch has the Unicode mirrored property and there is another Unicode
- * character that typically has a glyph that is the mirror image of @ch's
- * glyph, puts that character in the address pointed to by @mirrored_ch.
+ * Returns the mirrored character of a Unicode character.
+ *
+ * Mirror characters are determined by the Unicode mirrored property.
  *
  * Use g_unichar_get_mirror_char() instead; the docs for that function
  * provide full details.
@@ -327,8 +312,8 @@ pango_unichar_direction (gunichar ch)
  * filled in, %FALSE otherwise
  **/
 gboolean
-pango_get_mirror_char (gunichar        ch,
-		       gunichar       *mirrored_ch)
+pango_get_mirror_char (gunichar  ch,
+		       gunichar *mirrored_ch)
 {
   return g_unichar_get_mirror_char (ch, mirrored_ch);
 }
diff --git a/pango/pango-bidi-type.h b/pango/pango-bidi-type.h
index aa1896c1..ebfaa574 100644
--- a/pango/pango-bidi-type.h
+++ b/pango/pango-bidi-type.h
@@ -52,7 +52,7 @@ G_BEGIN_DECLS
  * @PANGO_BIDI_TYPE_WS: Whitespace
  * @PANGO_BIDI_TYPE_ON: Other Neutrals
  *
- * The #PangoBidiType type represents the bidirectional character
+ * `PangoBidiType` represents the bidirectional character
  * type of a Unicode character as specified by the
  * <ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>.
  *
diff --git a/pango/pango-break.h b/pango/pango-break.h
index 9209ee15..ae7d953a 100644
--- a/pango/pango-break.h
+++ b/pango/pango-break.h
@@ -37,51 +37,44 @@ G_BEGIN_DECLS
  * @is_char_break: if set, can break here when doing character wrapping
  * @is_white: is whitespace character
  * @is_cursor_position: if set, cursor can appear in front of character.
- * i.e. this is a grapheme boundary, or the first character
- * in the text.
- * This flag implements Unicode's
- * <ulink url="http://www.unicode.org/reports/tr29/">Grapheme
- * Cluster Boundaries</ulink> semantics.
+ *   i.e. this is a grapheme boundary, or the first character in the text.
+ *   This flag implements Unicode's
+ *   [Grapheme Cluster Boundaries](http://www.unicode.org/reports/tr29/)
+ *   semantics.
  * @is_word_start: is first character in a word
  * @is_word_end: is first non-word char after a word
- * Note that in degenerate cases, you could have both @is_word_start
- * and @is_word_end set for some character.
+ *   Note that in degenerate cases, you could have both @is_word_start
+ *   and @is_word_end set for some character.
  * @is_sentence_boundary: is a sentence boundary.
- * There are two ways to divide sentences. The first assigns all
- * inter-sentence whitespace/control/format chars to some sentence,
- * so all chars are in some sentence; @is_sentence_boundary denotes
- * the boundaries there. The second way doesn't assign
- * between-sentence spaces, etc. to any sentence, so
+ *   There are two ways to divide sentences. The first assigns all
+ *   inter-sentence whitespace/control/format chars to some sentence,
+ *   so all chars are in some sentence; @is_sentence_boundary denotes
+ *   the boundaries there. The second way doesn't assign
+ *   between-sentence spaces, etc. to any sentence, so
  * @is_sentence_start/@is_sentence_end mark the boundaries of those sentences.
  * @is_sentence_start: is first character in a sentence
  * @is_sentence_end: is first char after a sentence.
- * Note that in degenerate cases, you could have both @is_sentence_start
- * and @is_sentence_end set for some character. (e.g. no space after a
- * period, so the next sentence starts right away)
+ *   Note that in degenerate cases, you could have both @is_sentence_start
+ *   and @is_sentence_end set for some character. (e.g. no space after a
+ *   period, so the next sentence starts right away)
  * @backspace_deletes_character: if set, backspace deletes one character
- * rather than the entire grapheme cluster. This
- * field is only meaningful on grapheme
- * boundaries (where @is_cursor_position is
- * set).  In some languages, the full grapheme
- * (e.g.  letter + diacritics) is considered a
- * unit, while in others, each decomposed
- * character in the grapheme is a unit. In the
- * default implementation of pango_break(), this
- * bit is set on all grapheme boundaries except
- * those following Latin, Cyrillic or Greek base characters.
+ *   rather than the entire grapheme cluster. This field is only meaningful
+ *   on grapheme boundaries (where @is_cursor_position is set). In some languages,
+ *   the full grapheme (e.g. letter + diacritics) is considered a unit, while in
+ *   others, each decomposed character in the grapheme is a unit. In the default
+ *   implementation of [func@break], this bit is set on all grapheme boundaries
+ *   except those following Latin, Cyrillic or Greek base characters.
  * @is_expandable_space: is a whitespace character that can possibly be
- * expanded for justification purposes. (Since: 1.18)
+ *   expanded for justification purposes. (Since: 1.18)
  * @is_word_boundary: is a word boundary, as defined by UAX#29.
- * More specifically, means that this is not a position in the middle
- * of a word.  For example, both sides of a punctuation mark are
- * considered word boundaries.  This flag is particularly useful when
- * selecting text word-by-word.
- * This flag implements Unicode's
- * <ulink url="http://www.unicode.org/reports/tr29/">Word
- * Boundaries</ulink> semantics. (Since: 1.22)
+ *   More specifically, means that this is not a position in the middle of a word.
+ *   For example, both sides of a punctuation mark are considered word boundaries.
+ *   This flag is particularly useful when selecting text word-by-word. This flag
+ *   implements Unicode's [Word Boundaries](http://www.unicode.org/reports/tr29/)
+ *   semantics. (Since: 1.22)
  *
- * The #PangoLogAttr structure stores information
- * about the attributes of a single character.
+ * The `PangoLogAttr` structure stores information about the attributes of a
+ * single character.
  */
 struct _PangoLogAttr
 {
diff --git a/pango/pango-color.c b/pango/pango-color.c
index a530719f..f616e1f0 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -36,14 +36,15 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color,
  * pango_color_copy:
  * @src: (nullable): color to copy, may be %NULL
  *
- * Creates a copy of @src, which should be freed with
- * pango_color_free(). Primarily used by language bindings,
- * not that useful otherwise (since colors can just be copied
- * by assignment in C).
+ * Creates a copy of @src.
  *
- * Return value: (nullable): the newly allocated #PangoColor, which
- *               should be freed with pango_color_free(), or %NULL if
- *               @src was %NULL.
+ * The copy should be freed with pango_color_free(). Primarily
+ * used by language bindings, not that useful otherwise (since
+ * colors can just be copied by assignment in C).
+ *
+ * Return value: (nullable): the newly allocated `PangoColor`, which
+ *   should be freed with [method@Pango.Color.free], or %NULL if
+ *   @src was %NULL.
  **/
 PangoColor*
 pango_color_copy (const PangoColor *src)
@@ -79,10 +80,11 @@ pango_color_free (PangoColor *color)
  * pango_color_to_string:
  * @color: a #PangoColor
  *
- * Returns a textual specification of @color in the hexadecimal form
- * <literal>&num;rrrrggggbbbb</literal>, where <literal>r</literal>,
- * <literal>g</literal> and <literal>b</literal> are hex digits representing
- * the red, green, and blue components respectively.
+ * Returns a textual specification of @color.
+ *
+ * The string is in the hexadecimal form `#rrrrggggbbbb`, where
+ * `r`, `g` and `b` are hex digits representing the red, green,
+ * and blue components respectively.
  *
  * Return value: a newly-allocated text string that must be freed with g_free().
  *
@@ -209,28 +211,27 @@ hex (const char *spec,
 
 /**
  * pango_color_parse_with_alpha:
- * @color: (nullable): a #PangoColor structure in which to store the
+ * @color: (nullable): a `PangoColor` structure in which to store the
  *   result, or %NULL
  * @alpha: (out) (optional): return location for alpha, or %NULL
  * @spec: a string specifying the new color
  *
- * Fill in the fields of a color from a string specification. The
- * string can either one of a large set of standard names. (Taken
- * from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal
- * value in the
- * form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where
- * 'r', 'g' and 'b' are hex digits of the red, green, and blue
- * components of the color, respectively. (White in the four
- * forms is '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff')
+ * Fill in the fields of a color from a string specification.
  *
- * Additionally, parse strings of the form
- * '&num;rgba', '&num;rrggbbaa', '&num;rrrrggggbbbbaaaa',
- * if @alpha is not %NULL, and set @alpha to the value specified
- * by the hex digits for 'a'. If no alpha component is found
+ * The string can
+ * either one of a large set of standard names. (Taken from the CSS Color
+ * [specification](https://www.w3.org/TR/css-color-4/#named-colors),
+ * or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb`
+ * or `#rrrrggggbbbb` where `r`, `g` and `b` are hex digits of the red, green,
+ * and blue components of the color, respectively. (White in the four
+ * forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
+ *
+ * Additionally, parse strings of the form `#rgba`, `#rrggbbaa`,
+ * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha to the value
+ * specified by the hex digits for `a`. If no alpha component is found
  * in @spec, @alpha is set to 0xffff (for a solid color).
  *
- * Return value: %TRUE if parsing of the specifier succeeded,
- *   otherwise false.
+ * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
  *
  * Since: 1.46
  */
@@ -319,25 +320,25 @@ pango_color_parse_with_alpha (PangoColor *color,
 
 /**
  * pango_color_parse:
- * @color: (nullable): a #PangoColor structure in which to store the
+ * @color: (nullable): a `PangoColor` structure in which to store the
  *   result, or %NULL
  * @spec: a string specifying the new color
  *
- * Fill in the fields of a color from a string specification. The
- * string can either one of a large set of standard names. (Taken
- * from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal
- * value in the
- * form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where
- * 'r', 'g' and 'b' are hex digits of the red, green, and blue
- * components of the color, respectively. (White in the four
- * forms is '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff')
+ * Fill in the fields of a color from a string specification.
+ *
+ * The string can either
+ * one of a large set of standard names. (Taken from the CSS Color
+ * [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be
+ * a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where
+ * `r`, `g` and `b` are hex digits of the red, green, and blue components of the
+ * color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff`
+ * and `#ffffffffffff`.)
  *
- * Return value: %TRUE if parsing of the specifier succeeded,
- *   otherwise false.
+ * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
  **/
 gboolean
 pango_color_parse (PangoColor *color,
-		   const char *spec)
+                   const char *spec)
 {
   return pango_color_parse_with_alpha (color, NULL, spec);
 }
diff --git a/pango/pango-context.c b/pango/pango-context.c
index ec1014fa..1db11a1c 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -19,18 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:main
- * @title:Rendering
- * @short_description:Functions to run the rendering pipeline
- *
- * The Pango rendering pipeline takes a string of
- * Unicode characters and converts it into glyphs.
- * The functions described in this section accomplish
- * various steps of this process.
- *
- * ![](pipeline.png)
- */
 #include "config.h"
 #include <string.h>
 #include <stdlib.h>
@@ -45,21 +33,16 @@
 #include "pango-emoji-private.h"
 
 /**
- * SECTION:context
- * @title:Contexts
- * @short_description: Global context object
- *
- * The #PangoContext structure stores global information
- * influencing Pango's operation, such as the fontmap used
- * to look up fonts, and default values such as the default
- * language, default gravity, or default font.
- */
-
-/**
  * PangoContext:
  *
- * The #PangoContext structure stores global information
- * used to control the itemization process.
+ * A `PangoContext` stores global information used to control the
+ * itemization process.
+ *
+ * The information stored by `PangoContext includes the fontmap used
+ * to look up fonts, and default values such as the default language,
+ * default gravity, or default font.
+ *
+ * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context].
  */
 struct _PangoContext
 {
@@ -144,21 +127,21 @@ pango_context_finalize (GObject *object)
 /**
  * pango_context_new:
  *
- * Creates a new #PangoContext initialized to default values.
+ * Creates a new `PangoContext` initialized to default values.
  *
  * This function is not particularly useful as it should always
- * be followed by a pango_context_set_font_map() call, and the
- * function pango_font_map_create_context() does these two steps
+ * be followed by a [method@Pango.Context.set_font_map] call, and the
+ * function [method@Pango.FontMap.create_context] does these two steps
  * together and hence users are recommended to use that.
  *
  * If you are using Pango as part of a higher-level system,
- * that system may have it's own way of create a #PangoContext.
- * For instance, the GTK+ toolkit has, among others,
- * gtk_widget_get_pango_context(). Use those instead.
+ * that system may have it's own way of create a `PangoContext`.
+ * For instance, the GTK toolkit has, among others,
+ * `gtk_widget_get_pango_context()`. Use those instead.
  *
- * Return value: the newly allocated #PangoContext, which should
- *               be freed with g_object_unref().
- **/
+ * Return value: the newly allocated `PangoContext`, which should
+ *   be freed with g_object_unref().
+ */
 PangoContext *
 pango_context_new (void)
 {
@@ -180,22 +163,24 @@ update_resolved_gravity (PangoContext *context)
 
 /**
  * pango_context_set_matrix:
- * @context: a #PangoContext
- * @matrix: (allow-none): a #PangoMatrix, or %NULL to unset any existing
+ * @context: a `PangoContext`
+ * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing
  * matrix. (No matrix set is the same as setting the identity matrix.)
  *
  * Sets the transformation matrix that will be applied when rendering
- * with this context. Note that reported metrics are in the user space
- * coordinates before the application of the matrix, not device-space
- * coordinates after the application of the matrix. So, they don't scale
- * with the matrix, though they may change slightly for different
- * matrices, depending on how the text is fit to the pixel grid.
+ * with this context.
+ *
+ * Note that reported metrics are in the user space coordinates before
+ * the application of the matrix, not device-space coordinates after the
+ * application of the matrix. So, they don't scale with the matrix, though
+ * they may change slightly for different matrices, depending on how the
+ * text is fit to the pixel grid.
  *
  * Since: 1.6
- **/
+ */
 void
-pango_context_set_matrix (PangoContext       *context,
-			  const PangoMatrix  *matrix)
+pango_context_set_matrix (PangoContext      *context,
+                          const PangoMatrix *matrix)
 {
   g_return_if_fail (PANGO_IS_CONTEXT (context));
 
@@ -214,17 +199,19 @@ pango_context_set_matrix (PangoContext       *context,
 
 /**
  * pango_context_get_matrix:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
  * Gets the transformation matrix that will be applied when
- * rendering with this context. See pango_context_set_matrix().
+ * rendering with this context.
+ *
+ * See [method@Pango.Context.set_matrix].
  *
  * Return value: (nullable): the matrix, or %NULL if no matrix has
- *  been set (which is the same as the identity matrix). The returned
- *  matrix is owned by Pango and must not be modified or freed.
+ *   been set (which is the same as the identity matrix). The returned
+ *   matrix is owned by Pango and must not be modified or freed.
  *
  * Since: 1.6
- **/
+ */
 const PangoMatrix *
 pango_context_get_matrix (PangoContext *context)
 {
@@ -235,16 +222,19 @@ pango_context_get_matrix (PangoContext *context)
 
 /**
  * pango_context_set_font_map:
- * @context: a #PangoContext
- * @font_map: the #PangoFontMap to set.
+ * @context: a `PangoContext`
+ * @font_map: the `PangoFontMap` to set.
  *
- * Sets the font map to be searched when fonts are looked-up in this context.
- * This is only for internal use by Pango backends, a #PangoContext obtained
- * via one of the recommended methods should already have a suitable font map.
- **/
+ * Sets the font map to be searched when fonts are looked-up
+ * in this context.
+ *
+ * This is only for internal use by Pango backends, a `PangoContext`
+ * obtained via one of the recommended methods should already have a
+ * suitable font map.
+ */
 void
 pango_context_set_font_map (PangoContext *context,
-			    PangoFontMap *font_map)
+                            PangoFontMap *font_map)
 {
   g_return_if_fail (PANGO_IS_CONTEXT (context));
   g_return_if_fail (!font_map || PANGO_IS_FONT_MAP (font_map));
@@ -266,15 +256,15 @@ pango_context_set_font_map (PangoContext *context,
 
 /**
  * pango_context_get_font_map:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
- * Gets the #PangoFontMap used to look up fonts for this context.
+ * Gets the `PangoFontMap` used to look up fonts for this context.
  *
- * Return value: (transfer none): the font map for the #PangoContext.
- *               This value is owned by Pango and should not be unreferenced.
+ * Return value: (transfer none): the font map for the `PangoContext`.
+ *   This value is owned by Pango and should not be unreferenced.
  *
  * Since: 1.6
- **/
+ */
 PangoFontMap *
 pango_context_get_font_map (PangoContext *context)
 {
@@ -285,18 +275,18 @@ pango_context_get_font_map (PangoContext *context)
 
 /**
  * pango_context_list_families:
- * @context: a #PangoContext
- * @families: (out) (array length=n_families) (transfer container): location to store a pointer to
- *            an array of #PangoFontFamily *. This array should be freed
- *            with g_free().
+ * @context: a `PangoContext`
+ * @families: (out) (array length=n_families) (transfer container): location
+ *   to store a pointer to an array of `PangoFontFamily`. This array should
+ *   be freed with g_free().
  * @n_families: (out): location to store the number of elements in @descs
  *
  * List all families for a context.
- **/
+ */
 void
-pango_context_list_families (PangoContext          *context,
-			     PangoFontFamily     ***families,
-			     int                   *n_families)
+pango_context_list_families (PangoContext      *context,
+                             PangoFontFamily ***families,
+                             int               *n_families)
 {
   g_return_if_fail (context != NULL);
   g_return_if_fail (families == NULL || n_families != NULL);
@@ -308,7 +298,7 @@ pango_context_list_families (PangoContext          *context,
     {
       *n_families = 0;
       if (families)
-	*families = NULL;
+        *families = NULL;
 
       return;
     }
@@ -318,18 +308,18 @@ pango_context_list_families (PangoContext          *context,
 
 /**
  * pango_context_load_font:
- * @context: a #PangoContext
- * @desc: a #PangoFontDescription describing the font to load
+ * @context: a `PangoContext`
+ * @desc: a `PangoFontDescription` describing the font to load
  *
  * Loads the font in one of the fontmaps in the context
  * that is the closest match for @desc.
  *
- * Returns: (transfer full) (nullable): the newly allocated #PangoFont
- *          that was loaded, or %NULL if no font matched.
- **/
+ * Returns: (transfer full) (nullable): the newly allocated `PangoFont`
+ *   that was loaded, or %NULL if no font matched.
+ */
 PangoFont *
 pango_context_load_font (PangoContext               *context,
-			 const PangoFontDescription *desc)
+                         const PangoFontDescription *desc)
 {
   g_return_val_if_fail (context != NULL, NULL);
   g_return_val_if_fail (context->font_map != NULL, NULL);
@@ -339,20 +329,20 @@ pango_context_load_font (PangoContext               *context,
 
 /**
  * pango_context_load_fontset:
- * @context: a #PangoContext
- * @desc: a #PangoFontDescription describing the fonts to load
- * @language: a #PangoLanguage the fonts will be used for
+ * @context: a `PangoContext`
+ * @desc: a `PangoFontDescription` describing the fonts to load
+ * @language: a `PangoLanguage` the fonts will be used for
  *
  * Load a set of fonts in the context that can be used to render
  * a font matching @desc.
  *
  * Returns: (transfer full) (nullable): the newly allocated
- *          #PangoFontset loaded, or %NULL if no font matched.
- **/
+ *   `PangoFontset` loaded, or %NULL if no font matched.
+ */
 PangoFontset *
 pango_context_load_fontset (PangoContext               *context,
-			    const PangoFontDescription *desc,
-			    PangoLanguage             *language)
+                            const PangoFontDescription *desc,
+                            PangoLanguage             *language)
 {
   g_return_val_if_fail (context != NULL, NULL);
 
@@ -361,14 +351,14 @@ pango_context_load_fontset (PangoContext               *context,
 
 /**
  * pango_context_set_font_description:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @desc: the new pango font description
  *
  * Set the default font description for the context
- **/
+ */
 void
 pango_context_set_font_description (PangoContext               *context,
-				    const PangoFontDescription *desc)
+                                    const PangoFontDescription *desc)
 {
   g_return_if_fail (context != NULL);
   g_return_if_fail (desc != NULL);
@@ -385,13 +375,13 @@ pango_context_set_font_description (PangoContext               *context,
 
 /**
  * pango_context_get_font_description:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
  * Retrieve the default font description for the context.
  *
  * Return value: (transfer none): a pointer to the context's default font
- *               description. This value must not be modified or freed.
- **/
+ *   description. This value must not be modified or freed.
+ */
 PangoFontDescription *
 pango_context_get_font_description (PangoContext *context)
 {
@@ -402,16 +392,17 @@ pango_context_get_font_description (PangoContext *context)
 
 /**
  * pango_context_set_language:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @language: the new language tag.
  *
- * Sets the global language tag for the context.  The default language
- * for the locale of the running process can be found using
- * pango_language_get_default().
- **/
+ * Sets the global language tag for the context.
+ *
+ * The default language for the locale of the running process
+ * can be found using [type_func@Pango.Language.get_default].
+ */
 void
-pango_context_set_language (PangoContext *context,
-			    PangoLanguage    *language)
+pango_context_set_language (PangoContext  *context,
+                            PangoLanguage *language)
 {
   g_return_if_fail (context != NULL);
 
@@ -427,12 +418,12 @@ pango_context_set_language (PangoContext *context,
 
 /**
  * pango_context_get_language:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
  * Retrieves the global language tag for the context.
  *
  * Return value: the global language tag.
- **/
+ */
 PangoLanguage *
 pango_context_get_language (PangoContext *context)
 {
@@ -443,7 +434,7 @@ pango_context_get_language (PangoContext *context)
 
 /**
  * pango_context_set_base_dir:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @direction: the new base direction
  *
  * Sets the base direction for the context.
@@ -451,13 +442,13 @@ pango_context_get_language (PangoContext *context)
  * The base direction is used in applying the Unicode bidirectional
  * algorithm; if the @direction is %PANGO_DIRECTION_LTR or
  * %PANGO_DIRECTION_RTL, then the value will be used as the paragraph
- * direction in the Unicode bidirectional algorithm.  A value of
+ * direction in the Unicode bidirectional algorithm. A value of
  * %PANGO_DIRECTION_WEAK_LTR or %PANGO_DIRECTION_WEAK_RTL is used only
  * for paragraphs that do not contain any strong characters themselves.
- **/
+ */
 void
-pango_context_set_base_dir (PangoContext  *context,
-			    PangoDirection direction)
+pango_context_set_base_dir (PangoContext   *context,
+                            PangoDirection  direction)
 {
   g_return_if_fail (context != NULL);
 
@@ -469,13 +460,14 @@ pango_context_set_base_dir (PangoContext  *context,
 
 /**
  * pango_context_get_base_dir:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
+ *
+ * Retrieves the base direction for the context.
  *
- * Retrieves the base direction for the context. See
- * pango_context_set_base_dir().
+ * See [method@Pango.Context.set_base_dir].
  *
  * Return value: the base direction for the context.
- **/
+ */
 PangoDirection
 pango_context_get_base_dir (PangoContext *context)
 {
@@ -486,7 +478,7 @@ pango_context_get_base_dir (PangoContext *context)
 
 /**
  * pango_context_set_base_gravity:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @gravity: the new base gravity
  *
  * Sets the base gravity for the context.
@@ -494,10 +486,10 @@ pango_context_get_base_dir (PangoContext *context)
  * The base gravity is used in laying vertical text out.
  *
  * Since: 1.16
- **/
+ */
 void
-pango_context_set_base_gravity (PangoContext  *context,
-				PangoGravity gravity)
+pango_context_set_base_gravity (PangoContext *context,
+                                PangoGravity  gravity)
 {
   g_return_if_fail (context != NULL);
 
@@ -511,15 +503,16 @@ pango_context_set_base_gravity (PangoContext  *context,
 
 /**
  * pango_context_get_base_gravity:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
+ *
+ * Retrieves the base gravity for the context.
  *
- * Retrieves the base gravity for the context. See
- * pango_context_set_base_gravity().
+ * See [method@Pango.Context.set_base_gravity].
  *
  * Return value: the base gravity for the context.
  *
  * Since: 1.16
- **/
+ */
 PangoGravity
 pango_context_get_base_gravity (PangoContext *context)
 {
@@ -530,17 +523,19 @@ pango_context_get_base_gravity (PangoContext *context)
 
 /**
  * pango_context_get_gravity:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
+ *
+ * Retrieves the gravity for the context.
  *
- * Retrieves the gravity for the context. This is similar to
- * pango_context_get_base_gravity(), except for when the base gravity
- * is %PANGO_GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used
- * to return the gravity from the current context matrix.
+ * This is similar to [method@Pango.Context.get_base_gravity],
+ * except for when the base gravity is %PANGO_GRAVITY_AUTO for
+ * which [type_func@Pango.Gravity.get_for_matrix] is used to return the
+ * gravity from the current context matrix.
  *
  * Return value: the resolved gravity for the context.
  *
  * Since: 1.16
- **/
+ */
 PangoGravity
 pango_context_get_gravity (PangoContext *context)
 {
@@ -551,20 +546,21 @@ pango_context_get_gravity (PangoContext *context)
 
 /**
  * pango_context_set_gravity_hint:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @hint: the new gravity hint
  *
  * Sets the gravity hint for the context.
  *
- * The gravity hint is used in laying vertical text out, and is only relevant
- * if gravity of the context as returned by pango_context_get_gravity()
- * is set %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST.
+ * The gravity hint is used in laying vertical text out, and
+ * is only relevant if gravity of the context as returned by
+ * [method@Pango.Context.get_gravity] is set to %PANGO_GRAVITY_EAST
+ * or %PANGO_GRAVITY_WEST.
  *
  * Since: 1.16
- **/
+ */
 void
-pango_context_set_gravity_hint (PangoContext    *context,
-				PangoGravityHint hint)
+pango_context_set_gravity_hint (PangoContext     *context,
+                                PangoGravityHint  hint)
 {
   g_return_if_fail (context != NULL);
 
@@ -576,15 +572,16 @@ pango_context_set_gravity_hint (PangoContext    *context,
 
 /**
  * pango_context_get_gravity_hint:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
+ *
+ * Retrieves the gravity hint for the context.
  *
- * Retrieves the gravity hint for the context. See
- * pango_context_set_gravity_hint() for details.
+ * See [method@Pango.Context.set_gravity_hint] for details.
  *
  * Return value: the gravity hint for the context.
  *
  * Since: 1.16
- **/
+ */
 PangoGravityHint
 pango_context_get_gravity_hint (PangoContext *context)
 {
@@ -597,7 +594,7 @@ pango_context_get_gravity_hint (PangoContext *context)
 
 static gboolean
 advance_attr_iterator_to (PangoAttrIterator *iterator,
-			  int                start_index)
+                          int                start_index)
 {
   int start_range, end_range;
 
@@ -606,13 +603,13 @@ advance_attr_iterator_to (PangoAttrIterator *iterator,
   while (start_index >= end_range)
     {
       if (!pango_attr_iterator_next (iterator))
-	return FALSE;
+        return FALSE;
       pango_attr_iterator_range (iterator, &start_range, &end_range);
     }
 
   if (start_range > start_index)
     g_warning ("In pango_itemize(), the cached iterator passed in "
-	       "had already moved beyond the start_index");
+               "had already moved beyond the start_index");
 
   return TRUE;
 }
@@ -659,7 +656,7 @@ retry:
     {
       cache = g_slice_new (FontCache);
       cache->hash = g_hash_table_new_full (g_direct_hash, NULL,
-					   NULL, (GDestroyNotify)font_element_destroy);
+                                           NULL, (GDestroyNotify)font_element_destroy);
       if (!g_object_replace_qdata (G_OBJECT (fontset), cache_quark, NULL,
                                    cache, (GDestroyNotify)font_cache_destroy,
                                    NULL))
@@ -674,8 +671,8 @@ retry:
 
 static gboolean
 font_cache_get (FontCache   *cache,
-		gunichar     wc,
-		PangoFont  **font)
+                gunichar     wc,
+                PangoFont  **font)
 {
   FontElement *element;
 
@@ -692,8 +689,8 @@ font_cache_get (FontCache   *cache,
 
 static void
 font_cache_insert (FontCache   *cache,
-		   gunichar           wc,
-		   PangoFont         *font)
+                   gunichar           wc,
+                   PangoFont         *font)
 {
   FontElement *element = g_slice_new (FontElement);
   element->font = font ? g_object_ref (font) : NULL;
@@ -719,11 +716,11 @@ typedef struct _PangoWidthIter PangoWidthIter;
 
 struct _PangoWidthIter
 {
-	const gchar *text_start;
-	const gchar *text_end;
-	const gchar *start;
-	const gchar *end;
-	gboolean     upright;
+        const gchar *text_start;
+        const gchar *text_end;
+        const gchar *start;
+        const gchar *end;
+        gboolean     upright;
 };
 
 typedef struct _ItemizeState ItemizeState;
@@ -784,7 +781,7 @@ update_embedding_end (ItemizeState *state)
 {
   state->embedding = state->embedding_levels[state->embedding_end_offset];
   while (state->embedding_end < state->end &&
-	 state->embedding_levels[state->embedding_end_offset] == state->embedding)
+         state->embedding_levels[state->embedding_end_offset] == state->embedding)
     {
       state->embedding_end_offset++;
       state->embedding_end = g_utf8_next_char (state->embedding_end);
@@ -795,7 +792,7 @@ update_embedding_end (ItemizeState *state)
 
 static PangoAttribute *
 find_attribute (GSList        *attr_list,
-		PangoAttrType  type)
+                PangoAttrType  type)
 {
   GSList *node;
 
@@ -830,7 +827,7 @@ update_attr_iterator (ItemizeState *state)
     pango_font_description_free (state->font_desc);
   state->font_desc = pango_font_description_copy_static (state->context->font_desc);
   pango_attr_iterator_get_font (state->attr_iter, state->font_desc,
-				&state->lang, &state->extra_attrs);
+                                &state->lang, &state->extra_attrs);
   if (pango_font_description_get_set_fields (state->font_desc) & PANGO_FONT_MASK_GRAVITY)
     state->font_desc_gravity = pango_font_description_get_gravity (state->font_desc);
   else
@@ -971,7 +968,9 @@ width_iter_next(PangoWidthIter* iter)
 }
 
 static void
-width_iter_init (PangoWidthIter* iter, const char* text, int length)
+width_iter_init (PangoWidthIter *iter,
+                 const char     *text,
+                 int             length)
 {
   iter->text_start = text;
   iter->text_end = text + length;
@@ -986,15 +985,15 @@ width_iter_fini (PangoWidthIter* iter)
 }
 
 static void
-itemize_state_init (ItemizeState      *state,
-		    PangoContext      *context,
-		    const char        *text,
-		    PangoDirection     base_dir,
-		    int                start_index,
-		    int                length,
-		    PangoAttrList     *attrs,
-		    PangoAttrIterator *cached_iter,
-		    const PangoFontDescription *desc)
+itemize_state_init (ItemizeState               *state,
+                    PangoContext               *context,
+                    const char                 *text,
+                    PangoDirection              base_dir,
+                    int                         start_index,
+                    int                         length,
+                    PangoAttrList              *attrs,
+                    PangoAttrIterator          *cached_iter,
+                    const PangoFontDescription *desc)
 {
 
   state->context = context;
@@ -1059,7 +1058,7 @@ itemize_state_init (ItemizeState      *state,
    */
   _pango_script_iter_init (&state->script_iter, text + start_index, length);
   pango_script_iter_get_range (&state->script_iter, NULL,
-			       &state->script_end, &state->script);
+                               &state->script_end, &state->script);
 
   width_iter_init (&state->width_iter, text + start_index, length);
   _pango_emoji_iter_init (&state->emoji_iter, text + start_index, length);
@@ -1110,7 +1109,7 @@ itemize_state_next (ItemizeState *state)
     {
       pango_script_iter_next (&state->script_iter);
       pango_script_iter_get_range (&state->script_iter, NULL,
-				   &state->script_end, &state->script);
+                                   &state->script_end, &state->script);
       state->changed |= SCRIPT_CHANGED;
     }
   if (state->run_end == state->emoji_iter.end)
@@ -1146,7 +1145,7 @@ copy_attr_slist (GSList *attr_slist)
 
 static void
 itemize_state_fill_font (ItemizeState *state,
-			 PangoFont    *font)
+                         PangoFont    *font)
 {
   GList *l;
 
@@ -1156,33 +1155,33 @@ itemize_state_fill_font (ItemizeState *state,
       if (item->analysis.font)
         break;
       if (font)
-	item->analysis.font = g_object_ref (font);
+        item->analysis.font = g_object_ref (font);
     }
 }
 
 static void
 itemize_state_add_character (ItemizeState *state,
-			     PangoFont    *font,
-			     gboolean      force_break,
-			     const char   *pos)
+                             PangoFont    *font,
+                             gboolean      force_break,
+                             const char   *pos)
 {
   if (state->item)
     {
       if (!state->item->analysis.font && font)
-	{
-	  itemize_state_fill_font (state, font);
-	}
+        {
+          itemize_state_fill_font (state, font);
+        }
       else if (state->item->analysis.font && !font)
-	{
-	  font = state->item->analysis.font;
-	}
+        {
+          font = state->item->analysis.font;
+        }
 
       if (!force_break &&
-	  state->item->analysis.font == font)
-	{
-	  state->item->num_chars++;
-	  return;
-	}
+          state->item->analysis.font == font)
+        {
+          state->item->num_chars++;
+          return;
+        }
 
       state->item->length = (pos - state->text) - state->item->offset;
     }
@@ -1200,15 +1199,15 @@ itemize_state_add_character (ItemizeState *state,
   state->item->analysis.gravity = state->resolved_gravity;
 
   /* The level vs. gravity dance:
-   *	- If gravity is SOUTH, leave level untouched.
-   *	- If gravity is NORTH, step level one up, to
-   *	  not get mirrored upside-down text.
-   *	- If gravity is EAST, step up to an even level, as
-   *	  it's a clockwise-rotated layout, so the rotated
-   *	  top is unrotated left.
-   *	- If gravity is WEST, step up to an odd level, as
-   *	  it's a counter-clockwise-rotated layout, so the rotated
-   *	  top is unrotated right.
+   *    - If gravity is SOUTH, leave level untouched.
+   *    - If gravity is NORTH, step level one up, to
+   *      not get mirrored upside-down text.
+   *    - If gravity is EAST, step up to an even level, as
+   *      it's a clockwise-rotated layout, so the rotated
+   *      top is unrotated left.
+   *    - If gravity is WEST, step up to an odd level, as
+   *      it's a counter-clockwise-rotated layout, so the rotated
+   *      top is unrotated right.
    *
    * A similar dance is performed in pango-layout.c:
    * line_set_resolved_dir().  Keep in synch.
@@ -1217,17 +1216,17 @@ itemize_state_add_character (ItemizeState *state,
     {
       case PANGO_GRAVITY_SOUTH:
       default:
-	break;
+        break;
       case PANGO_GRAVITY_NORTH:
-	state->item->analysis.level++;
-	break;
+        state->item->analysis.level++;
+        break;
       case PANGO_GRAVITY_EAST:
-	state->item->analysis.level += 1;
-	state->item->analysis.level &= ~1;
-	break;
+        state->item->analysis.level += 1;
+        state->item->analysis.level &= ~1;
+        break;
       case PANGO_GRAVITY_WEST:
-	state->item->analysis.level |= 1;
-	break;
+        state->item->analysis.level |= 1;
+        break;
     }
 
   state->item->analysis.flags = state->centered_baseline ? PANGO_ANALYSIS_FLAG_CENTERED_BASELINE : 0;
@@ -1256,8 +1255,8 @@ typedef struct {
 
 static gboolean
 get_font_foreach (PangoFontset *fontset,
-		  PangoFont    *font,
-		  gpointer      data)
+                  PangoFont    *font,
+                  gpointer      data)
 {
   GetFontInfo *info = data;
 
@@ -1284,8 +1283,8 @@ get_base_font (ItemizeState *state)
 {
   if (!state->base_font)
     state->base_font = pango_font_map_load_font (state->context->font_map,
-						 state->context,
-						 state->font_desc);
+                                                 state->context,
+                                                 state->font_desc);
   return state->base_font;
 }
 
@@ -1321,7 +1320,7 @@ get_font (ItemizeState  *state,
 
 static PangoLanguage *
 compute_derived_language (PangoLanguage *lang,
-			  PangoScript    script)
+                          PangoScript    script)
 {
   PangoLanguage *derived_lang;
 
@@ -1342,7 +1341,7 @@ compute_derived_language (PangoLanguage *lang,
        * safe here, though Keith Packard claims it is.
        */
       if (!derived_lang)
-	derived_lang = pango_language_from_string ("xx");
+        derived_lang = pango_language_from_string ("xx");
     }
 
   return derived_lang;
@@ -1357,28 +1356,28 @@ itemize_state_update_for_new_run (ItemizeState *state)
     {
       /* Font-desc gravity overrides everything */
       if (state->font_desc_gravity != PANGO_GRAVITY_AUTO)
-	{
-	  state->resolved_gravity = state->font_desc_gravity;
-	}
+        {
+          state->resolved_gravity = state->font_desc_gravity;
+        }
       else
-	{
-	  PangoGravity gravity = state->gravity;
-	  PangoGravityHint gravity_hint = state->gravity_hint;
+        {
+          PangoGravity gravity = state->gravity;
+          PangoGravityHint gravity_hint = state->gravity_hint;
 
-	  if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO))
-	    gravity = state->context->resolved_gravity;
+          if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO))
+            gravity = state->context->resolved_gravity;
 
-	  state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script,
-									    state->width_iter.upright,
-									    gravity,
-									    gravity_hint);
-	}
+          state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script,
+                                                                            state->width_iter.upright,
+                                                                            gravity,
+                                                                            gravity_hint);
+        }
 
       if (state->font_desc_gravity != state->resolved_gravity)
-	{
-	  pango_font_description_set_gravity (state->font_desc, state->resolved_gravity);
-	  state->changed |= FONT_CHANGED;
-	}
+        {
+          pango_font_description_set_gravity (state->font_desc, state->resolved_gravity);
+          state->changed |= FONT_CHANGED;
+        }
     }
 
   if (state->changed & (SCRIPT_CHANGED | LANG_CHANGED))
@@ -1386,7 +1385,7 @@ itemize_state_update_for_new_run (ItemizeState *state)
       PangoLanguage *old_derived_lang = state->derived_lang;
       state->derived_lang = compute_derived_language (state->lang, state->script);
       if (old_derived_lang != state->derived_lang)
-	state->changed |= DERIVED_LANG_CHANGED;
+        state->changed |= DERIVED_LANG_CHANGED;
     }
 
   if (state->changed & (EMOJI_CHANGED))
@@ -1411,9 +1410,9 @@ itemize_state_update_for_new_run (ItemizeState *state)
         pango_font_description_set_family_static (state->emoji_font_desc, "emoji");
       }
       state->current_fonts = pango_font_map_load_fontset (state->context->font_map,
-							  state->context,
-							  is_emoji ? state->emoji_font_desc : state->font_desc,
-							  state->derived_lang);
+                                                          state->context,
+                                                          is_emoji ? state->emoji_font_desc : state->font_desc,
+                                                          state->derived_lang);
       state->cache = get_font_cache (state->current_fonts);
     }
 
@@ -1470,16 +1469,16 @@ itemize_state_process_run (ItemizeState *state)
                       (wc >= 0xfe00u && wc <= 0xfe0fu) ||
                       (wc >= 0xe0100u && wc <= 0xe01efu)))
         {
-	  font = NULL;
+          font = NULL;
         }
       else
         {
-	  get_font (state, wc, &font);
-	}
+          get_font (state, wc, &font);
+        }
 
       itemize_state_add_character (state, font,
-				   is_forced_break || last_was_forced_break,
-				   p);
+                                   is_forced_break || last_was_forced_break,
+                                   p);
 
       last_was_forced_break = is_forced_break;
     }
@@ -1534,35 +1533,36 @@ itemize_state_finish (ItemizeState *state)
 
 /**
  * pango_itemize_with_base_dir:
- * @context:   a structure holding information that affects
- *             the itemization process.
- * @base_dir:  base direction to use for bidirectional processing
- * @text:      the text to itemize.
+ * @context: a structure holding information that affects
+ *   the itemization process.
+ * @base_dir: base direction to use for bidirectional processing
+ * @text: the text to itemize.
  * @start_index: first byte in @text to process
- * @length:    the number of bytes (not characters) to process
- *             after @start_index. This must be >= 0.
- * @attrs:     the set of attributes that apply to @text.
+ * @length: the number of bytes (not characters) to process
+ *   after @start_index. This must be >= 0.
+ * @attrs: the set of attributes that apply to @text.
  * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
  *
- * Like pango_itemize(), but the base direction to use when
- * computing bidirectional levels (see pango_context_set_base_dir ()),
- * is specified explicitly rather than gotten from the #PangoContext.
+ * Like `pango_itemize()`, but with an explicitly specified base direction.
  *
- * Return value: (transfer full) (element-type Pango.Item): a #GList of
- *               #PangoItem structures.  The items should be freed using
- *               pango_item_free() probably in combination with
- *               g_list_foreach(), and the list itself using g_list_free().
+ * The base direction is used when computing bidirectional levels.
+ * (see [method@Pango.Context.set_base_dir]). [func@itemize] gets the
+ * base direction from the `PangoContext`.
+ *
+ * Return value: (transfer full) (element-type Pango.Item): a `GList` of
+ *   [struct@Pango.Item] structures. The items should be freed using
+ *   [method@Pango.Item.free] probably in combination with g_list_free_full().
  *
  * Since: 1.4
  */
 GList *
 pango_itemize_with_base_dir (PangoContext      *context,
-			     PangoDirection     base_dir,
-			     const char        *text,
-			     int                start_index,
-			     int                length,
-			     PangoAttrList     *attrs,
-			     PangoAttrIterator *cached_iter)
+                             PangoDirection     base_dir,
+                             const char        *text,
+                             int                start_index,
+                             int                length,
+                             PangoAttrList     *attrs,
+                             PangoAttrIterator *cached_iter)
 {
   ItemizeState state;
 
@@ -1575,7 +1575,7 @@ pango_itemize_with_base_dir (PangoContext      *context,
     return NULL;
 
   itemize_state_init (&state, context, text, base_dir, start_index, length,
-		      attrs, cached_iter, NULL);
+                      attrs, cached_iter, NULL);
 
   do
     itemize_state_process_run (&state);
@@ -1588,10 +1588,10 @@ pango_itemize_with_base_dir (PangoContext      *context,
 
 static GList *
 itemize_with_font (PangoContext               *context,
-		   const char                 *text,
-		   int                         start_index,
-		   int                         length,
-		   const PangoFontDescription *desc)
+                   const char                 *text,
+                   int                         start_index,
+                   int                         length,
+                   const PangoFontDescription *desc)
 {
   ItemizeState state;
 
@@ -1599,7 +1599,7 @@ itemize_with_font (PangoContext               *context,
     return NULL;
 
   itemize_state_init (&state, context, text, context->base_dir, start_index, length,
-		      NULL, NULL, desc);
+                      NULL, NULL, desc);
 
   do
     itemize_state_process_run (&state);
@@ -1612,39 +1612,39 @@ itemize_with_font (PangoContext               *context,
 
 /**
  * pango_itemize:
- * @context:   a structure holding information that affects
-	       the itemization process.
- * @text:      the text to itemize. Must be valid UTF-8
+ * @context: a structure holding information that affects
+ *   the itemization process.
+ * @text: the text to itemize. Must be valid UTF-8
  * @start_index: first byte in @text to process
- * @length:    the number of bytes (not characters) to process
- *             after @start_index.
- *             This must be >= 0.
- * @attrs:     the set of attributes that apply to @text.
+ * @length: the number of bytes (not characters) to process
+ *   after @start_index. This must be >= 0.
+ * @attrs: the set of attributes that apply to @text.
  * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
  *
- * Breaks a piece of text into segments with consistent
- * directional level and shaping engine. Each byte of @text will
- * be contained in exactly one of the items in the returned list;
- * the generated list of items will be in logical order (the start
- * offsets of the items are ascending).
- *
- * @cached_iter should be an iterator over @attrs currently positioned at a
- * range before or containing @start_index; @cached_iter will be advanced to
- * the range covering the position just after @start_index + @length.
- * (i.e. if itemizing in a loop, just keep passing in the same @cached_iter).
- *
- * Return value: (transfer full) (element-type Pango.Item): a #GList of #PangoItem
- *               structures. The items should be freed using pango_item_free()
- *               probably in combination with g_list_foreach(), and the list itself
- *               using g_list_free().
+ * Breaks a piece of text into segments with consistent directional
+ * level and font.
+ *
+ * Each byte of @text will be contained in exactly one of the items in the
+ * returned list; the generated list of items will be in logical order (the
+ * start offsets of the items are ascending).
+ *
+ * @cached_iter should be an iterator over @attrs currently positioned
+ * at a range before or containing @start_index; @cached_iter will be
+ * advanced to the range covering the position just after
+ * @start_index + @length. (i.e. if itemizing in a loop, just keep passing
+ * in the same @cached_iter).
+ *
+ * Return value: (transfer full) (element-type Pango.Item): a `GList` of
+ *   [struct@Pango.Item] structures. The items should be freed using
+ *   [method@Pango.Item.free] probably in combination with g_list_free_full().
  */
 GList *
 pango_itemize (PangoContext      *context,
-	       const char        *text,
-	       int                start_index,
-	       int                length,
-	       PangoAttrList     *attrs,
-	       PangoAttrIterator *cached_iter)
+               const char        *text,
+               int                start_index,
+               int                length,
+               PangoAttrList     *attrs,
+               PangoAttrIterator *cached_iter)
 {
   g_return_val_if_fail (context != NULL, NULL);
   g_return_val_if_fail (start_index >= 0, NULL);
@@ -1652,13 +1652,13 @@ pango_itemize (PangoContext      *context,
   g_return_val_if_fail (length == 0 || text != NULL, NULL);
 
   return pango_itemize_with_base_dir (context, context->base_dir,
-				      text, start_index, length, attrs, cached_iter);
+                                      text, start_index, length, attrs, cached_iter);
 }
 
 static gboolean
 get_first_metrics_foreach (PangoFontset  *fontset,
-			   PangoFont     *font,
-			   gpointer       data)
+                           PangoFont     *font,
+                           gpointer       data)
 {
   PangoFontMetrics *fontset_metrics = data;
   PangoLanguage *language = PANGO_FONTSET_GET_CLASS (fontset)->get_language (fontset);
@@ -1675,7 +1675,7 @@ get_first_metrics_foreach (PangoFontset  *fontset,
 
   pango_font_metrics_unref (font_metrics);
 
-  return TRUE;			/* Stops iteration */
+  return TRUE;                  /* Stops iteration */
 }
 
 static PangoFontMetrics *
@@ -1691,10 +1691,10 @@ get_base_metrics (PangoFontset *fontset)
 
 static void
 update_metrics_from_items (PangoFontMetrics *metrics,
-			   PangoLanguage    *language,
-			   const char       *text,
-			   unsigned int      text_len,
-			   GList            *items)
+                           PangoLanguage    *language,
+                           const char       *text,
+                           unsigned int      text_len,
+                           GList            *items)
 
 {
   GHashTable *fonts_seen = g_hash_table_new (NULL, NULL);
@@ -1713,20 +1713,20 @@ update_metrics_from_items (PangoFontMetrics *metrics,
       PangoFont *font = item->analysis.font;
 
       if (font != NULL && g_hash_table_lookup (fonts_seen, font) == NULL)
-	{
-	  PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language);
-	  g_hash_table_insert (fonts_seen, font, font);
-
-	  /* metrics will already be initialized from the first font in the fontset */
-	  metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent);
-	  metrics->descent = MAX (metrics->descent, raw_metrics->descent);
-	  metrics->height = MAX (metrics->height, raw_metrics->height);
-	  pango_font_metrics_unref (raw_metrics);
-	}
+        {
+          PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language);
+          g_hash_table_insert (fonts_seen, font, font);
+
+          /* metrics will already be initialized from the first font in the fontset */
+          metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent);
+          metrics->descent = MAX (metrics->descent, raw_metrics->descent);
+          metrics->height = MAX (metrics->height, raw_metrics->height);
+          pango_font_metrics_unref (raw_metrics);
+        }
 
       pango_shape_full (text + item->offset, item->length,
-			text, text_len,
-			&item->analysis, glyphs);
+                        text, text_len,
+                        &item->analysis, glyphs);
       metrics->approximate_char_width += pango_glyph_string_get_width (glyphs);
     }
 
@@ -1740,35 +1740,34 @@ update_metrics_from_items (PangoFontMetrics *metrics,
 
 /**
  * pango_context_get_metrics:
- * @context: a #PangoContext
- * @desc: (allow-none): a #PangoFontDescription structure.  %NULL means that the
- *            font description from the context will be used.
+ * @context: a `PangoContext`
+ * @desc: (allow-none): a `PangoFontDescription` structure. %NULL means that the
+ *   font description from the context will be used.
  * @language: (allow-none): language tag used to determine which script to get
- *            the metrics for. %NULL means that the language tag from the context
- *            will be used. If no language tag is set on the context, metrics
- *            for the default language (as determined by pango_language_get_default())
- *            will be returned.
- *
- * Get overall metric information for a particular font
- * description.  Since the metrics may be substantially different for
- * different scripts, a language tag can be provided to indicate that
- * the metrics should be retrieved that correspond to the script(s)
- * used by that language.
- *
- * The #PangoFontDescription is interpreted in the same way as
- * by pango_itemize(), and the family name may be a comma separated
- * list of figures. If characters from multiple of these families
- * would be used to render the string, then the returned fonts would
- * be a composite of the metrics for the fonts loaded for the
- * individual families.
- *
- * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref()
- *   when finished using the object.
- **/
+ *   the metrics for. %NULL means that the language tag from the context
+ *   will be used. If no language tag is set on the context, metrics
+ *   for the default language (as determined by [type_func@Pango.Language.get_default]
+ *   will be returned.
+ *
+ * Get overall metric information for a particular font description.
+ *
+ * Since the metrics may be substantially different for different scripts,
+ * a language tag can be provided to indicate that the metrics should be
+ * retrieved that correspond to the script(s) used by that language.
+ *
+ * The `PangoFontDescription` is interpreted in the same way as by [func@itemize],
+ * and the family name may be a comma separated list of names. If characters
+ * from multiple of these families would be used to render the string, then
+ * the returned fonts would be a composite of the metrics for the fonts loaded
+ * for the individual families.
+ *
+ * Return value: a `PangoFontMetrics` object. The caller must call
+ *   [method@Pango.FontMetrics.unref] when finished using the object.
+ */
 PangoFontMetrics *
-pango_context_get_metrics (PangoContext                 *context,
-			   const PangoFontDescription   *desc,
-			   PangoLanguage                *language)
+pango_context_get_metrics (PangoContext               *context,
+                           const PangoFontDescription *desc,
+                           PangoLanguage              *language)
 {
   PangoFontset *current_fonts = NULL;
   PangoFontMetrics *metrics;
@@ -1802,7 +1801,7 @@ pango_context_get_metrics (PangoContext                 *context,
 }
 
 static void
-context_changed  (PangoContext *context)
+context_changed (PangoContext *context)
 {
   context->serial++;
   if (context->serial == 0)
@@ -1811,9 +1810,9 @@ context_changed  (PangoContext *context)
 
 /**
  * pango_context_changed:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
- * Forces a change in the context, which will cause any #PangoLayout
+ * Forces a change in the context, which will cause any `PangoLayout`
  * using this context to re-layout.
  *
  * This function is only useful when implementing a new backend
@@ -1824,7 +1823,7 @@ context_changed  (PangoContext *context)
  * Since: 1.32.4
  **/
 void
-pango_context_changed  (PangoContext *context)
+pango_context_changed (PangoContext *context)
 {
   context_changed (context);
 }
@@ -1845,23 +1844,25 @@ check_fontmap_changed (PangoContext *context)
 
 /**
  * pango_context_get_serial:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
+ *
+ * Returns the current serial number of @context.
  *
- * Returns the current serial number of @context.  The serial number is
- * initialized to an small number larger than zero when a new context
- * is created and is increased whenever the context is changed using any
- * of the setter functions, or the #PangoFontMap it uses to find fonts has
- * changed. The serial may wrap, but will never have the value 0. Since it
- * can wrap, never compare it with "less than", always use "not equals".
+ * The serial number is initialized to an small number larger than zero
+ * when a new context is created and is increased whenever the context
+ * is changed using any of the setter functions, or the `PangoFontMap` it
+ * uses to find fonts has changed. The serial may wrap, but will never
+ * have the value 0. Since it can wrap, never compare it with "less than",
+ * always use "not equals".
  *
- * This can be used to automatically detect changes to a #PangoContext, and
- * is only useful when implementing objects that need update when their
- * #PangoContext changes, like #PangoLayout.
+ * This can be used to automatically detect changes to a `PangoContext`,
+ * and is only useful when implementing objects that need update when their
+ * `PangoContext` changes, like `PangoLayout`.
  *
  * Return value: The current serial number of @context.
  *
  * Since: 1.32.4
- **/
+ */
 guint
 pango_context_get_serial (PangoContext *context)
 {
@@ -1871,7 +1872,7 @@ pango_context_get_serial (PangoContext *context)
 
 /**
  * pango_context_set_round_glyph_positions:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  * @round_positions: whether to round glyph positions
  *
  * Sets whether font rendering with this context should
@@ -1899,7 +1900,7 @@ pango_context_set_round_glyph_positions (PangoContext *context,
 
 /**
  * pango_context_get_round_glyph_positions:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
  * Returns whether font rendering with this context should
  * round glyph positions and widths.
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index 5358e4e7..ebd258b2 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -19,16 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:coverage-maps
- * @short_description:Unicode character range coverage storage
- * @title:Coverage Maps
- *
- * It is often necessary in Pango to determine if a particular font can
- * represent a particular character, and also how well it can represent
- * that character. The #PangoCoverage is a data structure that is used
- * to represent that information.
- */
 #include "config.h"
 #include <string.h>
 
@@ -117,9 +107,9 @@ pango_coverage_class_init (PangoCoverageClass *class)
 /**
  * pango_coverage_new:
  *
- * Create a new #PangoCoverage
+ * Create a new `PangoCoverage`
  *
- * Return value: the newly allocated #PangoCoverage,
+ * Return value: the newly allocated `PangoCoverage`,
  *               initialized to %PANGO_COVERAGE_NONE
  *               with a reference count of one, which
  *               should be freed with pango_coverage_unref().
@@ -132,12 +122,11 @@ pango_coverage_new (void)
 
 /**
  * pango_coverage_copy:
- * @coverage: a #PangoCoverage
+ * @coverage: a `PangoCoverage`
  *
- * Copy an existing #PangoCoverage. (This function may now be unnecessary
- * since we refcount the structure. File a bug if you use it.)
+ * Copy an existing `PangoCoverage`.
  *
- * Return value: (transfer full): the newly allocated #PangoCoverage,
+ * Return value: (transfer full): the newly allocated `PangoCoverage`,
  *               with a reference count of one, which should be freed
  *               with pango_coverage_unref().
  **/
@@ -149,9 +138,9 @@ pango_coverage_copy (PangoCoverage *coverage)
 
 /**
  * pango_coverage_ref:
- * @coverage: (not nullable): a #PangoCoverage
+ * @coverage: (not nullable): a `PangoCoverage`
  *
- * Increase the reference count on the #PangoCoverage by one
+ * Increase the reference count on the `PangoCoverage` by one.
  *
  * Return value: (transfer full): @coverage
  **/
@@ -163,9 +152,10 @@ pango_coverage_ref (PangoCoverage *coverage)
 
 /**
  * pango_coverage_unref:
- * @coverage: (transfer full) (not nullable): a #PangoCoverage
+ * @coverage: (transfer full) (not nullable): a `PangoCoverage`
+ *
+ * Decrease the reference count on the `PangoCoverage` by one.
  *
- * Decrease the reference count on the #PangoCoverage by one.
  * If the result is zero, free the coverage and all associated memory.
  **/
 void
@@ -176,10 +166,10 @@ pango_coverage_unref (PangoCoverage *coverage)
 
 /**
  * pango_coverage_get:
- * @coverage: a #PangoCoverage
+ * @coverage: a `PangoCoverage`
  * @index_: the index to check
  *
- * Determine whether a particular index is covered by @coverage
+ * Determine whether a particular index is covered by @coverage.
  *
  * Return value: the coverage level of @coverage for character @index_.
  **/
@@ -192,7 +182,7 @@ pango_coverage_get (PangoCoverage *coverage,
 
 /**
  * pango_coverage_set:
- * @coverage: a #PangoCoverage
+ * @coverage: a `PangoCoverage`
  * @index_: the index to modify
  * @level: the new level for @index_
  *
@@ -208,8 +198,8 @@ pango_coverage_set (PangoCoverage     *coverage,
 
 /**
  * pango_coverage_max:
- * @coverage: a #PangoCoverage
- * @other: another #PangoCoverage
+ * @coverage: a `PangoCoverage`
+ * @other: another `PangoCoverage`
  *
  * Set the coverage for each index in @coverage to be the max (better)
  * value of the current coverage for the index and the coverage for
@@ -225,12 +215,12 @@ pango_coverage_max (PangoCoverage *coverage,
 
 /**
  * pango_coverage_to_bytes:
- * @coverage: a #PangoCoverage
+ * @coverage: a `PangoCoverage`
  * @bytes: (out) (array length=n_bytes) (element-type guint8):
  *   location to store result (must be freed with g_free())
  * @n_bytes: (out): location to store size of result
  *
- * Convert a #PangoCoverage structure into a flat binary format
+ * Convert a `PangoCoverage` structure into a flat binary format.
  *
  * Deprecated: 1.44: This returns %NULL
  **/
@@ -246,14 +236,14 @@ pango_coverage_to_bytes (PangoCoverage  *coverage,
 /**
  * pango_coverage_from_bytes:
  * @bytes: (array length=n_bytes) (element-type guint8): binary data
- *   representing a #PangoCoverage
+ *   representing a `PangoCoverage`
  * @n_bytes: the size of @bytes in bytes
  *
  * Convert data generated from pango_coverage_to_bytes() back
- * to a #PangoCoverage
+ * to a `PangoCoverage`.
  *
  * Return value: (transfer full) (nullable): a newly allocated
- *               #PangoCoverage, or %NULL if the data was invalid.
+ *               `PangoCoverage`, or %NULL if the data was invalid.
  *
  * Deprecated: 1.44: This returns %NULL
  **/
diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h
index 7467dbda..67fc6306 100644
--- a/pango/pango-coverage.h
+++ b/pango/pango-coverage.h
@@ -32,8 +32,13 @@ G_BEGIN_DECLS
 /**
  * PangoCoverage:
  *
- * The #PangoCoverage structure represents a map from Unicode characters
- * to #PangoCoverageLevel. It is an opaque structure with no public fields.
+ * A #PangoCoverage structure is a map from Unicode characters
+ * to #PangoCoverageLevel values.
+ *
+ * It is often necessary in Pango to determine if a particular font can
+ * represent a particular character, and also how well it can represent
+ * that character. The #PangoCoverage is a data structure that is used to
+ * represent that information. It is an opaque structure with no public fields.
  */
 typedef struct _PangoCoverage PangoCoverage;
 
@@ -49,8 +54,8 @@ typedef struct _PangoCoverage PangoCoverage;
  * the current script.
  * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form.
  *
- * Used to indicate how well a font can represent a particular Unicode
- * character point for a particular script.
+ * `PangoCoverageLevel` is used to indicate how well a font can represent
+ * a particular Unicode character for a particular script.
  *
  * Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT
  * will be returned.
diff --git a/pango/pango-direction.h b/pango/pango-direction.h
index 6cbd5aa7..7da14175 100644
--- a/pango/pango-direction.h
+++ b/pango/pango-direction.h
@@ -38,26 +38,25 @@ G_BEGIN_DECLS
  * @PANGO_DIRECTION_WEAK_RTL: A weak right-to-left direction
  * @PANGO_DIRECTION_NEUTRAL: No direction specified
  *
- * The #PangoDirection type represents a direction in the
- * Unicode bidirectional algorithm; not every value in this
- * enumeration makes sense for every usage of #PangoDirection;
- * for example, the return value of pango_unichar_direction()
- * and pango_find_base_dir() cannot be %PANGO_DIRECTION_WEAK_LTR
- * or %PANGO_DIRECTION_WEAK_RTL, since every character is either
- * neutral or has a strong direction; on the other hand
- * %PANGO_DIRECTION_NEUTRAL doesn't make sense to pass
- * to pango_itemize_with_base_dir().
+ * `PangoDirection` represents a direction in the Unicode bidirectional
+ * algorithm.
  *
- * The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL
- * values come from an earlier interpretation of this
- * enumeration as the writing direction of a block of
- * text and are no longer used; See #PangoGravity for how
+ * Not every value in this enumeration makes sense for every usage of
+ * `PangoDirection`; for example, the return value of [func@unichar_direction]
+ * and [func@find_base_dir] cannot be %PANGO_DIRECTION_WEAK_LTR or
+ * %PANGO_DIRECTION_WEAK_RTL, since every character is either neutral
+ * or has a strong direction; on the other hand %PANGO_DIRECTION_NEUTRAL
+ * doesn't make sense to pass to [func@itemize_with_base_dir].
+ *
+ * The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL values come from
+ * an earlier interpretation of this enumeration as the writing direction
+ * of a block of text and are no longer used; See `PangoGravity` for how
  * vertical text is handled in Pango.
  *
- * If you are interested in text direction, you should
- * really use fribidi directly. PangoDirection is only
- * retained because it is used in some public apis.
- **/
+ * If you are interested in text direction, you should really use fribidi
+ * directly. `PangoDirection` is only retained because it is used in some
+ * public apis.
+ */
 typedef enum {
   PANGO_DIRECTION_LTR,
   PANGO_DIRECTION_RTL,
diff --git a/pango/pango-engine.c b/pango/pango-engine.c
index 34d09641..e52bcd99 100644
--- a/pango/pango-engine.c
+++ b/pango/pango-engine.c
@@ -19,44 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:engines
- * @short_description:Language-specific and rendering-system-specific processing
- * @title:Engines
- *
- * Pango used to have a module architecture in which the language-specific
- * and render-system-specific components are provided by loadable
- * modules.
- *
- * This is no longer the case, and all the APIs related
- * to modules and engines should not be used anymore.
- *
- * Deprecated: 1.38
- */
-/**
- * SECTION:pango-engine-lang
- * @short_description:Rendering-system independent script engines
- * @title:PangoEngineLang
- * @stability:Unstable
- *
- * The <firstterm>language engines</firstterm> are rendering-system independent
- * engines that determine line, word, and character breaks for character strings.
- * These engines are used in pango_break().
- *
- * Deprecated: 1.38
- */
-/**
- * SECTION:pango-engine-shape
- * @short_description:Rendering-system dependent script engines
- * @title:PangoEngineShape
- * @stability:Unstable
- *
- * The <firstterm>shape engines</firstterm> are rendering-system dependent
- * engines that convert character strings into glyph strings.
- * These engines are used in pango_shape().
- *
- * Deprecated: 1.38
- */
 #include "config.h"
 
 #include "pango-engine.h"
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 25cfd6ba..16b39c3f 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -30,6 +30,11 @@
 
 G_BEGIN_DECLS
 
+/* All of this is deprecated and entirely useless for bindings.
+ * Leave it out of the gir file.
+ */
+#ifndef __GI_SCANNER__
+
 #ifndef PANGO_DISABLE_DEPRECATED
 
 /**
@@ -196,7 +201,7 @@ struct _PangoEngineShape
  *   appropriately using pango_glyph_string_set_size()). All fields
  *   of the @log_clusters and @glyphs array must be filled in, with
  *   the exception that Pango will automatically generate
- *   <literal>glyphs->glyphs[i].attr.is_cluster_start</literal>
+ *   `glyphs->glyphs[i].attr.is_cluster_start`
  *   using the @log_clusters array. Each input character must occur in one
  *   of the output logical clusters;
  *   if no rendering is desired for a character, this may involve
@@ -287,11 +292,6 @@ struct _PangoEngineInfo
   gint n_scripts;
 };
 
-/* We should to ignore these unprefixed symbols when going through
- * this header with the introspection scanner
- */
-#ifndef __GI_SCANNER__
-
 /**
  * script_engine_list: (skip)
  * @engines: location to store a pointer to an array of engines.
@@ -368,8 +368,8 @@ prefix ## _register_type (GTypeModule *module)				  \
 
 /**
  * PANGO_ENGINE_LANG_DEFINE_TYPE:
- * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
- * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
+ * @name: Name of the the type to register (for example:, ArabicEngineFc)
+ * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
  * @class_init: (nullable): Class initialization function for the new type, or %NULL
  * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
  *
@@ -378,18 +378,17 @@ prefix ## _register_type (GTypeModule *module)				  \
  * are defined.
  *
  * <programlisting>
- *  static GType <replaceable>prefix</replaceable>_type;
- *  static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
- * </programlisting>
+ *  static GType *prefix*_type;
+ *  static void *prefix*_register_type (GTypeModule module);
  *
- * The <function><replaceable>prefix</replaceable>_register_type()</function>
+ * The *prefix*_register_type()
  * function should be called in your script_engine_init() function for
  * each type that your module implements, and then your script_engine_create()
  * function can create instances of the object as follows:
  *
- * <informalexample><programlisting>
- *  PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
- * </programlisting></informalexample>
+ * ```
+ * PangoEngine *engine = g_object_new (prefix_type, NULL);
+ * ```
  *
  * Deprecated: 1.38
  **/
@@ -400,8 +399,8 @@ prefix ## _register_type (GTypeModule *module)				  \
 
 /**
  * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
- * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
- * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
+ * @name: Name of the the type to register (for example:, ArabicEngineFc)
+ * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
  * @class_init: (nullable): Class initialization function for the new type, or %NULL
  * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
  *
@@ -410,18 +409,18 @@ prefix ## _register_type (GTypeModule *module)				  \
  * are defined.
  *
  * <programlisting>
- *  static GType <replaceable>prefix</replaceable>_type;
- *  static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
+ *  static GType *prefix*_type;
+ *  static void *prefix*_register_type (GTypeModule module);
  * </programlisting>
  *
- * The <function><replaceable>prefix</replaceable>_register_type()</function>
+ * The *prefix*_register_type()
  * function should be called in your script_engine_init() function for
  * each type that your module implements, and then your script_engine_create()
  * function can create instances of the object as follows:
  *
- * <informalexample><programlisting>
- *  PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
- * </programlisting></informalexample>
+ * ```
+ * PangoEngine *engine = g_object_new (prefix_type, NULL);
+ * ```
  *
  * Deprecated: 1.38
  **/
diff --git a/pango/pango-font.h b/pango/pango-font.h
index ba1ea3ae..13f8a222 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -33,20 +33,25 @@ G_BEGIN_DECLS
 /**
  * PangoFontDescription:
  *
- * The #PangoFontDescription structure represents the description
- * of an ideal font. These structures are used both to list
- * what fonts are available on the system and also for specifying
- * the characteristics of a font to load.
+ * A `PangoFontDescription` describes a font in an implementation-independent
+ * manner.
+ *
+ * `PangoFontDescription` structures are used both to list what fonts are
+ * available on the system and also for specifying the characteristics of
+ * a font to load.
  */
 typedef struct _PangoFontDescription PangoFontDescription;
+
 /**
  * PangoFontMetrics:
  *
- * A #PangoFontMetrics structure holds the overall metric information
- * for a font (possibly restricted to a script). The fields of this
- * structure are private to implementations of a font backend. See
- * the documentation of the corresponding getters for documentation
- * of their meaning.
+ * A `PangoFontMetrics` structure holds the overall metric information
+ * for a font.
+ *
+ * The information in a `PangoFontMetrics` structure may be restricted
+ * to a script. The fields of this structure are private to implementations
+ * of a font backend. See the documentation of the corresponding getters
+ * for documentation of their meaning.
  */
 typedef struct _PangoFontMetrics PangoFontMetrics;
 
@@ -92,8 +97,10 @@ typedef enum {
  * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
  * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24)
  *
- * An enumeration specifying the weight (boldness) of a font. This is a numerical
- * value ranging from 100 to 1000, but there are some predefined values:
+ * An enumeration specifying the weight (boldness) of a font.
+ *
+ * This is a numerical value ranging from 100 to 1000, but there
+ * are some predefined values.
  */
 typedef enum {
   PANGO_WEIGHT_THIN = 100,
@@ -148,8 +155,8 @@ typedef enum {
  * @PANGO_FONT_MASK_GRAVITY: the font gravity is specified (Since: 1.16.)
  * @PANGO_FONT_MASK_VARIATIONS: OpenType font variations are specified (Since: 1.42)
  *
- * The bits in a #PangoFontMask correspond to fields in a
- * #PangoFontDescription that have been set.
+ * The bits in a `PangoFontMask` correspond to the set fields in a
+ * `PangoFontDescription`.
  */
 typedef enum {
   PANGO_FONT_MASK_FAMILY  = 1 << 0,
@@ -210,11 +217,6 @@ typedef enum {
  * PangoFontDescription
  */
 
-/**
- * PANGO_TYPE_FONT_DESCRIPTION:
- *
- * The #GObject type for #PangoFontDescription.
- */
 #define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
@@ -229,54 +231,54 @@ PANGO_AVAILABLE_IN_ALL
 guint                 pango_font_description_hash        (const PangoFontDescription  *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 gboolean              pango_font_description_equal       (const PangoFontDescription  *desc1,
-							  const PangoFontDescription  *desc2) G_GNUC_PURE;
+                                                          const PangoFontDescription  *desc2) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_description_free        (PangoFontDescription        *desc);
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_descriptions_free       (PangoFontDescription       **descs,
-							  int                          n_descs);
+                                                          int                          n_descs);
 
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_family        (PangoFontDescription *desc,
-							       const char           *family);
+                                                               const char           *family);
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_family_static (PangoFontDescription *desc,
-							       const char           *family);
+                                                               const char           *family);
 PANGO_AVAILABLE_IN_ALL
 const char          *pango_font_description_get_family        (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_style         (PangoFontDescription *desc,
-							       PangoStyle            style);
+                                                               PangoStyle            style);
 PANGO_AVAILABLE_IN_ALL
 PangoStyle           pango_font_description_get_style         (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_variant       (PangoFontDescription *desc,
-							       PangoVariant          variant);
+                                                               PangoVariant          variant);
 PANGO_AVAILABLE_IN_ALL
 PangoVariant         pango_font_description_get_variant       (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_weight        (PangoFontDescription *desc,
-							       PangoWeight           weight);
+                                                               PangoWeight           weight);
 PANGO_AVAILABLE_IN_ALL
 PangoWeight          pango_font_description_get_weight        (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_stretch       (PangoFontDescription *desc,
-							       PangoStretch          stretch);
+                                                               PangoStretch          stretch);
 PANGO_AVAILABLE_IN_ALL
 PangoStretch         pango_font_description_get_stretch       (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_size          (PangoFontDescription *desc,
-							       gint                  size);
+                                                               gint                  size);
 PANGO_AVAILABLE_IN_ALL
 gint                 pango_font_description_get_size          (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_8
 void                 pango_font_description_set_absolute_size (PangoFontDescription *desc,
-							       double                size);
+                                                               double                size);
 PANGO_AVAILABLE_IN_1_8
 gboolean             pango_font_description_get_size_is_absolute (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_16
 void                 pango_font_description_set_gravity       (PangoFontDescription *desc,
-							       PangoGravity          gravity);
+                                                               PangoGravity          gravity);
 PANGO_AVAILABLE_IN_1_16
 PangoGravity         pango_font_description_get_gravity       (const PangoFontDescription *desc) G_GNUC_PURE;
 
@@ -293,21 +295,21 @@ PANGO_AVAILABLE_IN_ALL
 PangoFontMask pango_font_description_get_set_fields (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void          pango_font_description_unset_fields   (PangoFontDescription       *desc,
-						     PangoFontMask               to_unset);
+                                                     PangoFontMask               to_unset);
 
 PANGO_AVAILABLE_IN_ALL
 void pango_font_description_merge        (PangoFontDescription       *desc,
-					  const PangoFontDescription *desc_to_merge,
-					  gboolean                    replace_existing);
+                                          const PangoFontDescription *desc_to_merge,
+                                          gboolean                    replace_existing);
 PANGO_AVAILABLE_IN_ALL
 void pango_font_description_merge_static (PangoFontDescription       *desc,
-					  const PangoFontDescription *desc_to_merge,
-					  gboolean                    replace_existing);
+                                          const PangoFontDescription *desc_to_merge,
+                                          gboolean                    replace_existing);
 
 PANGO_AVAILABLE_IN_ALL
 gboolean pango_font_description_better_match (const PangoFontDescription *desc,
-					      const PangoFontDescription *old_match,
-					      const PangoFontDescription *new_match) G_GNUC_PURE;
+                                              const PangoFontDescription *old_match,
+                                              const PangoFontDescription *new_match) G_GNUC_PURE;
 
 PANGO_AVAILABLE_IN_ALL
 PangoFontDescription *pango_font_description_from_string (const char                  *str);
@@ -320,11 +322,6 @@ char *                pango_font_description_to_filename (const PangoFontDescrip
  * PangoFontMetrics
  */
 
-/**
- * PANGO_TYPE_FONT_METRICS:
- *
- * The #GObject type for #PangoFontMetrics.
- */
 #define PANGO_TYPE_FONT_METRICS  (pango_font_metrics_get_type ())
 
 struct _PangoFontMetrics
@@ -373,23 +370,6 @@ int               pango_font_metrics_get_strikethrough_thickness (PangoFontMetri
  * PangoFontFamily
  */
 
-/**
- * PANGO_TYPE_FONT_FAMILY:
- *
- * The #GObject type for #PangoFontFamily.
- */
-/**
- * PANGO_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFamily.
- */
-/**
- * PANGO_IS_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFamily.
- */
 #define PANGO_TYPE_FONT_FAMILY              (pango_font_family_get_type ())
 #define PANGO_FONT_FAMILY(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY, PangoFontFamily))
 #define PANGO_IS_FONT_FAMILY(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
@@ -406,9 +386,11 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
 /**
  * PangoFontFamily:
  *
- * The #PangoFontFamily structure is used to represent a family of related
- * font faces. The faces in a family share a common design, but differ in
- * slant, weight, width and other aspects.
+ * A `PangoFontFamily` is used to represent a family of related
+ * font faces.
+ *
+ * The font faces in a family share a common design, but differ in
+ * slant, weight, width or other aspects.
  */
 struct _PangoFontFamily
 {
@@ -445,8 +427,8 @@ GType      pango_font_family_get_type       (void) G_GNUC_CONST;
 
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_family_list_faces (PangoFontFamily  *family,
-						   PangoFontFace  ***faces,
-						   int              *n_faces);
+                                                   PangoFontFace  ***faces,
+                                                   int              *n_faces);
 PANGO_AVAILABLE_IN_ALL
 const char *pango_font_family_get_name   (PangoFontFamily  *family) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_4
@@ -463,23 +445,6 @@ PangoFontFace *pango_font_family_get_face (PangoFontFamily *family,
  * PangoFontFace
  */
 
-/**
- * PANGO_TYPE_FONT_FACE:
- *
- * The #GObject type for #PangoFontFace.
- */
-/**
- * PANGO_FONT_FACE:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFace.
- */
-/**
- * PANGO_IS_FONT_FACE:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFace.
- */
 #define PANGO_TYPE_FONT_FACE              (pango_font_face_get_type ())
 #define PANGO_FONT_FACE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE, PangoFontFace))
 #define PANGO_IS_FONT_FACE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
@@ -494,8 +459,8 @@ typedef struct _PangoFontFaceClass   PangoFontFaceClass;
 /**
  * PangoFontFace:
  *
- * The #PangoFontFace structure is used to represent a group of fonts with
- * the same family, slant, weight, width, but varying sizes.
+ * A `PangoFontFace` is used to represent a group of fonts with
+ * the same family, slant, weight, and width, but varying sizes.
  */
 struct _PangoFontFace
 {
@@ -534,8 +499,8 @@ PANGO_AVAILABLE_IN_ALL
 const char           *pango_font_face_get_face_name  (PangoFontFace  *face) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_4
 void                  pango_font_face_list_sizes     (PangoFontFace  *face,
-						      int           **sizes,
-						      int            *n_sizes);
+                                                      int           **sizes,
+                                                      int            *n_sizes);
 PANGO_AVAILABLE_IN_1_18
 gboolean              pango_font_face_is_synthesized (PangoFontFace  *face) G_GNUC_PURE;
 
@@ -547,23 +512,6 @@ PangoFontFamily *     pango_font_face_get_family     (PangoFontFace  *face);
  * PangoFont
  */
 
-/**
- * PANGO_TYPE_FONT:
- *
- * The #GObject type for #PangoFont.
- */
-/**
- * PANGO_FONT:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFont.
- */
-/**
- * PANGO_IS_FONT:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFont.
- */
 #define PANGO_TYPE_FONT              (pango_font_get_type ())
 #define PANGO_FONT(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
 #define PANGO_IS_FONT(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
@@ -577,18 +525,8 @@ PangoFontFamily *     pango_font_face_get_family     (PangoFontFace  *face);
 /**
  * PangoFont:
  *
- * The #PangoFont structure is used to represent
- * a font in a rendering-system-independent matter.
- * To create an implementation of a #PangoFont,
- * the rendering-system specific code should allocate
- * a larger structure that contains a nested
- * #PangoFont, fill in the <structfield>klass</structfield> member of
- * the nested #PangoFont with a pointer to
- * a appropriate #PangoFontClass, then call
- * pango_font_init() on the structure.
- *
- * The #PangoFont structure contains one member
- * which the implementation fills in.
+ * A `PangoFont` is used to represent a font in a
+ * rendering-system-independent manner.
  */
 struct _PangoFont
 {
@@ -631,19 +569,21 @@ PANGO_AVAILABLE_IN_1_14
 PangoFontDescription *pango_font_describe_with_absolute_size (PangoFont        *font);
 PANGO_AVAILABLE_IN_ALL
 PangoCoverage *       pango_font_get_coverage      (PangoFont        *font,
-						    PangoLanguage    *language);
+                                                    PangoLanguage    *language);
+#ifndef __GI_SCANNER__
 PANGO_DEPRECATED_IN_1_44
 PangoEngineShape *    pango_font_find_shaper       (PangoFont        *font,
-						    PangoLanguage    *language,
-						    guint32           ch);
+                                                    PangoLanguage    *language,
+                                                    guint32           ch);
+#endif
 PANGO_AVAILABLE_IN_ALL
 PangoFontMetrics *    pango_font_get_metrics       (PangoFont        *font,
-						    PangoLanguage    *language);
+                                                    PangoLanguage    *language);
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_get_glyph_extents (PangoFont        *font,
-						    PangoGlyph        glyph,
-						    PangoRectangle   *ink_rect,
-						    PangoRectangle   *logical_rect);
+                                                    PangoGlyph        glyph,
+                                                    PangoRectangle   *ink_rect,
+                                                    PangoRectangle   *logical_rect);
 PANGO_AVAILABLE_IN_1_10
 PangoFontMap         *pango_font_get_font_map      (PangoFont        *font);
 
@@ -664,50 +604,54 @@ hb_font_t *           pango_font_get_hb_font       (PangoFont        *font);
 /**
  * PANGO_GLYPH_EMPTY:
  *
- * The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
- *  special meaning, which is a zero-width empty glyph.  This is useful for
- * example in shaper modules, to use as the glyph for various zero-width
- * Unicode characters (those passing pango_is_zero_width()).
+ * A `PangoGlyph` value that indicates a zero-width empty glpyh.
+ *
+ * This is useful for example in shaper modules, to use as the glyph for
+ * various zero-width Unicode characters (those passing [func@is_zero_width]).
  */
+
 /**
  * PANGO_GLYPH_INVALID_INPUT:
  *
- * The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a
- * special meaning of invalid input.  #PangoLayout produces one such glyph
- * per invalid input UTF-8 byte and such a glyph is rendered as a crossed
- * box.
+ * A `PangoGlyph` value for invalid input.
+ *
+ * `PangoLayout` produces one such glyph per invalid input UTF-8 byte and such
+ * a glyph is rendered as a crossed box.
  *
  * Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG
- * on.
+ * set.
  *
  * Since: 1.20
  */
 /**
  * PANGO_GLYPH_UNKNOWN_FLAG:
  *
- * The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
- * a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
- * value, representing an unknown-character glyph for the respective #gunichar.
+ * Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode
+ * character into an unknown-character glyph for that `gunichar`.
+ *
+ * Such unknown-character glyphs may be rendered as a 'hex box'.
  */
 /**
  * PANGO_GET_UNKNOWN_GLYPH:
  * @wc: a Unicode character
  *
- * The way this unknown glyphs are rendered is backend specific.  For example,
+ * The way this unknown glyphs are rendered is backend specific. For example,
  * a box with the hexadecimal Unicode code-point of the character written in it
  * is what is done in the most common backends.
  *
- * Returns: a #PangoGlyph value that means no glyph was found for @wc.
+ * Returns: a `PangoGlyph` value that means no glyph was found for @wc.
  */
 #define PANGO_GLYPH_EMPTY           ((PangoGlyph)0x0FFFFFFF)
 #define PANGO_GLYPH_INVALID_INPUT   ((PangoGlyph)0xFFFFFFFF)
 #define PANGO_GLYPH_UNKNOWN_FLAG    ((PangoGlyph)0x10000000)
 #define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG)
 
+#ifndef __GI_SCANNER__
 #ifndef PANGO_DISABLE_DEPRECATED
 #define PANGO_UNKNOWN_GLYPH_WIDTH  10
 #define PANGO_UNKNOWN_GLYPH_HEIGHT 14
 #endif
+#endif
 
 G_END_DECLS
 
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index d4cdefa6..bc18a7da 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -29,9 +29,9 @@
 #include <stdlib.h>
 
 static PangoFontset *pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
-						       PangoContext               *context,
-						       const PangoFontDescription *desc,
-						       PangoLanguage              *language);
+                                                       PangoContext               *context,
+                                                       const PangoFontDescription *desc,
+                                                       PangoLanguage              *language);
 
 
 static PangoFontFamily *pango_font_map_real_get_family (PangoFontMap *fontmap,
@@ -64,21 +64,23 @@ pango_font_map_init (PangoFontMap *fontmap G_GNUC_UNUSED)
 
 /**
  * pango_font_map_create_context:
- * @fontmap: a #PangoFontMap
+ * @fontmap: a `PangoFontMap`
  *
- * Creates a #PangoContext connected to @fontmap.  This is equivalent
- * to pango_context_new() followed by pango_context_set_font_map().
+ * Creates a `PangoContext` connected to @fontmap.
+ *
+ * This is equivalent to [ctor@Pango.Context.new] followed by
+ * [method@Pango.Context.set_font_map].
  *
  * If you are using Pango as part of a higher-level system,
- * that system may have it's own way of create a #PangoContext.
- * For instance, the GTK+ toolkit has, among others,
+ * that system may have it's own way of create a `PangoContext`.
+ * For instance, the GTK toolkit has, among others,
  * gtk_widget_get_pango_context(). Use those instead.
  *
- * Return value: (transfer full): the newly allocated #PangoContext,
- *               which should be freed with g_object_unref().
+ * Return value: (transfer full): the newly allocated `PangoContext`,
+ *   which should be freed with g_object_unref().
  *
  * Since: 1.22
- **/
+ */
 PangoContext *
 pango_font_map_create_context (PangoFontMap *fontmap)
 {
@@ -94,19 +96,19 @@ pango_font_map_create_context (PangoFontMap *fontmap)
 
 /**
  * pango_font_map_load_font:
- * @fontmap: a #PangoFontMap
- * @context: the #PangoContext the font will be used with
- * @desc: a #PangoFontDescription describing the font to load
+ * @fontmap: a `PangoFontMap`
+ * @context: the `PangoContext` the font will be used with
+ * @desc: a `PangoFontDescription` describing the font to load
  *
  * Load the font in the fontmap that is the closest match for @desc.
  *
- * Returns: (transfer full) (nullable): the newly allocated #PangoFont
- *          loaded, or %NULL if no font matched.
- **/
+ * Returns: (transfer full) (nullable): the newly allocated `PangoFont`
+ *   loaded, or %NULL if no font matched.
+ */
 PangoFont *
 pango_font_map_load_font  (PangoFontMap               *fontmap,
-			   PangoContext               *context,
-			   const PangoFontDescription *desc)
+                           PangoContext               *context,
+                           const PangoFontDescription *desc)
 {
   g_return_val_if_fail (fontmap != NULL, NULL);
 
@@ -115,45 +117,45 @@ pango_font_map_load_font  (PangoFontMap               *fontmap,
 
 /**
  * pango_font_map_list_families:
- * @fontmap: a #PangoFontMap
- * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of #PangoFontFamily *.
+ * @fontmap: a `PangoFontMap`
+ * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of `PangoFontFamily` *.
  *            This array should be freed with g_free().
  * @n_families: (out): location to store the number of elements in @families
  *
  * List all families for a fontmap.
- **/
+ */
 void
 pango_font_map_list_families (PangoFontMap      *fontmap,
-			      PangoFontFamily ***families,
-			      int               *n_families)
+                              PangoFontFamily ***families,
+                              int               *n_families)
 {
   PangoFontMapPrivate *priv = pango_font_map_get_instance_private (fontmap);
   g_return_if_fail (fontmap != NULL);
 
   PANGO_FONT_MAP_GET_CLASS (fontmap)->list_families (fontmap, families, n_families);
-  
+
   /* keep this value for GListModel::changed */
   priv->n_families = *n_families;
 }
 
 /**
  * pango_font_map_load_fontset:
- * @fontmap: a #PangoFontMap
- * @context: the #PangoContext the font will be used with
- * @desc: a #PangoFontDescription describing the font to load
- * @language: a #PangoLanguage the fonts will be used for
+ * @fontmap: a `PangoFontMap`
+ * @context: the `PangoContext` the font will be used with
+ * @desc: a `PangoFontDescription` describing the font to load
+ * @language: a `PangoLanguage` the fonts will be used for
  *
  * Load a set of fonts in the fontmap that can be used to render
  * a font matching @desc.
  *
  * Returns: (transfer full) (nullable): the newly allocated
- *          #PangoFontset loaded, or %NULL if no font matched.
- **/
+ *   `PangoFontset` loaded, or %NULL if no font matched.
+ */
 PangoFontset *
-pango_font_map_load_fontset (PangoFontMap                 *fontmap,
-			     PangoContext                 *context,
-			     const PangoFontDescription   *desc,
-			     PangoLanguage                *language)
+pango_font_map_load_fontset (PangoFontMap               *fontmap,
+                             PangoContext               *context,
+                             const PangoFontDescription *desc,
+                             PangoLanguage              *language)
 {
   g_return_val_if_fail (fontmap != NULL, NULL);
 
@@ -162,10 +164,10 @@ pango_font_map_load_fontset (PangoFontMap                 *fontmap,
 
 static void
 pango_font_map_fontset_add_fonts (PangoFontMap          *fontmap,
-				  PangoContext          *context,
-				  PangoFontsetSimple    *fonts,
-				  PangoFontDescription  *desc,
-				  const char            *family)
+                                  PangoContext          *context,
+                                  PangoFontsetSimple    *fonts,
+                                  PangoFontDescription  *desc,
+                                  const char            *family)
 {
   PangoFont *font;
 
@@ -177,9 +179,9 @@ pango_font_map_fontset_add_fonts (PangoFontMap          *fontmap,
 
 static PangoFontset *
 pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
-				  PangoContext               *context,
-				  const PangoFontDescription *desc,
-				  PangoLanguage              *language)
+                                  PangoContext               *context,
+                                  const PangoFontDescription *desc,
+                                  PangoLanguage              *language)
 {
   PangoFontDescription *tmp_desc = pango_font_description_copy_static (desc);
   const char *family;
@@ -196,10 +198,10 @@ pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
 
   for (i = 0; families[i]; i++)
     pango_font_map_fontset_add_fonts (fontmap,
-				      context,
-				      fonts,
-				      tmp_desc,
-				      families[i]);
+                                      context,
+                                      fonts,
+                                      tmp_desc,
+                                      families[i]);
 
   g_strfreev (families);
 
@@ -211,32 +213,32 @@ pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
       char *ctmp1, *ctmp2;
 
       pango_font_description_set_family_static (tmp_desc,
-						pango_font_description_get_family (desc));
+                                                pango_font_description_get_family (desc));
 
       ctmp1 = pango_font_description_to_string (desc);
       pango_font_description_set_family_static (tmp_desc, "Sans");
 
       G_LOCK (warned_fonts);
       if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1))
-	{
-	  if (!warned_fonts)
-	    warned_fonts = g_hash_table_new (g_str_hash, g_str_equal);
+        {
+          if (!warned_fonts)
+            warned_fonts = g_hash_table_new (g_str_hash, g_str_equal);
 
-	  g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1));
+          g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1));
 
-	  ctmp2 = pango_font_description_to_string (tmp_desc);
-	  g_warning ("couldn't load font \"%s\", falling back to \"%s\", "
-		     "expect ugly output.", ctmp1, ctmp2);
-	  g_free (ctmp2);
-	}
+          ctmp2 = pango_font_description_to_string (tmp_desc);
+          g_warning ("couldn't load font \"%s\", falling back to \"%s\", "
+                     "expect ugly output.", ctmp1, ctmp2);
+          g_free (ctmp2);
+        }
       G_UNLOCK (warned_fonts);
       g_free (ctmp1);
 
       pango_font_map_fontset_add_fonts (fontmap,
-					context,
-					fonts,
-					tmp_desc,
-					"Sans");
+                                        context,
+                                        fonts,
+                                        tmp_desc,
+                                        "Sans");
     }
 
   /* We couldn't try with Sans and the specified style. Try Sans Normal
@@ -254,23 +256,23 @@ pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
 
       G_LOCK (warned_fonts);
       if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1))
-	{
-	  g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1));
+        {
+          g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1));
 
-	  ctmp2 = pango_font_description_to_string (tmp_desc);
+          ctmp2 = pango_font_description_to_string (tmp_desc);
 
-	  g_warning ("couldn't load font \"%s\", falling back to \"%s\", "
-		     "expect ugly output.", ctmp1, ctmp2);
-	  g_free (ctmp2);
-	}
+          g_warning ("couldn't load font \"%s\", falling back to \"%s\", "
+                     "expect ugly output.", ctmp1, ctmp2);
+          g_free (ctmp2);
+        }
       G_UNLOCK (warned_fonts);
       g_free (ctmp1);
 
       pango_font_map_fontset_add_fonts (fontmap,
-					context,
-					fonts,
-					tmp_desc,
-					"Sans");
+                                        context,
+                                        fonts,
+                                        tmp_desc,
+                                        "Sans");
     }
 
   pango_font_description_free (tmp_desc);
@@ -286,19 +288,17 @@ pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
 
 /**
  * pango_font_map_get_shape_engine_type:
- * @fontmap: a #PangoFontMap
+ * @fontmap: a `PangoFontMap`
  *
  * Returns the render ID for shape engines for this fontmap.
- * See the <structfield>render_type</structfield> field of
- * #PangoEngineInfo.
+ * See the `render_type` field of #PangoEngineInfo.
   *
- * Return value: the ID string for shape engines for
- *  this fontmap. Owned by Pango, should not be modified
- *  or freed.
+ * Return value: the ID string for shape engines for this fontmap.
+ *   Owned by Pango, should not be modified or freed.
  *
  * Since: 1.4
  * Deprecated: 1.38
- **/
+ */
 const char *
 pango_font_map_get_shape_engine_type (PangoFontMap *fontmap)
 {
@@ -309,24 +309,25 @@ pango_font_map_get_shape_engine_type (PangoFontMap *fontmap)
 
 /**
  * pango_font_map_get_serial:
- * @fontmap: a #PangoFontMap
+ * @fontmap: a `PangoFontMap`
  *
- * Returns the current serial number of @fontmap.  The serial number is
- * initialized to an small number larger than zero when a new fontmap
- * is created and is increased whenever the fontmap is changed. It may
- * wrap, but will never have the value 0. Since it can wrap, never compare
- * it with "less than", always use "not equals".
+ * Returns the current serial number of @fontmap.
+ *
+ * The serial number is initialized to an small number larger than zero
+ * when a new fontmap is created and is increased whenever the fontmap
+ * is changed. It may wrap, but will never have the value 0. Since it can
+ * wrap, never compare it with "less than", always use "not equals".
  *
  * The fontmap can only be changed using backend-specific API, like changing
  * fontmap resolution.
  *
- * This can be used to automatically detect changes to a #PangoFontMap, like
- * in #PangoContext.
+ * This can be used to automatically detect changes to a `PangoFontMap`,
+ * like in `PangoContext`.
  *
  * Return value: The current serial number of @fontmap.
  *
  * Since: 1.32.4
- **/
+ */
 guint
 pango_font_map_get_serial (PangoFontMap *fontmap)
 {
@@ -347,23 +348,23 @@ pango_font_map_real_changed (PangoFontMap *fontmap)
   removed = priv->n_families;
   added = g_list_model_get_n_items (G_LIST_MODEL (fontmap));
 
-  g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added);  
+  g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added);
 }
 
 /**
  * pango_font_map_changed:
- * @fontmap: a #PangoFontMap
+ * @fontmap: a `PangoFontMap`
  *
- * Forces a change in the context, which will cause any #PangoContext
+ * Forces a change in the context, which will cause any `PangoContext`
  * using this fontmap to change.
  *
  * This function is only useful when implementing a new backend
  * for Pango, something applications won't do. Backends should
- * call this function if they have attached extra data to the context
- * and such data is changed.
+ * call this function if they have attached extra data to the
+ * context and such data is changed.
  *
  * Since: 1.34
- **/
+ */
 void
 pango_font_map_changed (PangoFontMap *fontmap)
 {
@@ -402,12 +403,12 @@ pango_font_map_real_get_family (PangoFontMap *fontmap,
 
 /**
  * pango_font_map_get_family:
- * @fontmap: a #PangoFontMap
+ * @fontmap: a `PangoFontMap`
  * @name: a family name
  *
  * Gets a font family by name.
  *
- * Returns: (transfer none): the #PangoFontFamily
+ * Returns: (transfer none): the `PangoFontFamily`
  *
  * Since: 1.46
  */
diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h
index f30780ee..64b04da3 100644
--- a/pango/pango-fontmap.h
+++ b/pango/pango-fontmap.h
@@ -57,17 +57,11 @@ typedef struct _PangoContext PangoContext;
 /**
  * PangoFontMap:
  *
- * The #PangoFontMap represents the set of fonts available for a
- * particular rendering system. This is a virtual object with
- * implementations being specific to particular rendering systems.  To
- * create an implementation of a #PangoFontMap, the rendering-system
- * specific code should allocate a larger structure that contains a nested
- * #PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a
- * pointer to a appropriate #PangoFontMapClass, then call
- * pango_font_map_init() on the structure.
+ * A `PangoFontMap` represents the set of fonts available for a
+ * particular rendering system.
  *
- * The #PangoFontMap structure contains one member which the implementation
- * fills in.
+ * This is a virtual object with implementations being specific to
+ * particular rendering systems.
  */
 struct _PangoFontMap
 {
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index 6a3ef4c6..6f3bdcbf 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -49,14 +49,14 @@ pango_fontset_class_init (PangoFontsetClass *class)
 
 /**
  * pango_fontset_get_font:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @wc: a Unicode character
  *
- * Returns the font in the fontset that contains the best glyph for the
- * Unicode character @wc.
+ * Returns the font in the fontset that contains the best glyph for a
+ * Unicode character.
  *
- * Return value: (transfer full): a #PangoFont. The caller must call
- *          g_object_unref when finished with the font.
+ * Return value: (transfer full): a `PangoFont`. The caller must call
+ *          g_object_unref() when finished with the font.
  **/
 PangoFont *
 pango_fontset_get_font (PangoFontset  *fontset,
@@ -87,12 +87,14 @@ pango_fontset_get_metrics (PangoFontset  *fontset)
 
 /**
  * pango_fontset_foreach:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @func: (closure data) (scope call): Callback function
  * @data: (closure): data to pass to the callback function
  *
  * Iterates through all the fonts in a fontset, calling @func for
- * each one. If @func returns %TRUE, that stops the iteration.
+ * each one.
+ *
+ * If @func returns %TRUE, that stops the iteration.
  *
  * Since: 1.4
  **/
@@ -232,11 +234,11 @@ struct _PangoFontsetSimpleClass
 
 /**
  * pango_fontset_simple_new:
- * @language: a #PangoLanguage tag
+ * @language: a `PangoLanguage` tag
  *
- * Creates a new #PangoFontsetSimple for the given language.
+ * Creates a new `PangoFontsetSimple` for the given language.
  *
- * Return value: the newly allocated #PangoFontsetSimple, which should
+ * Return value: the newly allocated `PangoFontsetSimple`, which should
  *               be freed with g_object_unref().
  **/
 PangoFontsetSimple *
@@ -301,8 +303,8 @@ pango_fontset_simple_finalize (GObject *object)
 
 /**
  * pango_fontset_simple_append:
- * @fontset: a #PangoFontsetSimple.
- * @font: a #PangoFont.
+ * @fontset: a `PangoFontsetSimple`.
+ * @font: a `PangoFont`.
  *
  * Adds a font to the fontset.
  **/
@@ -316,7 +318,7 @@ pango_fontset_simple_append (PangoFontsetSimple *fontset,
 
 /**
  * pango_fontset_simple_size:
- * @fontset: a #PangoFontsetSimple.
+ * @fontset: a `PangoFontsetSimple`.
  *
  * Returns the number of fonts in the fontset.
  *
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index ce7d4107..2b2018dd 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -54,12 +54,12 @@ typedef struct _PangoFontsetClass   PangoFontsetClass;
 
 /**
  * PangoFontsetForeachFunc:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @font: a font from @fontset
  * @user_data: callback data
  *
- * A callback function used by pango_fontset_foreach() when enumerating
- * the fonts in a fontset.
+ * Callback used by pango_fontset_foreach() when enumerating
+ * fonts in a fontset.
  *
  * Returns: if %TRUE, stop iteration and return immediately.
  *
@@ -72,12 +72,12 @@ typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset  *fontset,
 /**
  * PangoFontset:
  *
- * A #PangoFontset represents a set of #PangoFont to use
- * when rendering text. It is the result of resolving a
- * #PangoFontDescription against a particular #PangoContext.
- * It has operations for finding the component font for
- * a particular Unicode character, and for finding a composite
- * set of metrics for the entire fontset.
+ * A `PangoFontset` represents a set of `PangoFont` to use when rendering text.
+ *
+ * A `PAngoFontset` is the result of resolving a `PangoFontDescription`
+ * against a particular `PangoContext`. It has operations for finding the
+ * component font for a particular Unicode character, and for finding a
+ * composite set of metrics for the entire fontset.
  */
 struct _PangoFontset
 {
@@ -130,10 +130,11 @@ struct _PangoFontsetClass
 /**
  * PangoFontsetSimple:
  *
- * #PangoFontsetSimple is a implementation of the abstract
- * #PangoFontset base class in terms of an array of fonts,
- * which the creator provides when constructing the
- * #PangoFontsetSimple.
+ * `PangoFontsetSimple` is a implementation of the abstract
+ * `PangoFontset` base class as an array of fonts.
+ *
+ * When creating a `PangoFontsetSimple`, you have to provide
+ * the array of fonts that make up the fontset.
  */
 #define PANGO_TYPE_FONTSET_SIMPLE       (pango_fontset_simple_get_type ())
 #define PANGO_FONTSET_SIMPLE(object)    (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET_SIMPLE, PangoFontsetSimple))
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 326ae37f..8cca8627 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -30,13 +30,15 @@
 
 /**
  * pango_glyph_item_split:
- * @orig: a #PangoItem
+ * @orig: a `PangoItem`
  * @text: text to which positions in @orig apply
  * @split_index: byte index of position to split item, relative to the start of the item
  *
  * Modifies @orig to cover only the text after @split_index, and
  * returns a new item that covers the text before @split_index that
- * used to be in @orig. You can think of @split_index as the length of
+ * used to be in @orig.
+ *
+ * You can think of @split_index as the length of
  * the returned item. @split_index may not be 0, and it may not be
  * greater than or equal to the length of @orig (that is, there must
  * be at least one byte assigned to each item, you can't create a
@@ -132,11 +134,11 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 
 /**
  * pango_glyph_item_copy:
- * @orig: (nullable): a #PangoGlyphItem, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`, may be %NULL
  *
- * Make a deep copy of an existing #PangoGlyphItem structure.
+ * Make a deep copy of an existing `PangoGlyphItem` structure.
  *
- * Return value: (nullable): the newly allocated #PangoGlyphItem, which should
+ * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should
  *               be freed with pango_glyph_item_free(), or %NULL
  *               if @orig was %NULL.
  *
@@ -160,9 +162,9 @@ pango_glyph_item_copy  (PangoGlyphItem *orig)
 
 /**
  * pango_glyph_item_free:
- * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL
+ * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL
  *
- * Frees a #PangoGlyphItem and resources to which it points.
+ * Frees a `PangoGlyphItem` and resources to which it points.
  *
  * Since: 1.6
  **/
@@ -187,13 +189,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
 
 /**
  * pango_glyph_item_iter_copy:
- * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL
  *
- * Make a shallow copy of an existing #PangoGlyphItemIter structure.
+ * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
  *
- * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should
- *               be freed with pango_glyph_item_iter_free(), or %NULL
- *               if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItemIter`,
+ *   which should be freed with pango_glyph_item_iter_free(), or %NULL
+ *   if @orig was %NULL.
  *
  * Since: 1.22
  **/
@@ -214,9 +216,9 @@ pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
 
 /**
  * pango_glyph_item_iter_free:
- * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL
  *
- * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy().
+ * Frees a `PangoGlyphItem`Iter.
  *
  * Since: 1.22
  **/
@@ -235,13 +237,14 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter,
 
 /**
  * pango_glyph_item_iter_next_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  *
  * Advances the iterator to the next cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
  *
- * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the
- *  last cluster.
+ * See `PangoGlyphItemIter` for details of cluster orders.
+ *
+ * Return value: %TRUE if the iterator was advanced,
+ *   %FALSE if we were already on the  last cluster.
  *
  * Since: 1.22
  **/
@@ -325,13 +328,13 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
 
 /**
  * pango_glyph_item_iter_prev_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  *
  * Moves the iterator to the preceding cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
- * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the
- *  first cluster.
+ * Return value: %TRUE if the iterator was moved,
+ *   %FALSE if we were already on the first cluster.
  *
  * Since: 1.22
  **/
@@ -418,13 +421,14 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
 
 /**
  * pango_glyph_item_iter_init_start:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
  * first cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
  * Return value: %FALSE if there are no clusters in the glyph item
  *
@@ -456,13 +460,14 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
 
 /**
  * pango_glyph_item_iter_init_end:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
  * last cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
  * Return value: %FALSE if there are no clusters in the glyph item
  *
@@ -554,12 +559,14 @@ split_before_cluster_start (ApplyAttrsState *state)
  * pango_glyph_item_apply_attrs:
  * @glyph_item: a shaped item
  * @text: text that @list applies to
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
- * Splits a shaped item (PangoGlyphItem) into multiple items based
- * on an attribute list. The idea is that if you have attributes
+ * Splits a shaped item (`PangoGlyphItem`) into multiple items based
+ * on an attribute list.
+ *
+ * The idea is that if you have attributes
  * that don't affect shaping, such as color or underline, to avoid
- * affecting shaping, you filter them out (pango_attr_list_filter()),
+ * affecting shaping, you filter them out ([method@Pango.AttrList.filter]),
  * apply the shaping process and then reapply them to the result using
  * this function.
  *
@@ -567,7 +574,7 @@ split_before_cluster_start (ApplyAttrsState *state)
  * to that cluster; for instance, if half of a cluster is underlined
  * and the other-half strikethrough, then the cluster will end
  * up with both underline and strikethrough attributes. In these
- * cases, it may happen that item->extra_attrs for some of the
+ * cases, it may happen that @item->extra_attrs for some of the
  * result items can have multiple attributes of the same type.
  *
  * This function takes ownership of @glyph_item; it will be reused
@@ -575,7 +582,7 @@ split_before_cluster_start (ApplyAttrsState *state)
  *
  * Return value: (transfer full) (element-type Pango.GlyphItem): a
  *   list of glyph items resulting from splitting @glyph_item. Free
- *   the elements using pango_glyph_item_free(), the list using
+ *   the elements using [method@Pango.GlyphItem.free], the list using
  *   g_slist_free().
  *
  * Since: 1.2
@@ -711,7 +718,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
 
 /**
  * pango_glyph_item_letter_space:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
@@ -726,7 +733,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
  * give the effect of typographic letter spacing.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
 			       const char     *text,
@@ -784,7 +791,7 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
 
 /**
  * pango_glyph_item_get_logical_widths:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
@@ -793,12 +800,13 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
  *                  glyph_item->item->num_chars) to be filled in with
  *                  the resulting character widths.
  *
- * Given a #PangoGlyphItem and the corresponding
- * text, determine the screen width corresponding to each character. When
- * multiple characters compose a single cluster, the width of the entire
+ * Given a `PangoGlyphItem` and the corresponding text, determine the width
+ * corresponding to each character.
+ *
+ * When multiple characters compose a single cluster, the width of the entire
  * cluster is divided equally among the characters.
  *
- * See also pango_glyph_string_get_logical_widths().
+ * See also [method@Pango.GlyphString.get_logical_widths].
  *
  * Since: 1.26
  **/
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index daf2b15f..8a1dbff4 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -31,14 +31,15 @@ G_BEGIN_DECLS
 
 /**
  * PangoGlyphItem:
- * @item: corresponding #PangoItem.
- * @glyphs: corresponding #PangoGlyphString.
- *
- * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
- * resulting from shaping the text corresponding to an item.
- * As an example of the usage of #PangoGlyphItem, the results
- * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
- * each of which contains a list of #PangoGlyphItem.
+ * @item: corresponding `PangoItem`
+ * @glyphs: corresponding `PangoGlyphString`
+ *
+ * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
+ * resulting from shaping the items text.
+ *
+ * As an example of the usage of `PangoGlyphItem`, the results
+ * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
+ * each of which contains a list of `PangoGlyphItem`.
  */
 typedef struct _PangoGlyphItem PangoGlyphItem;
 
@@ -84,43 +85,46 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
 /**
  * PangoGlyphItemIter:
  *
- * A #PangoGlyphItemIter is an iterator over the clusters in a
- * #PangoGlyphItem.  The <firstterm>forward direction</firstterm> of the
- * iterator is the logical direction of text.  That is, with increasing
- * @start_index and @start_char values.  If @glyph_item is right-to-left
- * (that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
+ * A `PangoGlyphItemIter` is an iterator over the clusters in a
+ * `PangoGlyphItem`.
+ *
+ * The *forward direction* of the iterator is the logical direction of text.
+ * That is, with increasing @start_index and @start_char values. If @glyph_item
+ * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
  * then @start_glyph decreases as the iterator moves forward.  Moreover,
  * in right-to-left cases, @start_glyph is greater than @end_glyph.
  *
- * An iterator should be initialized using either of
- * pango_glyph_item_iter_init_start() and
+ * An iterator should be initialized using either
+ * pango_glyph_item_iter_init_start() or
  * pango_glyph_item_iter_init_end(), for forward and backward iteration
  * respectively, and walked over using any desired mixture of
  * pango_glyph_item_iter_next_cluster() and
- * pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
- * forward iteration over the clusters is:
- * <programlisting>
+ * pango_glyph_item_iter_prev_cluster().
+ *
+ * A common idiom for doing a forward iteration over the clusters is:
+ *
+ * ```
  * PangoGlyphItemIter cluster_iter;
  * gboolean have_cluster;
  *
- * for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
+ * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
  *                                                       glyph_item, text);
  *      have_cluster;
- *      have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
+ *      have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
  * {
  *   ...
  * }
- * </programlisting>
+ * ```
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by <literal>@glyph_item->item->offset</literal> to get to the
- * text of @glyph_item.  The @start_index and @end_index values can directly
- * index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
- * values however are zero-based for the @glyph_item.  For each cluster, the
- * item pointed at by the start variables is included in the cluster while
- * the one pointed at by end variables is not.
- *
- * None of the members of a #PangoGlyphItemIter should be modified manually.
+ * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
+ * The @start_index and @end_index values can directly index into @text. The
+ * @start_glyph, @end_glyph, @start_char, and @end_char values however are
+ * zero-based for the @glyph_item.  For each cluster, the item pointed at by
+ * the start variables is included in the cluster while the one pointed at by
+ * end variables is not.
+ *
+ * None of the members of a `PangoGlyphItemIter` should be modified manually.
  *
  * Since: 1.22
  */
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 628eac96..7c1bf7b5 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -36,8 +36,10 @@ typedef struct _PangoGlyphString PangoGlyphString;
 /**
  * PangoGlyphUnit:
  *
- * The #PangoGlyphUnit type is used to store dimensions within
- * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * The `PangoGlyphUnit` type is used to store dimensions within
+ * Pango.
+ *
+ * Dimensions are stored in 1/%PANGO_SCALE of a device unit.
  * (A device unit might be a pixel for screen display, or
  * a point on a printer.) %PANGO_SCALE is currently 1024, and
  * may change in the future (unlikely though), but you should not
@@ -54,7 +56,7 @@ typedef gint32 PangoGlyphUnit;
  * @x_offset: horizontal offset from nominal character position.
  * @y_offset: vertical offset from nominal character position.
  *
- * The #PangoGlyphGeometry structure contains width and positioning
+ * The `PangoGlyphGeometry` structure contains width and positioning
  * information for a single glyph.
  */
 struct _PangoGlyphGeometry
@@ -68,15 +70,17 @@ struct _PangoGlyphGeometry
  */
 /**
  * PangoGlyphVisAttr:
- * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
- * are stored in visual order, within the cluster, glyphs
- * are always ordered in logical order, since visual
- * order is meaningless; that is, in Arabic text, accent glyphs
- * follow the glyphs for the base character.)
+ * @is_cluster_start: set for the first logical glyph in each cluster.
+ *   (Clusters are stored in visual order, within the cluster, glyphs
+ *   are always ordered in logical order, since visual order is meaningless;
+ *   that is, in Arabic text, accent glyphs follow the glyphs for the
+ *   base character.)
+ *
+ * A `PangoGlyphVisAttr` structure communicates information between
+ * the shaping and rendering phases.
  *
- * The PangoGlyphVisAttr is used to communicate information between
- * the shaping phase and the rendering phase.  More attributes may be
- * added in the future.
+ * Currently, it contains only cluster start information. yMore attributes
+ * may be added in the future.
  */
 struct _PangoGlyphVisAttr
 {
@@ -91,9 +95,8 @@ struct _PangoGlyphVisAttr
  * @geometry: the positional information about the glyph.
  * @attr: the visual attributes of the glyph.
  *
- * The #PangoGlyphInfo structure represents a single glyph together with
+ * A `PangoGlyphInfo` structure represents a single glyph with
  * positioning information and visual attributes.
- * It contains the following fields.
  */
 struct _PangoGlyphInfo
 {
@@ -102,9 +105,6 @@ struct _PangoGlyphInfo
   PangoGlyphVisAttr  attr;
 };
 
-/* A string of glyphs with positional information and visual attributes -
- * ready for drawing
- */
 /**
  * PangoGlyphString:
  * @num_glyphs: number of the glyphs in this glyph string.
@@ -113,10 +113,11 @@ struct _PangoGlyphInfo
  * @log_clusters: logical cluster info, indexed by the byte index
  *                within the text corresponding to the glyph string.
  *
- * The #PangoGlyphString structure is used to store strings
- * of glyphs with geometry and visual attribute information.
- * The storage for the glyph information is owned
- * by the structure which simplifies memory management.
+ * A `PangoGlyphString` is used to store strings of glyphs with geometry
+ * and visual attribute information.
+ *
+ * The storage for the glyph information is owned by the structure
+ * which simplifies memory management.
  */
 struct _PangoGlyphString {
   gint num_glyphs;
@@ -211,7 +212,8 @@ void pango_shape_full (const char          *item_text,
  *     positioning of glyphs.
  *
  * Flags influencing the shaping process.
- * These can be passed to pango_shape_with_flags().
+ *
+ * `PangoShapeFlags` can be passed to pango_shape_with_flags().
  */
 typedef enum {
   PANGO_SHAPE_NONE            = 0,
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index 8565db16..a21749b6 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -19,64 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:vertical
- * @short_description:Laying text out in vertical directions
- * @title:Vertical Text
- * @see_also: pango_context_get_base_gravity(),
- * pango_context_set_base_gravity(),
- * pango_context_get_gravity(),
- * pango_context_get_gravity_hint(),
- * pango_context_set_gravity_hint(),
- * pango_font_description_set_gravity(),
- * pango_font_description_get_gravity(),
- * pango_attr_gravity_new(),
- * pango_attr_gravity_hint_new()
- *
- * Since 1.16, Pango is able to correctly lay vertical text out.  In fact, it can
- * set layouts of mixed vertical and non-vertical text.  This section describes
- * the types used for setting vertical text parameters.
- *
- * The way this is implemented is through the concept of
- * <firstterm>gravity</firstterm>.  Gravity of normal Latin text is south.  A
- * gravity value of east means that glyphs will be rotated ninety degrees
- * counterclockwise.  So, to render vertical text one needs to set the gravity
- * and rotate the layout using the matrix machinery already in place.  This has
- * the huge advantage that most algorithms working on a #PangoLayout do not need
- * any change as the assumption that lines run in the X direction and stack in
- * the Y direction holds even for vertical text layouts.
- *
- * Applications should only need to set base gravity on #PangoContext in use, and
- * let Pango decide the gravity assigned to each run of text.  This automatically
- * handles text with mixed scripts.  A very common use is to set the context base
- * gravity to auto using pango_context_set_base_gravity()
- * and rotate the layout normally.  Pango will make sure that
- * Asian languages take the right form, while other scripts are rotated normally.
- *
- * The correct way to set gravity on a layout is to set it on the context
- * associated with it using pango_context_set_base_gravity().  The context
- * of a layout can be accessed using pango_layout_get_context().  The currently
- * set base gravity of the context can be accessed using
- * pango_context_get_base_gravity() and the <firstterm>resolved</firstterm>
- * gravity of it using pango_context_get_gravity().  The resolved gravity is
- * the same as the base gravity for the most part, except that if the base
- * gravity is set to %PANGO_GRAVITY_AUTO, the resolved gravity will depend
- * on the current matrix set on context, and is derived using
- * pango_gravity_get_for_matrix().
- *
- * The next thing an application may want to set on the context is the
- * <firstterm>gravity hint</firstterm>.  A #PangoGravityHint instructs how
- * different scripts should react to the set base gravity.
- *
- * Font descriptions have a gravity property too, that can be set using
- * pango_font_description_set_gravity() and accessed using
- * pango_font_description_get_gravity().  However, those are rarely useful
- * from application code and are mainly used by #PangoLayout internally.
- *
- * Last but not least, one can create #PangoAttribute<!---->s for gravity
- * and gravity hint using pango_attr_gravity_new() and
- * pango_attr_gravity_hint_new().
- */
 #include "config.h"
 
 #include "pango-gravity.h"
@@ -85,13 +27,12 @@
 
 /**
  * pango_gravity_to_rotation:
- * @gravity: gravity to query
+ * @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO
  *
  * Converts a #PangoGravity value to its natural rotation in radians.
- * @gravity should not be %PANGO_GRAVITY_AUTO.
  *
- * Note that pango_matrix_rotate() takes angle in degrees, not radians.
- * So, to call pango_matrix_rotate() with the output of this function
+ * Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians.
+ * So, to call [method@Pango.Matrix,rotate] with the output of this function
  * you should multiply it by (180. / G_PI).
  *
  * Return value: the rotation value corresponding to @gravity.
@@ -120,10 +61,10 @@ pango_gravity_to_rotation (PangoGravity gravity)
 
 /**
  * pango_gravity_get_for_matrix:
- * @matrix: (nullable): a #PangoMatrix
+ * @matrix: (nullable): a `PangoMatrix`
  *
  * Finds the gravity that best matches the rotation component
- * in a #PangoMatrix.
+ * in a `PangoMatrix`.
  *
  * Return value: the gravity of @matrix, which will never be
  * %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL
@@ -295,8 +236,9 @@ get_script_properties (PangoScript script)
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
  *
- * Based on the script, base gravity, and hint, returns actual gravity
- * to use in laying out a single #PangoItem.
+ * Returns the gravity to use in laying out a `PangoItem`.
+ *
+ * The gravity is determined based on the script, base gravity, and hint.
  *
  * If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the
  * preferred gravity of @script.  To get the preferred gravity of a script,
@@ -328,14 +270,16 @@ pango_gravity_get_for_script (PangoScript      script,
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
  *
- * Based on the script, East Asian width, base gravity, and hint,
- * returns actual gravity to use in laying out a single character
- * or #PangoItem.
+ * Returns the gravity to use in laying out a single character
+ * or `PangoItem`.
+ *
+ * The gravity is determined based on the script, East Asian width,
+ * base gravity, and hint,
  *
- * This function is similar to pango_gravity_get_for_script() except
+ * This function is similar to [type_func@Pango.Gravity.get_for_script] except
  * that this function makes a distinction between narrow/half-width and
- * wide/full-width characters also.  Wide/full-width characters always
- * stand <emphasis>upright</emphasis>, that is, they always take the base gravity,
+ * wide/full-width characters also. Wide/full-width characters always
+ * stand *upright*, that is, they always take the base gravity,
  * whereas narrow/full-width characters are always rotated in vertical
  * context.
  *
diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h
index 63c29e5e..a3aa7f19 100644
--- a/pango/pango-gravity.h
+++ b/pango/pango-gravity.h
@@ -34,19 +34,22 @@ G_BEGIN_DECLS
  * @PANGO_GRAVITY_WEST: Glyphs are rotated 90 degrees counter-clockwise
  * @PANGO_GRAVITY_AUTO: Gravity is resolved from the context matrix
  *
- * The #PangoGravity type represents the orientation of glyphs in a segment
- * of text.  This is useful when rendering vertical text layouts.  In
- * those situations, the layout is rotated using a non-identity PangoMatrix,
- * and then glyph orientation is controlled using #PangoGravity.
+ * `PangoGravity` represents the orientation of glyphs in a segment
+ * of text.
+ *
+ * This is useful when rendering vertical text layouts. In those situations,
+ * the layout is rotated using a non-identity [struct@Pango.Matrix], and then
+ * glyph orientation is controlled using `PangoGravity`.
+ *
  * Not every value in this enumeration makes sense for every usage of
- * #PangoGravity; for example, %PANGO_GRAVITY_AUTO only can be passed to
- * pango_context_set_base_gravity() and can only be returned by
- * pango_context_get_base_gravity().
+ * `PangoGravity`; for example, %PANGO_GRAVITY_AUTO only can be passed to
+ * [method@Pango.Context.set_base_gravity] and can only be returned by
+ * [method@Pango.Context.get_base_gravity].
  *
- * See also: #PangoGravityHint
+ * See also: [enum@Pango.GravityHint]
  *
  * Since: 1.16
- **/
+ */
 typedef enum {
   PANGO_GRAVITY_SOUTH,
   PANGO_GRAVITY_EAST,
@@ -66,11 +69,12 @@ typedef enum {
  * respects the line progression.  This means, Latin and Arabic will take
  * opposite gravities and both flow top-to-bottom for example.
  *
- * The #PangoGravityHint defines how horizontal scripts should behave in a
- * vertical context.  That is, English excerpt in a vertical paragraph for
- * example.
+ * `PangoGravityHint` defines how horizontal scripts should behave in a
+ * vertical context.
+ *
+ * That is, English excerpts in a vertical paragraph for example.
  *
- * See #PangoGravity.
+ * See also [enum@Pango.Gravity]
  *
  * Since: 1.16
  **/
diff --git a/pango/pango-item.c b/pango/pango-item.c
index dae65645..d1caa771 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -27,11 +27,11 @@
 /**
  * pango_item_new:
  *
- * Creates a new #PangoItem structure initialized to default values.
+ * Creates a new `PangoItem` structure initialized to default values.
  *
- * Return value: the newly allocated #PangoItem, which should
- *               be freed with pango_item_free().
- **/
+ * Return value: the newly allocated `PangoItem`, which should
+ *   be freed with [method@Pango.Item.free].
+ */
 PangoItem *
 pango_item_new (void)
 {
@@ -42,14 +42,14 @@ pango_item_new (void)
 
 /**
  * pango_item_copy:
- * @item: (nullable): a #PangoItem, may be %NULL
+ * @item: (nullable): a `PangoItem`, may be %NULL
  *
- * Copy an existing #PangoItem structure.
+ * Copy an existing `PangoItem` structure.
  *
- * Return value: (nullable): the newly allocated #PangoItem, which
- *               should be freed with pango_item_free(), or %NULL if
- *               @item was %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoItem`, which
+ *   should be freed with [method@Pango.Item.free], or %NULL if
+ *   @item was %NULL.
+ */
 PangoItem *
 pango_item_copy (PangoItem *item)
 {
@@ -58,7 +58,7 @@ pango_item_copy (PangoItem *item)
 
   if (item == NULL)
     return NULL;
-  
+
   result = g_slice_new (PangoItem);
 
   result->offset = item->offset;
@@ -84,9 +84,9 @@ pango_item_copy (PangoItem *item)
 
 /**
  * pango_item_free:
- * @item: (nullable): a #PangoItem, may be %NULL
+ * @item: (nullable): a `PangoItem`, may be %NULL
  *
- * Free a #PangoItem and all associated memory.
+ * Free a `PangoItem` and all associated memory.
  **/
 void
 pango_item_free (PangoItem *item)
@@ -112,28 +112,31 @@ G_DEFINE_BOXED_TYPE (PangoItem, pango_item,
 
 /**
  * pango_item_split:
- * @orig: a #PangoItem
- * @split_index: byte index of position to split item, relative to the start of the item
+ * @orig: a `PangoItem`
+ * @split_index: byte index of position to split item, relative to the
+ *   start of the item
  * @split_offset: number of chars between start of @orig and @split_index
  *
  * Modifies @orig to cover only the text after @split_index, and
  * returns a new item that covers the text before @split_index that
- * used to be in @orig. You can think of @split_index as the length of
- * the returned item. @split_index may not be 0, and it may not be
- * greater than or equal to the length of @orig (that is, there must
- * be at least one byte assigned to each item, you can't create a
- * zero-length item). @split_offset is the length of the first item in
- * chars, and must be provided because the text used to generate the
- * item isn't available, so pango_item_split() can't count the char
- * length of the split items itself.
+ * used to be in @orig.
+ *
+ * You can think of @split_index as the length of the returned item.
+ * @split_index may not be 0, and it may not be greater than or equal
+ * to the length of @orig (that is, there must be at least one byte
+ * assigned to each item, you can't create a zero-length item).
+ * @split_offset is the length of the first item in chars, and must be
+ * provided because the text used to generate the item isn't available,
+ * so `pango_item_split()` can't count the char length of the split items
+ * itself.
  *
  * Return value: new item representing text before @split_index, which
- *               should be freed with pango_item_free().
- **/
+ *   should be freed with [method@Pango.Item.free].
+ */
 PangoItem*
-pango_item_split (PangoItem  *orig,
-		  int         split_index,
-		  int         split_offset)
+pango_item_split (PangoItem *orig,
+                  int        split_index,
+                  int        split_offset)
 {
   PangoItem *new_item;
 
@@ -169,14 +172,15 @@ compare_attr (gconstpointer p1, gconstpointer p2)
 
 /**
  * pango_item_apply_attrs:
- * @item: a #PangoItem
- * @iter: a #PangoAttrIterator
- *
- * Add attributes to a PangoItem. The idea is that you have
- * attributes that don't affect itemization, such as font features,
- * so you filter them out using pango_attr_list_filter(), itemize
- * your text, then reapply the attributes to the resulting items
- * using this function.
+ * @item: a `PangoItem`
+ * @iter: a `PangoAttrIterator`
+ *
+ * Add attributes to a `PangoItem`.
+ *
+ * The idea is that you have attributes that don't affect itemization,
+ * such as font features, so you filter them out using
+ * [method@Pango.AttrList.filter], itemize your text, then reapply the
+ * attributes to the resulting items using this function.
  *
  * The @iter should be positioned before the range of the item,
  * and will be advanced past it. This function is meant to be called
diff --git a/pango/pango-item.h b/pango/pango-item.h
index d4162f90..a1e95086 100644
--- a/pango/pango-item.h
+++ b/pango/pango-item.h
@@ -34,7 +34,8 @@ typedef struct _PangoItem PangoItem;
  * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE:
  *
  * Whether the segment should be shifted to center around the baseline.
- * Used in vertical writing directions mostly.
+ *
+ * This is mainly used in vertical writing directions.
  *
  * Since: 1.16
  */
@@ -43,8 +44,7 @@ typedef struct _PangoItem PangoItem;
 /**
  * PANGO_ANALYSIS_FLAG_IS_ELLIPSIS:
  *
- * This flag is used to mark runs that hold ellipsized text,
- * in an ellipsized layout.
+ * Whether this run holds ellipsized text.
  *
  * Since: 1.36.7
  */
@@ -53,8 +53,7 @@ typedef struct _PangoItem PangoItem;
 /**
  * PANGO_ANALYSIS_FLAG_NEED_HYPHEN:
  *
- * This flag tells Pango to add a hyphen at the end of the
- * run during shaping.
+ * Whether to add a hyphen at the end of the run during shaping.
  *
  * Since: 1.44
  */
@@ -66,19 +65,24 @@ typedef struct _PangoItem PangoItem;
  * @lang_engine: unused
  * @font: the font for this segment.
  * @level: the bidirectional level for this segment.
- * @gravity: the glyph orientation for this segment (A #PangoGravity).
+ * @gravity: the glyph orientation for this segment (A `PangoGravity`).
  * @flags: boolean flags for this segment (Since: 1.16).
- * @script: the detected script for this segment (A #PangoScript) (Since: 1.18).
+ * @script: the detected script for this segment (A `PangoScript`) (Since: 1.18).
  * @language: the detected language for this segment.
  * @extra_attrs: extra attributes for this segment.
  *
- * The #PangoAnalysis structure stores information about
+ * The `PangoAnalysis` structure stores information about
  * the properties of a segment of text.
  */
 struct _PangoAnalysis
 {
+#ifndef __GI_SCANNER__
   PangoEngineShape *shape_engine;
   PangoEngineLang  *lang_engine;
+#else
+  gpointer shape_engine;
+  gpointer lang_engine;
+#endif
   PangoFont *font;
 
   guint8 level;
@@ -98,7 +102,10 @@ struct _PangoAnalysis
  * @num_chars: number of Unicode characters in the item.
  * @analysis: analysis results for the item.
  *
- * The #PangoItem structure stores information about a segment of text.
+ * The `PangoItem` structure stores information about a segment of text.
+ *
+ * You typically obtain `PangoItems` by itemizing a piece of text
+ * with [func@itemize].
  */
 struct _PangoItem
 {
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 04c3e0ca..2f79acec 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -136,10 +136,10 @@ pango_language_free (PangoLanguage *language G_GNUC_UNUSED)
 /**
  * PangoLanguage:
  *
- * The #PangoLanguage structure is used to
+ * The `PangoLanguage` structure is used to
  * represent a language.
  *
- * #PangoLanguage pointers can be efficiently
+ * `PangoLanguage` pointers can be efficiently
  * copied and compared with each other.
  */
 G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
@@ -151,13 +151,12 @@ G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
  *
  * Return the Unix-style locale string for the language currently in
  * effect. On Unix systems, this is the return value from
- * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can
- * affect this through the environment variables LC_ALL, LC_CTYPE or
- * LANG (checked in that order). The locale strings typically is in
- * the form lang_COUNTRY, where lang is an ISO-639 language code, and
- * COUNTRY is an ISO-3166 country code. For instance, sv_FI for
- * Swedish as written in Finland or pt_BR for Portuguese as written in
- * Brazil.
+ * `setlocale (LC_CTYPE, NULL)`, and the user can affect this through
+ * the environment variables LC_ALL, LC_CTYPE or LANG (checked
+ * in that order). The locale strings typically is in the form lang_COUNTRY,
+ * where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country
+ * code. For instance, sv_FI for Swedish as written in Finland or pt_BR for
+ * Portuguese as written in Brazil.
  *
  * On Windows, the C library doesn't use any such environment
  * variables, and setting them won't affect the behavior of functions
@@ -252,11 +251,10 @@ _pango_get_lc_ctype (void)
 /**
  * pango_language_get_default:
  *
- * Returns the #PangoLanguage for the current locale of the process.
- * Note that this can change over the life of an application.
+ * Returns the `PangoLanguage` for the current locale of the process.
  *
  * On Unix systems, this is the return value is derived from
- * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can
+ * `setlocale (LC_CTYPE, NULL)`, and the user can
  * affect this through the environment variables LC_ALL, LC_CTYPE or
  * LANG (checked in that order). The locale string typically is in
  * the form lang_COUNTRY, where lang is an ISO-639 language code, and
@@ -274,13 +272,15 @@ _pango_get_lc_ctype (void)
  * variables, and does return a Unix-style locale string based on
  * either said environment variables or the thread's current locale.
  *
- * Your application should call <literal>setlocale(LC_ALL, "");</literal>
- * for the user settings to take effect.  Gtk+ does this in its initialization
+ * Your application should call `setlocale(LC_ALL, "")` for the user
+ * settings to take effect. GTK does this in its initialization
  * functions automatically (by calling gtk_set_locale()).
- * See <literal>man setlocale</literal> for more details.
+ * See the setlocale() manpage for more details.
+ *
+ * Note that the default language can change over the life of an application.
  *
  * Return value: (transfer none): the default language as a
- *               #PangoLanguage, must not be freed.
+ *               `PangoLanguage`, must not be freed.
  *
  * Since: 1.16
  **/
@@ -308,23 +308,23 @@ pango_language_get_default (void)
  * pango_language_from_string:
  * @language: (allow-none): a string representing a language tag, or %NULL
  *
- * Take a RFC-3066 format language tag as a string and convert it to a
- * #PangoLanguage pointer that can be efficiently copied (copy the
- * pointer) and compared with other language tags (compare the
- * pointer.)
+ * Convert a language tag to a `PangoLanguage`.
+ *
+ * The language tag must be in a RFC-3066 format. `PangoLanguage` pointers
+ * can be efficiently copied (copy the pointer) and compared with other
+ * language tags (compare the pointer.)
  *
  * This function first canonicalizes the string by converting it to
  * lowercase, mapping '_' to '-', and stripping all characters other
  * than letters and '-'.
  *
- * Use pango_language_get_default() if you want to get the #PangoLanguage for
- * the current locale of the process.
+ * Use [type_func@Pango.Language.get_default] if you want to get the `PangoLanguage`
+ * for the current locale of the process.
  *
  * Return value: (transfer none) (nullable): an opaque pointer to a
- *               #PangoLanguage structure, or %NULL if @language was
- *               %NULL.  The returned pointer will be valid forever
- *               after, and should not be freed.
- **/
+ *   `PangoLanguage` structure, or %NULL if @language was %NULL. The
+ *   returned pointer will be valid forever after, and should not be freed.
+ */
 PangoLanguage *
 pango_language_from_string (const char *language)
 {
@@ -374,10 +374,10 @@ out:
  * pango_language_to_string:
  * @language: a language tag.
  *
- * Gets the RFC-3066 format string representing the given language tag. 
+ * Gets the RFC-3066 format string representing the given language tag.
  *
- * Returns: a string representing the language tag.  This is owned by
- *          Pango and should not be freed.
+ * Returns: a string representing the language tag. This is owned by
+ *   Pango and should not be freed.
  */
 const char *
 (pango_language_to_string) (PangoLanguage *language)
@@ -387,21 +387,23 @@ const char *
 
 /**
  * pango_language_matches:
- * @language: (nullable): a language tag (see pango_language_from_string()),
- *            %NULL is allowed and matches nothing but '*'
+ * @language: (nullable): a language tag (see [type_func@Pango.Language.from_string]),
+ *   %NULL is allowed and matches nothing but '*'
  * @range_list: a list of language ranges, separated by ';', ':',
  *   ',', or space characters.
  *   Each element must either be '*', or a RFC 3066 language range
- *   canonicalized as by pango_language_from_string()
+ *   canonicalized as by [type_func@Pango.Language.from_string]
  *
  * Checks if a language tag matches one of the elements in a list of
- * language ranges. A language tag is considered to match a range
+ * language ranges.
+ *
+ * A language tag is considered to match a range
  * in the list if the range is '*', the range is exactly the tag,
  * or the range is a prefix of the tag, and the character after it
  * in the tag is '-'.
  *
  * Return value: %TRUE if a match was found.
- **/
+ */
 gboolean
 pango_language_matches (PangoLanguage *language,
 			const char    *range_list)
@@ -561,30 +563,31 @@ static const LangInfo lang_texts[] = {
 
 /**
  * pango_language_get_sample_string:
- * @language: (nullable): a #PangoLanguage, or %NULL
+ * @language: (nullable): a `PangoLanguage`, or %NULL
  *
  * Get a string that is representative of the characters needed to
  * render a particular language.
  *
- * The sample text may be a pangram, but is not necessarily.  It is chosen to
- * be demonstrative of normal text in the language, as well as exposing font
- * feature requirements unique to the language.  It is suitable for use
+ * The sample text may be a pangram, but is not necessarily. It is chosen
+ * to be demonstrative of normal text in the language, as well as exposing
+ * font feature requirements unique to the language. It is suitable for use
  * as sample text in a font selection dialog.
  *
  * If @language is %NULL, the default language as found by
- * pango_language_get_default() is used.
+ * [type_func@Pango.Language.get_default] is used.
  *
  * If Pango does not have a sample string for @language, the classic
  * "The quick brown fox..." is returned.  This can be detected by
  * comparing the returned pointer value to that returned for (non-existent)
  * language code "xx".  That is, compare to:
- * <informalexample><programlisting>
+ *
+ * ```
  * pango_language_get_sample_string (pango_language_from_string ("xx"))
- * </programlisting></informalexample>
+ * ```
  *
  * Return value: the sample string. This value is owned by Pango
  *   and should not be freed.
- **/
+ */
 const char *
 pango_language_get_sample_string (PangoLanguage *language)
 {
@@ -615,11 +618,12 @@ pango_language_get_sample_string (PangoLanguage *language)
 
 /**
  * pango_language_get_scripts:
- * @language: (allow-none): a #PangoLanguage, or %NULL
- * @num_scripts: (out caller-allocates) (allow-none): location to return number of scripts,
- *            or %NULL
+ * @language: (allow-none): a `PangoLanguage`, or %NULL
+ * @num_scripts: (out caller-allocates) (allow-none): location to
+ *   return number of scripts, or %NULL
  *
  * Determines the scripts used to to write @language.
+ *
  * If nothing is known about the language tag @language,
  * or if @language is %NULL, then %NULL is returned.
  * The list of scripts returned starts with the script that the
@@ -630,27 +634,27 @@ pango_language_get_sample_string (PangoLanguage *language)
  *
  * Most languages use only one script for writing, but there are
  * some that use two (Latin and Cyrillic for example), and a few
- * use three (Japanese for example).  Applications should not make
+ * use three (Japanese for example). Applications should not make
  * any assumptions on the maximum number of scripts returned
  * though, except that it is positive if the return value is not
  * %NULL, and it is a small number.
  *
- * The pango_language_includes_script() function uses this function
+ * The [method@Pango.Language.includes_script] function uses this function
  * internally.
  *
- * Note: while the return value is declared as PangoScript, the
- * returned values are from the GUnicodeScript enumeration, which
+ * Note: while the return value is declared as `PangoScript`, the
+ * returned values are from the `GUnicodeScript` enumeration, which
  * may have more values. Callers need to handle unknown values.
  *
  * Return value: (array length=num_scripts) (nullable): An array of
- * #PangoScript values, with the number of entries in the array stored
- * in @num_scripts, or %NULL if Pango does not have any information
- * about this particular language tag (also the case if @language is
- * %NULL).  The returned array is owned by Pango and should not be
- * modified or freed.
- 
+ *   `PangoScript` values, with the number of entries in the array
+ *   stored in @num_scripts, or %NULL if Pango does not have any
+ *   information about this particular language tag (also the case
+ *   if @language is %NULL). The returned array is owned by Pango
+ *   and should not be modified or freed.
+ *
  * Since: 1.22
- **/
+ */
 const PangoScript *
 pango_language_get_scripts (PangoLanguage *language,
 			    int           *num_scripts)
@@ -686,8 +690,8 @@ pango_language_get_scripts (PangoLanguage *language,
 
 /**
  * pango_language_includes_script:
- * @language: (nullable): a #PangoLanguage, or %NULL
- * @script: a #PangoScript
+ * @language: (nullable): a `PangoLanguage`, or %NULL
+ * @script: a `PangoScript`
  *
  * Determines if @script is one of the scripts used to
  * write @language. The returned value is conservative;
@@ -697,18 +701,17 @@ pango_language_get_scripts (PangoLanguage *language,
  *
  * This routine is used in Pango's itemization process when
  * determining if a supplied language tag is relevant to
- * a particular section of text. It probably is not useful for
- * applications in most circumstances.
+ * a particular section of text. It probably is not useful
+ * for applications in most circumstances.
  *
- * This function uses pango_language_get_scripts() internally.
+ * This function uses [method@Pango.Language.get_scripts] internally.
  *
  * Return value: %TRUE if @script is one of the scripts used
- * to write @language or if nothing is known about @language
- * (including the case that @language is %NULL),
- * %FALSE otherwise.
- 
+ *   to write @language or if nothing is known about @language
+ *   (including the case that @language is %NULL), %FALSE otherwise.
+ *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_language_includes_script (PangoLanguage *language,
 				PangoScript    script)
@@ -838,18 +841,19 @@ out:
 /**
  * pango_language_get_preferred:
  *
- * Returns the list of languages that the user prefers, as specified
- * by the PANGO_LANGUAGE or LANGUAGE environment variables, in order
- * of preference. Note that this list does not necessarily include
- * the language returned by pango_language_get_default().
+ * Returns the list of languages that the user prefers.
+ *
+ * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment
+ * variables, in order of preference. Note that this list does not necessarily
+ * include the language returned by [type_func@Pango.Language.get_default].
  *
  * When choosing language-specific resources, such as the sample
- * text returned by pango_language_get_sample_string(), you should
+ * text returned by [method@Pango.Language.get_sample_string], you should
  * first try the default language, followed by the languages returned
  * by this function.
  *
  * Returns: (transfer none) (nullable): a %NULL-terminated array of
- *    PangoLanguage*
+ *   `PangoLanguage`*
  *
  * Since: 1.48
  */
@@ -864,44 +868,42 @@ pango_language_get_preferred (void)
 
 /**
  * pango_script_get_sample_language:
- * @script: a #PangoScript
+ * @script: a `PangoScript`
  *
- * Given a script, finds a language tag that is reasonably
- * representative of that script. This will usually be the
- * most widely spoken or used language written in that script:
- * for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
- * is <literal>ru</literal> (Russian), the sample language
- * for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>.
+ * Finds a language tag that is reasonably representative of @script.
  *
- * For some
- * scripts, no sample language will be returned because there
- * is no language that is sufficiently representative. The best
- * example of this is %PANGO_SCRIPT_HAN, where various different
+ * The language will usually be the most widely spoken or used language written
+ * in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
+ * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar.
+ *
+ * For some scripts, no sample language will be returned because
+ * there is no language that is sufficiently representative. The
+ * best example of this is %PANGO_SCRIPT_HAN, where various different
  * variants of written Chinese, Japanese, and Korean all use
  * significantly different sets of Han characters and forms
  * of shared characters. No sample language can be provided
  * for many historical scripts as well.
  *
  * As of 1.18, this function checks the environment variables
- * PANGO_LANGUAGE and LANGUAGE (checked in that order) first.
+ * `PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first.
  * If one of them is set, it is parsed as a list of language tags
- * separated by colons or other separators.  This function
+ * separated by colons or other separators. This function
  * will return the first language in the parsed list that Pango
- * believes may use @script for writing.  This last predicate
- * is tested using pango_language_includes_script().  This can
+ * believes may use @script for writing. This last predicate
+ * is tested using [method@Pango.Language.includes_script]. This can
  * be used to control Pango's font selection for non-primary
- * languages.  For example, a PANGO_LANGUAGE enviroment variable
- * set to "en:fa" makes Pango choose fonts suitable for Persian (fa) 
+ * languages. For example, a `PANGO_LANGUAGE` enviroment variable
+ * set to "en:fa" makes Pango choose fonts suitable for Persian (fa)
  * instead of Arabic (ar) when a segment of Arabic text is found
- * in an otherwise non-Arabic text.  The same trick can be used to
+ * in an otherwise non-Arabic text. The same trick can be used to
  * choose a default language for %PANGO_SCRIPT_HAN when setting
  * context language is not feasible.
  *
- * Return value: (nullable): a #PangoLanguage that is representative
+ * Return value: (nullable): a `PangoLanguage` that is representative
  * of the script, or %NULL if no such language exists.
  *
  * Since: 1.4
- **/
+ */
 PangoLanguage *
 pango_script_get_sample_language (PangoScript script)
 {
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 88e142af..5298647e 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -20,56 +20,48 @@
  */
 
 /**
- * SECTION:layout
- * @short_description:High-level layout driver objects
- * @title:Layout Objects
+ * PangoLayout:
+ *
+ * A `PangoLayout` structure represents an entire paragraph of text.
  *
  * While complete access to the layout capabilities of Pango is provided
  * using the detailed interfaces for itemization and shaping, using
  * that functionality directly involves writing a fairly large amount
- * of code. The objects and functions in this section provide a
- * high-level driver for formatting entire paragraphs of text
- * at once. This includes paragraph-level functionality such as
- * line-breaking, justification, alignment and ellipsization.
- */
-
-/**
- * PangoLayout:
- *
- * The #PangoLayout structure represents an entire paragraph
- * of text. It is initialized with a #PangoContext, UTF-8 string
- * and set of attributes for that string. Once that is done, the
- * set of formatted lines can be extracted from the object,
- * the layout can be rendered, and conversion between logical
- * character positions within the layout's text, and the physical
- * position of the resulting glyphs can be made.
- *
- * There are also a number of parameters to adjust the formatting
- * of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>.
- * It is possible, as well, to ignore the 2-D setup, and simply
- * treat the results of a #PangoLayout as a list of lines.
- *
- * <figure id="parameters">
- * <title>Adjustable parameters (on the left) and font metrics (on the right) for a PangoLayout</title>
- * <graphic fileref="layout.png" format="PNG"></graphic>
- * </figure>
- *
- * The #PangoLayout structure is opaque, and has no user-visible
- * fields.
+ * of code. `PangoLayout` provides a high-level driver for formatting
+ * entire paragraphs of text at once. This includes paragraph-level
+ * functionality such as line breaking, justification, alignment and
+ * ellipsization.
+ *
+ * A `PangoLayout is initialized with a `PangoContext`, UTF-8 string
+ * and set of attributes for that string. Once that is done, the set of
+ * formatted lines can be extracted from the object, the layout can be
+ * rendered, and conversion between logical character positions within
+ * the layout's text, and the physical position of the resulting glyphs
+ * can be made.
+ *
+ * There are a number of parameters to adjust the formatting of a
+ * `PangoLayout`. The following image shows adjustable parameters
+ * (on the left) and font metrics (on the right):
+ *
+ * ![Pango Layout Parameters](layout.png)
+ *
+ * It is possible, as well, to ignore the 2-D setup,
+ * and simply treat the results of a `PangoLayout` as a list of lines.
  */
 
 /**
  * PangoLayoutIter:
  *
- * A #PangoLayoutIter structure can be used to
- * iterate over the visual extents of a #PangoLayout.
+ * A `PangoLayoutIter` can be used to iterate over the visual
+ * extents of a `PangoLayout`.
+ *
+ * To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter].
  *
- * The #PangoLayoutIter structure is opaque, and
- * has no user-visible fields.
+ * The `PangoLayoutIter` structure is opaque, and has no user-visible fields.
  */
 
 #include "config.h"
-#include "pango-glyph.h"		/* For pango_shape() */
+#include "pango-glyph.h"                /* For pango_shape() */
 #include "pango-break.h"
 #include "pango-item.h"
 #include "pango-engine.h"
@@ -145,7 +137,7 @@ struct _PangoLayoutClass
 #define ITER_IS_INVALID(iter) G_UNLIKELY (check_invalid ((iter), G_STRLOC))
 static gboolean
 check_invalid (PangoLayoutIter *iter,
-	       const char      *loc)
+               const char      *loc)
 {
   if (iter->line->layout == NULL)
     {
@@ -169,24 +161,24 @@ static PangoAttrList *pango_layout_get_effective_attributes (PangoLayout *layout
 
 static PangoLayoutLine * pango_layout_line_new         (PangoLayout     *layout);
 static void              pango_layout_line_postprocess (PangoLayoutLine *line,
-							ParaBreakState  *state,
-							gboolean         wrapped);
+                                                        ParaBreakState  *state,
+                                                        gboolean         wrapped);
 
 static int *pango_layout_line_get_log2vis_map (PangoLayoutLine  *line,
-					       gboolean          strong);
+                                               gboolean          strong);
 static int *pango_layout_line_get_vis2log_map (PangoLayoutLine  *line,
-					       gboolean          strong);
+                                               gboolean          strong);
 static void pango_layout_line_leaked (PangoLayoutLine *line);
 
 /* doesn't leak line */
 static PangoLayoutLine* _pango_layout_iter_get_line (PangoLayoutIter *iter);
 
 static void pango_layout_get_item_properties (PangoItem      *item,
-					      ItemProperties *properties);
+                                              ItemProperties *properties);
 
 static void pango_layout_get_empty_extents_at_index (PangoLayout    *layout,
-						     int             index,
-						     PangoRectangle *logical_rect);
+                                                     int             index,
+                                                     PangoRectangle *logical_rect);
 
 static void pango_layout_finalize    (GObject          *object);
 
@@ -257,18 +249,16 @@ pango_layout_finalize (GObject *object)
   G_OBJECT_CLASS (pango_layout_parent_class)->finalize (object);
 }
 
-
 /**
  * pango_layout_new:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
  *
- * Create a new #PangoLayout object with attributes initialized to
- * default values for a particular #PangoContext.
+ * Create a new `PangoLayout` object with attributes initialized to
+ * default values for a particular `PangoContext`.
  *
- * Return value: the newly allocated #PangoLayout, with a reference
- *               count of one, which should be freed with
- *               g_object_unref().
- **/
+ * Return value: the newly allocated `PangoLayout`, with a reference
+ *   count of one, which should be freed with g_object_unref().
+ */
 PangoLayout *
 pango_layout_new (PangoContext *context)
 {
@@ -287,16 +277,17 @@ pango_layout_new (PangoContext *context)
 
 /**
  * pango_layout_copy:
- * @src: a #PangoLayout
+ * @src: a `PangoLayout`
  *
- * Does a deep copy-by-value of the @src layout. The attribute list,
- * tab array, and text from the original layout are all copied by
- * value.
+ * Creates a deep copy-by-value of the layout.
  *
- * Return value: (transfer full): the newly allocated #PangoLayout,
- *               with a reference count of one, which should be freed
- *               with g_object_unref().
- **/
+ * The attribute list, tab array, and text from the original layout
+ * are all copied by value.
+ *
+ * Return value: (transfer full): the newly allocated `PangoLayout`,
+ *   with a reference count of one, which should be freed
+ *   with g_object_unref().
+ */
 PangoLayout*
 pango_layout_copy (PangoLayout *src)
 {
@@ -319,21 +310,21 @@ pango_layout_copy (PangoLayout *src)
 
   /* Value fields */
   memcpy (&layout->copy_begin, &src->copy_begin,
-	  G_STRUCT_OFFSET (PangoLayout, copy_end) - G_STRUCT_OFFSET (PangoLayout, copy_begin));
+          G_STRUCT_OFFSET (PangoLayout, copy_end) - G_STRUCT_OFFSET (PangoLayout, copy_begin));
 
   return layout;
 }
 
 /**
  * pango_layout_get_context:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Retrieves the #PangoContext used for this layout.
+ * Retrieves the `PangoContext` used for this layout.
  *
- * Return value: (transfer none): the #PangoContext for the layout.
- * This does not have an additional refcount added, so if you want to
- * keep a copy of this around, you must reference it yourself.
- **/
+ * Return value: (transfer none): the `PangoContext` for the layout.
+ *   This does not have an additional refcount added, so if you want to
+ *   keep a copy of this around, you must reference it yourself.
+ */
 PangoContext *
 pango_layout_get_context (PangoLayout *layout)
 {
@@ -344,16 +335,18 @@ pango_layout_get_context (PangoLayout *layout)
 
 /**
  * pango_layout_set_width:
- * @layout: a #PangoLayout.
+ * @layout: a `PangoLayout`.
  * @width: the desired width in Pango units, or -1 to indicate that no
- *         wrapping or ellipsization should be performed.
+ *   wrapping or ellipsization should be performed.
  *
- * Sets the width to which the lines of the #PangoLayout should wrap or
- * ellipsized.  The default value is -1: no width set.
- **/
+ * Sets the width to which the lines of the `PangoLayout` should wrap or
+ * ellipsized.
+ *
+ * The default value is -1: no width set.
+ */
 void
 pango_layout_set_width (PangoLayout *layout,
-			int          width)
+                        int          width)
 {
   g_return_if_fail (layout != NULL);
 
@@ -374,12 +367,12 @@ pango_layout_set_width (PangoLayout *layout,
 
 /**
  * pango_layout_get_width:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Gets the width to which the lines of the #PangoLayout should wrap.
+ * Gets the width to which the lines of the `PangoLayout` should wrap.
  *
  * Return value: the width in Pango units, or -1 if no width set.
- **/
+ */
 int
 pango_layout_get_width (PangoLayout    *layout)
 {
@@ -389,28 +382,29 @@ pango_layout_get_width (PangoLayout    *layout)
 
 /**
  * pango_layout_set_height:
- * @layout: a #PangoLayout.
+ * @layout: a `PangoLayout`.
  * @height: the desired height of the layout in Pango units if positive,
- *          or desired number of lines if negative.
+ *   or desired number of lines if negative.
+ *
+ * Sets the height to which the `PangoLayout` should be ellipsized at.
  *
- * Sets the height to which the #PangoLayout should be ellipsized at.  There
- * are two different behaviors, based on whether @height is positive or
- * negative.
+ * There are two different behaviors, based on whether @height is positive
+ * or negative.
  *
- * If @height is positive, it will be the maximum height of the layout.  Only
+ * If @height is positive, it will be the maximum height of the layout. Only
  * lines would be shown that would fit, and if there is any text omitted,
- * an ellipsis added.  At least one line is included in each paragraph regardless
- * of how small the height value is.  A value of zero will render exactly one
+ * an ellipsis added. At least one line is included in each paragraph regardless
+ * of how small the height value is. A value of zero will render exactly one
  * line for the entire layout.
  *
- * If @height is negative, it will be the (negative of) maximum number of lines per
- * paragraph.  That is, the total number of lines shown may well be more than
+ * If @height is negative, it will be the (negative of) maximum number of lines
+ * per paragraph. That is, the total number of lines shown may well be more than
  * this value if the layout contains multiple paragraphs of text.
  * The default value of -1 means that first line of each paragraph is ellipsized.
  * This behavior may be changed in the future to act per layout instead of per
- * paragraph.  File a bug against pango at <ulink
- * url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> if your
- * code relies on this behavior.
+ * paragraph. File a bug against pango at
+ * [https://gitlab.gnome.org/gnome/pango](https://gitlab.gnome.org/gnome/pango)
+ * if your code relies on this behavior.
  *
  * Height setting only has effect if a positive width is set on
  * @layout and ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE.
@@ -419,10 +413,10 @@ pango_layout_get_width (PangoLayout    *layout)
  * future.
  *
  * Since: 1.20
- **/
+ */
 void
 pango_layout_set_height (PangoLayout *layout,
-			 int          height)
+                         int          height)
 {
   g_return_if_fail (layout != NULL);
 
@@ -435,26 +429,27 @@ pango_layout_set_height (PangoLayout *layout,
        * Bug 549003
        */
       if (layout->ellipsize != PANGO_ELLIPSIZE_NONE &&
-	  !(layout->lines && layout->is_ellipsized == FALSE &&
-	    height < 0 && layout->line_count <= (guint) -height))
-	layout_changed (layout);
+          !(layout->lines && layout->is_ellipsized == FALSE &&
+            height < 0 && layout->line_count <= (guint) -height))
+        layout_changed (layout);
     }
 }
 
 /**
  * pango_layout_get_height:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Gets the height of layout used for ellipsization.  See
- * pango_layout_set_height() for details.
+ * Gets the height of layout used for ellipsization.
  *
- * Return value: the height, in Pango units if positive, or
- * number of lines if negative.
+ * See [method@Pango.Layout.set_height] for details.
+ *
+ * Return value: the height, in Pango units if positive,
+ *   or number of lines if negative.
  *
  * Since: 1.20
- **/
+ */
 int
-pango_layout_get_height (PangoLayout    *layout)
+pango_layout_get_height (PangoLayout *layout)
 {
   g_return_val_if_fail (layout != NULL, 0);
   return layout->height;
@@ -462,16 +457,18 @@ pango_layout_get_height (PangoLayout    *layout)
 
 /**
  * pango_layout_set_wrap:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @wrap: the wrap mode
  *
- * Sets the wrap mode; the wrap mode only has effect if a width
- * is set on the layout with pango_layout_set_width().
- * To turn off wrapping, set the width to -1.
- **/
+ * Sets the wrap mode.
+ *
+ * The wrap mode only has effect if a width is set on the layout
+ * with [method@Pango.Layout.set_width]. To turn off wrapping,
+ * set the width to -1.
+ */
 void
-pango_layout_set_wrap (PangoLayout  *layout,
-		       PangoWrapMode wrap)
+pango_layout_set_wrap (PangoLayout   *layout,
+                       PangoWrapMode  wrap)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -480,21 +477,21 @@ pango_layout_set_wrap (PangoLayout  *layout,
       layout->wrap = wrap;
 
       if (layout->width != -1)
-	layout_changed (layout);
+        layout_changed (layout);
     }
 }
 
 /**
  * pango_layout_get_wrap:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the wrap mode for the layout.
  *
- * Use pango_layout_is_wrapped() to query whether any paragraphs
- * were actually wrapped.
+ * Use [method@Pango.Layout.is_wrapped] to query whether
+ * any paragraphs were actually wrapped.
  *
  * Return value: active wrap mode.
- **/
+ */
 PangoWrapMode
 pango_layout_get_wrap (PangoLayout *layout)
 {
@@ -505,7 +502,7 @@ pango_layout_get_wrap (PangoLayout *layout)
 
 /**
  * pango_layout_is_wrapped:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Queries whether the layout had to wrap any paragraphs.
  *
@@ -515,7 +512,7 @@ pango_layout_get_wrap (PangoLayout *layout)
  * to be wrapped.
  *
  * Return value: %TRUE if any paragraphs had to be wrapped, %FALSE
- * otherwise.
+ *   otherwise.
  *
  * Since: 1.16
  */
@@ -531,20 +528,21 @@ pango_layout_is_wrapped (PangoLayout *layout)
 
 /**
  * pango_layout_set_indent:
- * @layout: a #PangoLayout.
+ * @layout: a `PangoLayout`.
  * @indent: the amount by which to indent.
  *
- * Sets the width in Pango units to indent each paragraph. A negative value
- * of @indent will produce a hanging indentation. That is, the first line will
- * have the full width, and subsequent lines will be indented by the
- * absolute value of @indent.
+ * Sets the width in Pango units to indent each paragraph.
+ *
+ * A negative value of @indent will produce a hanging indentation.
+ * That is, the first line will have the full width, and subsequent
+ * lines will be indented by the absolute value of @indent.
  *
  * The indent setting is ignored if layout alignment is set to
  * %PANGO_ALIGN_CENTER.
- **/
+ */
 void
 pango_layout_set_indent (PangoLayout *layout,
-			 int          indent)
+                         int          indent)
 {
   g_return_if_fail (layout != NULL);
 
@@ -557,13 +555,14 @@ pango_layout_set_indent (PangoLayout *layout,
 
 /**
  * pango_layout_get_indent:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
+ *
+ * Gets the paragraph indent width in Pango units.
  *
- * Gets the paragraph indent width in Pango units. A negative value
- * indicates a hanging indentation.
+ * A negative value indicates a hanging indentation.
  *
  * Return value: the indent in Pango units.
- **/
+ */
 int
 pango_layout_get_indent (PangoLayout *layout)
 {
@@ -573,24 +572,25 @@ pango_layout_get_indent (PangoLayout *layout)
 
 /**
  * pango_layout_set_spacing:
- * @layout: a #PangoLayout.
+ * @layout: a `PangoLayout`.
  * @spacing: the amount of spacing
  *
  * Sets the amount of spacing in Pango unit between
- * the lines of the layout. When placing lines with
- * spacing, Pango arranges things so that
+ * the lines of the layout.
+ *
+ * When placing lines with spacing, Pango arranges things so that
  *
  * line2.top = line1.bottom + spacing
  *
- * Note: Since 1.44, Pango defaults to using the
- * line height (as determined by the font) for placing
- * lines. The @spacing set with this function is only
- * taken into account when the line-height factor is
- * set to zero with pango_layout_set_line_spacing().
- **/
+ * Note: Since 1.44, Pango defaults to using the line height
+ * (as determined by the font) for placing lines. The @spacing
+ * set with this function is only taken into account when the
+ * line height factor is set to zero with
+ * [method@Pango.Layout.set_line_spacing].
+ */
 void
 pango_layout_set_spacing (PangoLayout *layout,
-			  int          spacing)
+                          int          spacing)
 {
   g_return_if_fail (layout != NULL);
 
@@ -603,12 +603,12 @@ pango_layout_set_spacing (PangoLayout *layout,
 
 /**
  * pango_layout_get_spacing:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the amount of spacing between the lines of the layout.
  *
  * Return value: the spacing in Pango units.
- **/
+ */
 int
 pango_layout_get_spacing (PangoLayout *layout)
 {
@@ -618,31 +618,28 @@ pango_layout_get_spacing (PangoLayout *layout)
 
 /**
  * pango_layout_set_line_spacing:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @factor: the new line spacing factor
  *
  * Sets a factor for line spacing.
- * Typical values are: 0, 1, 1.5, 2.
- * The default values is 0.
  *
- * If @factor is non-zero, lines are placed
- * so that
+ * Typical values are: 0, 1, 1.5, 2. The default values is 0.
  *
- * baseline2 = baseline1 + factor * height2
+ * If @factor is non-zero, lines are placed so that
  *
- * where height2 is the line height of the
- * second line (as determined by the font(s)).
- * In this case, the spacing set with
- * pango_layout_set_spacing() is ignored.
+ *     baseline2 = baseline1 + factor * height2
  *
- * If @factor is zero, spacing is applied as
- * before.
+ * where height2 is the line height of the second line
+ * (as determined by the font(s)). In this case, the spacing
+ * set with [method@Pango.Layout.set_spacing] is ignored.
+ *
+ * If @factor is zero, spacing is applied as before.
  *
  * Since: 1.44
  */
 void
 pango_layout_set_line_spacing (PangoLayout *layout,
-			       float        factor)
+                               float        factor)
 {
   g_return_if_fail (layout != NULL);
 
@@ -655,10 +652,11 @@ pango_layout_set_line_spacing (PangoLayout *layout,
 
 /**
  * pango_layout_get_line_spacing:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
+ *
+ * Gets the line spacing factor of @layout.
  *
- * Gets the value that has been
- * set with pango_layout_set_line_spacing().
+ * See [method@Pango.Layout.set_line_spacing].
  *
  * Since: 1.44
  */
@@ -671,12 +669,12 @@ pango_layout_get_line_spacing (PangoLayout *layout)
 
 /**
  * pango_layout_set_attributes:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @attrs: (allow-none) (transfer none): a #PangoAttrList, can be %NULL
  *
  * Sets the text attributes for a layout object.
  * References @attrs, so the caller can unref its reference.
- **/
+ */
 void
 pango_layout_set_attributes (PangoLayout   *layout,
                              PangoAttrList *attrs)
@@ -698,7 +696,6 @@ pango_layout_set_attributes (PangoLayout   *layout,
   /* We always clear lines such that this function can be called
    * whenever attrs changes.
    */
-
   layout->attrs = attrs;
   if (layout->attrs)
     pango_attr_list_ref (layout->attrs);
@@ -712,13 +709,13 @@ pango_layout_set_attributes (PangoLayout   *layout,
 
 /**
  * pango_layout_get_attributes:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the attribute list for the layout, if any.
  *
- * Return value: (transfer none) (nullable): a #PangoAttrList or %NULL
+ * Return value: (transfer none) (nullable): a `PangoAttrList` or %NULL
  *   if none was set.
- **/
+ */
 PangoAttrList*
 pango_layout_get_attributes (PangoLayout *layout)
 {
@@ -729,17 +726,18 @@ pango_layout_get_attributes (PangoLayout *layout)
 
 /**
  * pango_layout_set_font_description:
- * @layout: a #PangoLayout
- * @desc: (allow-none): the new #PangoFontDescription, or %NULL to unset the
- *        current font description
+ * @layout: a `PangoLayout`
+ * @desc: (allow-none): the new `PangoFontDescription`, or %NULL
+ *   to unset the current font description
+ *
+ * Sets the default font description for the layout.
  *
- * Sets the default font description for the layout. If no font
- * description is set on the layout, the font description from
+ * If no font description is set on the layout, the font description from
  * the layout's context is used.
- **/
+ */
 void
-pango_layout_set_font_description (PangoLayout                 *layout,
-				    const PangoFontDescription *desc)
+pango_layout_set_font_description (PangoLayout                *layout,
+                                   const PangoFontDescription *desc)
 {
   g_return_if_fail (layout != NULL);
 
@@ -747,7 +745,7 @@ pango_layout_set_font_description (PangoLayout                 *layout,
       (!desc || !layout->font_desc || !pango_font_description_equal(desc, layout->font_desc)))
     {
       if (layout->font_desc)
-	pango_font_description_free (layout->font_desc);
+        pango_font_description_free (layout->font_desc);
 
       layout->font_desc = desc ? pango_font_description_copy (desc) : NULL;
 
@@ -758,17 +756,17 @@ pango_layout_set_font_description (PangoLayout                 *layout,
 
 /**
  * pango_layout_get_font_description:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the font description for the layout, if any.
  *
  * Return value: (nullable): a pointer to the layout's font
- *  description, or %NULL if the font description from the layout's
- *  context is inherited. This value is owned by the layout and must
- *  not be modified or freed.
+ *   description, or %NULL if the font description from the layout's
+ *   context is inherited. This value is owned by the layout and must
+ *   not be modified or freed.
  *
  * Since: 1.8
- **/
+ */
 const PangoFontDescription *
 pango_layout_get_font_description (PangoLayout *layout)
 {
@@ -779,21 +777,22 @@ pango_layout_get_font_description (PangoLayout *layout)
 
 /**
  * pango_layout_set_justify:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @justify: whether the lines in the layout should be justified.
  *
- * Sets whether each complete line should be stretched to
- * fill the entire width of the layout. This stretching is typically
- * done by adding whitespace, but for some scripts (such as Arabic),
- * the justification may be done in more complex ways, like extending
- * the characters.
+ * Sets whether each complete line should be stretched to fill the
+ * entire width of the layout.
  *
- * Note that this setting is not implemented and so is ignored in Pango
- * older than 1.18.
- **/
+ * Stretching is typically done by adding whitespace, but for some scripts
+ * (such as Arabic), the justification may be done in more complex ways,
+ * like extending the characters.
+ *
+ * Note that this setting is not implemented and so is ignored in
+ * Pango older than 1.18.
+ */
 void
 pango_layout_set_justify (PangoLayout *layout,
-			  gboolean     justify)
+                          gboolean     justify)
 {
   g_return_if_fail (layout != NULL);
 
@@ -802,19 +801,19 @@ pango_layout_set_justify (PangoLayout *layout,
       layout->justify = justify;
 
       if (layout->is_ellipsized || layout->is_wrapped)
-	layout_changed (layout);
+        layout_changed (layout);
     }
 }
 
 /**
  * pango_layout_get_justify:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets whether each complete line should be stretched to fill the entire
  * width of the layout.
  *
  * Return value: the justify.
- **/
+ */
 gboolean
 pango_layout_get_justify (PangoLayout *layout)
 {
@@ -824,32 +823,32 @@ pango_layout_get_justify (PangoLayout *layout)
 
 /**
  * pango_layout_set_auto_dir:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @auto_dir: if %TRUE, compute the bidirectional base direction
  *   from the layout's contents.
  *
- * Sets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout;
- * when this flag is on (the default), then paragraphs in
-   @layout that begin with strong right-to-left characters
- * (Arabic and Hebrew principally), will have right-to-left
- * layout, paragraphs with letters from other scripts will
- * have left-to-right layout. Paragraphs with only neutral
- * characters get their direction from the surrounding paragraphs.
+ * Sets whether to calculate the base direction
+ * for the layout according to its contents.
  *
- * When %FALSE, the choice between left-to-right and
- * right-to-left layout is done according to the base direction
- * of the layout's #PangoContext. (See pango_context_set_base_dir()).
+ * When this flag is on (the default), then paragraphs in @layout that
+ * begin with strong right-to-left characters (Arabic and Hebrew principally),
+ * will have right-to-left layout, paragraphs with letters from other scripts
+ * will have left-to-right layout. Paragraphs with only neutral characters
+ * get their direction from the surrounding paragraphs.
+ *
+ * When %FALSE, the choice between left-to-right and right-to-left
+ * layout is done according to the base direction of the layout's
+ * `PangoContext`. (See [method@Pango.Context.set_base_dir]).
  *
  * When the auto-computed direction of a paragraph differs from the
  * base direction of the context, the interpretation of
  * %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_layout_set_auto_dir (PangoLayout *layout,
-			   gboolean     auto_dir)
+                           gboolean     auto_dir)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -864,17 +863,18 @@ pango_layout_set_auto_dir (PangoLayout *layout,
 
 /**
  * pango_layout_get_auto_dir:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
+ *
+ * Gets whether to calculate the base direction for the layout
+ * according to its contents.
  *
- * Gets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout.
- * See pango_layout_set_auto_dir().
+ * See [method@Pango.Layout.set_auto_dir].
  *
  * Return value: %TRUE if the bidirectional base direction
  *   is computed from the layout's contents, %FALSE otherwise.
  *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_layout_get_auto_dir (PangoLayout *layout)
 {
@@ -885,15 +885,15 @@ pango_layout_get_auto_dir (PangoLayout *layout)
 
 /**
  * pango_layout_set_alignment:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @alignment: the alignment
  *
  * Sets the alignment for the layout: how partial lines are
  * positioned within the horizontal space available.
- **/
+ */
 void
 pango_layout_set_alignment (PangoLayout   *layout,
-			    PangoAlignment alignment)
+                            PangoAlignment alignment)
 {
   g_return_if_fail (layout != NULL);
 
@@ -906,13 +906,13 @@ pango_layout_set_alignment (PangoLayout   *layout,
 
 /**
  * pango_layout_get_alignment:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the alignment for the layout: how partial lines are
  * positioned within the horizontal space available.
  *
  * Return value: the alignment.
- **/
+ */
 PangoAlignment
 pango_layout_get_alignment (PangoLayout *layout)
 {
@@ -923,17 +923,18 @@ pango_layout_get_alignment (PangoLayout *layout)
 
 /**
  * pango_layout_set_tabs:
- * @layout: a #PangoLayout
- * @tabs: (allow-none): a #PangoTabArray, or %NULL
+ * @layout: a `PangoLayout`
+ * @tabs: (allow-none): a `PangoTabArray`, or %NULL
  *
- * Sets the tabs to use for @layout, overriding the default tabs
- * (by default, tabs are every 8 spaces). If @tabs is %NULL, the default
- * tabs are reinstated. @tabs is copied into the layout; you must
- * free your copy of @tabs yourself.
- **/
+ * Sets the tabs to use for @layout, overriding the default tabs.
+ *
+ * By default, tabs are every 8 spaces. If @tabs is %NULL, the
+ * default tabs are reinstated. @tabs is copied into the layout;
+ * you must free your copy of @tabs yourself.
+ */
 void
 pango_layout_set_tabs (PangoLayout   *layout,
-		       PangoTabArray *tabs)
+                       PangoTabArray *tabs)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -941,7 +942,7 @@ pango_layout_set_tabs (PangoLayout   *layout,
   if (tabs != layout->tabs)
     {
       if (layout->tabs)
-	pango_tab_array_free (layout->tabs);
+        pango_tab_array_free (layout->tabs);
 
       layout->tabs = tabs ? pango_tab_array_copy (tabs) : NULL;
 
@@ -951,16 +952,18 @@ pango_layout_set_tabs (PangoLayout   *layout,
 
 /**
  * pango_layout_get_tabs:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Gets the current #PangoTabArray used by this layout. If no
- * #PangoTabArray has been set, then the default tabs are in use
- * and %NULL is returned. Default tabs are every 8 spaces.
- * The return value should be freed with pango_tab_array_free().
+ * Gets the current `PangoTabArray` used by this layout.
  *
- * Return value: (nullable): a copy of the tabs for this layout, or
- * %NULL.
- **/
+ * If no `PangoTabArray` has been set, then the default tabs are
+ * in use and %NULL is returned. Default tabs are every 8 spaces.
+ *
+ * The return value should be freed with [method@Pango.TabArray.free].
+ *
+ * Return value: (nullable): a copy of the tabs for this layout,
+ * or %NULL.
+ */
 PangoTabArray*
 pango_layout_get_tabs (PangoLayout *layout)
 {
@@ -974,17 +977,19 @@ pango_layout_get_tabs (PangoLayout *layout)
 
 /**
  * pango_layout_set_single_paragraph_mode:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @setting: new setting
  *
+ * Sets the single paragraph mode of @layout.
+ *
  * If @setting is %TRUE, do not treat newlines and similar characters
  * as paragraph separators; instead, keep all text in a single paragraph,
  * and display a glyph for paragraph separator characters. Used when
  * you want to allow editing of newlines on a single text line.
- **/
+ */
 void
 pango_layout_set_single_paragraph_mode (PangoLayout *layout,
-					gboolean     setting)
+                                        gboolean     setting)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -999,13 +1004,15 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
 
 /**
  * pango_layout_get_single_paragraph_mode:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
+ *
+ * Obtains whether @layout is in single paragraph mode.
  *
- * Obtains the value set by pango_layout_set_single_paragraph_mode().
+ * See [method@Pango.Layout.set_single_paragraph_mode].
  *
  * Return value: %TRUE if the layout does not break paragraphs at
  * paragraph separator characters, %FALSE otherwise.
- **/
+ */
 gboolean
 pango_layout_get_single_paragraph_mode (PangoLayout *layout)
 {
@@ -1016,26 +1023,27 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout)
 
 /**
  * pango_layout_set_ellipsize:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @ellipsize: the new ellipsization mode for @layout
  *
  * Sets the type of ellipsization being performed for @layout.
+ *
  * Depending on the ellipsization mode @ellipsize text is
  * removed from the start, middle, or end of text so they
  * fit within the width and height of layout set with
- * pango_layout_set_width() and pango_layout_set_height().
+ * [method@Pango.Layout.set_width] and [method@Pango.Layout.set_height].
  *
  * If the layout contains characters such as newlines that
  * force it to be layed out in multiple paragraphs, then whether
  * each paragraph is ellipsized separately or the entire layout
  * is ellipsized as a whole depends on the set height of the layout.
- * See pango_layout_set_height() for details.
+ * See [method@Pango.Layout.set_height] for details.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_layout_set_ellipsize (PangoLayout        *layout,
-			    PangoEllipsizeMode  ellipsize)
+                            PangoEllipsizeMode  ellipsize)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -1044,24 +1052,25 @@ pango_layout_set_ellipsize (PangoLayout        *layout,
       layout->ellipsize = ellipsize;
 
       if (layout->is_ellipsized || layout->is_wrapped)
-	layout_changed (layout);
+        layout_changed (layout);
     }
 }
 
 /**
  * pango_layout_get_ellipsize:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the type of ellipsization being performed for @layout.
- * See pango_layout_set_ellipsize()
  *
- * Return value: the current ellipsization mode for @layout.
+ * See [method@Pango.Layout.set_ellipsize].
  *
- * Use pango_layout_is_ellipsized() to query whether any paragraphs
- * were actually ellipsized.
+ * Use [method@Pango.Layout.is_ellipsized] to query whether any
+ * paragraphs were actually ellipsized.
+ *
+ * Return value: the current ellipsization mode for @layout.
  *
  * Since: 1.6
- **/
+ */
 PangoEllipsizeMode
 pango_layout_get_ellipsize (PangoLayout *layout)
 {
@@ -1072,7 +1081,7 @@ pango_layout_get_ellipsize (PangoLayout *layout)
 
 /**
  * pango_layout_is_ellipsized:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Queries whether the layout had to ellipsize any paragraphs.
  *
@@ -1098,29 +1107,28 @@ pango_layout_is_ellipsized (PangoLayout *layout)
 
 /**
  * pango_layout_set_text:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @text: the text
  * @length: maximum length of @text, in bytes. -1 indicates that
- *          the string is nul-terminated and the length should be
- *          calculated.  The text will also be truncated on
- *          encountering a nul-termination even when @length is
- *          positive.
+ *   the string is nul-terminated and the length should be calculated.
+ *   The text will also be truncated on encountering a nul-termination
+ *   even when @length is positive.
  *
  * Sets the text of the layout.
- * 
+ *
  * This function validates @text and renders invalid UTF-8
  * with a placeholder glyph.
  *
- * Note that if you have used pango_layout_set_markup() or
- * pango_layout_set_markup_with_accel() on @layout before, you may
- * want to call pango_layout_set_attributes() to clear the attributes
- * set on the layout from the markup as this function does not clear
- * attributes.
- **/
+ * Note that if you have used [method@Pango.Layout.set_markup] or
+ * [method@Pango.Layout.set_markup_with_accel] on @layout before, you
+ * may want to call [method@Pango.Layout.set_attributes] to clear the
+ * attributes set on the layout from the markup as this function does
+ * not clear attributes.
+ */
 void
 pango_layout_set_text (PangoLayout *layout,
-		       const char  *text,
-		       int          length)
+                       const char  *text,
+                       int          length)
 {
   char *old_text, *start, *end;
 
@@ -1182,7 +1190,7 @@ pango_layout_set_text (PangoLayout *layout,
 
 /**
  * pango_layout_get_text:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the text in the layout. The returned text should not
  * be freed or modified.
@@ -1204,13 +1212,13 @@ pango_layout_get_text (PangoLayout *layout)
 
 /**
  * pango_layout_get_character_count:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Returns the number of Unicode characters in the
  * the text of @layout.
  *
  * Return value: the number of Unicode characters
- *     in the text of @layout
+ *   in the text of @layout
  *
  * Since: 1.30
  */
@@ -1224,37 +1232,41 @@ pango_layout_get_character_count (PangoLayout *layout)
 
 /**
  * pango_layout_set_markup:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @markup: marked-up text
  * @length: length of marked-up text in bytes, or -1 if @markup is
- *          null-terminated
+ *   null-terminated
  *
- * Same as pango_layout_set_markup_with_accel(), but
- * the markup text isn't scanned for accelerators.
+ * Sets the layout text and attribute list from marked-up text.
  *
- **/
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
+ *
+ * This is the Same as [method@Pango.Layout.set_markup_with_accel],
+ * but the markup text isn't scanned for accelerators.
+ */
 void
 pango_layout_set_markup (PangoLayout *layout,
-			 const char  *markup,
-			 int          length)
+                         const char  *markup,
+                         int          length)
 {
   pango_layout_set_markup_with_accel (layout, markup, length, 0, NULL);
 }
 
 /**
  * pango_layout_set_markup_with_accel:
- * @layout: a #PangoLayout
- * @markup: marked-up text
- * (see <link linkend="PangoMarkupFormat">markup format</link>)
+ * @layout: a `PangoLayout`
+ * @markup: marked-up text (see [Pango Markup](pango_markup.html))
  * @length: length of marked-up text in bytes, or -1 if @markup is
- *          null-terminated
+ *   null-terminated
  * @accel_marker: marker for accelerators in the text
  * @accel_char: (out caller-allocates) (allow-none): return location
- *                    for first located accelerator, or %NULL
+ *   for first located accelerator, or %NULL
  *
- * Sets the layout text and attribute list from marked-up text (see
- * <link linkend="PangoMarkupFormat">markup format</link>). Replaces
- * the current text and attribute list.
+ * Sets the layout text and attribute list from marked-up text.
+ *
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
  *
  * If @accel_marker is nonzero, the given character will mark the
  * character following it as an accelerator. For example, @accel_marker
@@ -1263,13 +1275,13 @@ pango_layout_set_markup (PangoLayout *layout,
  * and the first character so marked will be returned in @accel_char.
  * Two @accel_marker characters following each other produce a single
  * literal @accel_marker character.
- **/
+ */
 void
-pango_layout_set_markup_with_accel (PangoLayout    *layout,
-				    const char     *markup,
-				    int             length,
-				    gunichar        accel_marker,
-				    gunichar       *accel_char)
+pango_layout_set_markup_with_accel (PangoLayout *layout,
+                                    const char  *markup,
+                                    int          length,
+                                    gunichar     accel_marker,
+                                    gunichar    *accel_char)
 {
   PangoAttrList *list = NULL;
   char *text = NULL;
@@ -1280,10 +1292,10 @@ pango_layout_set_markup_with_accel (PangoLayout    *layout,
 
   error = NULL;
   if (!pango_parse_markup (markup, length,
-			   accel_marker,
-			   &list, &text,
-			   accel_char,
-			   &error))
+                           accel_marker,
+                           &list, &text,
+                           accel_char,
+                           &error))
     {
       g_warning ("pango_layout_set_markup_with_accel: %s", error->message);
       g_error_free (error);
@@ -1298,11 +1310,9 @@ pango_layout_set_markup_with_accel (PangoLayout    *layout,
 
 /**
  * pango_layout_get_unknown_glyphs_count:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Counts the number unknown glyphs in @layout.  That is, zero if
- * glyphs for all characters in the layout text were found, or more
- * than zero otherwise.
+ * Counts the number of unknown glyphs in @layout.
  *
  * This function can be used to determine if there are any fonts
  * available to render all characters in a certain string, or when
@@ -1332,22 +1342,22 @@ pango_layout_get_unknown_glyphs_count (PangoLayout *layout)
     lines_list = layout->lines;
     while (lines_list)
       {
-	line = lines_list->data;
-	runs_list = line->runs;
-
-	while (runs_list)
-	  {
-	    run = runs_list->data;
-
-	    for (i = 0; i < run->glyphs->num_glyphs; i++)
-	      {
-		if (run->glyphs->glyphs[i].glyph & PANGO_GLYPH_UNKNOWN_FLAG)
-		    count++;
-	      }
-
-	    runs_list = runs_list->next;
-	  }
-	lines_list = lines_list->next;
+        line = lines_list->data;
+        runs_list = line->runs;
+
+        while (runs_list)
+          {
+            run = runs_list->data;
+
+            for (i = 0; i < run->glyphs->num_glyphs; i++)
+              {
+                if (run->glyphs->glyphs[i].glyph & PANGO_GLYPH_UNKNOWN_FLAG)
+                    count++;
+              }
+
+            runs_list = runs_list->next;
+          }
+        lines_list = lines_list->next;
       }
 
     layout->unknown_glyphs_count = count;
@@ -1376,13 +1386,14 @@ layout_changed (PangoLayout *layout)
 
 /**
  * pango_layout_context_changed:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
- * Forces recomputation of any state in the #PangoLayout that
- * might depend on the layout's context. This function should
- * be called if you make changes to the context subsequent
- * to creating the layout.
- **/
+ * Forces recomputation of any state in the `PangoLayout` that
+ * might depend on the layout's context.
+ *
+ * This function should be called if you make changes to the context
+ * subsequent to creating the layout.
+ */
 void
 pango_layout_context_changed (PangoLayout *layout)
 {
@@ -1394,23 +1405,25 @@ pango_layout_context_changed (PangoLayout *layout)
 
 /**
  * pango_layout_get_serial:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
+ *
+ * Returns the current serial number of @layout.
  *
- * Returns the current serial number of @layout.  The serial number is
- * initialized to an small number  larger than zero when a new layout
- * is created and is increased whenever the layout is changed using any
- * of the setter functions, or the #PangoContext it uses has changed.
- * The serial may wrap, but will never have the value 0. Since it
- * can wrap, never compare it with "less than", always use "not equals".
+ * The serial number is initialized to an small number larger than zero
+ * when a new layout is created and is increased whenever the layout is
+ * changed using any of the setter functions, or the `PangoContext` it
+ * uses has changed. The serial may wrap, but will never have the value 0.
+ * Since it can wrap, never compare it with "less than", always use "not equals".
  *
- * This can be used to automatically detect changes to a #PangoLayout, and
- * is useful for example to decide whether a layout needs redrawing.
- * To force the serial to be increased, use pango_layout_context_changed().
+ * This can be used to automatically detect changes to a `PangoLayout`,
+ * and is useful for example to decide whether a layout needs redrawing.
+ * To force the serial to be increased, use
+ * [method@Pango.Layout.context_changed].
  *
  * Return value: The current serial number of @layout.
  *
  * Since: 1.32.4
- **/
+ */
 guint
 pango_layout_get_serial (PangoLayout *layout)
 {
@@ -1420,23 +1433,23 @@ pango_layout_get_serial (PangoLayout *layout)
 
 /**
  * pango_layout_get_log_attrs:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @attrs: (out)(array length=n_attrs)(transfer container):
- *         location to store a pointer to an array of logical attributes
- *         This value must be freed with g_free().
+ *   location to store a pointer to an array of logical attributes
+ *   This value must be freed with g_free().
  * @n_attrs: (out): location to store the number of the attributes in the
- *           array. (The stored value will be one more than the total number
- *           of characters in the layout, since there need to be attributes
- *           corresponding to both the position before the first character
- *           and the position after the last character.)
+ *   array. (The stored value will be one more than the total number
+ *   of characters in the layout, since there need to be attributes
+ *   corresponding to both the position before the first character
+ *   and the position after the last character.)
  *
  * Retrieves an array of logical attributes for each character in
  * the @layout.
- **/
+ */
 void
-pango_layout_get_log_attrs (PangoLayout    *layout,
-			    PangoLogAttr  **attrs,
-			    gint           *n_attrs)
+pango_layout_get_log_attrs (PangoLayout   *layout,
+                            PangoLogAttr **attrs,
+                            gint          *n_attrs)
 {
   g_return_if_fail (layout != NULL);
 
@@ -1454,14 +1467,14 @@ pango_layout_get_log_attrs (PangoLayout    *layout,
 
 /**
  * pango_layout_get_log_attrs_readonly:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @n_attrs: (out): location to store the number of the attributes in
  *   the array
  *
  * Retrieves an array of logical attributes for each character in
  * the @layout.
  *
- * This is a faster alternative to pango_layout_get_log_attrs().
+ * This is a faster alternative to [method@Pango.Layout.get_log_attrs].
  * The returned array is part of @layout and must not be modified.
  * Modifying the layout will invalidate the returned array.
  *
@@ -1493,12 +1506,12 @@ pango_layout_get_log_attrs_readonly (PangoLayout *layout,
 
 /**
  * pango_layout_get_line_count:
- * @layout: #PangoLayout
+ * @layout: `PangoLayout`
  *
  * Retrieves the count of lines for the @layout.
  *
  * Return value: the line count.
- **/
+ */
 int
 pango_layout_get_line_count (PangoLayout   *layout)
 {
@@ -1510,18 +1523,18 @@ pango_layout_get_line_count (PangoLayout   *layout)
 
 /**
  * pango_layout_get_lines:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Returns the lines of the @layout as a list.
  *
- * Use the faster pango_layout_get_lines_readonly() if you do not plan
- * to modify the contents of the lines (glyphs, glyph widths, etc.).
+ * Use the faster [method@Pango.Layout.get_lines_readonly] if you do not
+ * plan to modify the contents of the lines (glyphs, glyph widths, etc.).
  *
- * Return value: (element-type Pango.LayoutLine) (transfer none): a #GSList containing
- * the lines in the layout. This points to internal data of the #PangoLayout
- * and must be used with care. It will become invalid on any change to the layout's
- * text or properties.
- **/
+ * Return value: (element-type Pango.LayoutLine) (transfer none): a `GSList`
+ *   containing the lines in the layout. This points to internal data of the
+ *   `PangoLayout` and must be used with care. It will become invalid on any
+ *   change to the layout's text or properties.
+ */
 GSList *
 pango_layout_get_lines (PangoLayout *layout)
 {
@@ -1531,12 +1544,12 @@ pango_layout_get_lines (PangoLayout *layout)
     {
       GSList *tmp_list = layout->lines;
       while (tmp_list)
-	{
-	  PangoLayoutLine *line = tmp_list->data;
-	  tmp_list = tmp_list->next;
+        {
+          PangoLayoutLine *line = tmp_list->data;
+          tmp_list = tmp_list->next;
 
-	  pango_layout_line_leaked (line);
-	}
+          pango_layout_line_leaked (line);
+        }
     }
 
   return layout->lines;
@@ -1544,21 +1557,22 @@ pango_layout_get_lines (PangoLayout *layout)
 
 /**
  * pango_layout_get_lines_readonly:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Returns the lines of the @layout as a list.
  *
- * This is a faster alternative to pango_layout_get_lines(),
- * but the user is not expected
- * to modify the contents of the lines (glyphs, glyph widths, etc.).
+ * This is a faster alternative to [method@Pango.Layout.get_lines],
+ * but the user is not expected to modify the contents of the lines
+ * (glyphs, glyph widths, etc.).
  *
- * Return value: (element-type Pango.LayoutLine) (transfer none): a #GSList containing
- * the lines in the layout. This points to internal data of the #PangoLayout and
- * must be used with care. It will become invalid on any change to the layout's
- * text or properties.  No changes should be made to the lines.
+ * Return value: (element-type Pango.LayoutLine) (transfer none): a `GSList`
+ *   containing the lines in the layout. This points to internal data of the
+ *   `PangoLayout` and must be used with care. It will become invalid on any
+ *   change to the layout's text or properties. No changes should be made to
+ *   the lines.
  *
  * Since: 1.16
- **/
+ */
 GSList *
 pango_layout_get_lines_readonly (PangoLayout *layout)
 {
@@ -1569,24 +1583,23 @@ pango_layout_get_lines_readonly (PangoLayout *layout)
 
 /**
  * pango_layout_get_line:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @line: the index of a line, which must be between 0 and
- *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
+ *        `pango_layout_get_line_count(layout) - 1`, inclusive.
  *
- * Retrieves a particular line from a #PangoLayout.
+ * Retrieves a particular line from a `PangoLayout`.
  *
- * Use the faster pango_layout_get_line_readonly() if you do not plan
- * to modify the contents of the line (glyphs, glyph widths, etc.).
+ * Use the faster [method@Pango.Layout.get_line_readonly] if you do not
+ * plan to modify the contents of the line (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none) (nullable): the requested
- *               #PangoLayoutLine, or %NULL if the index is out of
- *               range. This layout line can be ref'ed and retained,
- *               but will become invalid if changes are made to the
- *               #PangoLayout.
- **/
+ * Return value: (transfer none) (nullable): the requested `PangoLayoutLine`,
+ *   or %NULL if the index is out of range. This layout line can be ref'ed
+ *   and retained, but will become invalid if changes are made to the
+ *   `PangoLayout`.
+ */
 PangoLayoutLine *
 pango_layout_get_line (PangoLayout *layout,
-		       int          line)
+                       int          line)
 {
   GSList *list_item;
   g_return_val_if_fail (layout != NULL, NULL);
@@ -1611,27 +1624,26 @@ pango_layout_get_line (PangoLayout *layout,
 
 /**
  * pango_layout_get_line_readonly:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @line: the index of a line, which must be between 0 and
- *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
+ *        `pango_layout_get_line_count(layout) - 1`, inclusive.
  *
- * Retrieves a particular line from a #PangoLayout.
+ * Retrieves a particular line from a `PangoLayout`.
  *
- * This is a faster alternative to pango_layout_get_line(),
- * but the user is not expected
- * to modify the contents of the line (glyphs, glyph widths, etc.).
+ * This is a faster alternative to [method@Pango.Layout.get_line],
+ * but the user is not expected to modify the contents of the line
+ * (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none) (nullable): the requested
- *               #PangoLayoutLine, or %NULL if the index is out of
- *               range. This layout line can be ref'ed and retained,
- *               but will become invalid if changes are made to the
- *               #PangoLayout.  No changes should be made to the line.
+ * Return value: (transfer none) (nullable): the requested `PangoLayoutLine`,
+ *   or %NULL if the index is out of range. This layout line can be ref'ed
+ *   and retained, but will become invalid if changes are made to the
+ *   `PangoLayout`. No changes should be made to the line.
  *
  * Since: 1.16
- **/
+ */
 PangoLayoutLine *
 pango_layout_get_line_readonly (PangoLayout *layout,
-				int          line)
+                                int          line)
 {
   GSList *list_item;
   g_return_val_if_fail (layout != NULL, NULL);
@@ -1654,21 +1666,20 @@ pango_layout_get_line_readonly (PangoLayout *layout,
 
 /**
  * pango_layout_line_index_to_x:
- * @line:     a #PangoLayoutLine
- * @index_:   byte offset of a grapheme within the layout
+ * @line: a `PangoLayoutLine`
+ * @index_: byte offset of a grapheme within the layout
  * @trailing: an integer indicating the edge of the grapheme to retrieve
- *            the position of. If > 0, the trailing edge of the grapheme,
- *            if 0, the leading of the grapheme.
- * @x_pos: (out): location to store the x_offset (in Pango unit)
+ *    the position of. If > 0, the trailing edge of the grapheme,
+ *    if 0, the leading of the grapheme.
+ * @x_pos: (out): location to store the x_offset (in Pango units)
  *
  * Converts an index within a line to a X position.
- *
- **/
+ */
 void
-pango_layout_line_index_to_x (PangoLayoutLine  *line,
-			      int               index,
-			      int               trailing,
-			      int              *x_pos)
+pango_layout_line_index_to_x (PangoLayoutLine *line,
+                              int              index,
+                              int              trailing,
+                              int             *x_pos)
 {
   PangoLayout *layout = line->layout;
   GSList *run_list = line->runs;
@@ -1679,39 +1690,39 @@ pango_layout_line_index_to_x (PangoLayoutLine  *line,
       PangoLayoutRun *run = run_list->data;
 
       if (run->item->offset <= index && run->item->offset + run->item->length > index)
-	{
-	  int offset = g_utf8_pointer_to_offset (layout->text, layout->text + index);
-	  if (trailing)
-	    {
-	      while (index < line->start_index + line->length &&
-		     offset + 1 < layout->n_chars &&
-		     !layout->log_attrs[offset + 1].is_cursor_position)
-		{
-		  offset++;
-		  index = g_utf8_next_char (layout->text + index) - layout->text;
-		}
-	    }
-	  else
-	    {
-	      while (index > line->start_index &&
-		     !layout->log_attrs[offset].is_cursor_position)
-		{
-		  offset--;
-		  index = g_utf8_prev_char (layout->text + index) - layout->text;
-		}
-
-	    }
-
-	  pango_glyph_string_index_to_x (run->glyphs,
-					 layout->text + run->item->offset,
-					 run->item->length,
-					 &run->item->analysis,
-					 index - run->item->offset, trailing, x_pos);
-	  if (x_pos)
-	    *x_pos += width;
-
-	  return;
-	}
+        {
+          int offset = g_utf8_pointer_to_offset (layout->text, layout->text + index);
+          if (trailing)
+            {
+              while (index < line->start_index + line->length &&
+                     offset + 1 < layout->n_chars &&
+                     !layout->log_attrs[offset + 1].is_cursor_position)
+                {
+                  offset++;
+                  index = g_utf8_next_char (layout->text + index) - layout->text;
+                }
+            }
+          else
+            {
+              while (index > line->start_index &&
+                     !layout->log_attrs[offset].is_cursor_position)
+                {
+                  offset--;
+                  index = g_utf8_prev_char (layout->text + index) - layout->text;
+                }
+
+            }
+
+          pango_glyph_string_index_to_x (run->glyphs,
+                                         layout->text + run->item->offset,
+                                         run->item->length,
+                                         &run->item->analysis,
+                                         index - run->item->offset, trailing, x_pos);
+          if (x_pos)
+            *x_pos += width;
+
+          return;
+        }
 
       width += pango_glyph_string_get_width (run->glyphs);
 
@@ -1724,10 +1735,10 @@ pango_layout_line_index_to_x (PangoLayoutLine  *line,
 
 static PangoLayoutLine *
 pango_layout_index_to_line (PangoLayout      *layout,
-			    int               index,
-			    int              *line_nr,
-			    PangoLayoutLine **line_before,
-			    PangoLayoutLine **line_after)
+                            int               index,
+                            int              *line_nr,
+                            PangoLayoutLine **line_before,
+                            PangoLayoutLine **line_after)
 {
   GSList *tmp_list;
   GSList *line_list;
@@ -1741,7 +1752,7 @@ pango_layout_index_to_line (PangoLayout      *layout,
       PangoLayoutLine *tmp_line = tmp_list->data;
 
       if (tmp_line->start_index > index)
-	break; /* index was in paragraph delimiters */
+        break; /* index was in paragraph delimiters */
 
       prev_line = line;
       line = tmp_line;
@@ -1749,7 +1760,7 @@ pango_layout_index_to_line (PangoLayout      *layout,
       i++;
 
       if (line->start_index + line->length > index)
-	break;
+        break;
 
       tmp_list = tmp_list->next;
     }
@@ -1768,8 +1779,8 @@ pango_layout_index_to_line (PangoLayout      *layout,
 
 static PangoLayoutLine *
 pango_layout_index_to_line_and_extents (PangoLayout     *layout,
-					int              index,
-					PangoRectangle  *line_rect)
+                                        int              index,
+                                        PangoRectangle  *line_rect)
 {
   PangoLayoutIter iter;
   PangoLayoutLine *line = NULL;
@@ -1779,20 +1790,20 @@ pango_layout_index_to_line_and_extents (PangoLayout     *layout,
   if (!ITER_IS_INVALID (&iter))
     while (TRUE)
       {
-	PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter);
+        PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter);
 
-	if (tmp_line->start_index > index)
-	    break; /* index was in paragraph delimiters */
+        if (tmp_line->start_index > index)
+            break; /* index was in paragraph delimiters */
 
-	line = tmp_line;
+        line = tmp_line;
 
-	pango_layout_iter_get_line_extents (&iter, NULL, line_rect);
+        pango_layout_iter_get_line_extents (&iter, NULL, line_rect);
 
-	if (line->start_index + line->length > index)
-	  break;
+        if (line->start_index + line->length > index)
+          break;
 
-	if (!pango_layout_iter_next_line (&iter))
-	  break; /* Use end of last line */
+        if (!pango_layout_iter_next_line (&iter))
+          break; /* Use end of last line */
       }
 
   _pango_layout_iter_destroy (&iter);
@@ -1802,25 +1813,26 @@ pango_layout_index_to_line_and_extents (PangoLayout     *layout,
 
 /**
  * pango_layout_index_to_line_x:
- * @layout:    a #PangoLayout
- * @index_:    the byte index of a grapheme within the layout.
- * @trailing:  an integer indicating the edge of the grapheme to retrieve the
- *             position of. If > 0, the trailing edge of the grapheme, if 0,
- *             the leading of the grapheme.
+ * @layout: a `PangoLayout`
+ * @index_: the byte index of a grapheme within the layout.
+ * @trailing: an integer indicating the edge of the grapheme to retrieve the
+ *   position of. If > 0, the trailing edge of the grapheme, if 0,
+ *   the leading of the grapheme.
  * @line: (out) (allow-none): location to store resulting line index. (which will
- *               between 0 and pango_layout_get_line_count(layout) - 1), or %NULL
+ *   between 0 and pango_layout_get_line_count(layout) - 1), or %NULL
  * @x_pos: (out) (allow-none): location to store resulting position within line
- *              (%PANGO_SCALE units per device unit), or %NULL
+ *   (%PANGO_SCALE units per device unit), or %NULL
  *
  * Converts from byte @index_ within the @layout to line and X position.
- * (X position is measured from the left edge of the line)
+ *
+ * The X position is measured from the left edge of the line.
  */
 void
 pango_layout_index_to_line_x (PangoLayout *layout,
-			      int          index,
-			      gboolean     trailing,
-			      int         *line,
-			      int         *x_pos)
+                              int          index,
+                              gboolean     trailing,
+                              int         *line,
+                              int         *x_pos)
 {
   int line_num;
   PangoLayoutLine *layout_line = NULL;
@@ -1832,77 +1844,77 @@ pango_layout_index_to_line_x (PangoLayout *layout,
   pango_layout_check_lines (layout);
 
   layout_line = pango_layout_index_to_line (layout, index,
-					    &line_num, NULL, NULL);
+                                            &line_num, NULL, NULL);
 
   if (layout_line)
     {
       /* use end of line if index was in the paragraph delimiters */
       if (index > layout_line->start_index + layout_line->length)
-	index = layout_line->start_index + layout_line->length;
+        index = layout_line->start_index + layout_line->length;
 
       if (line)
-	*line = line_num;
+        *line = line_num;
 
       pango_layout_line_index_to_x (layout_line, index, trailing, x_pos);
     }
   else
     {
       if (line)
-	*line = -1;
+        *line = -1;
       if (x_pos)
-	*x_pos = -1;
+        *x_pos = -1;
     }
 }
 
 /**
  * pango_layout_move_cursor_visually:
- * @layout:       a #PangoLayout.
- * @strong:       whether the moving cursor is the strong cursor or the
- *                weak cursor. The strong cursor is the cursor corresponding
- *                to text insertion in the base direction for the layout.
+ * @layout: a `PangoLayout`
+ * @strong: whether the moving cursor is the strong cursor or the
+ *   weak cursor. The strong cursor is the cursor corresponding
+ *   to text insertion in the base direction for the layout.
  * @old_index:    the byte index of the grapheme for the old index
  * @old_trailing: if 0, the cursor was at the leading edge of the
- *                grapheme indicated by @old_index, if > 0, the cursor
- *                was at the trailing edge.
+ *   grapheme indicated by @old_index, if > 0, the cursor
+ *   was at the trailing edge.
  * @direction:    direction to move cursor. A negative
- *                value indicates motion to the left.
- * @new_index: (out): location to store the new cursor byte index. A value of -1
- *                indicates that the cursor has been moved off the beginning
- *                of the layout. A value of %G_MAXINT indicates that
- *                the cursor has been moved off the end of the layout.
- * @new_trailing: (out): number of characters to move forward from the
- *                location returned for @new_index to get the position
- *                where the cursor should be displayed. This allows
- *                distinguishing the position at the beginning of one
- *                line from the position at the end of the preceding
- *                line. @new_index is always on the line where the
- *                cursor should be displayed.
- *
- * Computes a new cursor position from an old position and
- * a count of positions to move visually. If @direction is positive,
- * then the new strong cursor position will be one position
- * to the right of the old cursor position. If @direction is negative,
- * then the new strong cursor position will be one position
- * to the left of the old cursor position.
- *
- * In the presence of bidirectional text, the correspondence
- * between logical and visual order will depend on the direction
- * of the current run, and there may be jumps when the cursor
- * is moved off of the end of a run.
- *
- * Motion here is in cursor positions, not in characters, so a
- * single call to pango_layout_move_cursor_visually() may move the
- * cursor over multiple characters when multiple characters combine
- * to form a single grapheme.
- **/
+ *   value indicates motion to the left.
+ * @new_index: (out): location to store the new cursor byte index.
+ *   A value of -1 indicates that the cursor has been moved off the
+ *   beginning of the layout. A value of %G_MAXINT indicates that
+ *   the cursor has been moved off the end of the layout.
+ * @new_trailing: (out): number of characters to move forward from
+ *   the location returned for @new_index to get the position where
+ *   the cursor should be displayed. This allows distinguishing the
+ *   position at the beginning of one line from the position at the
+ *   end of the preceding line. @new_index is always on the line where
+ *   the cursor should be displayed.
+ *
+ * Computes a new cursor position from an old position and a count of
+ * positions to move visually.
+ *
+ * If @direction is positive, then the new strong cursor position will be
+ * one position to the right of the old cursor position. If @direction is
+ * negative, then the new strong cursor position will be one position to
+ * the left of the old cursor position.
+ *
+ * In the presence of bidirectional text, the correspondence between
+ * logical and visual order will depend on the direction of the current
+ * run, and there may be jumps when the cursor is moved off of the end
+ * of a run.
+ *
+ * Motion here is in cursor positions, not in characters, so a single
+ * call to [method@Pango.Layout.move_cursor_visually] may move the cursor over
+ * multiple characters when multiple characters combine to form a single
+ * grapheme.
+ */
 void
 pango_layout_move_cursor_visually (PangoLayout *layout,
-				   gboolean     strong,
-				   int          old_index,
-				   int          old_trailing,
-				   int          direction,
-				   int         *new_index,
-				   int         *new_trailing)
+                                   gboolean     strong,
+                                   int          old_index,
+                                   int          old_trailing,
+                                   int          direction,
+                                   int         *new_index,
+                                   int         *new_trailing)
 {
   PangoLayoutLine *line = NULL;
   PangoLayoutLine *prev_line;
@@ -1928,7 +1940,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
 
   /* Find the line the old cursor is on */
   line = pango_layout_index_to_line (layout, old_index,
-				     NULL, &prev_line, &next_line);
+                                     NULL, &prev_line, &next_line);
 
   start_offset = g_utf8_pointer_to_offset (layout->text, layout->text + line->start_index);
 
@@ -1950,16 +1962,16 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
   if (vis_pos == 0 && direction < 0)
     {
       if (line->resolved_dir == PANGO_DIRECTION_LTR)
-	off_start = TRUE;
+        off_start = TRUE;
       else
-	off_end = TRUE;
+        off_end = TRUE;
     }
   else if (vis_pos == n_vis && direction > 0)
     {
       if (line->resolved_dir == PANGO_DIRECTION_LTR)
-	off_end = TRUE;
+        off_end = TRUE;
       else
-	off_start = TRUE;
+        off_start = TRUE;
     }
 
   if (off_start || off_end)
@@ -1970,59 +1982,59 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
       gboolean paragraph_boundary;
 
       if (off_start)
-	{
-	  if (!prev_line)
-	    {
-	      *new_index = -1;
-	      *new_trailing = 0;
-	      return;
-	    }
-	  line = prev_line;
-	  paragraph_boundary = (line->start_index + line->length != old_index);
-	}
+        {
+          if (!prev_line)
+            {
+              *new_index = -1;
+              *new_trailing = 0;
+              return;
+            }
+          line = prev_line;
+          paragraph_boundary = (line->start_index + line->length != old_index);
+        }
       else
-	{
-	  if (!next_line)
-	    {
-	      *new_index = G_MAXINT;
-	      *new_trailing = 0;
-	      return;
-	    }
-	  line = next_line;
-	  paragraph_boundary = (line->start_index != old_index);
-	}
+        {
+          if (!next_line)
+            {
+              *new_index = G_MAXINT;
+              *new_trailing = 0;
+              return;
+            }
+          line = next_line;
+          paragraph_boundary = (line->start_index != old_index);
+        }
 
       n_vis = pango_utf8_strlen (layout->text + line->start_index, line->length);
       start_offset = g_utf8_pointer_to_offset (layout->text, layout->text + line->start_index);
 
       if (vis_pos == 0 && direction < 0)
-	{
-	  vis_pos = n_vis;
-	  if (paragraph_boundary)
-	    vis_pos++;
-	}
+        {
+          vis_pos = n_vis;
+          if (paragraph_boundary)
+            vis_pos++;
+        }
       else /* (vis_pos == n_vis && direction > 0) */
-	{
-	  vis_pos = 0;
-	  if (paragraph_boundary)
-	    vis_pos--;
-	}
+        {
+          vis_pos = 0;
+          if (paragraph_boundary)
+            vis_pos--;
+        }
     }
 
   vis2log_map = pango_layout_line_get_vis2log_map (line, strong);
 
   vis_pos_old = vis_pos + direction;
   log_pos = g_utf8_pointer_to_offset (layout->text + line->start_index,
-				      layout->text + line->start_index + vis2log_map[vis_pos_old]);
+                                      layout->text + line->start_index + vis2log_map[vis_pos_old]);
   do
     {
       vis_pos += direction;
       log_pos += g_utf8_pointer_to_offset (layout->text + line->start_index + vis2log_map[vis_pos_old],
-					   layout->text + line->start_index + vis2log_map[vis_pos]);
+                                           layout->text + line->start_index + vis2log_map[vis_pos]);
       vis_pos_old = vis_pos;
     }
   while (vis_pos > 0 && vis_pos < n_vis &&
-	 !layout->log_attrs[start_offset + log_pos].is_cursor_position);
+         !layout->log_attrs[start_offset + log_pos].is_cursor_position);
 
   *new_index = line->start_index + vis2log_map[vis_pos];
   g_free (vis2log_map);
@@ -2032,45 +2044,45 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
   if (*new_index == line->start_index + line->length && line->length > 0)
     {
       do
-	{
-	  log_pos--;
-	  *new_index = g_utf8_prev_char (layout->text + *new_index) - layout->text;
-	  (*new_trailing)++;
-	}
+        {
+          log_pos--;
+          *new_index = g_utf8_prev_char (layout->text + *new_index) - layout->text;
+          (*new_trailing)++;
+        }
       while (log_pos > 0 && !layout->log_attrs[start_offset + log_pos].is_cursor_position);
     }
 }
 
 /**
  * pango_layout_xy_to_index:
- * @layout:    a #PangoLayout
- * @x:         the X offset (in Pango units)
- *             from the left edge of the layout.
- * @y:         the Y offset (in Pango units)
- *             from the top edge of the layout
- * @index_: (out):   location to store calculated byte index
+ * @layout: a `PangoLayout`
+ * @x: the X offset (in Pango units) from the left edge of the layout.
+ * @y: the Y offset (in Pango units) from the top edge of the layout
+ * @index_: (out): location to store calculated byte index
  * @trailing: (out): location to store a integer indicating where
- *             in the grapheme the user clicked. It will either
- *             be zero, or the number of characters in the
- *             grapheme. 0 represents the leading edge of the grapheme.
- *
- * Converts from X and Y position within a layout to the byte
- * index to the character at that logical position. If the
- * Y position is not inside the layout, the closest position is chosen
- * (the position will be clamped inside the layout). If the
- * X position is not within the layout, then the start or the
- * end of the line is chosen as described for pango_layout_line_x_to_index().
- * If either the X or Y positions were not inside the layout, then the
- * function returns %FALSE; on an exact hit, it returns %TRUE.
+ *   in the grapheme the user clicked. It will either be zero, or the
+ *   number of characters in the grapheme. 0 represents the leading edge
+ *   of the grapheme.
+ *
+ * Converts from X and Y position within a layout to the byte index to the
+ * character at that logical position.
+ *
+ * If the Y position is not inside the
+ * layout, the closest position is chosen (the position will be clamped
+ * inside the layout). If the X position is not within the layout, then
+ * the start or the end of the line is chosen as described for
+ * [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions
+ * were not inside the layout, then the function returns %FALSE; on an
+ * exact hit, it returns %TRUE.
  *
  * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise.
- **/
+ */
 gboolean
 pango_layout_xy_to_index (PangoLayout *layout,
-			  int          x,
-			  int          y,
-			  int         *index,
-			  gint        *trailing)
+                          int          x,
+                          int          y,
+                          int         *index,
+                          gint        *trailing)
 {
   PangoLayoutIter iter;
   PangoLayoutLine *prev_line = NULL;
@@ -2096,34 +2108,34 @@ pango_layout_xy_to_index (PangoLayout *layout,
       pango_layout_iter_get_line_yrange (&iter, &first_y, &last_y);
 
       if (y < first_y)
-	{
-	  if (prev_line && y < (prev_last + (first_y - prev_last) / 2))
-	    {
-	      found = prev_line;
-	      found_line_x = prev_line_x;
-	    }
-	  else
-	    {
-	      if (prev_line == NULL)
-		outside = TRUE; /* off the top */
-
-	      found = _pango_layout_iter_get_line (&iter);
-	      found_line_x = x - line_logical.x;
-	    }
-	}
+        {
+          if (prev_line && y < (prev_last + (first_y - prev_last) / 2))
+            {
+              found = prev_line;
+              found_line_x = prev_line_x;
+            }
+          else
+            {
+              if (prev_line == NULL)
+                outside = TRUE; /* off the top */
+
+              found = _pango_layout_iter_get_line (&iter);
+              found_line_x = x - line_logical.x;
+            }
+        }
       else if (y >= first_y &&
-	       y < last_y)
-	{
-	  found = _pango_layout_iter_get_line (&iter);
-	  found_line_x = x - line_logical.x;
-	}
+               y < last_y)
+        {
+          found = _pango_layout_iter_get_line (&iter);
+          found_line_x = x - line_logical.x;
+        }
 
       prev_line = _pango_layout_iter_get_line (&iter);
       prev_last = last_y;
       prev_line_x = x - line_logical.x;
 
       if (found != NULL)
-	break;
+        break;
     }
   while (pango_layout_iter_next_line (&iter));
 
@@ -2139,8 +2151,8 @@ pango_layout_xy_to_index (PangoLayout *layout,
     }
 
   retval = pango_layout_line_x_to_index (found,
-					 found_line_x,
-					 index, trailing);
+                                         found_line_x,
+                                         index, trailing);
 
   if (outside)
     retval = FALSE;
@@ -2150,21 +2162,22 @@ pango_layout_xy_to_index (PangoLayout *layout,
 
 /**
  * pango_layout_index_to_pos:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @index_: byte index within @layout
  * @pos: (out): rectangle in which to store the position of the grapheme
  *
- * Converts from an index within a #PangoLayout to the onscreen position
- * corresponding to the grapheme at that index, which is represented
- * as rectangle.  Note that <literal>pos->x</literal> is always the leading
- * edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing
- * edge of the grapheme. If the directionality of the grapheme is right-to-left,
- * then <literal>pos->width</literal> will be negative.
- **/
+ * Converts from an index within a `PangoLayout` to the onscreen position
+ * corresponding to the grapheme at that index.
+ *
+ * The return value is represented as rectangle. Note that `pos->x` is
+ * always the leading edge of the grapheme and `pos->x + pos->width` the
+ * trailing edge of the grapheme. If the directionality of the grapheme
+ * is right-to-left, then `pos->width` will be negative.
+ */
 void
 pango_layout_index_to_pos (PangoLayout    *layout,
-			   int             index,
-			   PangoRectangle *pos)
+                           int             index,
+                           PangoRectangle *pos)
 {
   PangoRectangle logical_rect;
   PangoLayoutIter iter;
@@ -2180,35 +2193,35 @@ pango_layout_index_to_pos (PangoLayout    *layout,
   if (!ITER_IS_INVALID (&iter))
     {
       while (TRUE)
-	{
-	  PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter);
-
-	  if (tmp_line->start_index > index)
-	    {
-	      /* index is in the paragraph delim&iters, move to
-	       * end of previous line
-	       *
-	       * This shouldn’t occur in the first loop &iteration as the first
-	       * line’s start_index should always be 0.
-	       */
-	      g_assert (layout_line != NULL);
-	      index = layout_line->start_index + layout_line->length;
-	      break;
-	    }
-
-	  layout_line = tmp_line;
-
-	  pango_layout_iter_get_line_extents (&iter, NULL, &logical_rect);
-
-	  if (layout_line->start_index + layout_line->length > index)
-	    break;
-
-	  if (!pango_layout_iter_next_line (&iter))
-	    {
-	      index = layout_line->start_index + layout_line->length;
-	      break;
-	    }
-	}
+        {
+          PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter);
+
+          if (tmp_line->start_index > index)
+            {
+              /* index is in the paragraph delim&iters, move to
+               * end of previous line
+               *
+               * This shouldn’t occur in the first loop &iteration as the first
+               * line’s start_index should always be 0.
+               */
+              g_assert (layout_line != NULL);
+              index = layout_line->start_index + layout_line->length;
+              break;
+            }
+
+          layout_line = tmp_line;
+
+          pango_layout_iter_get_line_extents (&iter, NULL, &logical_rect);
+
+          if (layout_line->start_index + layout_line->length > index)
+            break;
+
+          if (!pango_layout_iter_next_line (&iter))
+            {
+              index = layout_line->start_index + layout_line->length;
+              break;
+            }
+        }
 
       pos->y = logical_rect.y;
       pos->height = logical_rect.height;
@@ -2217,12 +2230,12 @@ pango_layout_index_to_pos (PangoLayout    *layout,
       pos->x = logical_rect.x + x_pos;
 
       if (index < layout_line->start_index + layout_line->length)
-	{
-	  pango_layout_line_index_to_x (layout_line, index, 1, &x_pos);
-	  pos->width = (logical_rect.x + x_pos) - pos->x;
-	}
+        {
+          pango_layout_line_index_to_x (layout_line, index, 1, &x_pos);
+          pos->width = (logical_rect.x + x_pos) - pos->x;
+        }
       else
-	pos->width = 0;
+        pos->width = 0;
     }
 
   _pango_layout_iter_destroy (&iter);
@@ -2230,8 +2243,8 @@ pango_layout_index_to_pos (PangoLayout    *layout,
 
 static void
 pango_layout_line_get_range (PangoLayoutLine *line,
-			     char           **start,
-			     char           **end)
+                             char           **start,
+                             char           **end)
 {
   char *p;
 
@@ -2245,7 +2258,7 @@ pango_layout_line_get_range (PangoLayoutLine *line,
 
 static int *
 pango_layout_line_get_vis2log_map (PangoLayoutLine *line,
-				   gboolean         strong)
+                                   gboolean         strong)
 {
   PangoLayout *layout = line->layout;
   PangoDirection prev_dir;
@@ -2286,39 +2299,39 @@ pango_layout_line_get_vis2log_map (PangoLayoutLine *line,
       /* p is the logical byte index at the start of the run */
 
       if (run_dir == PANGO_DIRECTION_LTR)
-	{
-	  if ((cursor_dir == PANGO_DIRECTION_LTR) ||
-	      (prev_dir == run_dir))
-	    result[pos] = p - start;
-
-	  p = g_utf8_next_char (p);
-
-	  for (i = 1; i < run_n_chars; i++)
-	    {
-	      result[pos + i] = p - start;
-	      p = g_utf8_next_char (p);
-	    }
-
-	  if (cursor_dir == PANGO_DIRECTION_LTR)
-	    result[pos + run_n_chars] = p - start;
-	}
+        {
+          if ((cursor_dir == PANGO_DIRECTION_LTR) ||
+              (prev_dir == run_dir))
+            result[pos] = p - start;
+
+          p = g_utf8_next_char (p);
+
+          for (i = 1; i < run_n_chars; i++)
+            {
+              result[pos + i] = p - start;
+              p = g_utf8_next_char (p);
+            }
+
+          if (cursor_dir == PANGO_DIRECTION_LTR)
+            result[pos + run_n_chars] = p - start;
+        }
       else
-	{
-	  if (cursor_dir == PANGO_DIRECTION_RTL)
-	    result[pos + run_n_chars] = p - start;
+        {
+          if (cursor_dir == PANGO_DIRECTION_RTL)
+            result[pos + run_n_chars] = p - start;
 
-	  p = g_utf8_next_char (p);
+          p = g_utf8_next_char (p);
 
-	  for (i = 1; i < run_n_chars; i++)
-	    {
-	      result[pos + run_n_chars - i] = p - start;
-	      p = g_utf8_next_char (p);
-	    }
+          for (i = 1; i < run_n_chars; i++)
+            {
+              result[pos + run_n_chars - i] = p - start;
+              p = g_utf8_next_char (p);
+            }
 
-	  if ((cursor_dir == PANGO_DIRECTION_RTL) ||
-	      (prev_dir == run_dir))
-	    result[pos] = p - start;
-	}
+          if ((cursor_dir == PANGO_DIRECTION_RTL) ||
+              (prev_dir == run_dir))
+            result[pos] = p - start;
+        }
 
       pos += run_n_chars;
       prev_dir = run_dir;
@@ -2335,7 +2348,7 @@ pango_layout_line_get_vis2log_map (PangoLayoutLine *line,
 
 static int *
 pango_layout_line_get_log2vis_map (PangoLayoutLine *line,
-				   gboolean         strong)
+                                   gboolean         strong)
 {
   gchar *start, *end;
   int *reverse_map;
@@ -2359,7 +2372,7 @@ pango_layout_line_get_log2vis_map (PangoLayoutLine *line,
 
 static PangoDirection
 pango_layout_line_get_char_direction (PangoLayoutLine *layout_line,
-				      int              index)
+                                      int              index)
 {
   GSList *run_list;
 
@@ -2369,7 +2382,7 @@ pango_layout_line_get_char_direction (PangoLayoutLine *layout_line,
       PangoLayoutRun *run = run_list->data;
 
       if (run->item->offset <= index && run->item->offset + run->item->length > index)
-	return run->item->analysis.level % 2 ? PANGO_DIRECTION_RTL : PANGO_DIRECTION_LTR;
+        return run->item->analysis.level % 2 ? PANGO_DIRECTION_RTL : PANGO_DIRECTION_LTR;
 
       run_list = run_list->next;
     }
@@ -2381,11 +2394,10 @@ pango_layout_line_get_char_direction (PangoLayoutLine *layout_line,
 
 /**
  * pango_layout_get_direction:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @index: the byte index of the char
  *
- * Gets the text direction at the given character
- * position in @layout.
+ * Gets the text direction at the given character position in @layout.
  *
  * Returns: the text direction at @index
  *
@@ -2407,26 +2419,27 @@ pango_layout_get_direction (PangoLayout *layout,
 
 /**
  * pango_layout_get_cursor_pos:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @index_: the byte index of the cursor
- * @strong_pos: (out) (allow-none): location to store the strong cursor position
- *                     (may be %NULL)
- * @weak_pos: (out) (allow-none): location to store the weak cursor position (may be %NULL)
+ * @strong_pos: (out) (allow-none): location to store the strong
+ *   cursor position (may be %NULL)
+ * @weak_pos: (out) (allow-none): location to store the weak cursor
+ *   position (may be %NULL)
  *
  * Given an index within a layout, determines the positions that of the
- * strong and weak cursors if the insertion point is at that
- * index. The position of each cursor is stored as a zero-width
- * rectangle. The strong cursor location is the location where
- * characters of the directionality equal to the base direction of the
- * layout are inserted.  The weak cursor location is the location
- * where characters of the directionality opposite to the base
- * direction of the layout are inserted.
- **/
+ * strong and weak cursors if the insertion point is at that index.
+ *
+ * The position of each cursor is stored as a zero-width rectangle.
+ * The strong cursor location is the location where characters of the
+ * directionality equal to the base direction of the layout are inserted.
+ * The weak cursor location is the location where characters of the
+ * directionality opposite to the base direction of the layout are inserted.
+ */
 void
 pango_layout_get_cursor_pos (PangoLayout    *layout,
-			     int             index,
-			     PangoRectangle *strong_pos,
-			     PangoRectangle *weak_pos)
+                             int             index,
+                             PangoRectangle *strong_pos,
+                             PangoRectangle *weak_pos)
 {
   PangoDirection dir1;
   PangoRectangle line_rect;
@@ -2438,7 +2451,7 @@ pango_layout_get_cursor_pos (PangoLayout    *layout,
   g_return_if_fail (index >= 0 && index <= layout->length);
 
   layout_line = pango_layout_index_to_line_and_extents (layout, index,
-							&line_rect);
+                                                        &line_rect);
 
   g_assert (index >= layout_line->start_index);
 
@@ -2447,17 +2460,17 @@ pango_layout_get_cursor_pos (PangoLayout    *layout,
     {
       dir1 = layout_line->resolved_dir;
       if (layout_line->resolved_dir == PANGO_DIRECTION_LTR)
-	x1_trailing = 0;
+        x1_trailing = 0;
       else
-	x1_trailing = line_rect.width;
+        x1_trailing = line_rect.width;
     }
   else if (index >= layout_line->start_index + layout_line->length)
     {
       dir1 = layout_line->resolved_dir;
       if (layout_line->resolved_dir == PANGO_DIRECTION_LTR)
-	x1_trailing = line_rect.width;
+        x1_trailing = line_rect.width;
       else
-	x1_trailing = 0;
+        x1_trailing = 0;
     }
   else
     {
@@ -2470,9 +2483,9 @@ pango_layout_get_cursor_pos (PangoLayout    *layout,
   if (index >= layout_line->start_index + layout_line->length)
     {
       if (layout_line->resolved_dir == PANGO_DIRECTION_LTR)
-	x2 = line_rect.width;
+        x2 = line_rect.width;
       else
-	x2 = 0;
+        x2 = 0;
     }
   else
     {
@@ -2484,9 +2497,9 @@ pango_layout_get_cursor_pos (PangoLayout    *layout,
       strong_pos->x = line_rect.x;
 
       if (dir1 == layout_line->resolved_dir)
-	strong_pos->x += x1_trailing;
+        strong_pos->x += x1_trailing;
       else
-	strong_pos->x += x2;
+        strong_pos->x += x2;
 
       strong_pos->y = line_rect.y;
       strong_pos->width = 0;
@@ -2498,9 +2511,9 @@ pango_layout_get_cursor_pos (PangoLayout    *layout,
       weak_pos->x = line_rect.x;
 
       if (dir1 == layout_line->resolved_dir)
-	weak_pos->x += x2;
+        weak_pos->x += x2;
       else
-	weak_pos->x += x1_trailing;
+        weak_pos->x += x1_trailing;
 
       weak_pos->y = line_rect.y;
       weak_pos->width = 0;
@@ -2531,7 +2544,7 @@ direction_simple (PangoDirection d)
 
 static PangoAlignment
 get_alignment (PangoLayout     *layout,
-	       PangoLayoutLine *line)
+               PangoLayoutLine *line)
 {
   PangoAlignment alignment = layout->alignment;
 
@@ -2540,9 +2553,9 @@ get_alignment (PangoLayout     *layout,
       -direction_simple (pango_context_get_base_dir (layout->context)))
     {
       if (alignment == PANGO_ALIGN_LEFT)
-	alignment = PANGO_ALIGN_RIGHT;
+        alignment = PANGO_ALIGN_RIGHT;
       else if (alignment == PANGO_ALIGN_RIGHT)
-	alignment = PANGO_ALIGN_LEFT;
+        alignment = PANGO_ALIGN_LEFT;
     }
 
   return alignment;
@@ -2550,10 +2563,10 @@ get_alignment (PangoLayout     *layout,
 
 static void
 get_x_offset (PangoLayout     *layout,
-	      PangoLayoutLine *line,
-	      int              layout_width,
-	      int              line_width,
-	      int             *x_offset)
+              PangoLayoutLine *line,
+              int              layout_width,
+              int              line_width,
+              int             *x_offset)
 {
   PangoAlignment alignment = get_alignment (layout, line);
 
@@ -2567,14 +2580,13 @@ get_x_offset (PangoLayout     *layout,
     /* hinting */
     if (((layout_width | line_width) & (PANGO_SCALE - 1)) == 0)
       {
-	*x_offset = PANGO_UNITS_ROUND (*x_offset);
+        *x_offset = PANGO_UNITS_ROUND (*x_offset);
       }
   } else
     *x_offset = 0;
 
   /* Indentation */
 
-
   /* For center, we ignore indentation; I think I've seen word
    * processors that still do the indentation here as if it were
    * indented left/right, though we can't sensibly do that without
@@ -2587,22 +2599,22 @@ get_x_offset (PangoLayout     *layout,
   if (line->is_paragraph_start)
     {
       if (layout->indent > 0)
-	{
-	  if (alignment == PANGO_ALIGN_LEFT)
-	    *x_offset += layout->indent;
-	  else
-	    *x_offset -= layout->indent;
-	}
+        {
+          if (alignment == PANGO_ALIGN_LEFT)
+            *x_offset += layout->indent;
+          else
+            *x_offset -= layout->indent;
+        }
     }
   else
     {
       if (layout->indent < 0)
-	{
-	  if (alignment == PANGO_ALIGN_LEFT)
-	    *x_offset -= layout->indent;
-	  else
-	    *x_offset += layout->indent;
-	}
+        {
+          if (alignment == PANGO_ALIGN_LEFT)
+            *x_offset -= layout->indent;
+          else
+            *x_offset += layout->indent;
+        }
     }
 }
 
@@ -2613,12 +2625,12 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
                                           int            *height);
 static void
 get_line_extents_layout_coords (PangoLayout     *layout,
-				PangoLayoutLine *line,
-				int              layout_width,
-				int              y_offset,
-				int             *baseline,
-				PangoRectangle  *line_ink_layout,
-				PangoRectangle  *line_logical_layout)
+                                PangoLayoutLine *line,
+                                int              layout_width,
+                                int              y_offset,
+                                int             *baseline,
+                                PangoRectangle  *line_ink_layout,
+                                PangoRectangle  *line_logical_layout)
 {
   int x_offset;
   /* Line extents in line coords (origin at line baseline) */
@@ -2668,8 +2680,8 @@ get_line_extents_layout_coords (PangoLayout     *layout,
  */
 static void
 pango_layout_get_extents_internal (PangoLayout    *layout,
-				   PangoRectangle *ink_rect,
-				   PangoRectangle *logical_rect,
+                                   PangoRectangle *ink_rect,
+                                   PangoRectangle *logical_rect,
                                    Extents        **line_extents)
 {
   GSList *line_list;
@@ -2710,14 +2722,14 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
        */
       line_list = layout->lines;
       while (line_list && !need_width)
-	{
-	  PangoLayoutLine *line = line_list->data;
+        {
+          PangoLayoutLine *line = line_list->data;
 
-	  if (get_alignment (layout, line) != PANGO_ALIGN_LEFT)
-	    need_width = TRUE;
+          if (get_alignment (layout, line) != PANGO_ALIGN_LEFT)
+            need_width = TRUE;
 
-	  line_list = line_list->next;
-	}
+          line_list = line_list->next;
+        }
     }
   else if (layout->alignment != PANGO_ALIGN_LEFT)
     need_width = TRUE;
@@ -2757,79 +2769,79 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
 
       /* This block gets the line extents in layout coords */
       {
-	get_line_extents_layout_coords (layout, line,
-					width, y_offset,
-					&baseline,
-					ink_rect ? &line_ink_layout : NULL,
-					&line_logical_layout);
-
-	if (line_extents && layout->line_count > 0)
-	  {
-	    Extents *ext = &(*line_extents)[line_index];
-	    ext->baseline = baseline;
-	    ext->ink_rect = line_ink_layout;
-	    ext->logical_rect = line_logical_layout;
-	  }
+        get_line_extents_layout_coords (layout, line,
+                                        width, y_offset,
+                                        &baseline,
+                                        ink_rect ? &line_ink_layout : NULL,
+                                        &line_logical_layout);
+
+        if (line_extents && layout->line_count > 0)
+          {
+            Extents *ext = &(*line_extents)[line_index];
+            ext->baseline = baseline;
+            ext->ink_rect = line_ink_layout;
+            ext->logical_rect = line_logical_layout;
+          }
       }
 
       if (ink_rect)
-	{
-	  /* Compute the union of the current ink_rect with
-	   * line_ink_layout
-	   */
-
-	  if (line_list == layout->lines)
-	    {
-	      *ink_rect = line_ink_layout;
-	    }
-	  else
-	    {
-	      new_pos = MIN (ink_rect->x, line_ink_layout.x);
-	      ink_rect->width =
-		MAX (ink_rect->x + ink_rect->width,
-		     line_ink_layout.x + line_ink_layout.width) - new_pos;
-	      ink_rect->x = new_pos;
-
-	      new_pos = MIN (ink_rect->y, line_ink_layout.y);
-	      ink_rect->height =
-		MAX (ink_rect->y + ink_rect->height,
-		     line_ink_layout.y + line_ink_layout.height) - new_pos;
-	      ink_rect->y = new_pos;
-	    }
-	}
+        {
+          /* Compute the union of the current ink_rect with
+           * line_ink_layout
+           */
+
+          if (line_list == layout->lines)
+            {
+              *ink_rect = line_ink_layout;
+            }
+          else
+            {
+              new_pos = MIN (ink_rect->x, line_ink_layout.x);
+              ink_rect->width =
+                MAX (ink_rect->x + ink_rect->width,
+                     line_ink_layout.x + line_ink_layout.width) - new_pos;
+              ink_rect->x = new_pos;
+
+              new_pos = MIN (ink_rect->y, line_ink_layout.y);
+              ink_rect->height =
+                MAX (ink_rect->y + ink_rect->height,
+                     line_ink_layout.y + line_ink_layout.height) - new_pos;
+              ink_rect->y = new_pos;
+            }
+        }
 
       if (logical_rect)
-	{
-	  if (layout->width == -1)
-	    {
-	      /* When no width is set on layout, we can just compute the max of the
-	       * line lengths to get the horizontal extents ... logical_rect.x = 0.
-	       */
-	      logical_rect->width = MAX (logical_rect->width, line_logical_layout.width);
-	    }
-	  else
-	    {
-	      /* When a width is set, we have to compute the union of the horizontal
-	       * extents of all the lines.
-	       */
-	      if (line_list == layout->lines)
-		{
-		  logical_rect->x = line_logical_layout.x;
-		  logical_rect->width = line_logical_layout.width;
-		}
-	      else
-		{
-		  new_pos = MIN (logical_rect->x, line_logical_layout.x);
-		  logical_rect->width =
-		    MAX (logical_rect->x + logical_rect->width,
-			 line_logical_layout.x + line_logical_layout.width) - new_pos;
-		  logical_rect->x = new_pos;
-
-		}
-	    }
-
-	  logical_rect->height = line_logical_layout.y + line_logical_layout.height - logical_rect->y;
-	}
+        {
+          if (layout->width == -1)
+            {
+              /* When no width is set on layout, we can just compute the max of the
+               * line lengths to get the horizontal extents ... logical_rect.x = 0.
+               */
+              logical_rect->width = MAX (logical_rect->width, line_logical_layout.width);
+            }
+          else
+            {
+              /* When a width is set, we have to compute the union of the horizontal
+               * extents of all the lines.
+               */
+              if (line_list == layout->lines)
+                {
+                  logical_rect->x = line_logical_layout.x;
+                  logical_rect->width = line_logical_layout.width;
+                }
+              else
+                {
+                  new_pos = MIN (logical_rect->x, line_logical_layout.x);
+                  logical_rect->width =
+                    MAX (logical_rect->x + logical_rect->width,
+                         line_logical_layout.x + line_logical_layout.width) - new_pos;
+                  logical_rect->x = new_pos;
+
+                }
+            }
+
+          logical_rect->height = line_logical_layout.y + line_logical_layout.height - logical_rect->y;
+        }
 
       y_offset = line_logical_layout.y + line_logical_layout.height + layout->spacing;
       line_list = line_list->next;
@@ -2850,28 +2862,27 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
 
 /**
  * pango_layout_get_extents:
- * @layout:   a #PangoLayout
+ * @layout: a `PangoLayout`
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- *                   layout as drawn or %NULL to indicate that the result is
- *                   not needed.
+ *   layout as drawn or %NULL to indicate that the result is not needed.
  * @logical_rect: (out) (allow-none):rectangle used to store the logical
- *                      extents of the layout or %NULL to indicate that the
- *                      result is not needed.
+ *   extents of the layout or %NULL to indicate that the result is not needed.
+ *
+ * Computes the logical and ink extents of @layout.
  *
- * Computes the logical and ink extents of @layout. Logical extents
- * are usually what you want for positioning things.  Note that both extents
- * may have non-zero x and y.  You may want to use those to offset where you
- * render the layout.  Not doing that is a very typical bug that shows up as
- * right-to-left layouts not being correctly positioned in a layout with
- * a set width.
+ * Logical extents are usually what you want for positioning things. Note
+ * that both extents may have non-zero x and y. You may want to use those
+ * to offset where you render the layout. Not doing that is a very typical
+ * bug that shows up as right-to-left layouts not being correctly positioned
+ * in a layout with a set width.
  *
  * The extents are given in layout coordinates and in Pango units; layout
  * coordinates begin at the top left corner of the layout.
  */
 void
 pango_layout_get_extents (PangoLayout    *layout,
-			  PangoRectangle *ink_rect,
-			  PangoRectangle *logical_rect)
+                          PangoRectangle *ink_rect,
+                          PangoRectangle *logical_rect)
 {
   g_return_if_fail (layout != NULL);
 
@@ -2880,24 +2891,23 @@ pango_layout_get_extents (PangoLayout    *layout,
 
 /**
  * pango_layout_get_pixel_extents:
- * @layout:   a #PangoLayout
+ * @layout: a `PangoLayout`
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- *                   layout as drawn or %NULL to indicate that the result is
- *                   not needed.
+ *   layout as drawn or %NULL to indicate that the result is not needed.
  * @logical_rect: (out) (allow-none): rectangle used to store the logical
- *                       extents of the layout or %NULL to indicate that the
- *                       result is not needed.
+ *   extents of the layout or %NULL to indicate that the result is not needed.
  *
  * Computes the logical and ink extents of @layout in device units.
- * This function just calls pango_layout_get_extents() followed by
- * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect
+ *
+ * This function just calls [method@Pango.Layout.get_extents] followed by
+ * two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect
  * such that the rounded rectangles fully contain the unrounded one (that is,
- * passes them as first argument to pango_extents_to_pixels()).
- **/
+ * passes them as first argument to `pango_extents_to_pixels()`).
+ */
 void
-pango_layout_get_pixel_extents (PangoLayout *layout,
-				PangoRectangle *ink_rect,
-				PangoRectangle *logical_rect)
+pango_layout_get_pixel_extents (PangoLayout    *layout,
+                                PangoRectangle *ink_rect,
+                                PangoRectangle *logical_rect)
 {
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
@@ -2908,18 +2918,19 @@ pango_layout_get_pixel_extents (PangoLayout *layout,
 
 /**
  * pango_layout_get_size:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @width: (out) (allow-none): location to store the logical width, or %NULL
  * @height: (out) (allow-none): location to store the logical height, or %NULL
  *
- * Determines the logical width and height of a #PangoLayout
- * in Pango units (device units scaled by %PANGO_SCALE). This
- * is simply a convenience function around pango_layout_get_extents().
- **/
+ * Determines the logical width and height of a `PangoLayout` in Pango
+ * units.
+ *
+ * This is simply a convenience function around [method@Pango.Layout.get_extents].
+ */
 void
 pango_layout_get_size (PangoLayout *layout,
-		       int         *width,
-		       int         *height)
+                       int         *width,
+                       int         *height)
 {
   PangoRectangle logical_rect;
 
@@ -2933,20 +2944,21 @@ pango_layout_get_size (PangoLayout *layout,
 
 /**
  * pango_layout_get_pixel_size:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @width: (out) (allow-none): location to store the logical width, or %NULL
  * @height: (out) (allow-none): location to store the logical height, or %NULL
  *
- * Determines the logical width and height of a #PangoLayout
- * in device units. (pango_layout_get_size() returns the width
- * and height scaled by %PANGO_SCALE.) This
- * is simply a convenience function around
- * pango_layout_get_pixel_extents().
- **/
+ * Determines the logical width and height of a `PangoLayout` in device
+ * units.
+ *
+ * [method@Pango.Layout.get_size] returns the width and height
+ * scaled by %PANGO_SCALE. This is simply a convenience function around
+ * [method@Pango.Layout.get_pixel_extents].
+ */
 void
 pango_layout_get_pixel_size (PangoLayout *layout,
-			     int         *width,
-			     int         *height)
+                             int         *width,
+                             int         *height)
 {
   PangoRectangle logical_rect;
 
@@ -2961,16 +2973,16 @@ pango_layout_get_pixel_size (PangoLayout *layout,
 
 /**
  * pango_layout_get_baseline:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Gets the Y position of baseline of the first line in @layout.
  *
  * Return value: baseline of first line, from top of @layout.
  *
  * Since: 1.22
- **/
+ */
 int
-pango_layout_get_baseline (PangoLayout    *layout)
+pango_layout_get_baseline (PangoLayout *layout)
 {
   int baseline;
   Extents *extents = NULL;
@@ -2991,13 +3003,13 @@ pango_layout_clear_lines (PangoLayout *layout)
     {
       GSList *tmp_list = layout->lines;
       while (tmp_list)
-	{
-	  PangoLayoutLine *line = tmp_list->data;
-	  tmp_list = tmp_list->next;
+        {
+          PangoLayoutLine *line = tmp_list->data;
+          tmp_list = tmp_list->next;
 
-	  line->layout = NULL;
-	  pango_layout_line_unref (line);
-	}
+          line->layout = NULL;
+          pango_layout_line_unref (line);
+        }
 
       g_slist_free (layout->lines);
       layout->lines = NULL;
@@ -3038,7 +3050,7 @@ pango_layout_line_leaked (PangoLayoutLine *line)
 
 static void shape_tab (PangoLayoutLine  *line,
                        PangoItem        *item,
-		       PangoGlyphString *glyphs);
+                       PangoGlyphString *glyphs);
 
 static void
 free_run (PangoLayoutRun *run, gpointer data)
@@ -3138,7 +3150,7 @@ ensure_tab_width (PangoLayout *layout)
        * problems with the font.
        */
       if (layout->tab_width <= 0)
-	layout->tab_width = 50 * PANGO_SCALE; /* pretty much arbitrary */
+        layout->tab_width = 50 * PANGO_SCALE; /* pretty much arbitrary */
     }
 }
 
@@ -3146,7 +3158,9 @@ ensure_tab_width (PangoLayout *layout)
  * all tabs are left-aligned.
  */
 static int
-get_tab_pos (PangoLayout *layout, int index, gboolean *is_default)
+get_tab_pos (PangoLayout *layout,
+             int          index,
+             gboolean    *is_default)
 {
   gint n_tabs;
   gboolean in_pixels;
@@ -3156,14 +3170,14 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default)
       n_tabs = pango_tab_array_get_size (layout->tabs);
       in_pixels = pango_tab_array_get_positions_in_pixels (layout->tabs);
       if (is_default)
-	*is_default = FALSE;
+        *is_default = FALSE;
     }
   else
     {
       n_tabs = 0;
       in_pixels = FALSE;
       if (is_default)
-	*is_default = TRUE;
+        *is_default = TRUE;
     }
 
   if (index < n_tabs)
@@ -3173,9 +3187,9 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default)
       pango_tab_array_get_tab (layout->tabs, index, NULL, &pos);
 
       if (in_pixels)
-	return pos * PANGO_SCALE;
+        return pos * PANGO_SCALE;
       else
-	return pos;
+        return pos;
     }
 
   if (n_tabs > 0)
@@ -3190,24 +3204,24 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default)
       pango_tab_array_get_tab (layout->tabs, n_tabs - 1, NULL, &last_pos);
 
       if (n_tabs > 1)
-	pango_tab_array_get_tab (layout->tabs, n_tabs - 2, NULL, &next_to_last_pos);
+        pango_tab_array_get_tab (layout->tabs, n_tabs - 2, NULL, &next_to_last_pos);
       else
-	next_to_last_pos = 0;
+        next_to_last_pos = 0;
 
       if (in_pixels)
-	{
-	  next_to_last_pos *= PANGO_SCALE;
-	  last_pos *= PANGO_SCALE;
-	}
+        {
+          next_to_last_pos *= PANGO_SCALE;
+          last_pos *= PANGO_SCALE;
+        }
 
       if (last_pos > next_to_last_pos)
-	{
-	  tab_width = last_pos - next_to_last_pos;
-	}
+        {
+          tab_width = last_pos - next_to_last_pos;
+        }
       else
-	{
-	  tab_width = layout->tab_width;
-	}
+        {
+          tab_width = layout->tab_width;
+        }
 
       return last_pos + tab_width * (index - n_tabs + 1);
     }
@@ -3234,7 +3248,7 @@ line_width (PangoLayoutLine *line)
       PangoLayoutRun *run = l->data;
 
       for (i=0; i < run->glyphs->num_glyphs; i++)
-	width += run->glyphs->glyphs[i].geometry.width;
+        width += run->glyphs->glyphs[i].geometry.width;
     }
 
   return width;
@@ -3260,7 +3274,7 @@ showing_space (const PangoAnalysis *analysis)
 static void
 shape_tab (PangoLayoutLine  *line,
            PangoItem        *item,
-	   PangoGlyphString *glyphs)
+           PangoGlyphString *glyphs)
 {
   int i, space_width;
 
@@ -3292,17 +3306,17 @@ shape_tab (PangoLayoutLine  *line,
        * the pixel.
        */
       if (tab_pos >= current_width + (is_default ? space_width : 1))
-	{
-	  glyphs->glyphs[0].geometry.width = tab_pos - current_width;
-	  break;
-	}
+        {
+          glyphs->glyphs[0].geometry.width = tab_pos - current_width;
+          break;
+        }
     }
 }
 
 static inline gboolean
 can_break_at (PangoLayout *layout,
-	      gint         offset,
-	      gboolean     always_wrap_char)
+              gint         offset,
+              gboolean     always_wrap_char)
 {
   PangoWrapMode wrap;
   /* We probably should have a mode where we treat all white-space as
@@ -3329,9 +3343,9 @@ can_break_at (PangoLayout *layout,
 
 static inline gboolean
 can_break_in (PangoLayout *layout,
-	      int          start_offset,
-	      int          num_chars,
-	      gboolean     allow_break_at_start)
+              int          start_offset,
+              int          num_chars,
+              gboolean     allow_break_at_start)
 {
   int i;
 
@@ -3344,8 +3358,8 @@ can_break_in (PangoLayout *layout,
 
 static inline void
 distribute_letter_spacing (int  letter_spacing,
-			   int *space_left,
-			   int *space_right)
+                           int *space_left,
+                           int *space_right)
 {
   *space_left = letter_spacing / 2;
   /* hinting */
@@ -3368,41 +3382,41 @@ typedef enum
 struct _ParaBreakState
 {
   /* maintained per layout */
-  int line_height;		/* Estimate of height of current line; < 0 is no estimate */
-  int remaining_height;		/* Remaining height of the layout;  only defined if layout->height >= 0 */
+  int line_height;              /* Estimate of height of current line; < 0 is no estimate */
+  int remaining_height;         /* Remaining height of the layout;  only defined if layout->height >= 0 */
 
   /* maintained per paragraph */
-  PangoAttrList *attrs;		/* Attributes being used for itemization */
-  GList *items;			/* This paragraph turned into items */
-  PangoDirection base_dir;	/* Current resolved base direction */
-  int line_of_par;		/* Line of the paragraph, starting at 1 for first line */
-
-  PangoGlyphString *glyphs;	/* Glyphs for the first item in state->items */
-  int start_offset;		/* Character offset of first item in state->items in layout->text */
-  ItemProperties properties;	/* Properties for the first item in state->items */
-  int *log_widths;		/* Logical widths for first item in state->items.. */
+  PangoAttrList *attrs;         /* Attributes being used for itemization */
+  GList *items;                 /* This paragraph turned into items */
+  PangoDirection base_dir;      /* Current resolved base direction */
+  int line_of_par;              /* Line of the paragraph, starting at 1 for first line */
+
+  PangoGlyphString *glyphs;     /* Glyphs for the first item in state->items */
+  int start_offset;             /* Character offset of first item in state->items in layout->text */
+  ItemProperties properties;    /* Properties for the first item in state->items */
+  int *log_widths;              /* Logical widths for first item in state->items.. */
   int log_widths_offset;        /* Offset into log_widths to the point corresponding
-				 * to the remaining portion of the first item */
+                                 * to the remaining portion of the first item */
 
   int *need_hyphen;             /* Insert a hyphen if breaking here ? */
-  int line_start_index;		/* Start index (byte offset) of line in layout->text */
-  int line_start_offset;	/* Character offset of line in layout->text */
+  int line_start_index;         /* Start index (byte offset) of line in layout->text */
+  int line_start_offset;        /* Character offset of line in layout->text */
 
   /* maintained per line */
-  int line_width;		/* Goal width of line currently processing; < 0 is infinite */
-  int remaining_width;		/* Amount of space remaining on line; < 0 is infinite */
+  int line_width;               /* Goal width of line currently processing; < 0 is infinite */
+  int remaining_width;          /* Amount of space remaining on line; < 0 is infinite */
 
   int hyphen_width;             /* How much space a hyphen will take */
 };
 
 static gboolean
 should_ellipsize_current_line (PangoLayout    *layout,
-			       ParaBreakState *state);
+                               ParaBreakState *state);
 
 static PangoGlyphString *
 shape_run (PangoLayoutLine *line,
-	   ParaBreakState  *state,
-	   PangoItem       *item)
+           ParaBreakState  *state,
+           PangoItem       *item)
 {
   PangoLayout *layout = line->layout;
   PangoGlyphString *glyphs = pango_glyph_string_new ();
@@ -3417,9 +3431,9 @@ shape_run (PangoLayoutLine *line,
         shape_flags |= PANGO_SHAPE_ROUND_POSITIONS;
 
       if (state->properties.shape_set)
-	_pango_shape_shape (layout->text + item->offset, item->num_chars,
-			    state->properties.shape_ink_rect, state->properties.shape_logical_rect,
-			    glyphs);
+        _pango_shape_shape (layout->text + item->offset, item->num_chars,
+                            state->properties.shape_ink_rect, state->properties.shape_logical_rect,
+                            glyphs);
       else
         pango_shape_with_flags (layout->text + item->offset, item->length,
                                 layout->text, layout->length,
@@ -3427,24 +3441,24 @@ shape_run (PangoLayoutLine *line,
                                 shape_flags);
 
       if (state->properties.letter_spacing)
-	{
-	  PangoGlyphItem glyph_item;
-	  int space_left, space_right;
+        {
+          PangoGlyphItem glyph_item;
+          int space_left, space_right;
 
-	  glyph_item.item = item;
-	  glyph_item.glyphs = glyphs;
+          glyph_item.item = item;
+          glyph_item.glyphs = glyphs;
 
-	  pango_glyph_item_letter_space (&glyph_item,
-					 layout->text,
-					 layout->log_attrs + state->start_offset,
-					 state->properties.letter_spacing);
+          pango_glyph_item_letter_space (&glyph_item,
+                                         layout->text,
+                                         layout->log_attrs + state->start_offset,
+                                         state->properties.letter_spacing);
 
-	  distribute_letter_spacing (state->properties.letter_spacing, &space_left, &space_right);
+          distribute_letter_spacing (state->properties.letter_spacing, &space_left, &space_right);
 
-	  glyphs->glyphs[0].geometry.width += space_left;
-	  glyphs->glyphs[0].geometry.x_offset += space_left;
-	  glyphs->glyphs[glyphs->num_glyphs - 1].geometry.width += space_right;
-	}
+          glyphs->glyphs[0].geometry.width += space_left;
+          glyphs->glyphs[0].geometry.x_offset += space_left;
+          glyphs->glyphs[glyphs->num_glyphs - 1].geometry.width += space_right;
+        }
     }
 
   return glyphs;
@@ -3452,9 +3466,9 @@ shape_run (PangoLayoutLine *line,
 
 static void
 insert_run (PangoLayoutLine *line,
-	    ParaBreakState  *state,
-	    PangoItem       *run_item,
-	    gboolean         last_run)
+            ParaBreakState  *state,
+            PangoItem       *run_item,
+            gboolean         last_run)
 {
   PangoLayoutRun *run = g_slice_new (PangoLayoutRun);
 
@@ -3468,7 +3482,7 @@ insert_run (PangoLayoutLine *line,
   if (last_run)
     {
       if (state->log_widths_offset > 0)
-	pango_glyph_string_free (state->glyphs);
+        pango_glyph_string_free (state->glyphs);
       state->glyphs = NULL;
       g_free (state->log_widths);
       state->log_widths = NULL;
@@ -3524,19 +3538,19 @@ get_need_hyphen (PangoItem  *item,
           if (attr)
             insert_hyphens = ((PangoAttrInt*)attr)->value;
 
-	  /* Some scripts don't use hyphen.*/
-	  switch (item->analysis.script)
-	    {
-	    case PANGO_SCRIPT_COMMON:
-	    case PANGO_SCRIPT_HAN:
-	    case PANGO_SCRIPT_HANGUL:
-	    case PANGO_SCRIPT_HIRAGANA:
-	    case PANGO_SCRIPT_KATAKANA:
-	      insert_hyphens = FALSE;
-	      break;
-	    default:
-	      break;
-	    }
+          /* Some scripts don't use hyphen.*/
+          switch (item->analysis.script)
+            {
+            case PANGO_SCRIPT_COMMON:
+            case PANGO_SCRIPT_HAN:
+            case PANGO_SCRIPT_HANGUL:
+            case PANGO_SCRIPT_HIRAGANA:
+            case PANGO_SCRIPT_KATAKANA:
+              insert_hyphens = FALSE;
+              break;
+            default:
+              break;
+            }
         }
 
       switch (g_unichar_type (wc))
@@ -3627,7 +3641,7 @@ find_hyphen_width (PangoItem *item)
 
 static int
 find_break_extra_width (PangoLayout    *layout,
-	                ParaBreakState *state,
+                        ParaBreakState *state,
                         int             pos)
 {
   /* Check whether to insert a hyphen */
@@ -3652,11 +3666,11 @@ debug (const char *where, PangoLayoutLine *line, ParaBreakState *state)
 {
   int line_width = pango_layout_line_get_width (line);
 
-  g_debug ("rem %d + line %d = %d		%s",
-	   state->remaining_width,
-	   line_width,
-	   state->remaining_width + line_width,
-	   where);
+  g_debug ("rem %d + line %d = %d               %s",
+           state->remaining_width,
+           line_width,
+           state->remaining_width + line_width,
+           where);
 }
 #else
 # define DEBUG(where, line, state) do { } while (0)
@@ -3683,10 +3697,10 @@ debug (const char *where, PangoLayoutLine *line, ParaBreakState *state)
  */
 static BreakResult
 process_item (PangoLayout     *layout,
-	      PangoLayoutLine *line,
-	      ParaBreakState  *state,
-	      gboolean         force_fit,
-	      gboolean         no_break_at_end)
+              PangoLayoutLine *line,
+              ParaBreakState  *state,
+              gboolean         force_fit,
+              gboolean         no_break_at_end)
 {
   PangoItem *item = state->items->data;
   gboolean shape_set = FALSE;
@@ -3737,7 +3751,7 @@ process_item (PangoLayout     *layout,
   else
     {
       for (i = 0; i < item->num_chars; i++)
-	width += state->log_widths[state->log_widths_offset + i];
+        width += state->log_widths[state->log_widths_offset + i];
     }
 
   if ((width <= state->remaining_width || (item->num_chars == 1 && !line->runs)) &&
@@ -3759,13 +3773,13 @@ process_item (PangoLayout     *layout,
       gboolean retrying_with_char_breaks = FALSE;
 
       if (processing_new_item)
-	{
-	  PangoGlyphItem glyph_item = {item, state->glyphs};
-	  state->log_widths = g_new (int, item->num_chars);
-	  pango_glyph_item_get_logical_widths (&glyph_item, layout->text, state->log_widths);
-	  state->need_hyphen = g_new (int, item->num_chars);
+        {
+          PangoGlyphItem glyph_item = {item, state->glyphs};
+          state->log_widths = g_new (int, item->num_chars);
+          pango_glyph_item_get_logical_widths (&glyph_item, layout->text, state->log_widths);
+          state->need_hyphen = g_new (int, item->num_chars);
           get_need_hyphen (item, layout->text, state->need_hyphen);
-	}
+        }
 
     retry_break:
 
@@ -3773,103 +3787,103 @@ process_item (PangoLayout     *layout,
       width = 0;
       extra_width = 0;
       for (num_chars = 0; num_chars < item->num_chars; num_chars++)
-	{
-	  if (width + extra_width > state->remaining_width && break_num_chars < item->num_chars)
+        {
+          if (width + extra_width > state->remaining_width && break_num_chars < item->num_chars)
             {
               break;
             }
 
-	  /* If there are no previous runs we have to take care to grab at least one char. */
-	  if (can_break_at (layout, state->start_offset + num_chars, retrying_with_char_breaks) &&
-	      (num_chars > 0 || line->runs))
-	    {
-	      break_num_chars = num_chars;
-	      break_width = width;
+          /* If there are no previous runs we have to take care to grab at least one char. */
+          if (can_break_at (layout, state->start_offset + num_chars, retrying_with_char_breaks) &&
+              (num_chars > 0 || line->runs))
+            {
+              break_num_chars = num_chars;
+              break_width = width;
               break_extra_width = extra_width;
 
               extra_width = find_break_extra_width (layout, state, num_chars);
-	    }
+            }
           else
             extra_width = 0;
 
-	  width += state->log_widths[state->log_widths_offset + num_chars];
-	}
+          width += state->log_widths[state->log_widths_offset + num_chars];
+        }
 
       /* If there's a space at the end of the line, include that also.
        * The logic here should match zero_line_final_space().
        * XXX Currently it doesn't quite match the logic there.  We don't check
        * the cluster here.  But should be fine in practice. */
       if (break_num_chars > 0 && break_num_chars < item->num_chars &&
-	  layout->log_attrs[state->start_offset + break_num_chars - 1].is_white)
+          layout->log_attrs[state->start_offset + break_num_chars - 1].is_white)
       {
-	  break_width -= state->log_widths[state->log_widths_offset + break_num_chars - 1];
+          break_width -= state->log_widths[state->log_widths_offset + break_num_chars - 1];
       }
 
       if (layout->wrap == PANGO_WRAP_WORD_CHAR && force_fit && break_width + break_extra_width > state->remaining_width && !retrying_with_char_breaks)
-	{
-	  retrying_with_char_breaks = TRUE;
-	  num_chars = item->num_chars;
-	  width = orig_width;
-	  break_num_chars = num_chars;
-	  break_width = width;
-	  goto retry_break;
-	}
-
-      if (force_fit || break_width + break_extra_width <= state->remaining_width)	/* Successfully broke the item */
-	{
-	  if (state->remaining_width >= 0)
-	    {
-	      state->remaining_width -= break_width;
-	      state->remaining_width = MAX (state->remaining_width, 0);
-	    }
-
-	  if (break_num_chars == item->num_chars)
-	    {
+        {
+          retrying_with_char_breaks = TRUE;
+          num_chars = item->num_chars;
+          width = orig_width;
+          break_num_chars = num_chars;
+          break_width = width;
+          goto retry_break;
+        }
+
+      if (force_fit || break_width + break_extra_width <= state->remaining_width)       /* Successfully broke the item */
+        {
+          if (state->remaining_width >= 0)
+            {
+              state->remaining_width -= break_width;
+              state->remaining_width = MAX (state->remaining_width, 0);
+            }
+
+          if (break_num_chars == item->num_chars)
+            {
               if (break_needs_hyphen (layout, state, break_num_chars))
                 item->analysis.flags |= PANGO_ANALYSIS_FLAG_NEED_HYPHEN;
-	      insert_run (line, state, item, TRUE);
+              insert_run (line, state, item, TRUE);
 
-	      return BREAK_ALL_FIT;
-	    }
-	  else if (break_num_chars == 0)
-	    {
-	      return BREAK_EMPTY_FIT;
-	    }
-	  else
-	    {
-	      PangoItem *new_item;
+              return BREAK_ALL_FIT;
+            }
+          else if (break_num_chars == 0)
+            {
+              return BREAK_EMPTY_FIT;
+            }
+          else
+            {
+              PangoItem *new_item;
 
-	      length = g_utf8_offset_to_pointer (layout->text + item->offset, break_num_chars) - (layout->text + item->offset);
+              length = g_utf8_offset_to_pointer (layout->text + item->offset, break_num_chars) - (layout->text + item->offset);
 
-	      new_item = pango_item_split (item, length, break_num_chars);
+              new_item = pango_item_split (item, length, break_num_chars);
 
               if (break_needs_hyphen (layout, state, break_num_chars))
                 new_item->analysis.flags |= PANGO_ANALYSIS_FLAG_NEED_HYPHEN;
-	      /* Add the width back, to the line, reshape, subtract the new width */
-	      state->remaining_width += break_width;
-	      insert_run (line, state, new_item, FALSE);
-	      break_width = pango_glyph_string_get_width (((PangoGlyphItem *)(line->runs->data))->glyphs);
-	      state->remaining_width -= break_width;
+              /* Add the width back, to the line, reshape, subtract the new width */
+              state->remaining_width += break_width;
+              insert_run (line, state, new_item, FALSE);
+              break_width = pango_glyph_string_get_width (((PangoGlyphItem *)(line->runs->data))->glyphs);
+              state->remaining_width -= break_width;
 
-	      state->log_widths_offset += break_num_chars;
+              state->log_widths_offset += break_num_chars;
 
-	      /* Shaped items should never be broken */
-	      g_assert (!shape_set);
+              /* Shaped items should never be broken */
+              g_assert (!shape_set);
 
-	      return BREAK_SOME_FIT;
-	    }
-	}
+              return BREAK_SOME_FIT;
+            }
+        }
       else
-	{
-	  pango_glyph_string_free (state->glyphs);
-	  state->glyphs = NULL;
-	  g_free (state->log_widths);
-	  state->log_widths = NULL;
-	  g_free (state->need_hyphen);
-	  state->need_hyphen = NULL;
-
-	  return BREAK_NONE_FIT;
-	}
+        {
+          pango_glyph_string_free (state->glyphs);
+          state->glyphs = NULL;
+          g_free (state->log_widths);
+          state->log_widths = NULL;
+          g_free (state->need_hyphen);
+          state->need_hyphen = NULL;
+
+          return BREAK_NONE_FIT;
+        }
     }
 }
 
@@ -3878,7 +3892,7 @@ process_item (PangoLayout     *layout,
  */
 static void
 line_set_resolved_dir (PangoLayoutLine *line,
-		       PangoDirection   direction)
+                       PangoDirection   direction)
 {
   switch (direction)
     {
@@ -3897,14 +3911,14 @@ line_set_resolved_dir (PangoLayoutLine *line,
     }
 
   /* The direction vs. gravity dance:
-   *	- If gravity is SOUTH, leave direction untouched.
-   *	- If gravity is NORTH, switch direction.
-   *	- If gravity is EAST, set to LTR, as
-   *	  it's a clockwise-rotated layout, so the rotated
-   *	  top is unrotated left.
-   *	- If gravity is WEST, set to RTL, as
-   *	  it's a counter-clockwise-rotated layout, so the rotated
-   *	  top is unrotated right.
+   *    - If gravity is SOUTH, leave direction untouched.
+   *    - If gravity is NORTH, switch direction.
+   *    - If gravity is EAST, set to LTR, as
+   *      it's a clockwise-rotated layout, so the rotated
+   *      top is unrotated left.
+   *    - If gravity is WEST, set to RTL, as
+   *      it's a counter-clockwise-rotated layout, so the rotated
+   *      top is unrotated right.
    *
    * A similar dance is performed in pango-context.c:
    * itemize_state_add_character().  Keep in synch.
@@ -3917,8 +3931,8 @@ line_set_resolved_dir (PangoLayoutLine *line,
       break;
     case PANGO_GRAVITY_NORTH:
       line->resolved_dir = PANGO_DIRECTION_LTR
-			 + PANGO_DIRECTION_RTL
-			 - line->resolved_dir;
+                         + PANGO_DIRECTION_RTL
+                         - line->resolved_dir;
       break;
     case PANGO_GRAVITY_EAST:
       /* This is in fact why deprecated TTB_RTL is LTR */
@@ -3932,19 +3946,19 @@ line_set_resolved_dir (PangoLayoutLine *line,
 }
 
 static gboolean
-should_ellipsize_current_line (PangoLayout    *layout, 
-			       ParaBreakState *state)
+should_ellipsize_current_line (PangoLayout    *layout,
+                               ParaBreakState *state)
 {
   if (G_LIKELY (layout->ellipsize == PANGO_ELLIPSIZE_NONE || layout->width < 0))
     return FALSE;
-  
 
   if (layout->height >= 0)
     {
       /* state->remaining_height is height of layout left */
 
       /* if we can't stuff two more lines at the current guess of line height,
-       * the line we are going to produce is going to be the last line */
+       * the line we are going to produce is going to be the last line
+       */
       return state->line_height * 2 > state->remaining_height;
     }
   else
@@ -3956,7 +3970,7 @@ should_ellipsize_current_line (PangoLayout    *layout,
 
 static void
 add_line (PangoLayoutLine *line,
-	  ParaBreakState  *state)
+          ParaBreakState  *state)
 {
   PangoLayout *layout = line->layout;
 
@@ -3976,13 +3990,13 @@ add_line (PangoLayoutLine *line,
 
 static void
 process_line (PangoLayout    *layout,
-	      ParaBreakState *state)
+              ParaBreakState *state)
 {
   PangoLayoutLine *line;
 
   gboolean have_break = FALSE;      /* If we've seen a possible break yet */
   int break_remaining_width = 0;    /* Remaining width before adding run with break */
-  int break_start_offset = 0;	    /* Start offset before adding run with break */
+  int break_start_offset = 0;       /* Start offset before adding run with break */
   GSList *break_link = NULL;        /* Link holding run before break */
   gboolean wrapped = FALSE;         /* If we had to wrap the line */
 
@@ -3995,9 +4009,9 @@ process_line (PangoLayout    *layout,
   if (state->line_width >= 0 && layout->alignment != PANGO_ALIGN_CENTER)
     {
       if (line->is_paragraph_start && layout->indent >= 0)
-	state->line_width -= layout->indent;
+        state->line_width -= layout->indent;
       else if (!line->is_paragraph_start && layout->indent < 0)
-	state->line_width += layout->indent;
+        state->line_width += layout->indent;
 
       if (state->line_width < 0)
         state->line_width = 0;
@@ -4024,58 +4038,58 @@ process_line (PangoLayout    *layout,
       result = process_item (layout, line, state, !have_break, FALSE);
 
       switch (result)
-	{
-	case BREAK_ALL_FIT:
-	  if (can_break_in (layout, state->start_offset, old_num_chars, first_item_in_line))
-	    {
-	      have_break = TRUE;
-	      break_remaining_width = old_remaining_width;
-	      break_start_offset = state->start_offset;
-	      break_link = line->runs->next;
-	    }
+        {
+        case BREAK_ALL_FIT:
+          if (can_break_in (layout, state->start_offset, old_num_chars, first_item_in_line))
+            {
+              have_break = TRUE;
+              break_remaining_width = old_remaining_width;
+              break_start_offset = state->start_offset;
+              break_link = line->runs->next;
+            }
 
-	  state->items = g_list_delete_link (state->items, state->items);
-	  state->start_offset += old_num_chars;
+          state->items = g_list_delete_link (state->items, state->items);
+          state->start_offset += old_num_chars;
 
-	  break;
+          break;
 
-	case BREAK_EMPTY_FIT:
-	  wrapped = TRUE;
-	  goto done;
+        case BREAK_EMPTY_FIT:
+          wrapped = TRUE;
+          goto done;
 
-	case BREAK_SOME_FIT:
-	  state->start_offset += old_num_chars - item->num_chars;
-	  wrapped = TRUE;
-	  goto done;
+        case BREAK_SOME_FIT:
+          state->start_offset += old_num_chars - item->num_chars;
+          wrapped = TRUE;
+          goto done;
 
-	case BREAK_NONE_FIT:
-	  /* Back up over unused runs to run where there is a break */
-	  while (line->runs && line->runs != break_link)
-	    state->items = g_list_prepend (state->items, uninsert_run (line));
+        case BREAK_NONE_FIT:
+          /* Back up over unused runs to run where there is a break */
+          while (line->runs && line->runs != break_link)
+            state->items = g_list_prepend (state->items, uninsert_run (line));
 
-	  state->start_offset = break_start_offset;
-	  state->remaining_width = break_remaining_width;
+          state->start_offset = break_start_offset;
+          state->remaining_width = break_remaining_width;
 
-	  /* Reshape run to break */
-	  item = state->items->data;
+          /* Reshape run to break */
+          item = state->items->data;
 
-	  old_num_chars = item->num_chars;
-	  result = process_item (layout, line, state, TRUE, TRUE);
-	  g_assert (result == BREAK_SOME_FIT || result == BREAK_EMPTY_FIT);
+          old_num_chars = item->num_chars;
+          result = process_item (layout, line, state, TRUE, TRUE);
+          g_assert (result == BREAK_SOME_FIT || result == BREAK_EMPTY_FIT);
 
-	  state->start_offset += old_num_chars - item->num_chars;
+          state->start_offset += old_num_chars - item->num_chars;
 
-	  wrapped = TRUE;
-	  goto done;
+          wrapped = TRUE;
+          goto done;
 
-	case BREAK_LINE_SEPARATOR:
-	  state->items = g_list_delete_link (state->items, state->items);
-	  state->start_offset += old_num_chars;
-	  /* A line-separate is just a forced break.  Set wrapped, so we do
-	   * justification */
-	  wrapped = TRUE;
-	  goto done;
-	}
+        case BREAK_LINE_SEPARATOR:
+          state->items = g_list_delete_link (state->items, state->items);
+          state->start_offset += old_num_chars;
+          /* A line-separate is just a forced break.  Set wrapped, so we do
+           * justification */
+          wrapped = TRUE;
+          goto done;
+        }
     }
 
  done:
@@ -4090,8 +4104,8 @@ static void
 get_items_log_attrs (const char   *text,
                      int           start,
                      int           length,
-		     GList        *items,
-		     PangoLogAttr *log_attrs,
+                     GList        *items,
+                     PangoLogAttr *log_attrs,
                      int           log_attrs_len)
 {
   int offset = 0;
@@ -4304,7 +4318,7 @@ pango_layout_check_lines (PangoLayout *layout)
     {
       prev_base_dir = pango_find_base_dir (layout->text, layout->length);
       if (prev_base_dir == PANGO_DIRECTION_NEUTRAL)
-	prev_base_dir = pango_context_get_base_dir (layout->context);
+        prev_base_dir = pango_context_get_base_dir (layout->context);
     }
   else
     base_dir = pango_context_get_base_dir (layout->context);
@@ -4326,50 +4340,50 @@ pango_layout_check_lines (PangoLayout *layout)
       int delimiter_index, next_para_index;
 
       if (layout->single_paragraph)
-	{
-	  delimiter_index = layout->length;
-	  next_para_index = layout->length;
-	}
+        {
+          delimiter_index = layout->length;
+          next_para_index = layout->length;
+        }
       else
-	{
-	  pango_find_paragraph_boundary (start,
-					 (layout->text + layout->length) - start,
-					 &delimiter_index,
-					 &next_para_index);
-	}
+        {
+          pango_find_paragraph_boundary (start,
+                                         (layout->text + layout->length) - start,
+                                         &delimiter_index,
+                                         &next_para_index);
+        }
 
       g_assert (next_para_index >= delimiter_index);
 
       if (layout->auto_dir)
-	{
-	  base_dir = pango_find_base_dir (start, delimiter_index);
+        {
+          base_dir = pango_find_base_dir (start, delimiter_index);
 
-	  /* Propagate the base direction for neutral paragraphs */
-	  if (base_dir == PANGO_DIRECTION_NEUTRAL)
-	    base_dir = prev_base_dir;
-	  else
-	    prev_base_dir = base_dir;
-	}
+          /* Propagate the base direction for neutral paragraphs */
+          if (base_dir == PANGO_DIRECTION_NEUTRAL)
+            base_dir = prev_base_dir;
+          else
+            prev_base_dir = base_dir;
+        }
 
       end = start + delimiter_index;
 
       delim_len = next_para_index - delimiter_index;
 
       if (end == (layout->text + layout->length))
-	done = TRUE;
+        done = TRUE;
 
       g_assert (end <= (layout->text + layout->length));
       g_assert (start <= (layout->text + layout->length));
-      g_assert (delim_len < 4);	/* PS is 3 bytes */
+      g_assert (delim_len < 4); /* PS is 3 bytes */
       g_assert (delim_len >= 0);
 
       state.attrs = itemize_attrs;
       state.items = pango_itemize_with_base_dir (layout->context,
-						 base_dir,
-						 layout->text,
-						 start - layout->text,
-						 end - start,
-						 itemize_attrs,
+                                                 base_dir,
+                                                 layout->text,
+                                                 start - layout->text,
+                                                 end - start,
+                                                 itemize_attrs,
                                                  itemize_attrs ? &iter : NULL);
 
       apply_attributes_to_items (state.items, shape_attrs);
@@ -4378,7 +4392,7 @@ pango_layout_check_lines (PangoLayout *layout)
                            start - layout->text,
                            delimiter_index + delim_len,
                            state.items,
-			   layout->log_attrs + start_offset,
+                           layout->log_attrs + start_offset,
                            layout->n_chars + 1 - start_offset);
 
       state.base_dir = base_dir;
@@ -4399,27 +4413,27 @@ pango_layout_check_lines (PangoLayout *layout)
       state.hyphen_width = -1;
 
       if (state.items)
-	{
-	  while (state.items)
-	    process_line (layout, &state);
-	}
+        {
+          while (state.items)
+            process_line (layout, &state);
+        }
       else
-	{
-	  PangoLayoutLine *empty_line;
+        {
+          PangoLayoutLine *empty_line;
 
-	  empty_line = pango_layout_line_new (layout);
-	  empty_line->start_index = state.line_start_index;
-	  empty_line->is_paragraph_start = TRUE;
-	  line_set_resolved_dir (empty_line, base_dir);
+          empty_line = pango_layout_line_new (layout);
+          empty_line->start_index = state.line_start_index;
+          empty_line->is_paragraph_start = TRUE;
+          line_set_resolved_dir (empty_line, base_dir);
 
-	  add_line (empty_line, &state);
-	}
+          add_line (empty_line, &state);
+        }
 
       if (layout->height >= 0 && state.remaining_height < state.line_height)
-	done = TRUE;
+        done = TRUE;
 
       if (!done)
-	start_offset += pango_utf8_strlen (start, (end - start) + delim_len);
+        start_offset += pango_utf8_strlen (start, (end - start) + delim_len);
 
       start = end + delim_len;
     }
@@ -4442,14 +4456,14 @@ pango_layout_check_lines (PangoLayout *layout)
 
 /**
  * pango_layout_line_ref:
- * @line: (nullable): a #PangoLayoutLine, may be %NULL
+ * @line: (nullable): a `PangoLayoutLine`, may be %NULL
  *
- * Increase the reference count of a #PangoLayoutLine by one.
+ * Increase the reference count of a `PangoLayoutLine` by one.
  *
  * Return value: the line passed in.
  *
  * Since: 1.10
- **/
+ */
 PangoLayoutLine *
 pango_layout_line_ref (PangoLayoutLine *line)
 {
@@ -4465,12 +4479,12 @@ pango_layout_line_ref (PangoLayoutLine *line)
 
 /**
  * pango_layout_line_unref:
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  *
- * Decrease the reference count of a #PangoLayoutLine by one.
+ * Decrease the reference count of a `PangoLayoutLine` by one.
  * If the result is zero, the line and all associated memory
  * will be freed.
- **/
+ */
 void
 pango_layout_line_unref (PangoLayoutLine *line)
 {
@@ -4495,34 +4509,32 @@ G_DEFINE_BOXED_TYPE (PangoLayoutLine, pango_layout_line,
 
 /**
  * pango_layout_line_x_to_index:
- * @line:      a #PangoLayoutLine
- * @x_pos:     the X offset (in Pango units)
- *             from the left edge of the line.
- * @index_: (out):   location to store calculated byte index for
- *                   the grapheme in which the user clicked.
- * @trailing: (out): location to store an integer indicating where
- *                   in the grapheme the user clicked. It will either
- *                   be zero, or the number of characters in the
- *                   grapheme. 0 represents the leading edge of the grapheme.
- *
- * Converts from x offset to the byte index of the corresponding
- * character within the text of the layout. If @x_pos is outside the line,
- * @index_ and @trailing will point to the very first or very last position
- * in the line. This determination is based on the resolved direction
- * of the paragraph; for example, if the resolved direction is
- * right-to-left, then an X position to the right of the line (after it)
- * results in 0 being stored in @index_ and @trailing. An X position to the
- * left of the line results in @index_ pointing to the (logical) last
- * grapheme in the line and @trailing being set to the number of characters
- * in that grapheme. The reverse is true for a left-to-right line.
+ * @line: a `PangoLayoutLine`
+ * @x_pos: the X offset (in Pango units) from the left edge of the line.
+ * @index_: (out): location to store calculated byte index for the grapheme
+ *   in which the user clicked.
+ * @trailing: (out): location to store an integer indicating where in the
+ *   grapheme the user clicked. It will either be zero, or the number of
+ *   characters in the grapheme. 0 represents the leading edge of the grapheme.
+ *
+ * Converts from x offset to the byte index of the corresponding character
+ * within the text of the layout. If @x_pos is outside the line, @index_ and
+ * @trailing will point to the very first or very last position in the line.
+ * This determination is based on the resolved direction of the paragraph;
+ * for example, if the resolved direction is right-to-left, then an X position
+ * to the right of the line (after it) results in 0 being stored in @index_
+ * and @trailing. An X position to the left of the line results in @index_
+ * pointing to the (logical) last grapheme in the line and @trailing being
+ * set to the number of characters in that grapheme. The reverse is true for
+ * a left-to-right line.
  *
  * Return value: %FALSE if @x_pos was outside the line, %TRUE if inside
- **/
+ */
 gboolean
 pango_layout_line_x_to_index (PangoLayoutLine *line,
-			      int              x_pos,
-			      int             *index,
-			      int             *trailing)
+                              int              x_pos,
+                              int             *index,
+                              int             *trailing)
 {
   GSList *tmp_list;
   gint start_pos = 0;
@@ -4547,9 +4559,9 @@ pango_layout_line_x_to_index (PangoLayoutLine *line,
   if (line->length == 0)
     {
       if (index)
-	*index = first_index;
+        *index = first_index;
       if (trailing)
-	*trailing = 0;
+        *trailing = 0;
 
       return FALSE;
     }
@@ -4610,10 +4622,10 @@ pango_layout_line_x_to_index (PangoLayoutLine *line,
     {
       /* pick the leftmost char */
       if (index)
-	*index = (line->resolved_dir == PANGO_DIRECTION_LTR) ? first_index : last_index;
+        *index = (line->resolved_dir == PANGO_DIRECTION_LTR) ? first_index : last_index;
       /* and its leftmost edge */
       if (trailing)
-	*trailing = (line->resolved_dir == PANGO_DIRECTION_LTR || suppress_last_trailing) ? 0 : last_trailing;
+        *trailing = (line->resolved_dir == PANGO_DIRECTION_LTR || suppress_last_trailing) ? 0 : last_trailing;
 
       return FALSE;
     }
@@ -4627,58 +4639,58 @@ pango_layout_line_x_to_index (PangoLayoutLine *line,
       logical_width = pango_glyph_string_get_width (run->glyphs);
 
       if (x_pos >= start_pos && x_pos < start_pos + logical_width)
-	{
-	  int offset;
-	  gboolean char_trailing;
-	  int grapheme_start_index;
-	  int grapheme_start_offset;
-	  int grapheme_end_offset;
-	  int pos;
-	  int char_index;
-
-	  pango_glyph_string_x_to_index (run->glyphs,
-					 layout->text + run->item->offset, run->item->length,
-					 &run->item->analysis,
-					 x_pos - start_pos,
-					 &pos, &char_trailing);
-
-	  char_index = run->item->offset + pos;
-
-	  /* Convert from characters to graphemes */
-
-	  offset = g_utf8_pointer_to_offset (layout->text, layout->text + char_index);
-
-	  grapheme_start_offset = offset;
-	  grapheme_start_index = char_index;
-	  while (grapheme_start_offset > first_offset &&
-		 !layout->log_attrs[grapheme_start_offset].is_cursor_position)
-	    {
-	      grapheme_start_index = g_utf8_prev_char (layout->text + grapheme_start_index) - layout->text;
-	      grapheme_start_offset--;
-	    }
-
-	  grapheme_end_offset = offset;
-	  do
-	    {
-	      grapheme_end_offset++;
-	    }
-	  while (grapheme_end_offset < end_offset &&
-		 !layout->log_attrs[grapheme_end_offset].is_cursor_position);
-
-	  if (index)
-	    *index = grapheme_start_index;
-
-	  if (trailing)
-	    {
-	      if ((grapheme_end_offset == end_offset && suppress_last_trailing) ||
-		  offset + char_trailing <= (grapheme_start_offset + grapheme_end_offset) / 2)
-		*trailing = 0;
-	      else
-		*trailing = grapheme_end_offset - grapheme_start_offset;
-	    }
-
-	  return TRUE;
-	}
+        {
+          int offset;
+          gboolean char_trailing;
+          int grapheme_start_index;
+          int grapheme_start_offset;
+          int grapheme_end_offset;
+          int pos;
+          int char_index;
+
+          pango_glyph_string_x_to_index (run->glyphs,
+                                         layout->text + run->item->offset, run->item->length,
+                                         &run->item->analysis,
+                                         x_pos - start_pos,
+                                         &pos, &char_trailing);
+
+          char_index = run->item->offset + pos;
+
+          /* Convert from characters to graphemes */
+
+          offset = g_utf8_pointer_to_offset (layout->text, layout->text + char_index);
+
+          grapheme_start_offset = offset;
+          grapheme_start_index = char_index;
+          while (grapheme_start_offset > first_offset &&
+                 !layout->log_attrs[grapheme_start_offset].is_cursor_position)
+            {
+              grapheme_start_index = g_utf8_prev_char (layout->text + grapheme_start_index) - layout->text;
+              grapheme_start_offset--;
+            }
+
+          grapheme_end_offset = offset;
+          do
+            {
+              grapheme_end_offset++;
+            }
+          while (grapheme_end_offset < end_offset &&
+                 !layout->log_attrs[grapheme_end_offset].is_cursor_position);
+
+          if (index)
+            *index = grapheme_start_index;
+
+          if (trailing)
+            {
+              if ((grapheme_end_offset == end_offset && suppress_last_trailing) ||
+                  offset + char_trailing <= (grapheme_start_offset + grapheme_end_offset) / 2)
+                *trailing = 0;
+              else
+                *trailing = grapheme_end_offset - grapheme_start_offset;
+            }
+
+          return TRUE;
+        }
 
       start_pos += logical_width;
       tmp_list = tmp_list->next;
@@ -4715,24 +4727,21 @@ pango_layout_line_get_width (PangoLayoutLine *line)
 
 /**
  * pango_layout_line_get_x_ranges:
- * @line:        a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  * @start_index: Start byte index of the logical range. If this value
- *               is less than the start index for the line, then
- *               the first range will extend all the way to the leading
- *               edge of the layout. Otherwise it will start at the
- *               leading edge of the first character.
- * @end_index:   Ending byte index of the logical range. If this value
- *               is greater than the end index for the line, then
- *               the last range will extend all the way to the trailing
- *               edge of the layout. Otherwise, it will end at the
- *               trailing edge of the last character.
- * @ranges: (out) (array length=n_ranges) (transfer full):
- *               location to store a pointer to an array of ranges.
- *               The array will be of length <literal>2*n_ranges</literal>,
- *               with each range starting at <literal>(*ranges)[2*n]</literal>
- *               and of width <literal>(*ranges)[2*n + 1] - (*ranges)[2*n]</literal>.
- *               This array must be freed with g_free(). The coordinates are relative
- *               to the layout and are in Pango units.
+ *   is less than the start index for the line, then the first range
+ *   will extend all the way to the leading edge of the layout. Otherwise,
+ *   it will start at the leading edge of the first character.
+ * @end_index: Ending byte index of the logical range. If this value is
+ *   greater than the end index for the line, then the last range will
+ *   extend all the way to the trailing edge of the layout. Otherwise,
+ *   it will end at the trailing edge of the last character.
+ * @ranges: (out) (array length=n_ranges) (transfer full): location to
+ *   store a pointer to an array of ranges. The array will be of length
+ *   `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of
+ *   width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed
+ *   with g_free(). The coordinates are relative to the layout and are in
+ *   Pango units.
  * @n_ranges: The number of ranges stored in @ranges.
  *
  * Gets a list of visual ranges corresponding to a given logical range.
@@ -4740,13 +4749,13 @@ pango_layout_line_get_width (PangoLayoutLine *line)
  * ranges which are adjacent. The ranges will be sorted from left to
  * right. The ranges are with respect to the left edge of the entire
  * layout, not with respect to the line.
- **/
+ */
 void
 pango_layout_line_get_x_ranges (PangoLayoutLine  *line,
-				int               start_index,
-				int               end_index,
-				int             **ranges,
-				int              *n_ranges)
+                                int               start_index,
+                                int               end_index,
+                                int             **ranges,
+                                int              *n_ranges)
 {
   gint line_start_index = 0;
   GSList *tmp_list;
@@ -4794,10 +4803,10 @@ pango_layout_line_get_x_ranges (PangoLayoutLine  *line,
        (line->resolved_dir == PANGO_DIRECTION_RTL && end_index > line_start_index + line->length)))
     {
       if (ranges)
-	{
-	  (*ranges)[2*range_count] = 0;
-	  (*ranges)[2*range_count + 1] = x_offset;
-	}
+        {
+          (*ranges)[2*range_count] = 0;
+          (*ranges)[2*range_count + 1] = x_offset;
+        }
 
       range_count ++;
     }
@@ -4808,42 +4817,42 @@ pango_layout_line_get_x_ranges (PangoLayoutLine  *line,
       PangoLayoutRun *run = (PangoLayoutRun *)tmp_list->data;
 
       if ((start_index < run->item->offset + run->item->length &&
-	   end_index > run->item->offset))
-	{
-	  if (ranges)
-	    {
-	      int run_start_index = MAX (start_index, run->item->offset);
-	      int run_end_index = MIN (end_index, run->item->offset + run->item->length);
-	      int run_start_x, run_end_x;
-
-	      g_assert (run_end_index > 0);
-
-	      /* Back the end_index off one since we want to find the trailing edge of the preceding character */
-
-	      run_end_index = g_utf8_prev_char (line->layout->text + run_end_index) - line->layout->text;
-
-	      pango_glyph_string_index_to_x (run->glyphs,
-					     line->layout->text + run->item->offset,
-					     run->item->length,
-					     &run->item->analysis,
-					     run_start_index - run->item->offset, FALSE,
-					     &run_start_x);
-	      pango_glyph_string_index_to_x (run->glyphs,
-					     line->layout->text + run->item->offset,
-					     run->item->length,
-					     &run->item->analysis,
-					     run_end_index - run->item->offset, TRUE,
-					     &run_end_x);
-
-	      (*ranges)[2*range_count] = x_offset + accumulated_width + MIN (run_start_x, run_end_x);
-	      (*ranges)[2*range_count + 1] = x_offset + accumulated_width + MAX (run_start_x, run_end_x);
-	    }
-
-	  range_count++;
-	}
+           end_index > run->item->offset))
+        {
+          if (ranges)
+            {
+              int run_start_index = MAX (start_index, run->item->offset);
+              int run_end_index = MIN (end_index, run->item->offset + run->item->length);
+              int run_start_x, run_end_x;
+
+              g_assert (run_end_index > 0);
+
+              /* Back the end_index off one since we want to find the trailing edge of the preceding character */
+
+              run_end_index = g_utf8_prev_char (line->layout->text + run_end_index) - line->layout->text;
+
+              pango_glyph_string_index_to_x (run->glyphs,
+                                             line->layout->text + run->item->offset,
+                                             run->item->length,
+                                             &run->item->analysis,
+                                             run_start_index - run->item->offset, FALSE,
+                                             &run_start_x);
+              pango_glyph_string_index_to_x (run->glyphs,
+                                             line->layout->text + run->item->offset,
+                                             run->item->length,
+                                             &run->item->analysis,
+                                             run_end_index - run->item->offset, TRUE,
+                                             &run_end_x);
+
+              (*ranges)[2*range_count] = x_offset + accumulated_width + MIN (run_start_x, run_end_x);
+              (*ranges)[2*range_count + 1] = x_offset + accumulated_width + MAX (run_start_x, run_end_x);
+            }
+
+          range_count++;
+        }
 
       if (tmp_list->next)
-	accumulated_width += pango_glyph_string_get_width (run->glyphs);
+        accumulated_width += pango_glyph_string_get_width (run->glyphs);
 
       tmp_list = tmp_list->next;
     }
@@ -4853,10 +4862,10 @@ pango_layout_line_get_x_ranges (PangoLayoutLine  *line,
        (line->resolved_dir == PANGO_DIRECTION_RTL && start_index < line_start_index)))
     {
       if (ranges)
-	{
-	  (*ranges)[2*range_count] = x_offset + line_width;
-	  (*ranges)[2*range_count + 1] = line->layout->width;
-	}
+        {
+          (*ranges)[2*range_count] = x_offset + line_width;
+          (*ranges)[2*range_count + 1] = line->layout->width;
+        }
 
       range_count ++;
     }
@@ -4867,8 +4876,8 @@ pango_layout_line_get_x_ranges (PangoLayoutLine  *line,
 
 static void
 pango_layout_get_empty_extents_at_index (PangoLayout    *layout,
-					 int             index,
-					 PangoRectangle *logical_rect)
+                                         int             index,
+                                         PangoRectangle *logical_rect)
 {
   if (logical_rect)
     {
@@ -4880,76 +4889,76 @@ pango_layout_get_empty_extents_at_index (PangoLayout    *layout,
 
       if (layout->font_desc)
         {
-	  font_desc = pango_font_description_copy_static (font_desc);
-	  pango_font_description_merge (font_desc, layout->font_desc, TRUE);
-	  free_font_desc = TRUE;
-	}
+          font_desc = pango_font_description_copy_static (font_desc);
+          pango_font_description_merge (font_desc, layout->font_desc, TRUE);
+          free_font_desc = TRUE;
+        }
 
       /* Find the font description for this line
        */
       if (layout->attrs)
-	{
+        {
           PangoAttrIterator iter;
-	  int start, end;
+          int start, end;
 
           _pango_attr_list_get_iterator (layout->attrs, &iter);
 
-	  do
-	    {
+          do
+            {
               pango_attr_iterator_range (&iter, &start, &end);
 
-	      if (start <= index && index < end)
-		{
-		  if (!free_font_desc)
-		    {
-		      font_desc = pango_font_description_copy_static (font_desc);
-		      free_font_desc = TRUE;
-		    }
+              if (start <= index && index < end)
+                {
+                  if (!free_font_desc)
+                    {
+                      font_desc = pango_font_description_copy_static (font_desc);
+                      free_font_desc = TRUE;
+                    }
 
                   pango_attr_iterator_get_font (&iter,
-						font_desc,
-						NULL,
-						NULL);
+                                                font_desc,
+                                                NULL,
+                                                NULL);
 
-		  break;
-		}
+                  break;
+                }
 
-	    }
+            }
           while (pango_attr_iterator_next (&iter));
 
           _pango_attr_iterator_destroy (&iter);
-	}
+        }
 
       font = pango_context_load_font (layout->context, font_desc);
       if (font)
-	{
-	  PangoFontMetrics *metrics;
-
-	  metrics = pango_font_get_metrics (font,
-					    pango_context_get_language (layout->context));
-
-	  if (metrics)
-	    {
-	      logical_rect->y = - pango_font_metrics_get_ascent (metrics);
-	      logical_rect->height = - logical_rect->y + pango_font_metrics_get_descent (metrics);
-
-	      pango_font_metrics_unref (metrics);
-	    }
-	  else
-	    {
-	      logical_rect->y = 0;
-	      logical_rect->height = 0;
-	    }
-	  g_object_unref (font);
-	}
+        {
+          PangoFontMetrics *metrics;
+
+          metrics = pango_font_get_metrics (font,
+                                            pango_context_get_language (layout->context));
+
+          if (metrics)
+            {
+              logical_rect->y = - pango_font_metrics_get_ascent (metrics);
+              logical_rect->height = - logical_rect->y + pango_font_metrics_get_descent (metrics);
+
+              pango_font_metrics_unref (metrics);
+            }
+          else
+            {
+              logical_rect->y = 0;
+              logical_rect->height = 0;
+            }
+          g_object_unref (font);
+        }
       else
-	{
-	  logical_rect->y = 0;
-	  logical_rect->height = 0;
-	}
+        {
+          logical_rect->y = 0;
+          logical_rect->height = 0;
+        }
 
       if (free_font_desc)
-	pango_font_description_free (font_desc);
+        pango_font_description_free (font_desc);
 
       logical_rect->x = 0;
       logical_rect->width = 0;
@@ -4958,7 +4967,7 @@ pango_layout_get_empty_extents_at_index (PangoLayout    *layout,
 
 static void
 pango_layout_line_get_empty_extents (PangoLayoutLine *line,
-				     PangoRectangle  *logical_rect)
+                                     PangoRectangle  *logical_rect)
 {
   pango_layout_get_empty_extents_at_index (line->layout, line->start_index, logical_rect);
 }
@@ -4992,12 +5001,12 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
 
   if (properties.shape_set)
     _pango_shape_get_extents (run->item->num_chars,
-			      properties.shape_ink_rect,
-			      properties.shape_logical_rect,
-			      run_ink, run_logical);
+                              properties.shape_ink_rect,
+                              properties.shape_logical_rect,
+                              run_ink, run_logical);
   else
     pango_glyph_string_extents (run->glyphs, run->item->analysis.font,
-				run_ink, run_logical);
+                                run_ink, run_logical);
 
   if (run_ink && (has_underline || has_overline || properties.strikethrough))
     {
@@ -5009,7 +5018,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
 
       if (!metrics)
         metrics = pango_font_get_metrics (run->item->analysis.font,
-					  run->item->analysis.language);
+                                          run->item->analysis.language);
 
       underline_thickness = pango_font_metrics_get_underline_thickness (metrics);
       underline_position = pango_font_metrics_get_underline_position (metrics);
@@ -5028,18 +5037,18 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
        */
 
       if (properties.strikethrough)
-	{
-	  if (run_ink->height == 0)
-	    {
-	      run_ink->height = strikethrough_thickness;
-	      run_ink->y = -strikethrough_position;
-	    }
-	}
+        {
+          if (run_ink->height == 0)
+            {
+              run_ink->height = strikethrough_thickness;
+              run_ink->y = -strikethrough_position;
+            }
+        }
 
       if (properties.oline_single)
         {
-	  run_ink->y -= underline_thickness;
-	  run_ink->height += underline_thickness;
+          run_ink->y -= underline_thickness;
+          run_ink->height += underline_thickness;
         }
 
       if (properties.uline_low)
@@ -5059,7 +5068,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
     {
       if (!metrics)
         metrics = pango_font_get_metrics (run->item->analysis.font,
-				          run->item->analysis.language);
+                                          run->item->analysis.language);
       *height = pango_font_metrics_get_height (metrics);
     }
 
@@ -5069,7 +5078,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
       int adjustment = run_logical->y + run_logical->height / 2;
 
       if (is_hinted)
-	adjustment = PANGO_UNITS_ROUND (adjustment);
+        adjustment = PANGO_UNITS_ROUND (adjustment);
 
       properties.rise += adjustment;
     }
@@ -5077,10 +5086,10 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run,
   if (properties.rise != 0)
     {
       if (run_ink)
-	run_ink->y -= properties.rise;
+        run_ink->y -= properties.rise;
 
       if (run_logical)
-	run_logical->y -= properties.rise;
+        run_logical->y -= properties.rise;
     }
 
   if (metrics)
@@ -5107,28 +5116,28 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
     {
     case CACHED:
       {
-	if (ink_rect)
-	  *ink_rect = private->ink_rect;
-	if (logical_rect)
-	  *logical_rect = private->logical_rect;
+        if (ink_rect)
+          *ink_rect = private->ink_rect;
+        if (logical_rect)
+          *logical_rect = private->logical_rect;
         if (height)
           *height = private->height;
-	return;
+        return;
       }
     case NOT_CACHED:
       {
-	caching = TRUE;
-	if (!ink_rect)
-	  ink_rect = &private->ink_rect;
-	if (!logical_rect)
-	  logical_rect = &private->logical_rect;
+        caching = TRUE;
+        if (!ink_rect)
+          ink_rect = &private->ink_rect;
+        if (!logical_rect)
+          logical_rect = &private->logical_rect;
         if (!height)
           height = &private->height;
-	break;
+        break;
       }
     case LEAKED:
       {
-	break;
+        break;
       }
     }
 
@@ -5166,37 +5175,37 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
                                                height ? &run_height : NULL);
 
       if (ink_rect)
-	{
-	  if (ink_rect->width == 0 || ink_rect->height == 0)
-	    {
-	      *ink_rect = run_ink;
-	      ink_rect->x += x_pos;
-	    }
-	  else if (run_ink.width != 0 && run_ink.height != 0)
-	    {
-	      new_pos = MIN (ink_rect->x, x_pos + run_ink.x);
-	      ink_rect->width = MAX (ink_rect->x + ink_rect->width,
-				     x_pos + run_ink.x + run_ink.width) - new_pos;
-	      ink_rect->x = new_pos;
-
-	      new_pos = MIN (ink_rect->y, run_ink.y);
-	      ink_rect->height = MAX (ink_rect->y + ink_rect->height,
-				      run_ink.y + run_ink.height) - new_pos;
-	      ink_rect->y = new_pos;
-	    }
-	}
+        {
+          if (ink_rect->width == 0 || ink_rect->height == 0)
+            {
+              *ink_rect = run_ink;
+              ink_rect->x += x_pos;
+            }
+          else if (run_ink.width != 0 && run_ink.height != 0)
+            {
+              new_pos = MIN (ink_rect->x, x_pos + run_ink.x);
+              ink_rect->width = MAX (ink_rect->x + ink_rect->width,
+                                     x_pos + run_ink.x + run_ink.width) - new_pos;
+              ink_rect->x = new_pos;
+
+              new_pos = MIN (ink_rect->y, run_ink.y);
+              ink_rect->height = MAX (ink_rect->y + ink_rect->height,
+                                      run_ink.y + run_ink.height) - new_pos;
+              ink_rect->y = new_pos;
+            }
+        }
 
       if (logical_rect)
         {
           new_pos = MIN (logical_rect->x, x_pos + run_logical.x);
           logical_rect->width = MAX (logical_rect->x + logical_rect->width,
-				     x_pos + run_logical.x + run_logical.width) - new_pos;
-	  logical_rect->x = new_pos;
+                                     x_pos + run_logical.x + run_logical.width) - new_pos;
+          logical_rect->x = new_pos;
 
-	  new_pos = MIN (logical_rect->y, run_logical.y);
-	  logical_rect->height = MAX (logical_rect->y + logical_rect->height,
-				      run_logical.y + run_logical.height) - new_pos;
-	  logical_rect->y = new_pos;
+          new_pos = MIN (logical_rect->y, run_logical.y);
+          logical_rect->height = MAX (logical_rect->y + logical_rect->height,
+                                      run_logical.y + run_logical.height) - new_pos;
+          logical_rect->y = new_pos;
         }
 
       if (height)
@@ -5212,9 +5221,9 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
   if (caching)
     {
       if (&private->ink_rect != ink_rect)
-	private->ink_rect = *ink_rect;
+        private->ink_rect = *ink_rect;
       if (&private->logical_rect != logical_rect)
-	private->logical_rect = *logical_rect;
+        private->logical_rect = *logical_rect;
       if (&private->height != height)
         private->height = *height;
       private->cache_status = CACHED;
@@ -5223,37 +5232,37 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
 
 /**
  * pango_layout_line_get_extents:
- * @line:     a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of
- *            the glyph string as drawn, or %NULL
+ *   the glyph string as drawn, or %NULL
  * @logical_rect: (out) (allow-none):rectangle used to store the logical
- *                extents of the glyph string, or %NULL
+ *   extents of the glyph string, or %NULL
  *
  * Computes the logical and ink extents of a layout line. See
- * pango_font_get_glyph_extents() for details about the interpretation
- * of the rectangles.
+ * [method@Pango.Font.get_glyph_extents] for details about the
+ * interpretation of the rectangles.
  */
 void
 pango_layout_line_get_extents (PangoLayoutLine *line,
-			       PangoRectangle  *ink_rect,
-			       PangoRectangle  *logical_rect)
+                               PangoRectangle  *ink_rect,
+                               PangoRectangle  *logical_rect)
 {
   pango_layout_line_get_extents_and_height (line, ink_rect, logical_rect, NULL);
 }
 
 /**
  * pango_layout_line_get_height:
- * @line:     a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  * @height: (out) (allow-none): return location for the line height
  *
- * Computes the height of the line, ie the distance between
+ * Computes the height of the line, i.e. the distance between
  * this and the previous lines baseline.
  *
  * Since: 1.44
  */
 void
 pango_layout_line_get_height (PangoLayoutLine *line,
-			      int             *height)
+                              int             *height)
 {
   pango_layout_line_get_extents_and_height (line, NULL, NULL, height);
 }
@@ -5277,22 +5286,23 @@ pango_layout_line_new (PangoLayout *layout)
 
 /**
  * pango_layout_line_get_pixel_extents:
- * @layout_line: a #PangoLayoutLine
+ * @layout_line: a `PangoLayoutLine`
  * @ink_rect: (out) (allow-none): rectangle used to store the extents of
- *                   the glyph string as drawn, or %NULL
+ *   the glyph string as drawn, or %NULL
  * @logical_rect: (out) (allow-none): rectangle used to store the logical
- *                       extents of the glyph string, or %NULL
+ *   extents of the glyph string, or %NULL
  *
  * Computes the logical and ink extents of @layout_line in device units.
- * This function just calls pango_layout_line_get_extents() followed by
- * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect
+ *
+ * This function just calls [method@Pango.LayoutLine.get_extents] followed by
+ * two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect
  * such that the rounded rectangles fully contain the unrounded one (that is,
- * passes them as first argument to pango_extents_to_pixels()).
- **/
+ * passes them as first argument to [func@extents_to_pixels]).
+ */
 void
 pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,
-				     PangoRectangle  *ink_rect,
-				     PangoRectangle  *logical_rect)
+                                     PangoRectangle  *ink_rect,
+                                     PangoRectangle  *logical_rect)
 {
   g_return_if_fail (LINE_IS_VALID (layout_line));
 
@@ -5305,9 +5315,9 @@ pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,
  * NB: This implement the exact same algorithm as
  *     reorder-items.c:pango_reorder_items().
  */
-
 static GSList *
-reorder_runs_recurse (GSList *items, int n_items)
+reorder_runs_recurse (GSList *items,
+                      int     n_items)
 {
   GSList *tmp_list, *level_start_node;
   int i, level_start_i;
@@ -5335,23 +5345,23 @@ reorder_runs_recurse (GSList *items, int n_items)
       PangoLayoutRun *run = tmp_list->data;
 
       if (run->item->analysis.level == min_level)
-	{
-	  if (min_level % 2)
-	    {
-	      if (i > level_start_i)
-		result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result);
-	      result = g_slist_prepend (result, run);
-	    }
-	  else
-	    {
-	      if (i > level_start_i)
-		result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i));
-	      result = g_slist_append (result, run);
-	    }
-
-	  level_start_i = i + 1;
-	  level_start_node = tmp_list->next;
-	}
+        {
+          if (min_level % 2)
+            {
+              if (i > level_start_i)
+                result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result);
+              result = g_slist_prepend (result, run);
+            }
+          else
+            {
+              if (i > level_start_i)
+                result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i));
+              result = g_slist_append (result, run);
+            }
+
+          level_start_i = i + 1;
+          level_start_node = tmp_list->next;
+        }
 
       tmp_list = tmp_list->next;
     }
@@ -5359,12 +5369,12 @@ reorder_runs_recurse (GSList *items, int n_items)
   if (min_level % 2)
     {
       if (i > level_start_i)
-	result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result);
+        result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result);
     }
   else
     {
       if (i > level_start_i)
-	result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i));
+        result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i));
     }
 
   return result;
@@ -5420,8 +5430,8 @@ get_item_letter_spacing (PangoItem *item)
 
 static void
 pad_glyphstring_right (PangoGlyphString *glyphs,
-		       ParaBreakState   *state,
-		       int               adjustment)
+                       ParaBreakState   *state,
+                       int               adjustment)
 {
   int glyph = glyphs->num_glyphs - 1;
 
@@ -5442,8 +5452,8 @@ pad_glyphstring_right (PangoGlyphString *glyphs,
 
 static void
 pad_glyphstring_left (PangoGlyphString *glyphs,
-		      ParaBreakState   *state,
-		      int               adjustment)
+                      ParaBreakState   *state,
+                      int               adjustment)
 {
   int glyph = 0;
 
@@ -5460,15 +5470,15 @@ pad_glyphstring_left (PangoGlyphString *glyphs,
 
 static gboolean
 is_tab_run (PangoLayout    *layout,
-	    PangoLayoutRun *run)
+            PangoLayoutRun *run)
 {
   return (layout->text[run->item->offset] == '\t');
 }
 
 static void
 zero_line_final_space (PangoLayoutLine *line,
-		       ParaBreakState  *state,
-		       PangoLayoutRun  *run)
+                       ParaBreakState  *state,
+                       PangoLayoutRun  *run)
 {
   PangoLayout *layout = line->layout;
   PangoItem *item = run->item;
@@ -5509,7 +5519,7 @@ zero_line_final_space (PangoLayoutLine *line,
  */
 static void
 adjust_line_letter_spacing (PangoLayoutLine *line,
-			    ParaBreakState  *state)
+                            ParaBreakState  *state)
 {
   PangoLayout *layout = line->layout;
   gboolean reversed;
@@ -5526,12 +5536,12 @@ adjust_line_letter_spacing (PangoLayoutLine *line,
   if (line->resolved_dir == PANGO_DIRECTION_RTL)
     {
       for (l = line->runs; l; l = l->next)
-	if (is_tab_run (layout, l->data))
-	  {
-	    line->runs = g_slist_reverse (line->runs);
-	    reversed = TRUE;
-	    break;
-	  }
+        if (is_tab_run (layout, l->data))
+          {
+            line->runs = g_slist_reverse (line->runs);
+            reversed = TRUE;
+            break;
+          }
     }
 
   /* Walk over the runs in the line, redistributing letter
@@ -5543,7 +5553,6 @@ adjust_line_letter_spacing (PangoLayoutLine *line,
    * which we add onto the next tab stop space to keep the
    * things properly aligned.
    */
-
   last_run = NULL;
   tab_adjustment = 0;
   for (l = line->runs; l; l = l->next)
@@ -5552,43 +5561,43 @@ adjust_line_letter_spacing (PangoLayoutLine *line,
       PangoLayoutRun *next_run = l->next ? l->next->data : NULL;
 
       if (is_tab_run (layout, run))
-	{
-	  pad_glyphstring_right (run->glyphs, state, tab_adjustment);
-	  tab_adjustment = 0;
-	}
+        {
+          pad_glyphstring_right (run->glyphs, state, tab_adjustment);
+          tab_adjustment = 0;
+        }
       else
-	{
-	  PangoLayoutRun *visual_next_run = reversed ? last_run : next_run;
-	  PangoLayoutRun *visual_last_run = reversed ? next_run : last_run;
-	  int run_spacing = get_item_letter_spacing (run->item);
-	  int space_left, space_right;
-
-	  distribute_letter_spacing (run_spacing, &space_left, &space_right);
-
-	  if (run->glyphs->glyphs[0].geometry.width == 0)
-	    {
-	      /* we've zeroed this space glyph at the end of line, now remove
-	       * the letter spacing added to its adjacent glyph */
-	      pad_glyphstring_left (run->glyphs, state, - space_left);
-	    }
-	  else if (!visual_last_run || is_tab_run (layout, visual_last_run))
-	    {
-	      pad_glyphstring_left (run->glyphs, state, - space_left);
-	      tab_adjustment += space_left;
-	    }
-
-	  if (run->glyphs->glyphs[run->glyphs->num_glyphs - 1].geometry.width == 0)
-	    {
-	      /* we've zeroed this space glyph at the end of line, now remove
-	       * the letter spacing added to its adjacent glyph */
-	      pad_glyphstring_right (run->glyphs, state, - space_right);
-	    }
-	  else if (!visual_next_run || is_tab_run (layout, visual_next_run))
-	    {
-	      pad_glyphstring_right (run->glyphs, state, - space_right);
-	      tab_adjustment += space_right;
-	    }
-	}
+        {
+          PangoLayoutRun *visual_next_run = reversed ? last_run : next_run;
+          PangoLayoutRun *visual_last_run = reversed ? next_run : last_run;
+          int run_spacing = get_item_letter_spacing (run->item);
+          int space_left, space_right;
+
+          distribute_letter_spacing (run_spacing, &space_left, &space_right);
+
+          if (run->glyphs->glyphs[0].geometry.width == 0)
+            {
+              /* we've zeroed this space glyph at the end of line, now remove
+               * the letter spacing added to its adjacent glyph */
+              pad_glyphstring_left (run->glyphs, state, - space_left);
+            }
+          else if (!visual_last_run || is_tab_run (layout, visual_last_run))
+            {
+              pad_glyphstring_left (run->glyphs, state, - space_left);
+              tab_adjustment += space_left;
+            }
+
+          if (run->glyphs->glyphs[run->glyphs->num_glyphs - 1].geometry.width == 0)
+            {
+              /* we've zeroed this space glyph at the end of line, now remove
+               * the letter spacing added to its adjacent glyph */
+              pad_glyphstring_right (run->glyphs, state, - space_right);
+            }
+          else if (!visual_next_run || is_tab_run (layout, visual_next_run))
+            {
+              pad_glyphstring_right (run->glyphs, state, - space_right);
+              tab_adjustment += space_right;
+            }
+        }
 
       last_run = run;
     }
@@ -5599,7 +5608,7 @@ adjust_line_letter_spacing (PangoLayoutLine *line,
 
 static void
 justify_clusters (PangoLayoutLine *line,
-		  ParaBreakState  *state)
+                  ParaBreakState  *state)
 {
   const gchar *text = line->layout->text;
   const PangoLogAttr *log_attrs = line->layout->log_attrs;
@@ -5631,120 +5640,120 @@ justify_clusters (PangoLayoutLine *line,
       gaps_so_far = 0;
 
       for (run_iter = line->runs; run_iter; run_iter = run_iter->next)
-	{
-	  PangoLayoutRun *run = run_iter->data;
-	  PangoGlyphString *glyphs = run->glyphs;
-	  PangoGlyphItemIter cluster_iter;
-	  gboolean have_cluster;
-	  int dir;
-	  int offset;
-
-	  dir = run->item->analysis.level % 2 == 0 ? +1 : -1;
-
-	  /* We need character offset of the start of the run.  We don't have this.
-	   * Compute by counting from the beginning of the line.  The naming is
-	   * confusing.  Note that:
-	   *
-	   * run->item->offset        is byte offset of start of run in layout->text.
-	   * state->line_start_index  is byte offset of start of line in layout->text.
-	   * state->line_start_offset is character offset of start of line in layout->text.
-	   */
-	  g_assert (run->item->offset >= state->line_start_index);
-	  offset = state->line_start_offset
-		 + pango_utf8_strlen (text + state->line_start_index,
-				      run->item->offset - state->line_start_index);
-
-	  for (have_cluster = dir > 0 ?
-		 pango_glyph_item_iter_init_start (&cluster_iter, run, text) :
-		 pango_glyph_item_iter_init_end   (&cluster_iter, run, text);
-	       have_cluster;
-	       have_cluster = dir > 0 ?
-	         pango_glyph_item_iter_next_cluster (&cluster_iter) :
-	         pango_glyph_item_iter_prev_cluster (&cluster_iter))
-	    {
-	      int i;
-	      int width = 0;
-
-	      /* don't expand in the middle of graphemes */
-	      if (!log_attrs[offset + cluster_iter.start_char].is_cursor_position)
-		continue;
-
-	      for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir)
-		width += glyphs->glyphs[i].geometry.width;
-
-	      /* also don't expand zero-width clusters. */
-	      if (width == 0)
-		continue;
-
-	      gaps_so_far++;
-
-	      if (mode == ADJUST)
-		{
-		  int leftmost, rightmost;
-		  int adjustment, space_left, space_right;
-
-		  adjustment = total_remaining_width / total_gaps + residual;
-		  if (is_hinted)
-		  {
-		    int old_adjustment = adjustment;
-		    adjustment = PANGO_UNITS_ROUND (adjustment);
-		    residual = old_adjustment - adjustment;
-		  }
-		  /* distribute to before/after */
-		  distribute_letter_spacing (adjustment, &space_left, &space_right);
-
-		  if (cluster_iter.start_glyph < cluster_iter.end_glyph)
-		  {
-		    /* LTR */
-		    leftmost  = cluster_iter.start_glyph;
-		    rightmost = cluster_iter.end_glyph - 1;
-		  }
-		  else
-		  {
-		    /* RTL */
-		    leftmost  = cluster_iter.end_glyph + 1;
-		    rightmost = cluster_iter.start_glyph;
-		  }
-		  /* Don't add to left-side of left-most glyph of left-most non-zero run. */
-		  if (leftedge)
-		    leftedge = FALSE;
-		  else
-		  {
-		    glyphs->glyphs[leftmost].geometry.width    += space_left ;
-		    glyphs->glyphs[leftmost].geometry.x_offset += space_left ;
-		    added_so_far += space_left;
-		  }
-		  /* Don't add to right-side of right-most glyph of right-most non-zero run. */
-		  {
-		    /* Save so we can undo later. */
-		    rightmost_glyphs = glyphs;
-		    rightmost_space = space_right;
-
-		    glyphs->glyphs[rightmost].geometry.width  += space_right;
-		    added_so_far += space_right;
-		  }
-		}
-	    }
-	}
+        {
+          PangoLayoutRun *run = run_iter->data;
+          PangoGlyphString *glyphs = run->glyphs;
+          PangoGlyphItemIter cluster_iter;
+          gboolean have_cluster;
+          int dir;
+          int offset;
+
+          dir = run->item->analysis.level % 2 == 0 ? +1 : -1;
+
+          /* We need character offset of the start of the run.  We don't have this.
+           * Compute by counting from the beginning of the line.  The naming is
+           * confusing.  Note that:
+           *
+           * run->item->offset        is byte offset of start of run in layout->text.
+           * state->line_start_index  is byte offset of start of line in layout->text.
+           * state->line_start_offset is character offset of start of line in layout->text.
+           */
+          g_assert (run->item->offset >= state->line_start_index);
+          offset = state->line_start_offset
+                 + pango_utf8_strlen (text + state->line_start_index,
+                                      run->item->offset - state->line_start_index);
+
+          for (have_cluster = dir > 0 ?
+                 pango_glyph_item_iter_init_start (&cluster_iter, run, text) :
+                 pango_glyph_item_iter_init_end   (&cluster_iter, run, text);
+               have_cluster;
+               have_cluster = dir > 0 ?
+                 pango_glyph_item_iter_next_cluster (&cluster_iter) :
+                 pango_glyph_item_iter_prev_cluster (&cluster_iter))
+            {
+              int i;
+              int width = 0;
+
+              /* don't expand in the middle of graphemes */
+              if (!log_attrs[offset + cluster_iter.start_char].is_cursor_position)
+                continue;
+
+              for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir)
+                width += glyphs->glyphs[i].geometry.width;
+
+              /* also don't expand zero-width clusters. */
+              if (width == 0)
+                continue;
+
+              gaps_so_far++;
+
+              if (mode == ADJUST)
+                {
+                  int leftmost, rightmost;
+                  int adjustment, space_left, space_right;
+
+                  adjustment = total_remaining_width / total_gaps + residual;
+                  if (is_hinted)
+                  {
+                    int old_adjustment = adjustment;
+                    adjustment = PANGO_UNITS_ROUND (adjustment);
+                    residual = old_adjustment - adjustment;
+                  }
+                  /* distribute to before/after */
+                  distribute_letter_spacing (adjustment, &space_left, &space_right);
+
+                  if (cluster_iter.start_glyph < cluster_iter.end_glyph)
+                  {
+                    /* LTR */
+                    leftmost  = cluster_iter.start_glyph;
+                    rightmost = cluster_iter.end_glyph - 1;
+                  }
+                  else
+                  {
+                    /* RTL */
+                    leftmost  = cluster_iter.end_glyph + 1;
+                    rightmost = cluster_iter.start_glyph;
+                  }
+                  /* Don't add to left-side of left-most glyph of left-most non-zero run. */
+                  if (leftedge)
+                    leftedge = FALSE;
+                  else
+                  {
+                    glyphs->glyphs[leftmost].geometry.width    += space_left ;
+                    glyphs->glyphs[leftmost].geometry.x_offset += space_left ;
+                    added_so_far += space_left;
+                  }
+                  /* Don't add to right-side of right-most glyph of right-most non-zero run. */
+                  {
+                    /* Save so we can undo later. */
+                    rightmost_glyphs = glyphs;
+                    rightmost_space = space_right;
+
+                    glyphs->glyphs[rightmost].geometry.width  += space_right;
+                    added_so_far += space_right;
+                  }
+                }
+            }
+        }
 
       if (mode == MEASURE)
-	{
-	  total_gaps = gaps_so_far - 1;
-
-	  if (total_gaps == 0)
-	    {
-	      /* a single cluster, can't really justify it */
-	      return;
-	    }
-	}
+        {
+          total_gaps = gaps_so_far - 1;
+
+          if (total_gaps == 0)
+            {
+              /* a single cluster, can't really justify it */
+              return;
+            }
+        }
       else /* mode == ADJUST */
         {
-	  if (rightmost_glyphs)
-	   {
-	     rightmost_glyphs->glyphs[rightmost_glyphs->num_glyphs - 1].geometry.width -= rightmost_space;
-	     added_so_far -= rightmost_space;
-	   }
-	}
+          if (rightmost_glyphs)
+           {
+             rightmost_glyphs->glyphs[rightmost_glyphs->num_glyphs - 1].geometry.width -= rightmost_space;
+             added_so_far -= rightmost_space;
+           }
+        }
     }
 
   state->remaining_width -= added_so_far;
@@ -5752,7 +5761,7 @@ justify_clusters (PangoLayoutLine *line,
 
 static void
 justify_words (PangoLayoutLine *line,
-	       ParaBreakState  *state)
+               ParaBreakState  *state)
 {
   const gchar *text = line->layout->text;
   const PangoLogAttr *log_attrs = line->layout->log_attrs;
@@ -5779,71 +5788,71 @@ justify_words (PangoLayoutLine *line,
       spaces_so_far = 0;
 
       for (run_iter = line->runs; run_iter; run_iter = run_iter->next)
-	{
-	  PangoLayoutRun *run = run_iter->data;
-	  PangoGlyphString *glyphs = run->glyphs;
-	  PangoGlyphItemIter cluster_iter;
-	  gboolean have_cluster;
-	  int offset;
-
-	  /* We need character offset of the start of the run.  We don't have this.
-	   * Compute by counting from the beginning of the line.  The naming is
-	   * confusing.  Note that:
-	   *
-	   * run->item->offset        is byte offset of start of run in layout->text.
-	   * state->line_start_index  is byte offset of start of line in layout->text.
-	   * state->line_start_offset is character offset of start of line in layout->text.
-	   */
-	  g_assert (run->item->offset >= state->line_start_index);
-	  offset = state->line_start_offset
-		 + pango_utf8_strlen (text + state->line_start_index,
-				      run->item->offset - state->line_start_index);
-
-	  for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, run, text);
-	       have_cluster;
-	       have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
-	    {
-	      int i;
-	      int dir;
-
-	      if (!log_attrs[offset + cluster_iter.start_char].is_expandable_space)
-		continue;
-
-	      dir = (cluster_iter.start_glyph < cluster_iter.end_glyph) ? 1 : -1;
-	      for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir)
-		{
-		  int glyph_width = glyphs->glyphs[i].geometry.width;
-
-		  if (glyph_width == 0)
-		    continue;
-
-		  spaces_so_far += glyph_width;
-
-		  if (mode == ADJUST)
-		    {
-		      int adjustment;
-
-		      adjustment = ((guint64) spaces_so_far * total_remaining_width) / total_space_width - added_so_far;
-		      if (is_hinted)
-			adjustment = PANGO_UNITS_ROUND (adjustment);
-
-		      glyphs->glyphs[i].geometry.width += adjustment;
-		      added_so_far += adjustment;
-		    }
-		}
-	    }
-	}
+        {
+          PangoLayoutRun *run = run_iter->data;
+          PangoGlyphString *glyphs = run->glyphs;
+          PangoGlyphItemIter cluster_iter;
+          gboolean have_cluster;
+          int offset;
+
+          /* We need character offset of the start of the run.  We don't have this.
+           * Compute by counting from the beginning of the line.  The naming is
+           * confusing.  Note that:
+           *
+           * run->item->offset        is byte offset of start of run in layout->text.
+           * state->line_start_index  is byte offset of start of line in layout->text.
+           * state->line_start_offset is character offset of start of line in layout->text.
+           */
+          g_assert (run->item->offset >= state->line_start_index);
+          offset = state->line_start_offset
+                 + pango_utf8_strlen (text + state->line_start_index,
+                                      run->item->offset - state->line_start_index);
+
+          for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, run, text);
+               have_cluster;
+               have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
+            {
+              int i;
+              int dir;
+
+              if (!log_attrs[offset + cluster_iter.start_char].is_expandable_space)
+                continue;
+
+              dir = (cluster_iter.start_glyph < cluster_iter.end_glyph) ? 1 : -1;
+              for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir)
+                {
+                  int glyph_width = glyphs->glyphs[i].geometry.width;
+
+                  if (glyph_width == 0)
+                    continue;
+
+                  spaces_so_far += glyph_width;
+
+                  if (mode == ADJUST)
+                    {
+                      int adjustment;
+
+                      adjustment = ((guint64) spaces_so_far * total_remaining_width) / total_space_width - added_so_far;
+                      if (is_hinted)
+                        adjustment = PANGO_UNITS_ROUND (adjustment);
+
+                      glyphs->glyphs[i].geometry.width += adjustment;
+                      added_so_far += adjustment;
+                    }
+                }
+            }
+        }
 
       if (mode == MEASURE)
-	{
-	  total_space_width = spaces_so_far;
+        {
+          total_space_width = spaces_so_far;
 
-	  if (total_space_width == 0)
-	    {
-	      justify_clusters (line, state);
-	      return;
-	    }
-	}
+          if (total_space_width == 0)
+            {
+              justify_clusters (line, state);
+              return;
+            }
+        }
     }
 
   state->remaining_width -= added_so_far;
@@ -5851,8 +5860,8 @@ justify_words (PangoLayoutLine *line,
 
 static void
 pango_layout_line_postprocess (PangoLayoutLine *line,
-			       ParaBreakState  *state,
-			       gboolean         wrapped)
+                               ParaBreakState  *state,
+                               gboolean         wrapped)
 {
   gboolean ellipsized = FALSE;
   
@@ -5872,7 +5881,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line,
   /* Ellipsize the line if necessary
    */
   if (G_UNLIKELY (state->line_width >= 0 &&
-		  should_ellipsize_current_line (line->layout, state)))
+                  should_ellipsize_current_line (line->layout, state)))
     {
       PangoShapeFlags shape_flags = PANGO_SHAPE_NONE;
 
@@ -5902,7 +5911,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line,
     {
       /* if we ellipsized, we don't have remaining_width set */
       if (state->remaining_width < 0)
-	state->remaining_width = state->line_width - pango_layout_line_get_width (line);
+        state->remaining_width = state->line_width - pango_layout_line_get_width (line);
 
       justify_words (line, state);
     }
@@ -5915,7 +5924,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line,
 
 static void
 pango_layout_get_item_properties (PangoItem      *item,
-				  ItemProperties *properties)
+                                  ItemProperties *properties)
 {
   GSList *tmp_list = item->analysis.extra_attrs;
 
@@ -5936,8 +5945,8 @@ pango_layout_get_item_properties (PangoItem      *item,
       PangoAttribute *attr = tmp_list->data;
 
       switch ((int) attr->klass->type)
-	{
-	case PANGO_ATTR_UNDERLINE:
+        {
+        case PANGO_ATTR_UNDERLINE:
           switch (((PangoAttrInt *)attr)->value)
             {
             case PANGO_UNDERLINE_NONE:
@@ -5961,48 +5970,48 @@ pango_layout_get_item_properties (PangoItem      *item,
               g_assert_not_reached ();
               break;
             }
-	  break;
+          break;
 
-	case PANGO_ATTR_OVERLINE:
+        case PANGO_ATTR_OVERLINE:
           switch (((PangoAttrInt *)attr)->value)
             {
             case PANGO_OVERLINE_SINGLE:
-	      properties->oline_single = TRUE;
+              properties->oline_single = TRUE;
               break;
             default:
               g_assert_not_reached ();
               break;
             }
-	  break;
+          break;
 
-	case PANGO_ATTR_STRIKETHROUGH:
-	  properties->strikethrough = ((PangoAttrInt *)attr)->value;
-	  break;
+        case PANGO_ATTR_STRIKETHROUGH:
+          properties->strikethrough = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_RISE:
-	  properties->rise = ((PangoAttrInt *)attr)->value;
-	  break;
+        case PANGO_ATTR_RISE:
+          properties->rise = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_LETTER_SPACING:
-	  properties->letter_spacing = ((PangoAttrInt *)attr)->value;
-	  break;
+        case PANGO_ATTR_LETTER_SPACING:
+          properties->letter_spacing = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_SHAPE:
-	  properties->shape_set = TRUE;
-	  properties->shape_logical_rect = &((PangoAttrShape *)attr)->logical_rect;
-	  properties->shape_ink_rect = &((PangoAttrShape *)attr)->ink_rect;
-	  break;
+        case PANGO_ATTR_SHAPE:
+          properties->shape_set = TRUE;
+          properties->shape_logical_rect = &((PangoAttrShape *)attr)->logical_rect;
+          properties->shape_ink_rect = &((PangoAttrShape *)attr)->ink_rect;
+          break;
 
-	default:
-	  break;
-	}
+        default:
+          break;
+        }
       tmp_list = tmp_list->next;
     }
 }
 
 static int
 next_cluster_start (PangoGlyphString *gs,
-		    int               cluster_start)
+                    int               cluster_start)
 {
   int i;
 
@@ -6010,7 +6019,7 @@ next_cluster_start (PangoGlyphString *gs,
   while (i < gs->num_glyphs)
     {
       if (gs->glyphs[i].attr.is_cluster_start)
-	return i;
+        return i;
 
       i++;
     }
@@ -6020,7 +6029,7 @@ next_cluster_start (PangoGlyphString *gs,
 
 static int
 cluster_width (PangoGlyphString *gs,
-	       int               cluster_start)
+               int               cluster_start)
 {
   int i;
   int width;
@@ -6030,7 +6039,7 @@ cluster_width (PangoGlyphString *gs,
   while (i < gs->num_glyphs)
     {
       if (gs->glyphs[i].attr.is_cluster_start)
-	break;
+        break;
 
       width += gs->glyphs[i].geometry.width;
       i++;
@@ -6041,7 +6050,7 @@ cluster_width (PangoGlyphString *gs,
 
 static inline void
 offset_y (PangoLayoutIter *iter,
-	  int             *y)
+          int             *y)
 {
   *y += iter->line_extents[iter->line_index].baseline;
 }
@@ -6051,7 +6060,7 @@ offset_y (PangoLayoutIter *iter,
  */
 static void
 update_cluster (PangoLayoutIter *iter,
-		int              cluster_start_index)
+                int              cluster_start_index)
 {
   char             *cluster_text;
   PangoGlyphString *gs;
@@ -6069,9 +6078,9 @@ update_cluster (PangoLayoutIter *iter,
        * since logical and visual runs are in the same direction.
        */
       if (iter->next_cluster_glyph < gs->num_glyphs)
-	cluster_length = gs->log_clusters[iter->next_cluster_glyph] - cluster_start_index;
+        cluster_length = gs->log_clusters[iter->next_cluster_glyph] - cluster_start_index;
       else
-	cluster_length = iter->run->item->length - cluster_start_index;
+        cluster_length = iter->run->item->length - cluster_start_index;
     }
   else
     {
@@ -6080,12 +6089,12 @@ update_cluster (PangoLayoutIter *iter,
        */
       int i = iter->cluster_start;
       while (i > 0 && gs->log_clusters[i - 1] == cluster_start_index)
-	i--;
+        i--;
 
       if (i == 0)
-	cluster_length = iter->run->item->length - cluster_start_index;
+        cluster_length = iter->run->item->length - cluster_start_index;
       else
-	cluster_length = gs->log_clusters[i - 1] - cluster_start_index;
+        cluster_length = gs->log_clusters[i - 1] - cluster_start_index;
     }
 
   cluster_text = iter->layout->text + iter->run->item->offset + cluster_start_index;
@@ -6099,7 +6108,7 @@ update_cluster (PangoLayoutIter *iter,
 
 static void
 update_run (PangoLayoutIter *iter,
-	    int              run_start_index)
+            int              run_start_index)
 {
   const Extents *line_ext = &iter->line_extents[iter->line_index];
 
@@ -6145,16 +6154,16 @@ update_run (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_copy:
- * @iter: (nullable): a #PangoLayoutIter, may be %NULL
+ * @iter: (nullable): a `PangoLayoutIter`, may be %NULL
  *
- * Copies a #PangoLayoutIter.
+ * Copies a `PangoLayoutIter`.
  *
- * Return value: (nullable): the newly allocated #PangoLayoutIter,
- *               which should be freed with pango_layout_iter_free(),
- *               or %NULL if @iter was %NULL.
+ * Return value: (nullable): the newly allocated `PangoLayoutIter`,
+ *   which should be freed with [method@Pango.LayoutIter.free],
+ *   or %NULL if @iter was %NULL.
  *
  * Since: 1.20
- **/
+ */
 PangoLayoutIter *
 pango_layout_iter_copy (PangoLayoutIter *iter)
 {
@@ -6207,13 +6216,13 @@ G_DEFINE_BOXED_TYPE (PangoLayoutIter, pango_layout_iter,
 
 /**
  * pango_layout_get_iter:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  *
  * Returns an iterator to iterate over the visual extents of the layout.
  *
- * Return value: the new #PangoLayoutIter that should be freed using
- *               pango_layout_iter_free().
- **/
+ * Return value: the new `PangoLayoutIter` that should be freed using
+ *   [method@Pango.LayoutIter.free].
+ */
 PangoLayoutIter*
 pango_layout_get_iter (PangoLayout *layout)
 {
@@ -6293,7 +6302,7 @@ _pango_layout_iter_destroy (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_free:
- * @iter: (nullable): a #PangoLayoutIter, may be %NULL
+ * @iter: (nullable): a `PangoLayoutIter`, may be %NULL
  *
  * Frees an iterator that's no longer in use.
  **/
@@ -6309,15 +6318,15 @@ pango_layout_iter_free (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_index:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the current byte index. Note that iterating forward by char
  * moves in visual order, not logical order, so indexes may not be
  * sequential. Also, the index may be equal to the length of the text
- * in the layout, if on the %NULL run (see pango_layout_iter_get_run()).
+ * in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]).
  *
  * Return value: current byte index.
- **/
+ */
 int
 pango_layout_iter_get_index (PangoLayoutIter *iter)
 {
@@ -6329,18 +6338,18 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_run:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the current run. When iterating by run, at the end of each
  * line, there's a position with a %NULL run, so this function can return
  * %NULL. The %NULL run at the end of each line ensures that all lines have
  * at least one run, even lines consisting of only a newline.
  *
- * Use the faster pango_layout_iter_get_run_readonly() if you do not plan
- * to modify the contents of the run (glyphs, glyph widths, etc.).
+ * Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not
+ * plan to modify the contents of the run (glyphs, glyph widths, etc.).
  *
  * Return value: (transfer none) (nullable): the current run.
- **/
+ */
 PangoLayoutRun*
 pango_layout_iter_get_run (PangoLayoutIter *iter)
 {
@@ -6354,22 +6363,22 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_run_readonly:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the current run. When iterating by run, at the end of each
  * line, there's a position with a %NULL run, so this function can return
  * %NULL. The %NULL run at the end of each line ensures that all lines have
  * at least one run, even lines consisting of only a newline.
  *
- * This is a faster alternative to pango_layout_iter_get_run(),
- * but the user is not expected
- * to modify the contents of the run (glyphs, glyph widths, etc.).
+ * This is a faster alternative to [method@Pango.LayoutIter.get_run],
+ * but the user is not expected to modify the contents of the run (glyphs,
+ * glyph widths, etc.).
  *
  * Return value: (transfer none) (nullable): the current run, that
  * should not be modified.
  *
  * Since: 1.16
- **/
+ */
 PangoLayoutRun*
 pango_layout_iter_get_run_readonly (PangoLayoutIter *iter)
 {
@@ -6390,15 +6399,16 @@ _pango_layout_iter_get_line (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_line:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the current line.
  *
- * Use the faster pango_layout_iter_get_line_readonly() if you do not plan
- * to modify the contents of the line (glyphs, glyph widths, etc.).
+ * Use the faster [method@Pango.LayoutIter.get_line_readonly] if
+ * you do not plan to modify the contents of the line (glyphs,
+ * glyph widths, etc.).
  *
  * Return value: (transfer none): the current line.
- **/
+ */
 PangoLayoutLine*
 pango_layout_iter_get_line (PangoLayoutIter *iter)
 {
@@ -6412,19 +6422,19 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_line_readonly:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the current line for read-only access.
  *
- * This is a faster alternative to pango_layout_iter_get_line(),
- * but the user is not expected
- * to modify the contents of the line (glyphs, glyph widths, etc.).
+ * This is a faster alternative to [method@Pango.LayoutIter.get_line],
+ * but the user is not expected to modify the contents of the line
+ * (glyphs, glyph widths, etc.).
  *
  * Return value: (transfer none): the current line, that should not be
  * modified.
  *
  * Since: 1.16
- **/
+ */
 PangoLayoutLine*
 pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
 {
@@ -6436,12 +6446,12 @@ pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_at_last_line:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Determines whether @iter is on the last line of the layout.
  *
  * Return value: %TRUE if @iter is on the last line.
- **/
+ */
 gboolean
 pango_layout_iter_at_last_line (PangoLayoutIter *iter)
 {
@@ -6453,14 +6463,14 @@ pango_layout_iter_at_last_line (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_layout:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
- * Gets the layout associated with a #PangoLayoutIter.
+ * Gets the layout associated with a `PangoLayoutIter`.
  *
  * Return value: (transfer none): the layout associated with @iter.
  *
  * Since: 1.20
- **/
+ */
 PangoLayout*
 pango_layout_iter_get_layout (PangoLayoutIter *iter)
 {
@@ -6471,7 +6481,6 @@ pango_layout_iter_get_layout (PangoLayoutIter *iter)
   return iter->layout;
 }
 
-
 static gboolean
 line_is_terminated (PangoLayoutIter *iter)
 {
@@ -6482,7 +6491,7 @@ line_is_terminated (PangoLayoutIter *iter)
     {
       PangoLayoutLine *next_line = iter->line_list_link->next->data;
       if (next_line->is_paragraph_start)
-	return TRUE;
+        return TRUE;
     }
 
   return FALSE;
@@ -6494,7 +6503,7 @@ line_is_terminated (PangoLayoutIter *iter)
  */
 static gboolean
 next_nonempty_line (PangoLayoutIter *iter,
-		    gboolean         include_terminators)
+                    gboolean         include_terminators)
 {
   gboolean result;
 
@@ -6502,13 +6511,13 @@ next_nonempty_line (PangoLayoutIter *iter,
     {
       result = pango_layout_iter_next_line (iter);
       if (!result)
-	break;
+        break;
 
       if (iter->line->runs)
-	break;
+        break;
 
       if (include_terminators && line_is_terminated (iter))
-	break;
+        break;
     }
 
   return result;
@@ -6520,7 +6529,7 @@ next_nonempty_line (PangoLayoutIter *iter,
  */
 static gboolean
 next_nonempty_run (PangoLayoutIter *iter,
-		    gboolean         include_terminators)
+                    gboolean         include_terminators)
 {
   gboolean result;
 
@@ -6528,13 +6537,13 @@ next_nonempty_run (PangoLayoutIter *iter,
     {
       result = pango_layout_iter_next_run (iter);
       if (!result)
-	break;
+        break;
 
       if (iter->run)
-	break;
+        break;
 
       if (include_terminators && line_is_terminated (iter))
-	break;
+        break;
     }
 
   return result;
@@ -6546,7 +6555,7 @@ next_nonempty_run (PangoLayoutIter *iter,
  */
 static gboolean
 next_cluster_internal (PangoLayoutIter *iter,
-		       gboolean         include_terminators)
+                       gboolean         include_terminators)
 {
   PangoGlyphString *gs;
   int               next_start;
@@ -6576,13 +6585,13 @@ next_cluster_internal (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_next_char:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
- * Moves @iter forward to the next character in visual order. If @iter was already at
- * the end of the layout, returns %FALSE.
+ * Moves @iter forward to the next character in visual order.
+ * If @iter was already at the end of the layout, returns %FALSE.
  *
  * Return value: whether motion was possible.
- **/
+ */
 gboolean
 pango_layout_iter_next_char (PangoLayoutIter *iter)
 {
@@ -6595,12 +6604,12 @@ pango_layout_iter_next_char (PangoLayoutIter *iter)
     {
       /* We need to fake an iterator position in the middle of a \r\n line terminator */
       if (line_is_terminated (iter) &&
-	  strncmp (iter->layout->text + iter->line->start_index + iter->line->length, "\r\n", 2) == 0 &&
-	  iter->character_position == 0)
-	{
-	  iter->character_position++;
-	  return TRUE;
-	}
+          strncmp (iter->layout->text + iter->line->start_index + iter->line->length, "\r\n", 2) == 0 &&
+          iter->character_position == 0)
+        {
+          iter->character_position++;
+          return TRUE;
+        }
 
       return next_nonempty_line (iter, TRUE);
     }
@@ -6620,13 +6629,13 @@ pango_layout_iter_next_char (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_next_cluster:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
- * Moves @iter forward to the next cluster in visual order. If @iter
- * was already at the end of the layout, returns %FALSE.
+ * Moves @iter forward to the next cluster in visual order.
+ * If @iter was already at the end of the layout, returns %FALSE.
  *
  * Return value: whether motion was possible.
- **/
+ */
 gboolean
 pango_layout_iter_next_cluster (PangoLayoutIter *iter)
 {
@@ -6635,13 +6644,13 @@ pango_layout_iter_next_cluster (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_next_run:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
- * Moves @iter forward to the next run in visual order. If @iter was
- * already at the end of the layout, returns %FALSE.
+ * Moves @iter forward to the next run in visual order.
+ * If @iter was already at the end of the layout, returns %FALSE.
  *
  * Return value: whether motion was possible.
- **/
+ */
 gboolean
 pango_layout_iter_next_run (PangoLayoutIter *iter)
 {
@@ -6679,13 +6688,13 @@ pango_layout_iter_next_run (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_next_line:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
- * Moves @iter forward to the start of the next line. If @iter is
- * already on the last line, returns %FALSE.
+ * Moves @iter forward to the start of the next line.
+ * If @iter is already on the last line, returns %FALSE.
  *
  * Return value: whether motion was possible.
- **/
+ */
 gboolean
 pango_layout_iter_next_line (PangoLayoutIter *iter)
 {
@@ -6723,7 +6732,7 @@ pango_layout_iter_next_line (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_char_extents:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  * @logical_rect: (out caller-allocates): rectangle to fill with
  *   logical extents
  *
@@ -6731,11 +6740,10 @@ pango_layout_iter_next_line (PangoLayoutIter *iter)
  * (origin is the top left of the entire layout). Only logical extents
  * can sensibly be obtained for characters; ink extents make sense only
  * down to the level of clusters.
- *
- **/
+ */
 void
 pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
-				    PangoRectangle  *logical_rect)
+                                    PangoRectangle  *logical_rect)
 {
   PangoRectangle cluster_rect;
   int            x0, x1;
@@ -6775,18 +6783,17 @@ pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_get_cluster_extents:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
  * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
  *
  * Gets the extents of the current cluster, in layout coordinates
  * (origin is the top left of the entire layout).
- *
- **/
+ */
 void
 pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
-				       PangoRectangle  *ink_rect,
-				       PangoRectangle  *logical_rect)
+                                       PangoRectangle  *ink_rect,
+                                       PangoRectangle  *logical_rect)
 {
   if (ITER_IS_INVALID (iter))
     return;
@@ -6801,11 +6808,11 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
     }
 
   pango_glyph_string_extents_range (iter->run->glyphs,
-				    iter->cluster_start,
-				    iter->next_cluster_glyph,
-				    iter->run->item->analysis.font,
-				    ink_rect,
-				    logical_rect);
+                                    iter->cluster_start,
+                                    iter->next_cluster_glyph,
+                                    iter->run->item->analysis.font,
+                                    ink_rect,
+                                    logical_rect);
 
   if (ink_rect)
     {
@@ -6823,18 +6830,17 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_get_run_extents:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
  * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
  *
  * Gets the extents of the current run in layout coordinates
  * (origin is the top left of the entire layout).
- *
- **/
+ */
 void
 pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
-				   PangoRectangle  *ink_rect,
-				   PangoRectangle  *logical_rect)
+                                   PangoRectangle  *ink_rect,
+                                   PangoRectangle  *logical_rect)
 {
   if (G_UNLIKELY (!ink_rect && !logical_rect))
     return;
@@ -6847,16 +6853,16 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
       pango_layout_run_get_extents_and_height (iter->run, ink_rect, logical_rect, NULL);
 
       if (ink_rect)
-	{
-	  offset_y (iter, &ink_rect->y);
-	  ink_rect->x += iter->run_x;
-	}
+        {
+          offset_y (iter, &ink_rect->y);
+          ink_rect->x += iter->run_x;
+        }
 
       if (logical_rect)
-	{
-	  offset_y (iter, &logical_rect->y);
-	  logical_rect->x += iter->run_x;
-	}
+        {
+          offset_y (iter, &logical_rect->y);
+          logical_rect->x += iter->run_x;
+        }
     }
   else
     {
@@ -6865,37 +6871,36 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
       pango_layout_iter_get_line_extents (iter, ink_rect, logical_rect);
 
       if (ink_rect)
-	{
-	  ink_rect->x = iter->run_x;
-	  ink_rect->width = 0;
-	}
+        {
+          ink_rect->x = iter->run_x;
+          ink_rect->width = 0;
+        }
 
       if (logical_rect)
-	{
-	  logical_rect->x = iter->run_x;
-	  logical_rect->width = 0;
-	}
+        {
+          logical_rect->x = iter->run_x;
+          logical_rect->width = 0;
+        }
     }
 }
 
 /**
  * pango_layout_iter_get_line_extents:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
  * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
  *
  * Obtains the extents of the current line. @ink_rect or @logical_rect
  * can be %NULL if you aren't interested in them. Extents are in layout
  * coordinates (origin is the top-left corner of the entire
- * #PangoLayout).  Thus the extents returned by this function will be
+ * `PangoLayout`). Thus the extents returned by this function will be
  * the same width/height but not at the same x/y as the extents
- * returned from pango_layout_line_get_extents().
- *
- **/
+ * returned from [method@Pango.LayoutLine.get_extents].
+ */
 void
 pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
-				    PangoRectangle  *ink_rect,
-				    PangoRectangle  *logical_rect)
+                                    PangoRectangle  *ink_rect,
+                                    PangoRectangle  *logical_rect)
 {
   const Extents *ext;
 
@@ -6907,11 +6912,11 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
   if (ink_rect)
     {
       get_line_extents_layout_coords (iter->layout, iter->line,
-				      iter->layout_width,
-				      ext->logical_rect.y,
+                                      iter->layout_width,
+                                      ext->logical_rect.y,
                                       NULL,
-				      ink_rect,
-				      NULL);
+                                      ink_rect,
+                                      NULL);
     }
 
   if (logical_rect)
@@ -6920,26 +6925,25 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_get_line_yrange:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  * @y0_: (out) (allow-none): start of line, or %NULL
  * @y1_: (out) (allow-none): end of line, or %NULL
  *
- * Divides the vertical space in the #PangoLayout being iterated over
+ * Divides the vertical space in the `PangoLayout` being iterated over
  * between the lines in the layout, and returns the space belonging to
- * the current line.  A line's range includes the line's logical
- * extents, plus half of the spacing above and below the line, if
- * pango_layout_set_spacing() has been called to set layout spacing.
+ * the current line. A line's range includes the line's logical extents,
+ * plus half of the spacing above and below the line, if
+ * [method@Pango.Layout.set_spacing] has been called to set layout spacing.
  * The Y positions are in layout coordinates (origin at top left of the
  * entire layout).
  *
- * Note: Since 1.44, Pango uses line heights for placing lines,
- * and there may be gaps between the ranges returned by this
- * function.
+ * Note: Since 1.44, Pango uses line heights for placing lines, and there
+ * may be gaps between the ranges returned by this function.
  */
 void
 pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
-				   int             *y0,
-				   int             *y1)
+                                   int             *y0,
+                                   int             *y1)
 {
   const Extents *ext;
   int half_spacing;
@@ -6960,30 +6964,30 @@ pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
       /* No spacing above the first line */
 
       if (iter->line_index == 0)
-	*y0 = ext->logical_rect.y;
+        *y0 = ext->logical_rect.y;
       else
-	*y0 = ext->logical_rect.y - (iter->layout->spacing - half_spacing);
+        *y0 = ext->logical_rect.y - (iter->layout->spacing - half_spacing);
     }
 
   if (y1)
     {
       /* No spacing below the last line */
       if (iter->line_index == iter->layout->line_count - 1)
-	*y1 = ext->logical_rect.y + ext->logical_rect.height;
+        *y1 = ext->logical_rect.y + ext->logical_rect.height;
       else
-	*y1 = ext->logical_rect.y + ext->logical_rect.height + half_spacing;
+        *y1 = ext->logical_rect.y + ext->logical_rect.height + half_spacing;
     }
 }
 
 /**
  * pango_layout_iter_get_baseline:
- * @iter: a #PangoLayoutIter
+ * @iter: a `PangoLayoutIter`
  *
  * Gets the Y position of the current line's baseline, in layout
  * coordinates (origin at top left of the entire layout).
  *
  * Return value: baseline of current line.
- **/
+ */
 int
 pango_layout_iter_get_baseline (PangoLayoutIter *iter)
 {
@@ -6995,21 +6999,17 @@ pango_layout_iter_get_baseline (PangoLayoutIter *iter)
 
 /**
  * pango_layout_iter_get_layout_extents:
- * @iter: a #PangoLayoutIter
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents,
- *            or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical
- *                extents, or %NULL
- *
- * Obtains the extents of the #PangoLayout being iterated
- * over. @ink_rect or @logical_rect can be %NULL if you
- * aren't interested in them.
+ * @iter: a `PangoLayoutIter`
+ * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
+ * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
  *
- **/
+ * Obtains the extents of the `PangoLayout` being iterated over.
+ * @ink_rect or @logical_rect can be %NULL if you aren't interested in them.
+ */
 void
 pango_layout_iter_get_layout_extents  (PangoLayoutIter *iter,
-				       PangoRectangle  *ink_rect,
-				       PangoRectangle  *logical_rect)
+                                       PangoRectangle  *ink_rect,
+                                       PangoRectangle  *logical_rect)
 {
   if (ITER_IS_INVALID (iter))
     return;
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index d0a4fe8f..4a464230 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -36,10 +36,10 @@ typedef struct _PangoLayoutLine  PangoLayoutLine;
 /**
  * PangoLayoutRun:
  *
- * The #PangoLayoutRun structure represents a single run within
- * a #PangoLayoutLine; it is simply an alternate name for
- * #PangoGlyphItem.
- * See the #PangoGlyphItem docs for details on the fields.
+ * A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`.
+ *
+ * It is simply an alternate name for [struct@Pango.GlyphItem].
+ * See the [struct@Pango.GlyphItem] docs for details on the fields.
  */
 typedef PangoGlyphItem PangoLayoutRun;
 
@@ -49,9 +49,11 @@ typedef PangoGlyphItem PangoLayoutRun;
  * @PANGO_ALIGN_CENTER: Center the line within the available space
  * @PANGO_ALIGN_RIGHT: Put all available space on the left
  *
- * A #PangoAlignment describes how to align the lines of a #PangoLayout within the
- * available space. If the #PangoLayout is set to justify
- * using pango_layout_set_justify(), this only has effect for partial lines.
+ * `PangoAlignment` describes how to align the lines of a `PangoLayout`
+ * within the available space.
+ *
+ * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify],
+ * this only has effect for partial lines.
  */
 typedef enum {
   PANGO_ALIGN_LEFT,
@@ -63,10 +65,11 @@ typedef enum {
  * PangoWrapMode:
  * @PANGO_WRAP_WORD: wrap lines at word boundaries.
  * @PANGO_WRAP_CHAR: wrap lines at character boundaries.
- * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is not
- * enough space for a full word.
+ * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to
+ *   character boundaries if there is not enough space for a full word.
  *
- * A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
+ * `PangoWrapMode` describes how to wrap the lines of a `PangoLayout`
+ * to the desired width.
  */
 typedef enum {
   PANGO_WRAP_WORD,
@@ -81,9 +84,10 @@ typedef enum {
  * @PANGO_ELLIPSIZE_MIDDLE: Omit characters in the middle of the text
  * @PANGO_ELLIPSIZE_END: Omit characters at the end of the text
  *
- * The #PangoEllipsizeMode type describes what sort of (if any)
- * ellipsization should be applied to a line of text. In
- * the ellipsization process characters are removed from the
+ * `PangoEllipsizeMode` describes what sort of ellipsization
+ * should be applied to text.
+ *
+ * In the ellipsization process characters are removed from the
  * text in order to make it fit to a given width and replaced
  * with an ellipsis.
  */
@@ -104,14 +108,12 @@ typedef enum {
  * @is_paragraph_start: #TRUE if this is the first line of the paragraph
  * @resolved_dir: #Resolved PangoDirection of line
  *
- * The #PangoLayoutLine structure represents one of the lines resulting
- * from laying out a paragraph via #PangoLayout. #PangoLayoutLine
- * structures are obtained by calling pango_layout_get_line() and
- * are only valid until the text, attributes, or settings of the
- * parent #PangoLayout are modified.
+ * A `PangoLayoutLine` represents one of the lines resulting from laying
+ * out a paragraph via `PangoLayout`.
  *
- * Routines for rendering PangoLayout objects are provided in
- * code specific to each rendering system.
+ * `PangoLayoutLine` structures are obtained by calling
+ * [method@Pango.Layout.get_line] and are only valid until the text,
+ * attributes, or settings of the parent `PangoLayout` are modified.
  */
 struct _PangoLayoutLine
 {
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index d0b47016..eca3e630 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -30,197 +30,6 @@
 #include "pango-impl-utils.h"
 #include "pango-utils-internal.h"
 
-/**
- * SECTION:markup
- * @title:Markup
- * @short_description:Simple markup language for text with attributes
- *
- * Frequently, you want to display some text to the user with attributes
- * applied to part of the text (for example, you might want bold or
- * italicized words). With the base Pango interfaces, you could create a
- * #PangoAttrList and apply it to the text; the problem is that you'd
- * need to apply attributes to some numeric range of characters, for
- * example "characters 12-17." This is broken from an internationalization
- * standpoint; once the text is translated, the word you wanted to
- * italicize could be in a different position.
- *
- * The solution is to include the text attributes in the string to be
- * translated. Pango provides this feature with a small markup language.
- * You can parse a marked-up string into the string text plus a
- * #PangoAttrList using either of pango_parse_markup() or
- * pango_markup_parser_new().
- *
- * A simple example of a marked-up string might be:
- * |[
- * <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
- * ]|
- *
- * Pango uses #GMarkup to parse this language, which means that XML
- * features such as numeric character entities such as `&#169;` for
- * © can be used too.
- *
- * The root tag of a marked-up document is `<markup>`, but
- * pango_parse_markup() allows you to omit this tag, so you will most
- * likely never need to use it. The most general markup tag is `<span>`,
- * then there are some convenience tags.
- *
- * ## Span attributes
- *
- * `<span>` has the following attributes:
- *
- * * `font_desc`:
- *   A font description string, such as "Sans Italic 12".
- *   See pango_font_description_from_string() for a description of the
- *   format of the string representation . Note that any other span
- *   attributes will override this description. So if you have "Sans Italic"
- *   and also a `style="normal"` attribute, you will get Sans normal,
- *   not italic.
- *
- * * `font_family`:
- *   A font family name
- *
- * * `font_size`, `size`:
- *   Font size in 1024ths of a point, or one of the absolute
- *   sizes `xx-small`, `x-small`, `small`, `medium`, `large`,
- *   `x-large`, `xx-large`, or one of the relative sizes `smaller`
- *   or `larger`. If you want to specify a absolute size, it's usually
- *   easier to take advantage of the ability to specify a partial
- *   font description using `font`; you can use `font='12.5'`
- *   rather than `size='12800'`.
- *
- * * `font_style`:
- *   One of `normal`, `oblique`, `italic`
- *
- * * `font_weight`:
- *   One of `ultralight`, `light`, `normal`, `bold`,
- *   `ultrabold`, `heavy`, or a numeric weight
- *
- * * `font_variant`:
- *   One of `normal` or `smallcaps`
- *
- * * `font_stretch`, `stretch`:
- *   One of `ultracondensed`, `extracondensed`, `condensed`,
- *   `semicondensed`, `normal`, `semiexpanded`, `expanded`,
- *   `extraexpanded`, `ultraexpanded`
- *
- * * `font_features`:
- *   A comma-separated list of OpenType font feature
- *   settings, in the same syntax as accepted by CSS. E.g:
- *   `font_features='dlig=1, -kern, afrc on'`
- *
- * * `foreground`, `fgcolor`:
- *   An RGB color specification such as `#00FF00` or a color
- *   name such as `red`. Since 1.38, an RGBA color specification such
- *   as `#00FF007F` will be interpreted as specifying both a foreground
- *   color and foreground alpha.
- *
- * * `background`, `bgcolor`:
- *   An RGB color specification such as `#00FF00` or a color
- *   name such as `red`.
- *   Since 1.38, an RGBA color specification such as `#00FF007F` will
- *   be interpreted as specifying both a background color and
- *   background alpha.
- *
- * * `alpha`, `fgalpha`:
- *   An alpha value for the foreground color, either a plain
- *   integer between 1 and 65536 or a percentage value like `50%`.
- *
- * * `background_alpha`, `bgalpha`:
- *   An alpha value for the background color, either a plain
- *   integer between 1 and 65536 or a percentage value like `50%`.
- *
- * * `underline`:
- *   One of `none`, `single`, `double`, `low`, `error`,
- *   `single-line`, `double-line` or `error-line`.
- *
- * * `underline_color`:
- *   The color of underlines; an RGB color
- *   specification such as `#00FF00` or a color name such as `red`
- *
- * * `overline`:
- *   One of `none` or `single`
- *
- * * `overline_color`:
- *   The color of overlines; an RGB color
- *   specification such as `#00FF00` or a color name such as `red`
- *
- * * `rise`:
- *   Vertical displacement, in Pango units. Can be negative for
- *   subscript, positive for superscript.
- *
- * * `strikethrough`
- *   `true` or `false` whether to strike through the text
- *
- * * `strikethrough_color`:
- *   The color of strikethrough lines; an RGB
- *   color specification such as `#00FF00` or a color name such as `red`
- *
- * * `fallback`:
- *   `true` or `false` whether to enable fallback. If
- *   disabled, then characters will only be used from the closest
- *   matching font on the system. No fallback will be done to other
- *   fonts on the system that might contain the characters in the text.
- *   Fallback is enabled by default. Most applications should not
- *   disable fallback.
- *
- * * `allow_breaks`:
- *   `true` or `false` whether to allow line breaks or not. If
- *   not allowed, the range will be kept in a single run as far
- *   as possible. Breaks are allowed by default.
- *
- * * `insert_hyphens`:`
- *   `true` or `false` whether to insert hyphens when breaking
- *   lines in the middle of a word. Hyphens are inserted by default.
- *
- * * `show`:
- *   A value determining how invisible characters are treated.
- *   Possible values are `spaces`, `line-breaks`, `ignorables`
- *   or combinations, such as `spaces|line-breaks`.
- *
- * * `lang`:
- *   A language code, indicating the text language
- *
- * * `letter_spacing`:
- *   Inter-letter spacing in 1024ths of a point.
- *
- * * `gravity`:
- *   One of `south`, `east`, `north`, `west`, `auto`.
- *
- * * `gravity_hint`:
- *   One of `natural`, `strong`, `line`.
- *
- * ## Convenience tags
- *
- * The following convenience tags are provided:
- *
- * * `<b>`:
- *   Bold
- *
- * * `<big>`:
- *   Makes font relatively larger, equivalent to `<span size="larger">`
- *
- * * `<i>`:
- *   Italic
- *
- * * `<s>`:
- *   Strikethrough
- *
- * * `<sub>`:
- *   Subscript
- *
- * * `<sup>`:
- *   Superscript
- *
- * * `<small>`:
- *   Makes font relatively smaller, equivalent to `<span size="smaller">`
- *
- * * `<tt>`:
- *   Monospace
- *
- * * `<u>`:
- *   Underline
- */
-
 /* FIXME */
 #define _(x) x
 
@@ -790,17 +599,18 @@ pango_markup_parser_new_internal (char       accel_marker,
 
 /**
  * pango_parse_markup:
- * @markup_text: markup to parse (see <link linkend="PangoMarkupFormat">markup format</link>)
+ * @markup_text: markup to parse (see the Pango Markup docs)
  * @length: length of @markup_text, or -1 if nul-terminated
  * @accel_marker: character that precedes an accelerator, or 0 for none
- * @attr_list: (out) (allow-none): address of return location for a #PangoAttrList, or %NULL
+ * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
  * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
  * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
  * @error: address of return location for errors, or %NULL
  *
- * Parses marked-up text (see
- * <link linkend="PangoMarkupFormat">markup format</link>) to create
- * a plain-text string and an attribute list.
+ * Parses marked-up text to create a plain-text string and an attribute list.
+ *
+ * See the [Pango Markup](pango_markup.html) docs for details about the
+ * supported markup.
  *
  * If @accel_marker is nonzero, the given character will mark the
  * character following it as an accelerator. For example, @accel_marker
@@ -810,7 +620,7 @@ pango_markup_parser_new_internal (char       accel_marker,
  * Two @accel_marker characters following each other produce a single
  * literal @accel_marker character.
  *
- * To parse a stream of pango markup incrementally, use pango_markup_parser_new().
+ * To parse a stream of pango markup incrementally, use [func@markup_parser_new].
  *
  * If any error happens, none of the output arguments are touched except
  * for @error.
@@ -872,28 +682,30 @@ pango_parse_markup (const char                 *markup_text,
  * pango_markup_parser_new:
  * @accel_marker: character that precedes an accelerator, or 0 for none
  *
- * Parses marked-up text (see
- * <link linkend="PangoMarkupFormat">markup format</link>) to create
- * a plain-text string and an attribute list.
+ * Incrementally parses marked-up text to create a plain-text string
+ * and an attribute list.
+ *
+ * See the [Pango Markup](pango_markup.html) docs for details about the
+ * supported markup.
  *
  * If @accel_marker is nonzero, the given character will mark the
  * character following it as an accelerator. For example, @accel_marker
  * might be an ampersand or underscore. All characters marked
  * as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute,
  * and the first character so marked will be returned in @accel_char,
- * when calling finish(). Two @accel_marker characters following each
- * other produce a single literal @accel_marker character.
+ * when calling [func@markup_parser_finish]. Two @accel_marker characters
+ * following each other produce a single literal @accel_marker character.
  *
  * To feed markup to the parser, use g_markup_parse_context_parse()
- * on the returned #GMarkupParseContext. When done with feeding markup
- * to the parser, use pango_markup_parser_finish() to get the data out
+ * on the returned `GMarkupParseContext`. When done with feeding markup
+ * to the parser, use [func@markup_parser_finish] to get the data out
  * of it, and then use g_markup_parse_context_free() to free it.
  *
- * This function is designed for applications that read pango markup
- * from streams. To simply parse a string containing pango markup,
- * the simpler pango_parse_markup() API is recommended instead.
+ * This function is designed for applications that read Pango markup
+ * from streams. To simply parse a string containing Pango markup,
+ * the [func@parse_markup] API is recommended instead.
  *
- * Return value: (transfer none): a #GMarkupParseContext that should be
+ * Return value: (transfer none): a `GMarkupParseContext` that should be
  * destroyed with g_markup_parse_context_free().
  *
  * Since: 1.31.0
@@ -913,14 +725,16 @@ pango_markup_parser_new (gunichar               accel_marker)
 
 /**
  * pango_markup_parser_finish:
- * @context: A valid parse context that was returned from pango_markup_parser_new()
- * @attr_list: (out) (allow-none): address of return location for a #PangoAttrList, or %NULL
+ * @context: A valid parse context that was returned from [func@markup_parser_new]
+ * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
  * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
  * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
  * @error: address of return location for errors, or %NULL
  *
- * After feeding a pango markup parser some data with g_markup_parse_context_parse(),
- * use this function to get the list of pango attributes and text out of the
+ * Finishes parsing markup.
+ *
+ * After feeding a Pango markup parser some data with g_markup_parse_context_parse(),
+ * use this function to get the list of attributes and text out of the
  * markup. This function will not free @context, use g_markup_parse_context_free()
  * to do so.
  *
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 50f8be1a..731c3a26 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -32,16 +32,16 @@ G_DEFINE_BOXED_TYPE (PangoMatrix, pango_matrix,
 
 /**
  * pango_matrix_copy:
- * @matrix: (nullable): a #PangoMatrix, may be %NULL
+ * @matrix: (nullable): a `PangoMatrix`, may be %NULL
  *
- * Copies a #PangoMatrix.
+ * Copies a `PangoMatrix`.
  *
- * Return value: (nullable): the newly allocated #PangoMatrix, which
- *               should be freed with pango_matrix_free(), or %NULL if
- *               @matrix was %NULL.
+ * Return value: (nullable): the newly allocated `PangoMatrix`, which
+ *   should be freed with [method@Pango.Matrix.free], or %NULL if
+ *   @matrix was %NULL.
  *
  * Since: 1.6
- **/
+ */
 PangoMatrix *
 pango_matrix_copy (const PangoMatrix *matrix)
 {
@@ -59,12 +59,12 @@ pango_matrix_copy (const PangoMatrix *matrix)
 
 /**
  * pango_matrix_free:
- * @matrix: (nullable): a #PangoMatrix, may be %NULL
+ * @matrix: (nullable): a `PangoMatrix`, may be %NULL
  *
- * Free a #PangoMatrix created with pango_matrix_copy().
+ * Free a `PangoMatrix`.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_matrix_free (PangoMatrix *matrix)
 {
@@ -76,7 +76,7 @@ pango_matrix_free (PangoMatrix *matrix)
 
 /**
  * pango_matrix_translate:
- * @matrix: a #PangoMatrix
+ * @matrix: a `PangoMatrix`
  * @tx: amount to translate in the X direction
  * @ty: amount to translate in the Y direction
  *
@@ -85,7 +85,7 @@ pango_matrix_free (PangoMatrix *matrix)
  * then applying the original transformation.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_matrix_translate (PangoMatrix *matrix,
 			double       tx,
@@ -99,7 +99,7 @@ pango_matrix_translate (PangoMatrix *matrix,
 
 /**
  * pango_matrix_scale:
- * @matrix: a #PangoMatrix
+ * @matrix: a `PangoMatrix`
  * @scale_x: amount to scale by in X direction
  * @scale_y: amount to scale by in Y direction
  *
@@ -109,7 +109,7 @@ pango_matrix_translate (PangoMatrix *matrix,
  * transformation.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_matrix_scale (PangoMatrix *matrix,
 		    double       scale_x,
@@ -125,7 +125,7 @@ pango_matrix_scale (PangoMatrix *matrix,
 
 /**
  * pango_matrix_rotate:
- * @matrix: a #PangoMatrix
+ * @matrix: a `PangoMatrix`
  * @degrees: degrees to rotate counter-clockwise
  *
  * Changes the transformation represented by @matrix to be the
@@ -133,7 +133,7 @@ pango_matrix_scale (PangoMatrix *matrix,
  * counter-clockwise then applying the original transformation.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_matrix_rotate (PangoMatrix *matrix,
 		     double       degrees)
@@ -159,15 +159,15 @@ pango_matrix_rotate (PangoMatrix *matrix,
 
 /**
  * pango_matrix_concat:
- * @matrix: a #PangoMatrix
- * @new_matrix: a #PangoMatrix
+ * @matrix: a `PangoMatrix`
+ * @new_matrix: a `PangoMatrix`
  *
  * Changes the transformation represented by @matrix to be the
  * transformation given by first applying transformation
  * given by @new_matrix then applying the original transformation.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_matrix_concat (PangoMatrix       *matrix,
 		     const PangoMatrix *new_matrix)
@@ -188,18 +188,19 @@ pango_matrix_concat (PangoMatrix       *matrix,
 
 /**
  * pango_matrix_get_font_scale_factor:
- * @matrix: (allow-none): a #PangoMatrix, may be %NULL
+ * @matrix: (allow-none): a `PangoMatrix`, may be %NULL
  *
  * Returns the scale factor of a matrix on the height of the font.
+ *
  * That is, the scale factor in the direction perpendicular to the
  * vector that the X coordinate is mapped to.  If the scale in the X
- * coordinate is needed as well, use pango_matrix_get_font_scale_factors().
+ * coordinate is needed as well, use [method@Pango.Matrix.get_font_scale_factors].
  *
  * Return value: the scale factor of @matrix on the height of the font,
- * or 1.0 if @matrix is %NULL.
+ *   or 1.0 if @matrix is %NULL.
  *
  * Since: 1.12
- **/
+ */
 double
 pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
 {
@@ -210,11 +211,12 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
 
 /**
  * pango_matrix_get_font_scale_factors:
- * @matrix: (nullable): a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL
  * @xscale: (out) (allow-none): output scale factor in the x direction, or %NULL
  * @yscale: (out) (allow-none): output scale factor perpendicular to the x direction, or %NULL
  *
  * Calculates the scale factor of a matrix on the width and height of the font.
+ *
  * That is, @xscale is the scale factor in the direction of the X coordinate,
  * and @yscale is the scale factor in the direction perpendicular to the
  * vector that the X coordinate is mapped to.
@@ -264,19 +266,20 @@ pango_matrix_get_font_scale_factors (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_distance:
- * @matrix: (nullable): a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL
  * @dx: (inout): in/out X component of a distance vector
  * @dy: (inout): in/out Y component of a distance vector
  *
- * Transforms the distance vector (@dx,@dy) by @matrix. This is
- * similar to pango_matrix_transform_point() except that the translation
- * components of the transformation are ignored. The calculation of
- * the returned vector is as follows:
+ * Transforms the distance vector (@dx,@dy) by @matrix.
+ *
+ * This is similar to [method@Pango.Matrix.transform_point],
+ * except that the translation components of the transformation
+ * are ignored. The calculation of the returned vector is as follows:
  *
- * <programlisting>
+ * ```
  * dx2 = dx1 * xx + dy1 * xy;
  * dy2 = dx1 * yx + dy1 * yy;
- * </programlisting>
+ * ```
  *
  * Affine transformations are position invariant, so the same vector
  * always transforms to the same vector. If (@x1,@y1) transforms
@@ -284,7 +287,7 @@ pango_matrix_get_font_scale_factors (const PangoMatrix *matrix,
  * (@x1+@dx2,@y1+@dy2) for all values of @x1 and @x2.
  *
  * Since: 1.16
- **/
+ */
 void
 pango_matrix_transform_distance (const PangoMatrix *matrix,
 				 double            *dx,
@@ -304,7 +307,7 @@ pango_matrix_transform_distance (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_point:
- * @matrix: (nullable): a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL
  * @x: (inout): in/out X position
  * @y: (inout): in/out Y position
  *
@@ -328,18 +331,18 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_rectangle:
- * @matrix: (nullable): a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL
  * @rect: (inout) (allow-none): in/out bounding box in Pango units, or %NULL
  *
  * First transforms @rect using @matrix, then calculates the bounding box
- * of the transformed rectangle.  The rectangle should be in Pango units.
+ * of the transformed rectangle.
  *
  * This function is useful for example when you want to draw a rotated
  * @PangoLayout to an image buffer, and want to know how large the image
  * should be and how much you should shift the layout when rendering.
  *
  * If you have a rectangle in device units (pixels), use
- * pango_matrix_transform_pixel_rectangle().
+ * [method@Pango.Matrix.transform_pixel_rectangle].
  *
  * If you have the rectangle in Pango units and want to convert to
  * transformed pixel bounding box, it is more accurate to transform it first
@@ -351,7 +354,7 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
  * example).
  *
  * Since: 1.16
- **/
+ */
 void
 pango_matrix_transform_rectangle (const PangoMatrix *matrix,
 				  PangoRectangle    *rect)
@@ -408,23 +411,22 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_pixel_rectangle:
- * @matrix: (nullable): a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL
  * @rect: (inout) (allow-none): in/out bounding box in device units, or %NULL
  *
  * First transforms the @rect using @matrix, then calculates the bounding box
- * of the transformed rectangle.  The rectangle should be in device units
- * (pixels).
+ * of the transformed rectangle.
  *
  * This function is useful for example when you want to draw a rotated
  * @PangoLayout to an image buffer, and want to know how large the image
  * should be and how much you should shift the layout when rendering.
  *
- * For better accuracy, you should use pango_matrix_transform_rectangle() on
- * original rectangle in Pango units and convert to pixels afterward
- * using pango_extents_to_pixels()'s first argument.
+ * For better accuracy, you should use [method@Pango.Matrix.transform_rectangle]
+ * on original rectangle in Pango units and convert to pixels afterward
+ * using [func@extents_to_pixels]'s first argument.
  *
  * Since: 1.16
- **/
+ */
 void
 pango_matrix_transform_pixel_rectangle (const PangoMatrix *matrix,
 					PangoRectangle    *rect)
diff --git a/pango/pango-matrix.h b/pango/pango-matrix.h
index 9ec37042..c3ff5414 100644
--- a/pango/pango-matrix.h
+++ b/pango/pango-matrix.h
@@ -38,17 +38,18 @@ typedef struct _PangoMatrix    PangoMatrix;
  * @x0: x translation
  * @y0: y translation
  *
- * A structure specifying a transformation between user-space
- * coordinates and device coordinates. The transformation
- * is given by
+ * A `PangoMatrix` specifies a transformation between user-space
+ * and device coordinates.
  *
- * <programlisting>
+ * The transformation is given by
+ *
+ * ```
  * x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0;
  * y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0;
- * </programlisting>
+ * ```
  *
  * Since: 1.6
- **/
+ */
 struct _PangoMatrix
 {
   double xx;
@@ -72,10 +73,10 @@ struct _PangoMatrix
  * Constant that can be used to initialize a PangoMatrix to
  * the identity transform.
  *
- * <informalexample><programlisting>
+ * ```
  * PangoMatrix matrix = PANGO_MATRIX_INIT;
- * pango_matrix_rotate (&amp;matrix, 45.);
- * </programlisting></informalexample>
+ * pango_matrix_rotate (&matrix, 45.);
+ * ```
  *
  * Since: 1.6
  **/
diff --git a/pango/pango-modules.h b/pango/pango-modules.h
index 64900a17..54b347a2 100644
--- a/pango/pango-modules.h
+++ b/pango/pango-modules.h
@@ -26,6 +26,11 @@
 
 G_BEGIN_DECLS
 
+/* All of this is deprecated and entirely useless for bindings.
+ * Leave it out of the gir file.
+ */
+#ifndef __GI_SCANNER__
+
 #ifndef PANGO_DISABLE_DEPRECATED
 
 typedef struct _PangoMap PangoMap;
@@ -72,6 +77,8 @@ void           pango_module_register (PangoIncludedModule *module);
 
 #endif /* PANGO_DISABLE_DEPRECATED */
 
+#endif /* __GI_SCANNER__ */
+
 G_END_DECLS
 
 #endif /* __PANGO_MODULES_H__ */
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index 2b1b61f4..891ae323 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -19,18 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:opentype
- * @short_description:Obtaining information from OpenType tables
- * @title:OpenType Font Handling
- * @stability:Unstable
- *
- * Functions and macros in this section are used to implement
- * the OpenType Layout features and algorithms.
- *
- * They have been superseded by the harfbuzz library, and should
- * not be used anymore.
- */
 #include "config.h"
 
 #include "pango-ot-private.h"
@@ -76,7 +64,7 @@ pango_ot_info_finalizer (void *object)
 
 /**
  * pango_ot_info_get:
- * @face: a <type>FT_Face</type>.
+ * @face: a FT_Face
  *
  * Returns the #PangoOTInfo structure for the given FreeType font face.
  *
diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h
index d9d86644..7ba44c6a 100644
--- a/pango/pango-ot-private.h
+++ b/pango/pango-ot-private.h
@@ -40,7 +40,7 @@ typedef struct _PangoOTInfoClass PangoOTInfoClass;
  *
  * The #PangoOTInfo struct contains the various
  * tables associated with an OpenType font. It contains only private fields and
- * should only be accessed via the <function>pango_ot_info_*</function> functions
+ * should only be accessed via the pango_ot_info_… functions
  * which are documented below. To obtain a #PangoOTInfo,
  * use pango_ot_info_get().
  */
@@ -76,7 +76,7 @@ struct _PangoOTRulesetClass
  * The #PangoOTBuffer structure is used to store strings of glyphs associated
  * with a #PangoFcFont, suitable for OpenType layout processing.  It contains
  * only private fields and should only be accessed via the
- * <function>pango_ot_buffer_*</function> functions which are documented below.
+ * pango_ot_buffer_… functions which are documented below.
  * To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
  */
 struct _PangoOTBuffer
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 9df8faef..9cf4cfb0 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -120,29 +120,23 @@ pango_ot_ruleset_new (PangoOTInfo *info)
  * script, language, or feature indices manually.
  *
  * In excess to what pango_ot_ruleset_new() does, this function will:
- * <itemizedlist>
- *   <listitem>
- *   Find the #PangoOTTag script and language tags associated with
+ *
+ * * Find the #PangoOTTag script and language tags associated with
  *   @script and @language using pango_ot_tag_from_script() and
  *   pango_ot_tag_from_language(),
- *   </listitem>
- *   <listitem>
- *   For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS,
+ *
+ * * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS,
  *   find the script index of the script tag found and the language
  *   system index of the language tag found in that script system, using
  *   pango_ot_info_find_script() and pango_ot_info_find_language(),
- *   </listitem>
- *   <listitem>
- *   For found language-systems, if they have required feature
+ *
+ * * For found language-systems, if they have required feature
  *   index, add that feature to the ruleset using
  *   pango_ot_ruleset_add_feature(),
- *   </listitem>
- *   <listitem>
- *   Remember found script and language indices for both table types,
+ *
+ * * Remember found script and language indices for both table types,
  *   and use them in future pango_ot_ruleset_maybe_add_feature() and
  *   pango_ot_ruleset_maybe_add_features().
- *   </listitem>
- * </itemizedlist>
  *
  * Because of the way return values of pango_ot_info_find_script() and
  * pango_ot_info_find_language() are ignored, this function automatically
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index b8c6acc8..6390538b 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -42,7 +42,7 @@ G_BEGIN_DECLS
  *
  * The #PangoOTTag typedef is used to represent TrueType and OpenType
  * four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
- * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually.
+ * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually.
  */
 typedef guint32 PangoOTTag;
 
@@ -54,7 +54,7 @@ typedef guint32 PangoOTTag;
  * @c4: Fourth character.
  *
  * Creates a #PangoOTTag from four characters.  This is similar and
- * compatible with the <function>FT_MAKE_TAG()</function> macro from FreeType.
+ * compatible with the FT_MAKE_TAG() macro from FreeType.
  */
 /**
  * PANGO_OT_TAG_MAKE_FROM_STRING:
@@ -84,9 +84,9 @@ typedef struct _PangoOTRulesetDescription PangoOTRulesetDescription;
  * @PANGO_OT_TABLE_GSUB: The GSUB table.
  * @PANGO_OT_TABLE_GPOS: The GPOS table.
  *
- * The <type>PangoOTTableType</type> enumeration values are used to
+ * The PangoOTTableType enumeration values are used to
  * identify the various OpenType tables in the
- * <function>pango_ot_info_*</function> functions.
+ * pango_ot_info_… functions.
  */
 typedef enum
 {
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index 432875a4..2d676782 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -67,37 +67,37 @@ struct _PangoRendererPrivate
 
 static void pango_renderer_finalize                     (GObject          *gobject);
 static void pango_renderer_default_draw_glyphs          (PangoRenderer    *renderer,
-							 PangoFont        *font,
-							 PangoGlyphString *glyphs,
-							 int               x,
-							 int               y);
+                                                         PangoFont        *font,
+                                                         PangoGlyphString *glyphs,
+                                                         int               x,
+                                                         int               y);
 static void pango_renderer_default_draw_glyph_item      (PangoRenderer    *renderer,
-							 const char       *text,
-							 PangoGlyphItem   *glyph_item,
-							 int               x,
-							 int               y);
+                                                         const char       *text,
+                                                         PangoGlyphItem   *glyph_item,
+                                                         int               x,
+                                                         int               y);
 static void pango_renderer_default_draw_rectangle       (PangoRenderer    *renderer,
-							 PangoRenderPart   part,
-							 int               x,
-							 int               y,
-							 int               width,
-							 int               height);
+                                                         PangoRenderPart   part,
+                                                         int               x,
+                                                         int               y,
+                                                         int               width,
+                                                         int               height);
 static void pango_renderer_default_draw_error_underline (PangoRenderer    *renderer,
-							 int               x,
-							 int               y,
-							 int               width,
-							 int               height);
+                                                         int               x,
+                                                         int               y,
+                                                         int               width,
+                                                         int               height);
 static void pango_renderer_default_prepare_run          (PangoRenderer    *renderer,
-							 PangoLayoutRun   *run);
+                                                         PangoLayoutRun   *run);
 
 static void pango_renderer_prepare_run (PangoRenderer  *renderer,
-					PangoLayoutRun *run);
+                                        PangoLayoutRun *run);
 
 static void
 to_device (PangoMatrix *matrix,
-	   double       x,
-	   double       y,
-	   Point       *result)
+           double       x,
+           double       y,
+           Point       *result)
 {
   if (matrix)
     {
@@ -148,22 +148,22 @@ pango_renderer_finalize (GObject *gobject)
 
 /**
  * pango_renderer_draw_layout:
- * @renderer: a #PangoRenderer
- * @layout: a #PangoLayout
+ * @renderer: a `PangoRenderer`
+ * @layout: a `PangoLayout`
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
  *    in Pango units.
  *
- * Draws @layout with the specified #PangoRenderer.
+ * Draws @layout with the specified `PangoRenderer`.
  *
  * Since: 1.8
- **/
+ */
 void
-pango_renderer_draw_layout (PangoRenderer    *renderer,
-			    PangoLayout      *layout,
-			    int               x,
-			    int               y)
+pango_renderer_draw_layout (PangoRenderer *renderer,
+                            PangoLayout   *layout,
+                            int            x,
+                            int            y)
 {
   PangoLayoutIter iter;
 
@@ -177,7 +177,7 @@ pango_renderer_draw_layout (PangoRenderer    *renderer,
     {
       PangoContext *context = pango_layout_get_context (layout);
       pango_renderer_set_matrix (renderer,
-				 pango_context_get_matrix (context));
+                                 pango_context_get_matrix (context));
     }
 
   pango_renderer_activate (renderer);
@@ -196,9 +196,9 @@ pango_renderer_draw_layout (PangoRenderer    *renderer,
       baseline = pango_layout_iter_get_baseline (&iter);
 
       pango_renderer_draw_layout_line (renderer,
-				       line,
-				       x + logical_rect.x,
-				       y + baseline);
+                                       line,
+                                       x + logical_rect.x,
+                                       y + baseline);
     }
   while (pango_layout_iter_next_line (&iter));
 
@@ -209,7 +209,7 @@ pango_renderer_draw_layout (PangoRenderer    *renderer,
 
 static void
 draw_underline (PangoRenderer *renderer,
-		LineState     *state)
+                LineState     *state)
 {
   PangoRectangle *rect = &state->underline_rect;
   PangoUnderline underline = state->underline;
@@ -223,29 +223,29 @@ draw_underline (PangoRenderer *renderer,
     case PANGO_UNDERLINE_DOUBLE:
     case PANGO_UNDERLINE_DOUBLE_LINE:
       pango_renderer_draw_rectangle (renderer,
-				     PANGO_RENDER_PART_UNDERLINE,
-				     rect->x,
-				     rect->y + 2 * rect->height,
-				     rect->width,
-				     rect->height);
+                                     PANGO_RENDER_PART_UNDERLINE,
+                                     rect->x,
+                                     rect->y + 2 * rect->height,
+                                     rect->width,
+                                     rect->height);
       G_GNUC_FALLTHROUGH;
     case PANGO_UNDERLINE_SINGLE:
     case PANGO_UNDERLINE_LOW:
     case PANGO_UNDERLINE_SINGLE_LINE:
       pango_renderer_draw_rectangle (renderer,
-				     PANGO_RENDER_PART_UNDERLINE,
-				     rect->x,
-				     rect->y,
-				     rect->width,
-				     rect->height);
+                                     PANGO_RENDER_PART_UNDERLINE,
+                                     rect->x,
+                                     rect->y,
+                                     rect->width,
+                                     rect->height);
       break;
     case PANGO_UNDERLINE_ERROR:
     case PANGO_UNDERLINE_ERROR_LINE:
       pango_renderer_draw_error_underline (renderer,
-					   rect->x,
-					   rect->y,
-					   rect->width,
-					   3 * rect->height);
+                                           rect->x,
+                                           rect->y,
+                                           rect->width,
+                                           3 * rect->height);
       break;
     }
 }
@@ -265,18 +265,18 @@ draw_overline (PangoRenderer *renderer,
       break;
     case PANGO_OVERLINE_SINGLE:
       pango_renderer_draw_rectangle (renderer,
-				     PANGO_RENDER_PART_OVERLINE,
-				     rect->x,
-				     rect->y,
-				     rect->width,
-				     rect->height);
+                                     PANGO_RENDER_PART_OVERLINE,
+                                     rect->x,
+                                     rect->y,
+                                     rect->width,
+                                     rect->height);
       break;
     }
 }
 
 static void
 draw_strikethrough (PangoRenderer *renderer,
-		    LineState     *state)
+                    LineState     *state)
 {
   PangoRectangle *rect = &state->strikethrough_rect;
   gboolean strikethrough = state->strikethrough;
@@ -295,7 +295,7 @@ draw_strikethrough (PangoRenderer *renderer,
 
 static void
 handle_line_state_change (PangoRenderer  *renderer,
-			  PangoRenderPart part)
+                          PangoRenderPart part)
 {
   LineState *state = renderer->priv->line_state;
   if (!state)
@@ -340,12 +340,12 @@ handle_line_state_change (PangoRenderer  *renderer,
 
 static void
 add_underline (PangoRenderer    *renderer,
-	       LineState        *state,
-	       PangoFontMetrics *metrics,
-	       int               base_x,
-	       int               base_y,
-	       PangoRectangle   *ink_rect,
-	       PangoRectangle   *logical_rect)
+               LineState        *state,
+               PangoFontMetrics *metrics,
+               int               base_x,
+               int               base_y,
+               PangoRectangle   *ink_rect,
+               PangoRectangle   *logical_rect)
 {
   PangoRectangle *current_rect = &state->underline_rect;
   PangoRectangle new_rect;
@@ -453,12 +453,12 @@ add_overline (PangoRenderer    *renderer,
 
 static void
 add_strikethrough (PangoRenderer    *renderer,
-		   LineState        *state,
-		   PangoFontMetrics *metrics,
-		   int               base_x,
-		   int               base_y,
-		   PangoRectangle   *ink_rect G_GNUC_UNUSED,
-		   PangoRectangle   *logical_rect,
+                   LineState        *state,
+                   PangoFontMetrics *metrics,
+                   int               base_x,
+                   int               base_y,
+                   PangoRectangle   *ink_rect G_GNUC_UNUSED,
+                   PangoRectangle   *logical_rect,
                    int               num_glyphs)
 {
   PangoRectangle *current_rect = &state->strikethrough_rect;
@@ -490,8 +490,8 @@ add_strikethrough (PangoRenderer    *renderer,
 
 static void
 get_item_properties (PangoItem       *item,
-		     gint            *rise,
-		     PangoAttrShape **shape_attr)
+                     gint            *rise,
+                     PangoAttrShape **shape_attr)
 {
   GSList *l;
 
@@ -506,29 +506,29 @@ get_item_properties (PangoItem       *item,
       PangoAttribute *attr = l->data;
 
       switch ((int) attr->klass->type)
-	{
-	case PANGO_ATTR_SHAPE:
-	  if (shape_attr)
-	    *shape_attr = (PangoAttrShape *)attr;
-	  break;
-
-	case PANGO_ATTR_RISE:
-	  if (rise)
-	    *rise = ((PangoAttrInt *)attr)->value;
-	  break;
-
-	default:
-	  break;
-	}
+        {
+        case PANGO_ATTR_SHAPE:
+          if (shape_attr)
+            *shape_attr = (PangoAttrShape *)attr;
+          break;
+
+        case PANGO_ATTR_RISE:
+          if (rise)
+            *rise = ((PangoAttrInt *)attr)->value;
+          break;
+
+        default:
+          break;
+        }
     }
 }
 
 static void
 draw_shaped_glyphs (PangoRenderer    *renderer,
-		    PangoGlyphString *glyphs,
-		    PangoAttrShape   *attr,
-		    int               x,
-		    int               y)
+                    PangoGlyphString *glyphs,
+                    PangoAttrShape   *attr,
+                    int               x,
+                    int               y)
 {
   PangoRendererClass *class = PANGO_RENDERER_GET_CLASS (renderer);
   int i;
@@ -549,22 +549,22 @@ draw_shaped_glyphs (PangoRenderer    *renderer,
 
 /**
  * pango_renderer_draw_layout_line:
- * @renderer: a #PangoRenderer
- * @line: a #PangoLayoutLine
+ * @renderer: a `PangoRenderer`
+ * @line: a `PangoLayoutLine`
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
  *    in Pango units.
  *
- * Draws @line with the specified #PangoRenderer.
+ * Draws @line with the specified `PangoRenderer`.
  *
  * Since: 1.8
- **/
+ */
 void
-pango_renderer_draw_layout_line (PangoRenderer    *renderer,
-				 PangoLayoutLine  *line,
-				 int               x,
-				 int               y)
+pango_renderer_draw_layout_line (PangoRenderer   *renderer,
+                                 PangoLayoutLine *line,
+                                 int              x,
+                                 int              y)
 {
   int x_off = 0;
   int glyph_string_width;
@@ -581,10 +581,10 @@ pango_renderer_draw_layout_line (PangoRenderer    *renderer,
    */
   if (!renderer->active_count)
     pango_renderer_set_matrix (renderer,
-			       G_LIKELY (line->layout) ?
-			       pango_context_get_matrix
-			       (pango_layout_get_context (line->layout)) :
-			       NULL);
+                               G_LIKELY (line->layout) ?
+                               pango_context_get_matrix
+                               (pango_layout_get_context (line->layout)) :
+                               NULL);
 
   pango_renderer_activate (renderer);
 
@@ -607,118 +607,118 @@ pango_renderer_draw_layout_line (PangoRenderer    *renderer,
       PangoRectangle logical_rect, *logical = NULL;
 
       if (run->item->analysis.flags & PANGO_ANALYSIS_FLAG_CENTERED_BASELINE)
-	logical = &logical_rect;
+        logical = &logical_rect;
 
       pango_renderer_prepare_run (renderer, run);
 
       get_item_properties (run->item, &rise, &shape_attr);
 
       if (shape_attr)
-	{
-	  ink = &ink_rect;
-	  logical = &logical_rect;
+        {
+          ink = &ink_rect;
+          logical = &logical_rect;
           _pango_shape_get_extents (run->glyphs->num_glyphs,
-				    &shape_attr->ink_rect,
-				    &shape_attr->logical_rect,
-				    ink,
-				    logical);
-	  glyph_string_width = logical->width;
-	}
+                                    &shape_attr->ink_rect,
+                                    &shape_attr->logical_rect,
+                                    ink,
+                                    logical);
+          glyph_string_width = logical->width;
+        }
       else
-	{
-	  if (renderer->underline != PANGO_UNDERLINE_NONE ||
+        {
+          if (renderer->underline != PANGO_UNDERLINE_NONE ||
               renderer->priv->overline != PANGO_OVERLINE_NONE ||
-	      renderer->strikethrough)
-	    {
-	      ink = &ink_rect;
-	      logical = &logical_rect;
-	    }
-	  if (G_UNLIKELY (ink || logical))
-	    pango_glyph_string_extents (run->glyphs, run->item->analysis.font,
-					ink, logical);
-	  if (logical)
-	    glyph_string_width = logical_rect.width;
-	  else
-	    glyph_string_width = pango_glyph_string_get_width (run->glyphs);
-	}
+              renderer->strikethrough)
+            {
+              ink = &ink_rect;
+              logical = &logical_rect;
+            }
+          if (G_UNLIKELY (ink || logical))
+            pango_glyph_string_extents (run->glyphs, run->item->analysis.font,
+                                        ink, logical);
+          if (logical)
+            glyph_string_width = logical_rect.width;
+          else
+            glyph_string_width = pango_glyph_string_get_width (run->glyphs);
+        }
 
       state.logical_rect_end = x + x_off + glyph_string_width;
 
       if (run->item->analysis.flags & PANGO_ANALYSIS_FLAG_CENTERED_BASELINE)
-	{
-	  gboolean is_hinted = ((logical_rect.y | logical_rect.height) & (PANGO_SCALE - 1)) == 0;
-	  int adjustment = logical_rect.y + logical_rect.height / 2;
+        {
+          gboolean is_hinted = ((logical_rect.y | logical_rect.height) & (PANGO_SCALE - 1)) == 0;
+          int adjustment = logical_rect.y + logical_rect.height / 2;
 
-	  if (is_hinted)
-	    adjustment = PANGO_UNITS_ROUND (adjustment);
+          if (is_hinted)
+            adjustment = PANGO_UNITS_ROUND (adjustment);
 
-	  rise += adjustment;
-	}
+          rise += adjustment;
+        }
 
 
       if (renderer->priv->color_set[PANGO_RENDER_PART_BACKGROUND])
-	{
-	  if (!got_overall)
-	    {
-	      pango_layout_line_get_extents (line, NULL, &overall_rect);
-	      got_overall = TRUE;
-	    }
-
-	  pango_renderer_draw_rectangle (renderer,
-					 PANGO_RENDER_PART_BACKGROUND,
-					 x + x_off,
-					 y + overall_rect.y,
-					 glyph_string_width,
-					 overall_rect.height);
-	}
+        {
+          if (!got_overall)
+            {
+              pango_layout_line_get_extents (line, NULL, &overall_rect);
+              got_overall = TRUE;
+            }
+
+          pango_renderer_draw_rectangle (renderer,
+                                         PANGO_RENDER_PART_BACKGROUND,
+                                         x + x_off,
+                                         y + overall_rect.y,
+                                         glyph_string_width,
+                                         overall_rect.height);
+        }
 
       if (shape_attr)
-	{
-	  draw_shaped_glyphs (renderer, run->glyphs, shape_attr, x + x_off, y - rise);
-	}
+        {
+          draw_shaped_glyphs (renderer, run->glyphs, shape_attr, x + x_off, y - rise);
+        }
       else
-	{
-	  pango_renderer_draw_glyph_item (renderer,
-					  text,
-					  run,
-					  x + x_off, y - rise);
-	}
+        {
+          pango_renderer_draw_glyph_item (renderer,
+                                          text,
+                                          run,
+                                          x + x_off, y - rise);
+        }
 
       if (renderer->underline != PANGO_UNDERLINE_NONE ||
           renderer->priv->overline != PANGO_OVERLINE_NONE ||
-	  renderer->strikethrough)
-	{
-	  metrics = pango_font_get_metrics (run->item->analysis.font,
-					    run->item->analysis.language);
+          renderer->strikethrough)
+        {
+          metrics = pango_font_get_metrics (run->item->analysis.font,
+                                            run->item->analysis.language);
 
-	  if (renderer->underline != PANGO_UNDERLINE_NONE)
-	    add_underline (renderer, &state,metrics,
-			   x + x_off, y - rise,
-			   ink, logical);
+          if (renderer->underline != PANGO_UNDERLINE_NONE)
+            add_underline (renderer, &state,metrics,
+                           x + x_off, y - rise,
+                           ink, logical);
 
-	  if (renderer->priv->overline != PANGO_OVERLINE_NONE)
-	    add_overline (renderer, &state,metrics,
-			   x + x_off, y - rise,
-			   ink, logical);
+          if (renderer->priv->overline != PANGO_OVERLINE_NONE)
+            add_overline (renderer, &state,metrics,
+                           x + x_off, y - rise,
+                           ink, logical);
 
-	  if (renderer->strikethrough)
-	    add_strikethrough (renderer, &state, metrics,
-			       x + x_off, y - rise,
-			       ink, logical, run->glyphs->num_glyphs);
+          if (renderer->strikethrough)
+            add_strikethrough (renderer, &state, metrics,
+                               x + x_off, y - rise,
+                               ink, logical, run->glyphs->num_glyphs);
 
-	  pango_font_metrics_unref (metrics);
-	}
+          pango_font_metrics_unref (metrics);
+        }
 
       if (renderer->underline == PANGO_UNDERLINE_NONE &&
-	  state.underline != PANGO_UNDERLINE_NONE)
-	draw_underline (renderer, &state);
+          state.underline != PANGO_UNDERLINE_NONE)
+        draw_underline (renderer, &state);
 
       if (renderer->priv->overline == PANGO_OVERLINE_NONE &&
-	  state.overline != PANGO_OVERLINE_NONE)
-	draw_overline (renderer, &state);
+          state.overline != PANGO_OVERLINE_NONE)
+        draw_overline (renderer, &state);
 
       if (!renderer->strikethrough && state.strikethrough)
-	draw_strikethrough (renderer, &state);
+        draw_strikethrough (renderer, &state);
 
       x_off += glyph_string_width;
     }
@@ -737,24 +737,24 @@ pango_renderer_draw_layout_line (PangoRenderer    *renderer,
 
 /**
  * pango_renderer_draw_glyphs:
- * @renderer: a #PangoRenderer
- * @font: a #PangoFont
- * @glyphs: a #PangoGlyphString
+ * @renderer: a `PangoRenderer`
+ * @font: a `PangoFont`
+ * @glyphs: a `PangoGlyphString`
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
  *    in Pango units.
  *
- * Draws the glyphs in @glyphs with the specified #PangoRenderer.
+ * Draws the glyphs in @glyphs with the specified `PangoRenderer`.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_draw_glyphs (PangoRenderer    *renderer,
-			    PangoFont        *font,
-			    PangoGlyphString *glyphs,
-			    int               x,
-			    int               y)
+                            PangoFont        *font,
+                            PangoGlyphString *glyphs,
+                            int               x,
+                            int               y)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
 
@@ -767,10 +767,10 @@ pango_renderer_draw_glyphs (PangoRenderer    *renderer,
 
 static void
 pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
-				    PangoFont        *font,
-				    PangoGlyphString *glyphs,
-				    int               x,
-				    int               y)
+                                    PangoFont        *font,
+                                    PangoGlyphString *glyphs,
+                                    int               x,
+                                    int               y)
 {
   int i;
   int x_position = 0;
@@ -781,9 +781,9 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
       Point p;
 
       to_device (renderer->matrix,
-		 x + x_position + gi->geometry.x_offset,
-		 y +              gi->geometry.y_offset,
-		 &p);
+                 x + x_position + gi->geometry.x_offset,
+                 y +              gi->geometry.y_offset,
+                 &p);
 
       pango_renderer_draw_glyph (renderer, font, gi->glyph, p.x, p.y);
 
@@ -793,41 +793,43 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
 
 /**
  * pango_renderer_draw_glyph_item:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @text: (allow-none): the UTF-8 text that @glyph_item refers to, or %NULL
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
  *    in Pango units.
  *
- * Draws the glyphs in @glyph_item with the specified #PangoRenderer,
+ * Draws the glyphs in @glyph_item with the specified `PangoRenderer`,
  * embedding the text associated with the glyphs in the output if the
- * output format supports it (PDF for example).
+ * output format supports it.
+ *
+ * This is useful for rendering text in PDF.
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by <literal>@glyph_item->item->offset</literal>.
+ * indexed by `glyph_item->item->offset`.
  *
- * If @text is %NULL, this simply calls pango_renderer_draw_glyphs().
+ * If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs].
  *
  * The default implementation of this method simply falls back to
- * pango_renderer_draw_glyphs().
+ * [method@Pango.Renderer.draw_glyphs].
  *
  * Since: 1.22
- **/
+ */
 void
-pango_renderer_draw_glyph_item (PangoRenderer    *renderer,
-				const char       *text,
-				PangoGlyphItem   *glyph_item,
-				int               x,
-				int               y)
+pango_renderer_draw_glyph_item (PangoRenderer  *renderer,
+                                const char     *text,
+                                PangoGlyphItem *glyph_item,
+                                int             x,
+                                int             y)
 {
   if (!text)
     {
       pango_renderer_draw_glyphs (renderer,
-				  glyph_item->item->analysis.font,
-				  glyph_item->glyphs,
-				  x, y);
+                                  glyph_item->item->analysis.font,
+                                  glyph_item->glyphs,
+                                  x, y);
       return;
     }
 
@@ -841,42 +843,44 @@ pango_renderer_draw_glyph_item (PangoRenderer    *renderer,
 }
 
 static void
-pango_renderer_default_draw_glyph_item (PangoRenderer    *renderer,
-					const char       *text G_GNUC_UNUSED,
-					PangoGlyphItem   *glyph_item,
-					int               x,
-					int               y)
+pango_renderer_default_draw_glyph_item (PangoRenderer  *renderer,
+                                        const char     *text G_GNUC_UNUSED,
+                                        PangoGlyphItem *glyph_item,
+                                        int             x,
+                                        int             y)
 {
   pango_renderer_draw_glyphs (renderer,
-			      glyph_item->item->analysis.font,
-			      glyph_item->glyphs,
-			      x, y);
+                              glyph_item->item->analysis.font,
+                              glyph_item->glyphs,
+                              x, y);
 }
 
 /**
  * pango_renderer_draw_rectangle:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: type of object this rectangle is part of
- * @x: X position at which to draw rectangle, in user space coordinates in Pango units
- * @y: Y position at which to draw rectangle, in user space coordinates in Pango units
- * @width: width of rectangle in Pango units in user space coordinates
- * @height: height of rectangle in Pango units in user space coordinates
+ * @x: X position at which to draw rectangle, in user space coordinates
+ *   in Pango units
+ * @y: Y position at which to draw rectangle, in user space coordinates
+ *   in Pango units
+ * @width: width of rectangle in Pango units
+ * @height: height of rectangle in Pango units
  *
  * Draws an axis-aligned rectangle in user space coordinates with the
- * specified #PangoRenderer.
+ * specified `PangoRenderer`.
  *
- * This should be called while @renderer is already active.  Use
- * pango_renderer_activate() to activate a renderer.
+ * This should be called while @renderer is already active.
+ * Use [method@Pango.Renderer.activate] to activate a renderer.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_draw_rectangle (PangoRenderer   *renderer,
-			       PangoRenderPart  part,
-			       int              x,
-			       int              y,
-			       int              width,
-			       int              height)
+                               PangoRenderPart  part,
+                               int              x,
+                               int              y,
+                               int              width,
+                               int              height)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (IS_VALID_PART (part));
@@ -887,7 +891,7 @@ pango_renderer_draw_rectangle (PangoRenderer   *renderer,
 
 static int
 compare_points (const void *a,
-		const void *b)
+                const void *b)
 {
   const Point *pa = a;
   const Point *pb = b;
@@ -906,12 +910,12 @@ compare_points (const void *a,
 
 static void
 draw_rectangle (PangoRenderer   *renderer,
-		PangoMatrix     *matrix,
-		PangoRenderPart  part,
-		int              x,
-		int              y,
-		int              width,
-		int              height)
+                PangoMatrix     *matrix,
+                PangoRenderPart  part,
+                int              x,
+                int              y,
+                int              width,
+                int              height)
 {
   Point points[4];
 
@@ -944,8 +948,8 @@ draw_rectangle (PangoRenderer   *renderer,
     {
      /* Case 1 (pure shear) */
       pango_renderer_draw_trapezoid (renderer, part,                                      /* B */
-				     points[0].y, points[0].x, points[1].x,
-				     points[2].y, points[2].x, points[3].x);
+                                     points[0].y, points[0].x, points[1].x,
+                                     points[2].y, points[2].x, points[3].x);
     }
   else if (points[1].x < points[2].x)
     {
@@ -954,14 +958,14 @@ draw_rectangle (PangoRenderer   *renderer,
       double base_width = tmp_width + points[0].x - points[1].x;
 
       pango_renderer_draw_trapezoid (renderer, part,                                      /* A */
-				     points[0].y, points[0].x, points[0].x,
-				     points[1].y, points[1].x, points[1].x + base_width);
+                                     points[0].y, points[0].x, points[0].x,
+                                     points[1].y, points[1].x, points[1].x + base_width);
       pango_renderer_draw_trapezoid (renderer, part,                                      /* B */
-				     points[1].y, points[1].x, points[1].x + base_width,
-				     points[2].y, points[2].x - base_width, points[2].x);
+                                     points[1].y, points[1].x, points[1].x + base_width,
+                                     points[2].y, points[2].x - base_width, points[2].x);
       pango_renderer_draw_trapezoid (renderer, part,                                      /* C */
-				     points[2].y, points[2].x - base_width, points[2].x,
-				     points[3].y, points[3].x, points[3].x);
+                                     points[2].y, points[2].x - base_width, points[2].x,
+                                     points[3].y, points[3].x, points[3].x);
     }
   else
     {
@@ -970,31 +974,31 @@ draw_rectangle (PangoRenderer   *renderer,
       double base_width = tmp_width + points[1].x - points[0].x;
 
       pango_renderer_draw_trapezoid (renderer, part,                                     /* A */
-				     points[0].y, points[0].x, points[0].x,
-				     points[1].y,  points[1].x - base_width, points[1].x);
+                                     points[0].y, points[0].x, points[0].x,
+                                     points[1].y,  points[1].x - base_width, points[1].x);
       pango_renderer_draw_trapezoid (renderer, part,                                     /* B */
-				     points[1].y, points[1].x - base_width, points[1].x,
-				     points[2].y, points[2].x, points[2].x + base_width);
+                                     points[1].y, points[1].x - base_width, points[1].x,
+                                     points[2].y, points[2].x, points[2].x + base_width);
       pango_renderer_draw_trapezoid (renderer, part,                                     /* C */
-				     points[2].y, points[2].x, points[2].x + base_width,
-				     points[3].y, points[3].x, points[3].x);
+                                     points[2].y, points[2].x, points[2].x + base_width,
+                                     points[3].y, points[3].x, points[3].x);
     }
 }
 
 static void
 pango_renderer_default_draw_rectangle (PangoRenderer  *renderer,
-				       PangoRenderPart part,
-				       int             x,
-				       int             y,
-				       int             width,
-				       int             height)
+                                       PangoRenderPart part,
+                                       int             x,
+                                       int             y,
+                                       int             width,
+                                       int             height)
 {
   draw_rectangle (renderer, renderer->matrix, part, x, y, width, height);
 }
 
 /**
  * pango_renderer_draw_error_underline:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @x: X coordinate of underline, in Pango units in user coordinate system
  * @y: Y coordinate of underline, in Pango units in user coordinate system
  * @width: width of underline, in Pango units in user coordinate system
@@ -1002,21 +1006,22 @@ pango_renderer_default_draw_rectangle (PangoRenderer  *renderer,
  *
  * Draw a squiggly line that approximately covers the given rectangle
  * in the style of an underline used to indicate a spelling error.
- * (The width of the underline is rounded to an integer number
+ *
+ * The width of the underline is rounded to an integer number
  * of up/down segments and the resulting rectangle is centered
- * in the original rectangle)
+ * in the original rectangle.
  *
- * This should be called while @renderer is already active.  Use
- * pango_renderer_activate() to activate a renderer.
+ * This should be called while @renderer is already active.
+ * Use [method@Pango.Renderer.activate] to activate a renderer.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_draw_error_underline (PangoRenderer *renderer,
-				     int            x,
-				     int            y,
-				     int            width,
-				     int            height)
+                                     int            x,
+                                     int            y,
+                                     int            width,
+                                     int            height)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (renderer->active_count > 0);
@@ -1065,10 +1070,10 @@ pango_renderer_draw_error_underline (PangoRenderer *renderer,
 
 static void
 get_total_matrix (PangoMatrix       *total,
-		  const PangoMatrix *global,
-		  int                x,
-		  int                y,
-		  int                square)
+                  const PangoMatrix *global,
+                  int                x,
+                  int                y,
+                  int                square)
 {
   PangoMatrix local;
   gdouble scale = 0.5 * square;
@@ -1092,10 +1097,10 @@ get_total_matrix (PangoMatrix       *total,
 
 static void
 pango_renderer_default_draw_error_underline (PangoRenderer *renderer,
-					     int            x,
-					     int            y,
-					     int            width,
-					     int            height)
+                                             int            x,
+                                             int            y,
+                                             int            width,
+                                             int            height)
 {
   int square;
   int unit_width;
@@ -1129,16 +1134,16 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer,
   while (TRUE)
     {
       draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* A */
-		      0,                      0,
-		      HEIGHT_SQUARES * 2 - 1, 1);
+                      0,                      0,
+                      HEIGHT_SQUARES * 2 - 1, 1);
 
       if (i <= 0)
         break;
       i--;
 
       draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* B */
-		      HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 3),
-		      1,                      HEIGHT_SQUARES * 2 - 3);
+                      HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 3),
+                      1,                      HEIGHT_SQUARES * 2 - 3);
 
       total.x0 += dx0;
       total.y0 += dy0;
@@ -1146,14 +1151,14 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer,
   if (width_units % 2 == 0)
     {
       draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* C */
-		      HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 2),
-		      1,                      HEIGHT_SQUARES * 2 - 2);
+                      HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 2),
+                      1,                      HEIGHT_SQUARES * 2 - 2);
     }
 }
 
 /**
  * pango_renderer_draw_trapezoid:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: type of object this trapezoid is part of
  * @y1_: Y coordinate of top of trapezoid
  * @x11: X coordinate of left end of top of trapezoid
@@ -1163,32 +1168,32 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer,
  * @x22: X coordinate of right end of bottom of trapezoid
  *
  * Draws a trapezoid with the parallel sides aligned with the X axis
- * using the given #PangoRenderer; coordinates are in device space.
+ * using the given `PangoRenderer`; coordinates are in device space.
  *
  * Since: 1.8
- **/
+ */
 void
-pango_renderer_draw_trapezoid (PangoRenderer  *renderer,
-			       PangoRenderPart part,
-			       double          y1_,
-			       double          x11,
-			       double          x21,
-			       double          y2,
-			       double          x12,
-			       double          x22)
+pango_renderer_draw_trapezoid (PangoRenderer   *renderer,
+                               PangoRenderPart  part,
+                               double           y1_,
+                               double           x11,
+                               double           x21,
+                               double           y2,
+                               double           x12,
+                               double           x22)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (renderer->active_count > 0);
 
   if (PANGO_RENDERER_GET_CLASS (renderer)->draw_trapezoid)
     PANGO_RENDERER_GET_CLASS (renderer)->draw_trapezoid (renderer, part,
-							 y1_, x11, x21,
-							 y2, x12, x22);
+                                                         y1_, x11, x21,
+                                                         y2, x12, x22);
 }
 
 /**
  * pango_renderer_draw_glyph:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @font: a #PangoFont
  * @glyph: the glyph index of a single glyph
  * @x: X coordinate of left edge of baseline of glyph
@@ -1197,13 +1202,13 @@ pango_renderer_draw_trapezoid (PangoRenderer  *renderer,
  * Draws a single glyph with coordinates in device space.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_draw_glyph (PangoRenderer *renderer,
-			   PangoFont     *font,
-			   PangoGlyph     glyph,
-			   double         x,
-			   double         y)
+                           PangoFont     *font,
+                           PangoGlyph     glyph,
+                           double         x,
+                           double         y)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (renderer->active_count > 0);
@@ -1217,14 +1222,15 @@ pango_renderer_draw_glyph (PangoRenderer *renderer,
 
 /**
  * pango_renderer_activate:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  *
  * Does initial setup before rendering operations on @renderer.
- * pango_renderer_deactivate() should be called when done drawing.
- * Calls such as pango_renderer_draw_layout() automatically
+ * 
+ * [method@Pango.Renderer.deactivate] should be called when done drawing.
+ * Calls such as [method@Pango.Renderer.draw_layout] automatically
  * activate the layout before drawing on it. Calls to
- * pango_renderer_activate() and pango_renderer_deactivate() can
- * be nested and the renderer will only be initialized and
+ * `pango_renderer_activate()` and `pango_renderer_deactivate()`
+ * can be nested and the renderer will only be initialized and
  * deinitialized once.
  *
  * Since: 1.8
@@ -1238,19 +1244,20 @@ pango_renderer_activate (PangoRenderer *renderer)
   if (renderer->active_count == 1)
     {
       if (PANGO_RENDERER_GET_CLASS (renderer)->begin)
-	PANGO_RENDERER_GET_CLASS (renderer)->begin (renderer);
+        PANGO_RENDERER_GET_CLASS (renderer)->begin (renderer);
     }
 }
 
 /**
  * pango_renderer_deactivate:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
+ *
+ * Cleans up after rendering operations on @renderer.
  *
- * Cleans up after rendering operations on @renderer. See
- * docs for pango_renderer_activate().
+ * See docs for [method@Pango.Renderer.activate].
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_deactivate (PangoRenderer *renderer)
 {
@@ -1260,26 +1267,27 @@ pango_renderer_deactivate (PangoRenderer *renderer)
   if (renderer->active_count == 1)
     {
       if (PANGO_RENDERER_GET_CLASS (renderer)->end)
-	PANGO_RENDERER_GET_CLASS (renderer)->end (renderer);
+        PANGO_RENDERER_GET_CLASS (renderer)->end (renderer);
     }
   renderer->active_count--;
 }
 
 /**
  * pango_renderer_set_color:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: the part to change the color of
  * @color: (allow-none): the new color or %NULL to unset the current color
  *
  * Sets the color for part of the rendering.
- * Also see pango_renderer_set_alpha().
+ *
+ * Also see [method@Pango.Renderer.set_alpha].
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_set_color (PangoRenderer    *renderer,
-			  PangoRenderPart   part,
-			  const PangoColor *color)
+                          PangoRenderPart   part,
+                          const PangoColor *color)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (IS_VALID_PART (part));
@@ -1306,7 +1314,7 @@ pango_renderer_set_color (PangoRenderer    *renderer,
 
 /**
  * pango_renderer_get_color:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: the part to get the color for
  *
  * Gets the current rendering color for the specified part.
@@ -1316,10 +1324,10 @@ pango_renderer_set_color (PangoRenderer    *renderer,
  *   inherited from the environment.
  *
  * Since: 1.8
- **/
+ */
 PangoColor *
 pango_renderer_get_color (PangoRenderer   *renderer,
-			  PangoRenderPart  part)
+                          PangoRenderPart  part)
 {
   g_return_val_if_fail (PANGO_IS_RENDERER_FAST (renderer), NULL);
   g_return_val_if_fail (IS_VALID_PART (part), NULL);
@@ -1332,11 +1340,12 @@ pango_renderer_get_color (PangoRenderer   *renderer,
 
 /**
  * pango_renderer_set_alpha:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: the part to set the alpha for
  * @alpha: an alpha value between 1 and 65536, or 0 to unset the alpha
  *
  * Sets the alpha for part of the rendering.
+ *
  * Note that the alpha may only be used if a color is
  * specified for @part as well.
  *
@@ -1362,7 +1371,7 @@ pango_renderer_set_alpha (PangoRenderer   *renderer,
 
 /**
  * pango_renderer_get_alpha:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: the part to get the alpha for
  *
  * Gets the current alpha for the specified part.
@@ -1385,28 +1394,30 @@ pango_renderer_get_alpha (PangoRenderer   *renderer,
 
 /**
  * pango_renderer_part_changed:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  * @part: the part for which rendering has changed.
  *
  * Informs Pango that the way that the rendering is done
- * for @part has changed in a way that would prevent multiple
- * pieces being joined together into one drawing call. For
- * instance, if a subclass of #PangoRenderer was to add a stipple
+ * for @part has changed.
+ *
+ * This should be called if the rendering changes in a way that would
+ * prevent multiple pieces being joined together into one drawing call.
+ * For instance, if a subclass of `PangoRenderer` was to add a stipple
  * option for drawing underlines, it needs to call
  *
- * <informalexample><programlisting>
+ * ```
  * pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE);
- * </programlisting></informalexample>
+ * ```
  *
  * When the stipple changes or underlines with different stipples
  * might be joined together. Pango automatically calls this for
- * changes to colors. (See pango_renderer_set_color())
+ * changes to colors. (See [method@Pango.Renderer.set_color])
  *
  * Since: 1.8
- **/
+ */
 void
-pango_renderer_part_changed (PangoRenderer    *renderer,
-			     PangoRenderPart   part)
+pango_renderer_part_changed (PangoRenderer   *renderer,
+                             PangoRenderPart  part)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
   g_return_if_fail (IS_VALID_PART (part));
@@ -1420,16 +1431,16 @@ pango_renderer_part_changed (PangoRenderer    *renderer,
 
 /**
  * pango_renderer_prepare_run:
- * @renderer: a #PangoRenderer
- * @run: a #PangoLayoutRun
+ * @renderer: a `PangoRenderer`
+ * @run: a `PangoLayoutRun`
  *
- * Set up the state of the #PangoRenderer for rendering @run.
+ * Set up the state of the `PangoRenderer` for rendering @run.
  *
  * Since: 1.8
- **/
+ */
 static void
 pango_renderer_prepare_run (PangoRenderer  *renderer,
-			    PangoLayoutRun *run)
+                            PangoLayoutRun *run)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
 
@@ -1438,7 +1449,7 @@ pango_renderer_prepare_run (PangoRenderer  *renderer,
 
 static void
 pango_renderer_default_prepare_run (PangoRenderer  *renderer,
-				    PangoLayoutRun *run)
+                                    PangoLayoutRun *run)
 {
   PangoColor *fg_color = NULL;
   PangoColor *bg_color = NULL;
@@ -1458,50 +1469,50 @@ pango_renderer_default_prepare_run (PangoRenderer  *renderer,
       PangoAttribute *attr = l->data;
 
       switch ((int) attr->klass->type)
-	{
-	case PANGO_ATTR_UNDERLINE:
-	  renderer->underline = ((PangoAttrInt *)attr)->value;
-	  break;
+        {
+        case PANGO_ATTR_UNDERLINE:
+          renderer->underline = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_OVERLINE:
-	  renderer->priv->overline = ((PangoAttrInt *)attr)->value;
-	  break;
+        case PANGO_ATTR_OVERLINE:
+          renderer->priv->overline = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_STRIKETHROUGH:
-	  renderer->strikethrough = ((PangoAttrInt *)attr)->value;
-	  break;
+        case PANGO_ATTR_STRIKETHROUGH:
+          renderer->strikethrough = ((PangoAttrInt *)attr)->value;
+          break;
 
-	case PANGO_ATTR_FOREGROUND:
-	  fg_color = &((PangoAttrColor *)attr)->color;
-	  break;
+        case PANGO_ATTR_FOREGROUND:
+          fg_color = &((PangoAttrColor *)attr)->color;
+          break;
 
-	case PANGO_ATTR_BACKGROUND:
-	  bg_color = &((PangoAttrColor *)attr)->color;
-	  break;
+        case PANGO_ATTR_BACKGROUND:
+          bg_color = &((PangoAttrColor *)attr)->color;
+          break;
 
-	case PANGO_ATTR_UNDERLINE_COLOR:
-	  underline_color = &((PangoAttrColor *)attr)->color;
-	  break;
+        case PANGO_ATTR_UNDERLINE_COLOR:
+          underline_color = &((PangoAttrColor *)attr)->color;
+          break;
 
-	case PANGO_ATTR_OVERLINE_COLOR:
-	  overline_color = &((PangoAttrColor *)attr)->color;
-	  break;
+        case PANGO_ATTR_OVERLINE_COLOR:
+          overline_color = &((PangoAttrColor *)attr)->color;
+          break;
 
-	case PANGO_ATTR_STRIKETHROUGH_COLOR:
-	  strikethrough_color = &((PangoAttrColor *)attr)->color;
-	  break;
+        case PANGO_ATTR_STRIKETHROUGH_COLOR:
+          strikethrough_color = &((PangoAttrColor *)attr)->color;
+          break;
 
-	case PANGO_ATTR_FOREGROUND_ALPHA:
+        case PANGO_ATTR_FOREGROUND_ALPHA:
           fg_alpha = ((PangoAttrInt *)attr)->value;
-	  break;
+          break;
 
-	case PANGO_ATTR_BACKGROUND_ALPHA:
+        case PANGO_ATTR_BACKGROUND_ALPHA:
           bg_alpha = ((PangoAttrInt *)attr)->value;
-	  break;
+          break;
 
-	default:
-	  break;
-	}
+        default:
+          break;
+        }
     }
 
   if (!underline_color)
@@ -1528,17 +1539,17 @@ pango_renderer_default_prepare_run (PangoRenderer  *renderer,
 
 /**
  * pango_renderer_set_matrix:
- * @renderer: a #PangoRenderer
- * @matrix: (allow-none): a #PangoMatrix, or %NULL to unset any existing matrix.
+ * @renderer: a `PangoRenderer`
+ * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing matrix.
  *  (No matrix set is the same as setting the identity matrix.)
  *
  * Sets the transformation matrix that will be applied when rendering.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_set_matrix (PangoRenderer     *renderer,
-			   const PangoMatrix *matrix)
+                           const PangoMatrix *matrix)
 {
   g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer));
 
@@ -1548,17 +1559,19 @@ pango_renderer_set_matrix (PangoRenderer     *renderer,
 
 /**
  * pango_renderer_get_matrix:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  *
  * Gets the transformation matrix that will be applied when
- * rendering. See pango_renderer_set_matrix().
+ * rendering.
+ *
+ * See [method@Pango.Renderer.set_matrix].
  *
  * Return value: (nullable): the matrix, or %NULL if no matrix has
- *  been set (which is the same as the identity matrix). The returned
- *  matrix is owned by Pango and must not be modified or freed.
+ *   been set (which is the same as the identity matrix). The returned
+ *   matrix is owned by Pango and must not be modified or freed.
  *
  * Since: 1.8
- **/
+ */
 const PangoMatrix *
 pango_renderer_get_matrix (PangoRenderer *renderer)
 {
@@ -1569,9 +1582,10 @@ pango_renderer_get_matrix (PangoRenderer *renderer)
 
 /**
  * pango_renderer_get_layout:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  *
  * Gets the layout currently being rendered using @renderer.
+ *
  * Calling this function only makes sense from inside a subclass's
  * methods, like in its draw_shape vfunc, for example.
  *
@@ -1579,10 +1593,10 @@ pango_renderer_get_matrix (PangoRenderer *renderer)
  * rendered.
  *
  * Return value: (transfer none) (nullable): the layout, or %NULL if
- *  no layout is being rendered using @renderer at this time.
+ *   no layout is being rendered using @renderer at this time.
  *
  * Since: 1.20
- **/
+ */
 PangoLayout *
 pango_renderer_get_layout (PangoRenderer *renderer)
 {
@@ -1594,9 +1608,10 @@ pango_renderer_get_layout (PangoRenderer *renderer)
 
 /**
  * pango_renderer_get_layout_line:
- * @renderer: a #PangoRenderer
+ * @renderer: a `PangoRenderer`
  *
  * Gets the layout line currently being rendered using @renderer.
+ *
  * Calling this function only makes sense from inside a subclass's
  * methods, like in its draw_shape vfunc, for example.
  *
@@ -1607,9 +1622,9 @@ pango_renderer_get_layout (PangoRenderer *renderer)
  *   if no layout line is being rendered using @renderer at this time.
  *
  * Since: 1.20
- **/
+ */
 PangoLayoutLine *
-pango_renderer_get_layout_line (PangoRenderer     *renderer)
+pango_renderer_get_layout_line (PangoRenderer *renderer)
 {
   return renderer->priv->line;
 }
diff --git a/pango/pango-renderer.h b/pango/pango-renderer.h
index 89107fd1..98c4cfb0 100644
--- a/pango/pango-renderer.h
+++ b/pango/pango-renderer.h
@@ -65,12 +65,15 @@ typedef enum
  *    the Renderer; may be %NULL, which should be treated the
  *    same as the identity matrix.
  *
- * #PangoRenderer is a base class for objects that are used to
- * render Pango objects such as #PangoGlyphString and
- * #PangoLayout.
+ * `PangoRenderer` is a base class for objects that can render text
+ * provided as `PangoGlyphString` or `PangoLayout`.
+ *
+ * By subclassing `PangoRenderer` and overriding operations such as
+ * @draw_glyphs and @draw_rectangle, renderers for particular font
+ * backends and destinations can be created.
  *
  * Since: 1.8
- **/
+ */
 struct _PangoRenderer
 {
   /*< private >*/
diff --git a/pango/pango-script.c b/pango/pango-script.c
index fc95309f..7116a0a4 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -53,15 +53,6 @@
  * of the copyright holder.
  */
 
-/**
- * SECTION:scripts
- * @short_description:Identifying writing systems and languages
- * @title:Scripts and Languages
- *
- * The functions in this section are used to identify the writing
- * system, or <firstterm>script</firstterm> of individual characters
- * and of ranges within a larger text string.
- */
 #include "config.h"
 #include <stdlib.h>
 #include <string.h>
@@ -73,17 +64,18 @@
  * pango_script_for_unichar:
  * @ch: a Unicode character
  *
- * Looks up the script for a particular character (as defined by
- * Unicode Standard Annex \#24). No check is made for @ch being a
- * valid Unicode character; if you pass in invalid character, the
- * result is undefined.
+ * Looks up the script for a particular character.
+ *
+ * The script of a character is defined by Unicode Standard Annex \#24.
+ * No check is made for @ch being a valid Unicode character; if you pass
+ * in invalid character, the result is undefined.
  *
  * Note that while the return type of this function is declared
- * as PangoScript, as of Pango 1.18, this function simply returns
+ * as `PangoScript`, as of Pango 1.18, this function simply returns
  * the return value of g_unichar_get_script(). Callers must be
  * prepared to handle unknown values.
  *
- * Return value: the #PangoScript for the character.
+ * Return value: the `PangoScript` for the character.
  *
  * Since: 1.4
  * Deprecated: 1.44. Use g_unichar_get_script()
diff --git a/pango/pango-script.h b/pango/pango-script.h
index a7ec3246..c1579982 100644
--- a/pango/pango-script.h
+++ b/pango/pango-script.h
@@ -29,7 +29,7 @@ G_BEGIN_DECLS
 /**
  * PangoScriptIter:
  *
- * A #PangoScriptIter is used to iterate through a string
+ * A `PangoScriptIter` is used to iterate through a string
  * and identify ranges in different scripts.
  **/
 typedef struct _PangoScriptIter PangoScriptIter;
@@ -156,16 +156,16 @@ typedef struct _PangoScriptIter PangoScriptIter;
  * @PANGO_SCRIPT_OLD_HUNGARIAN:        Old Hungarian. Since: 1.40
  * @PANGO_SCRIPT_SIGNWRITING:          Signwriting. Since: 1.40
  *
- * The #PangoScript enumeration identifies different writing
- * systems. The values correspond to the names as defined in the
- * Unicode standard. See <ulink
- * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
- * #24: Script names</ulink>.
+ * The `PangoScript` enumeration identifies different writing
+ * systems.
+ *
+ * The values correspond to the names as defined in the Unicode standard. See
+ * [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/)
  *
  * Note that this enumeration is deprecated and will not be updated
  * to include values in newer versions of the Unicode standard.
- * Applications should use the GUnicodeScript enumeration instead,
- * whose values are interchangeable with PangoScript.
+ * Applications should use the `GUnicodeScript` enumeration instead,
+ * whose values are interchangeable with `PangoScript`.
  */
 typedef enum {                         /* ISO 15924 code */
       PANGO_SCRIPT_INVALID_CODE = -1,
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 56a34468..2c2717ee 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -10,7 +10,7 @@
  *
  * 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 GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -19,14 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:tab-stops
- * @short_description:Structures for storing tab stops
- * @title:Tab Stops
- *
- * Functions in this section are used to deal with #PangoTabArray objects
- * that can be used to set tab stop positions in a #PangoLayout.
- */
 #include "config.h"
 #include "pango-tabs.h"
 #include "pango-impl-utils.h"
@@ -36,19 +28,21 @@ typedef struct _PangoTab PangoTab;
 
 struct _PangoTab
 {
-  gint location;	        /* Offset in pixels of this tab stop
-				 * from the left margin of the text.
-				 */
+  gint location;                /* Offset in pixels of this tab stop
+                                 * from the left margin of the text.
+                                 */
   PangoTabAlign alignment;      /* Where the tab stop appears relative
-				 * to the text.
-				 */
+                                 * to the text.
+                                 */
 };
 
 /**
  * PangoTabArray:
  *
- * A #PangoTabArray struct contains an array
- * of tab stops. Each tab stop has an alignment and a position.
+ * A `PangoTabArray` contains an array of tab stops.
+ *
+ * `PangoTabArray` can be used to set tab stops in a `PangoLayout`.
+ * Each tab stop has an alignment and a position.
  */
 struct _PangoTabArray
 {
@@ -74,16 +68,17 @@ init_tabs (PangoTabArray *array, gint start, gint end)
  * @initial_size: Initial number of tab stops to allocate, can be 0
  * @positions_in_pixels: whether positions are in pixel units
  *
- * Creates an array of @initial_size tab stops. Tab stops are specified in
- * pixel units if @positions_in_pixels is %TRUE, otherwise in Pango
- * units. All stops are initially at position 0.
+ * Creates an array of @initial_size tab stops.
+ *
+ * Tab stops are specified in pixel units if @positions_in_pixels is %TRUE,
+ * otherwise in Pango units. All stops are initially at position 0.
  *
- * Return value: the newly allocated #PangoTabArray, which should
- *               be freed with pango_tab_array_free().
- **/
+ * Return value: the newly allocated `PangoTabArray`, which should
+ *   be freed with [method@Pango.TabArray.free].
+ */
 PangoTabArray*
-pango_tab_array_new (gint initial_size,
-		     gboolean positions_in_pixels)
+pango_tab_array_new (gint     initial_size,
+                     gboolean positions_in_pixels)
 {
   PangoTabArray *array;
 
@@ -95,8 +90,7 @@ pango_tab_array_new (gint initial_size,
    * optimization.
    */
   array = g_slice_new (PangoTabArray);
-  array->size = initial_size;
-  array->allocated = initial_size;
+  array->size = initial_size; array->allocated = initial_size;
 
   if (array->allocated > 0)
     {
@@ -119,20 +113,20 @@ pango_tab_array_new (gint initial_size,
  * @first_position: position of first tab stop
  * @...: additional alignment/position pairs
  *
- * This is a convenience function that creates a #PangoTabArray
- * and allows you to specify the alignment and position of each
- * tab stop. You <emphasis>must</emphasis> provide an alignment
- * and position for @size tab stops.
+ * Creates * a `PangoTabArray` and allows you to specify the alignment
+ * and position of each tab stop.
+ *
+ * You **must** provide an alignment and position for @size tab stops.
  *
- * Return value: the newly allocated #PangoTabArray, which should
- *               be freed with pango_tab_array_free().
- **/
+ * Return value: the newly allocated `PangoTabArray`, which should
+ *   be freed with [method@Pango.TabArray.free].
+ */
 PangoTabArray  *
 pango_tab_array_new_with_positions (gint           size,
-				    gboolean       positions_in_pixels,
-				    PangoTabAlign  first_alignment,
-				    gint           first_position,
-				    ...)
+                                    gboolean       positions_in_pixels,
+                                    PangoTabAlign  first_alignment,
+                                    gint           first_position,
+                                    ...)
 {
   PangoTabArray *array;
   va_list args;
@@ -176,13 +170,13 @@ G_DEFINE_BOXED_TYPE (PangoTabArray, pango_tab_array,
 
 /**
  * pango_tab_array_copy:
- * @src: #PangoTabArray to copy
+ * @src: `PangoTabArray` to copy
  *
- * Copies a #PangoTabArray
+ * Copies a `PangoTabArray`.
  *
- * Return value: the newly allocated #PangoTabArray, which should
- *               be freed with pango_tab_array_free().
- **/
+ * Return value: the newly allocated `PangoTabArray`, which should
+ *   be freed with [method@Pango.TabArray.free].
+ */
 PangoTabArray*
 pango_tab_array_copy (PangoTabArray *src)
 {
@@ -200,13 +194,12 @@ pango_tab_array_copy (PangoTabArray *src)
 
 /**
  * pango_tab_array_free:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  *
  * Frees a tab array and associated resources.
- *
- **/
+ */
 void
-pango_tab_array_free   (PangoTabArray *tab_array)
+pango_tab_array_free (PangoTabArray *tab_array)
 {
   g_return_if_fail (tab_array != NULL);
 
@@ -217,12 +210,12 @@ pango_tab_array_free   (PangoTabArray *tab_array)
 
 /**
  * pango_tab_array_get_size:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  *
  * Gets the number of tab stops in @tab_array.
  *
  * Return value: the number of tab stops in the array.
- **/
+ */
 gint
 pango_tab_array_get_size (PangoTabArray *tab_array)
 {
@@ -233,16 +226,17 @@ pango_tab_array_get_size (PangoTabArray *tab_array)
 
 /**
  * pango_tab_array_resize:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  * @new_size: new size of the array
  *
- * Resizes a tab array. You must subsequently initialize any tabs that
- * were added as a result of growing the array.
+ * Resizes a tab array.
  *
- **/
+ * You must subsequently initialize any tabs
+ * that were added as a result of growing the array.
+ */
 void
 pango_tab_array_resize (PangoTabArray *tab_array,
-			gint           new_size)
+                        gint           new_size)
 {
   if (new_size > tab_array->allocated)
     {
@@ -250,13 +244,13 @@ pango_tab_array_resize (PangoTabArray *tab_array,
 
       /* Ratchet allocated size up above the index. */
       if (tab_array->allocated == 0)
-	tab_array->allocated = 2;
+        tab_array->allocated = 2;
 
       while (new_size > tab_array->allocated)
-	tab_array->allocated = tab_array->allocated * 2;
+        tab_array->allocated = tab_array->allocated * 2;
 
       tab_array->tabs = g_renew (PangoTab, tab_array->tabs,
-				 tab_array->allocated);
+                                 tab_array->allocated);
 
       init_tabs (tab_array, current_end, tab_array->allocated);
     }
@@ -266,21 +260,21 @@ pango_tab_array_resize (PangoTabArray *tab_array,
 
 /**
  * pango_tab_array_set_tab:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  * @tab_index: the index of a tab stop
  * @alignment: tab alignment
  * @location: tab location in Pango units
  *
  * Sets the alignment and location of a tab stop.
- * @alignment must always be #PANGO_TAB_LEFT in the current
- * implementation.
  *
- **/
+ * @alignment must always be %PANGO_TAB_LEFT in the current
+ * implementation.
+ */
 void
-pango_tab_array_set_tab  (PangoTabArray *tab_array,
-			  gint           tab_index,
-			  PangoTabAlign  alignment,
-			  gint           location)
+pango_tab_array_set_tab (PangoTabArray *tab_array,
+                         gint           tab_index,
+                         PangoTabAlign  alignment,
+                         gint           location)
 {
   g_return_if_fail (tab_array != NULL);
   g_return_if_fail (tab_index >= 0);
@@ -296,19 +290,18 @@ pango_tab_array_set_tab  (PangoTabArray *tab_array,
 
 /**
  * pango_tab_array_get_tab:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  * @tab_index: tab stop index
  * @alignment: (out) (allow-none): location to store alignment, or %NULL
  * @location: (out) (allow-none): location to store tab position, or %NULL
  *
  * Gets the alignment and position of a tab stop.
- *
- **/
+ */
 void
-pango_tab_array_get_tab  (PangoTabArray *tab_array,
-			  gint           tab_index,
-			  PangoTabAlign *alignment,
-			  gint          *location)
+pango_tab_array_get_tab (PangoTabArray *tab_array,
+                         gint           tab_index,
+                         PangoTabAlign *alignment,
+                         gint          *location)
 {
   g_return_if_fail (tab_array != NULL);
   g_return_if_fail (tab_index < tab_array->size);
@@ -323,21 +316,22 @@ pango_tab_array_get_tab  (PangoTabArray *tab_array,
 
 /**
  * pango_tab_array_get_tabs:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  * @alignments: (out) (allow-none): location to store an array of tab
  *   stop alignments, or %NULL
  * @locations: (out) (allow-none) (array): location to store an array
  *   of tab positions, or %NULL
  *
  * If non-%NULL, @alignments and @locations are filled with allocated
- * arrays of length pango_tab_array_get_size(). You must free the
- * returned array.
+ * arrays.
  *
- **/
+ * The arrays are of length [method@Pango.TabArray.get_size].
+ * You must free the returned array.
+ */
 void
 pango_tab_array_get_tabs (PangoTabArray *tab_array,
-			  PangoTabAlign **alignments,
-			  gint          **locations)
+                          PangoTabAlign **alignments,
+                          gint          **locations)
 {
   gint i;
 
@@ -353,9 +347,9 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array,
   while (i < tab_array->size)
     {
       if (alignments)
-	(*alignments)[i] = tab_array->tabs[i].alignment;
+        (*alignments)[i] = tab_array->tabs[i].alignment;
       if (locations)
-	(*locations)[i] = tab_array->tabs[i].location;
+        (*locations)[i] = tab_array->tabs[i].location;
 
       ++i;
     }
@@ -363,13 +357,13 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array,
 
 /**
  * pango_tab_array_get_positions_in_pixels:
- * @tab_array: a #PangoTabArray
+ * @tab_array: a `PangoTabArray`
  *
- * Returns %TRUE if the tab positions are in pixels, %FALSE if they are
- * in Pango units.
+ * Returns %TRUE if the tab positions are in pixels,
+ * %FALSE if they are in Pango units.
  *
  * Return value: whether positions are in pixels.
- **/
+ */
 gboolean
 pango_tab_array_get_positions_in_pixels (PangoTabArray *tab_array)
 {
diff --git a/pango/pango-tabs.h b/pango/pango-tabs.h
index 664cedbb..893132ed 100644
--- a/pango/pango-tabs.h
+++ b/pango/pango-tabs.h
@@ -32,7 +32,7 @@ typedef struct _PangoTabArray PangoTabArray;
  * PangoTabAlign:
  * @PANGO_TAB_LEFT: the tab stop appears to the left of the text.
  *
- * A #PangoTabAlign specifies where a tab stop appears relative to the text.
+ * `PangoTabAlign` specifies where a tab stop appears relative to the text.
  */
 typedef enum
 {
@@ -47,11 +47,6 @@ typedef enum
    */
 } PangoTabAlign;
 
-/**
- * PANGO_TYPE_TAB_ARRAY:
- *
- * The #GObject type for #PangoTabArray.
- */
 #define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
diff --git a/pango/pango-types.h b/pango/pango-types.h
index 4662c71e..2998d8ec 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -31,8 +31,10 @@ G_BEGIN_DECLS
 
 typedef struct _PangoLogAttr PangoLogAttr;
 
+#ifndef __GI_SCANNER__
 typedef struct _PangoEngineLang PangoEngineLang;
 typedef struct _PangoEngineShape PangoEngineShape;
+#endif
 
 typedef struct _PangoFont    PangoFont;
 typedef struct _PangoFontMap PangoFontMap;
@@ -45,7 +47,7 @@ typedef struct _PangoRectangle PangoRectangle;
 /**
  * PangoGlyph:
  *
- * A #PangoGlyph represents a single glyph in the output form of a string.
+ * A `PangoGlyph` represents a single glyph in the output form of a string.
  */
 typedef guint32 PangoGlyph;
 
@@ -54,11 +56,11 @@ typedef guint32 PangoGlyph;
 /**
  * PANGO_SCALE:
  *
- * The %PANGO_SCALE macro represents the scale between dimensions used
- * for Pango distances and device units. (The definition of device
- * units is dependent on the output device; it will typically be pixels
- * for a screen, and points for a printer.) %PANGO_SCALE is currently
- * 1024, but this may be changed in the future.
+ * The scale between dimensions used for Pango distances and device units.
+ *
+ * The definition of device units is dependent on the output device; it will
+ * typically be pixels for a screen, and points for a printer. %PANGO_SCALE is
+ * currently 1024, but this may be changed in the future.
  *
  * When setting font sizes, device units are always considered to be
  * points (as in "12 point font"), rather than pixels.
@@ -130,10 +132,11 @@ double pango_units_to_double (int i) G_GNUC_CONST;
  * @width: width of the rectangle.
  * @height: height of the rectangle.
  *
- * The #PangoRectangle structure represents a rectangle. It is frequently
- * used to represent the logical or ink extents of a single glyph or section
- * of text. (See, for instance, pango_font_get_glyph_extents())
+ * The `PangoRectangle` structure represents a rectangle.
  *
+ * `PangoRectangle` is frequently used to represent the logical or ink
+ * extents of a single glyph or section of text. (See, for instance,
+ * [method@Pango.Font.get_glyph_extents].)
  */
 struct _PangoRectangle
 {
@@ -149,7 +152,7 @@ struct _PangoRectangle
  * PANGO_ASCENT:
  * @rect: a #PangoRectangle
  *
- * Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle
+ * Extracts the *ascent* from a #PangoRectangle
  * representing glyph extents. The ascent is the distance from the
  * baseline to the highest point of the character. This is positive if the
  * glyph ascends above the baseline.
@@ -158,7 +161,7 @@ struct _PangoRectangle
  * PANGO_DESCENT:
  * @rect: a #PangoRectangle
  *
- * Extracts the <firstterm>descent</firstterm> from a #PangoRectangle
+ * Extracts the *descent* from a #PangoRectangle
  * representing glyph extents. The descent is the distance from the
  * baseline to the lowest point of the character. This is positive if the
  * glyph descends below the baseline.
@@ -167,7 +170,7 @@ struct _PangoRectangle
  * PANGO_LBEARING:
  * @rect: a #PangoRectangle
  *
- * Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle
+ * Extracts the *left bearing* from a #PangoRectangle
  * representing glyph extents. The left bearing is the distance from the
  * horizontal origin to the farthest left point of the character.
  * This is positive for characters drawn completely to the right of the
@@ -177,7 +180,7 @@ struct _PangoRectangle
  * PANGO_RBEARING:
  * @rect: a #PangoRectangle
  *
- * Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle
+ * Extracts the *right bearing* from a #PangoRectangle
  * representing glyph extents. The right bearing is the distance from the
  * horizontal origin to the farthest right point of the character.
  * This is positive except for characters drawn completely to the left of the
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 6f48c62c..5283da35 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -19,24 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pango-version
- * @short_description:Tools for checking Pango version at compile- and run-time.
- * @title:Version Checking
- *
- * The capital-letter macros defined here can be used to check the version of Pango
- * at compile-time, and to <firstterm>encode</firstterm> Pango versions into integers.
- *
- * The functions can be used to check the version of the linked Pango library at run-time.
- */
-/**
- * SECTION:utils
- * @short_description:Various convenience and utility functions
- * @title: Miscellaneous Utilities
- *
- * The functions and utilities in this section are mostly used from Pango
- * backends and modules, but may be useful for other purposes too.
- */
 #include "config.h"
 #include <errno.h>
 #include <string.h>
@@ -70,15 +52,13 @@
 /**
  * pango_version:
  *
- * This is similar to the macro %PANGO_VERSION except that
- * it returns the encoded version of Pango available at run-time,
- * as opposed to the version available at compile-time.
+ * Returns the encoded version of Pango available at run-time.
  *
- * A version number can be encoded into an integer using
- * PANGO_VERSION_ENCODE().
+ * This is similar to the macro %PANGO_VERSION except that the macro
+ * returns the encoded version available at compile-time. A version
+ * number can be encoded into an integer using PANGO_VERSION_ENCODE().
  *
- * Returns: The encoded version of Pango library
- *   available at run time.
+ * Returns: The encoded version of Pango library available at run time.
  *
  * Since: 1.16
  **/
@@ -91,14 +71,14 @@ pango_version (void)
 /**
  * pango_version_string:
  *
- * This is similar to the macro %PANGO_VERSION_STRING except that
- * it returns the version of Pango available at run-time, as opposed to
- * the version available at compile-time.
+ * Returns the version of Pango available at run-time.
+ *
+ * This is similar to the macro %PANGO_VERSION_STRING except that the
+ * macro returns the version available at compile-time.
  *
- * Returns: A string containing the version of Pango library
- *   available at run time.
- *   The returned string is owned by Pango and should not be modified
- *   or freed.
+ * Returns: A string containing the version of Pango library available
+ *   at run time. The returned string is owned by Pango and should not
+ *   be modified or freed.
  *
  * Since: 1.16
  **/
@@ -115,11 +95,13 @@ pango_version_string (void)
  * @required_micro: the required major version.
  *
  * Checks that the Pango library in use is compatible with the
- * given version. Generally you would pass in the constants
- * %PANGO_VERSION_MAJOR, %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO
- * as the three arguments to this function; that produces
- * a check that the library in use at run-time is compatible with
- * the version of Pango the application or module was compiled against.
+ * given version.
+ *
+ * Generally you would pass in the constants %PANGO_VERSION_MAJOR,
+ * %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO as the three arguments
+ * to this function; that produces a check that the library in use at
+ * run-time is compatible with the version of Pango the application or
+ * module was compiled against.
  *
  * Compatibility is defined by two things: first the version
  * of the running library is newer than the version
@@ -258,17 +240,18 @@ pango_split_file_list (const char *str)
  * @stream: a stdio stream
  * @str: #GString buffer into which to write the result
  *
- * Reads an entire line from a file into a buffer. Lines may
- * be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter
+ * Reads an entire line from a file into a buffer.
+ *
+ * Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter
  * is not written into the buffer. Text after a '#' character is treated as
  * a comment and skipped. '\' can be used to escape a # character.
  * '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding
  * any other character is ignored and written into the output buffer
  * unmodified.
  *
- * Return value: 0 if the stream was already at an %EOF character, otherwise
- *               the number of lines read (this is useful for maintaining
- *               a line number counter which doesn't combine lines with '\')
+ * Return value: 0 if the stream was already at an %EOF character,
+ *   otherwise the number of lines read (this is useful for maintaining
+ *   a line number counter which doesn't combine lines with '\')
  *
  * Deprecated: 1.38
  **/
@@ -394,9 +377,10 @@ pango_skip_space (const char **pos)
  * @pos: (inout): in/out string position
  * @out: a #GString into which to write the result
  *
- * Scans a word into a #GString buffer. A word consists
- * of [A-Za-z_] followed by zero or more [A-Za-z_0-9]
- * Leading white space is skipped.
+ * Scans a word into a #GString buffer.
+ *
+ * A word consists of [A-Za-z_] followed by zero or more
+ * [A-Za-z_0-9]. Leading white space is skipped.
  *
  * Return value: %FALSE if a parse error occurred.
  *
@@ -438,9 +422,10 @@ pango_scan_word (const char **pos, GString *out)
  * @pos: (inout): in/out string position
  * @out: a #GString into which to write the result
  *
- * Scans a string into a #GString buffer. The string may either
- * be a sequence of non-white-space characters, or a quoted
- * string with '"'. Instead a quoted string, '\"' represents
+ * Scans a string into a #GString buffer.
+ *
+ * The string may either be a sequence of non-white-space characters,
+ * or a quoted string with '"'. Instead a quoted string, '\"' represents
  * a literal quote. Leading white space outside of quotes is skipped.
  *
  * Return value: %FALSE if a parse error occurred.
@@ -531,6 +516,7 @@ pango_scan_string (const char **pos, GString *out)
  * @out: (out): an int into which to write the result
  *
  * Scans an integer.
+ *
  * Leading white space is skipped.
  *
  * Return value: %FALSE if a parse error occurred.
@@ -842,6 +828,7 @@ pango_parse_flags (GType        type,
  * @n_families: (out): will be set to the length of the @families array.
  *
  * Look up all user defined aliases for the alias @fontname.
+ *
  * The resulting font family names will be stored in @families,
  * and the number of families in @n_families.
  *
@@ -903,11 +890,11 @@ pango_find_base_dir (const gchar *text,
  * pango_is_zero_width:
  * @ch: a Unicode character
  *
- * Checks @ch to see if it is a character that should not be
- * normally rendered on the screen.  This includes all Unicode characters
- * with "ZERO WIDTH" in their name, as well as <firstterm>bidi</firstterm> formatting characters, and
- * a few other ones.  This is totally different from g_unichar_iszerowidth()
- * and is at best misnamed.
+ * Checks if a character that should not be normally rendered.
+ *
+ * This includes all Unicode characters with "ZERO WIDTH" in their name,
+ * as well as *bidi* formatting characters, and a few other ones.  This is
+ * totally different from g_unichar_iszerowidth() and is at best misnamed.
  *
  * Return value: %TRUE if @ch is a zero-width character, %FALSE otherwise
  *
@@ -957,10 +944,10 @@ pango_is_zero_width (gunichar ch)
  * @thickness: (inout): pointer to the thickness of a line, in Pango units
  * @position: (inout): corresponding position
  *
- * Quantizes the thickness and position of a line, typically an
- * underline or strikethrough, to whole device pixels, that is integer
- * multiples of %PANGO_SCALE. The purpose of this function is to avoid
- * such lines looking blurry.
+ * Quantizes the thickness and position of a line to whole device pixels.
+ *
+ * This is typically used for underline or strikethrough. The purpose of
+ * this function is to avoid such lines looking blurry.
  *
  * Care is taken to make sure @thickness is at least one pixel when this
  * function returns, but returned @position may become zero as a result
@@ -994,8 +981,10 @@ pango_quantize_line_geometry (int *thickness,
  * pango_units_from_double:
  * @d: double floating-point value
  *
- * Converts a floating-point number to Pango units: multiplies
- * it by %PANGO_SCALE and rounds to nearest integer.
+ * Converts a floating-point number to Pango units.
+ *
+ * The conversion is done by multiplying @d by %PANGO_SCALE and
+ * rounding the result to nearest integer.
  *
  * Return value: the value in Pango units.
  *
@@ -1011,8 +1000,9 @@ pango_units_from_double (double d)
  * pango_units_to_double:
  * @i: value in Pango units
  *
- * Converts a number in Pango units to floating-point: divides
- * it by %PANGO_SCALE.
+ * Converts a number in Pango units to floating-point.
+ *
+ * The conversion is done by dividing @i by %PANGO_SCALE.
  *
  * Return value: the double value.
  *
@@ -1029,19 +1019,21 @@ pango_units_to_double (int i)
  * @inclusive: (allow-none): rectangle to round to pixels inclusively, or %NULL.
  * @nearest: (allow-none): rectangle to round to nearest pixels, or %NULL.
  *
- * Converts extents from Pango units to device units, dividing by the
- * %PANGO_SCALE factor and performing rounding.
+ * Converts extents from Pango units to device units.
+ *
+ * The conversion is done by dividing by the %PANGO_SCALE factor and
+ * performing rounding.
  *
- * The @inclusive rectangle is converted by flooring the x/y coordinates and extending
- * width/height, such that the final rectangle completely includes the original
- * rectangle.
+ * The @inclusive rectangle is converted by flooring the x/y coordinates
+ * and extending width/height, such that the final rectangle completely
+ * includes the original rectangle.
  *
  * The @nearest rectangle is converted by rounding the coordinates
  * of the rectangle to the nearest device unit (pixel).
  *
  * The rule to which argument to use is: if you want the resulting device-space
- * rectangle to completely contain the original rectangle, pass it in as @inclusive.
- * If you want two touching-but-not-overlapping rectangles stay
+ * rectangle to completely contain the original rectangle, pass it in as
+ * @inclusive. If you want two touching-but-not-overlapping rectangles stay
  * touching-but-not-overlapping after rounding to device units, pass them in
  * as @nearest.
  *
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 1b8bfbba..d880f1b3 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -158,16 +158,18 @@ _pango_cairo_update_context (cairo_t      *cr,
 /**
  * pango_cairo_update_context:
  * @cr: a Cairo context
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
- * Updates a #PangoContext previously created for use with Cairo to
+ * Updates a `PangoContext` previously created for use with Cairo to
  * match the current transformation and target surface of a Cairo
- * context. If any layouts have been created for the context,
- * it's necessary to call pango_layout_context_changed() on those
+ * context.
+ *
+ * If any layouts have been created for the context,
+ * it's necessary to call [method@Pango.Layout.context_changed] on those
  * layouts.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_update_context (cairo_t      *cr,
 			    PangoContext *context)
@@ -180,18 +182,20 @@ pango_cairo_update_context (cairo_t      *cr,
 
 /**
  * pango_cairo_context_set_resolution:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @dpi: the resolution in "dots per inch". (Physical inches aren't actually
  *   involved; the terminology is conventional.) A 0 or negative value
  *   means to use the resolution from the font map.
  *
- * Sets the resolution for the context. This is a scale factor between
- * points specified in a #PangoFontDescription and Cairo units. The
+ * Sets the resolution for the context.
+ *
+ * This is a scale factor between
+ * points specified in a `PangoFontDescription` and Cairo units. The
  * default value is 96, meaning that a 10 point font will be 13
  * units high. (10 * 96. / 72. = 13.3).
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_context_set_resolution (PangoContext *context,
 				    double        dpi)
@@ -202,15 +206,16 @@ pango_cairo_context_set_resolution (PangoContext *context,
 
 /**
  * pango_cairo_context_get_resolution:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
- * Gets the resolution for the context. See pango_cairo_context_set_resolution()
+ * Gets the resolution for the context.
+ * See [func@PangoCairo.context_set_resolution]
  *
  * Return value: the resolution in "dots per inch". A negative value will
- *  be returned if no resolution has previously been set.
+ *   be returned if no resolution has previously been set.
  *
  * Since: 1.10
- **/
+ */
 double
 pango_cairo_context_get_resolution (PangoContext *context)
 {
@@ -224,12 +229,13 @@ pango_cairo_context_get_resolution (PangoContext *context)
 
 /**
  * pango_cairo_context_set_font_options:
- * @context: a #PangoContext, from a pangocairo font map
- * @options: (nullable): a #cairo_font_options_t, or %NULL to unset
- *           any previously set options. A copy is made.
+ * @context: a `PangoContext`, from a pangocairo font map
+ * @options: (nullable): a `cairo_font_options_t`, or %NULL to unset
+ *   any previously set options. A copy is made.
  *
  * Sets the font options used when rendering text with this context.
- * These options override any options that pango_cairo_update_context()
+ *
+ * These options override any options that [func@update_context]
  * derives from the target surface.
  *
  * Since: 1.10
@@ -278,18 +284,21 @@ pango_cairo_context_set_font_options (PangoContext               *context,
 
 /**
  * pango_cairo_context_get_font_options:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
  * Retrieves any font rendering options previously set with
- * pango_cairo_context_set_font_options(). This function does not report options
- * that are derived from the target surface by pango_cairo_update_context()
+ * [func@PangoCairo.context_set_font_options].
+ *
+ * This function
+ * does not report options that are derived from the target
+ * surface by [func@update_context].
  *
  * Return value: (nullable): the font options previously set on the
  *   context, or %NULL if no options have been set. This value is
  *   owned by the context and must not be modified or freed.
  *
  * Since: 1.10
- **/
+ */
 const cairo_font_options_t *
 pango_cairo_context_get_font_options (PangoContext *context)
 {
@@ -307,15 +316,15 @@ pango_cairo_context_get_font_options (PangoContext *context)
 
 /**
  * _pango_cairo_context_merge_font_options:
- * @context: a #PangoContext
- * @options: a #cairo_font_options_t
+ * @context: a `PangoContext`
+ * @options: a `cairo_font_options_t`
  *
  * Merge together options from the target surface and explicitly set
  * on the context.
  *
  * Return value: the combined set of font options. This value is owned
- * by the context and must not be modified or freed.
- **/
+ *   by the context and must not be modified or freed.
+ */
 const cairo_font_options_t *
 _pango_cairo_context_get_merged_font_options (PangoContext *context)
 {
@@ -336,7 +345,7 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
 
 /**
  * pango_cairo_context_set_shape_renderer:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @func: (nullable): Callback function for rendering attributes of
  *        type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
  * @data: User data that will be passed to @func.
@@ -344,8 +353,9 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
  *           context is freed to release @data, or %NULL.
  *
  * Sets callback function for context to use for rendering attributes
- * of type %PANGO_ATTR_SHAPE.  See #PangoCairoShapeRendererFunc for
- * details.
+ * of type %PANGO_ATTR_SHAPE.
+ *
+ * See `PangoCairoShapeRendererFunc` for details.
  *
  * Since: 1.18
  */
@@ -371,26 +381,27 @@ pango_cairo_context_set_shape_renderer (PangoContext                *context,
 
 /**
  * pango_cairo_context_get_shape_renderer: (skip)
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @data: Pointer to #gpointer to return user data
  *
  * Sets callback function for context to use for rendering attributes
- * of type %PANGO_ATTR_SHAPE.  See #PangoCairoShapeRendererFunc for
- * details.
+ * of type %PANGO_ATTR_SHAPE.
+ *
+ * See `PangoCairoShapeRendererFunc` for details.
  *
  * Retrieves callback function and associated user data for rendering
  * attributes of type %PANGO_ATTR_SHAPE as set by
- * pango_cairo_context_set_shape_renderer(), if any.
+ * [func@PangoCairo.context_set_shape_renderer], if any.
  *
- * Return value: (transfer none) (nullable): the shape rendering callback previously
- *   set on the context, or %NULL if no shape rendering callback have
- *   been set.
+ * Return value: (transfer none) (nullable): the shape rendering callback
+ *   previously set on the context, or %NULL if no shape rendering callback
+ *   have been set.
  *
  * Since: 1.18
  */
 PangoCairoShapeRendererFunc
-pango_cairo_context_get_shape_renderer (PangoContext                *context,
-					gpointer                    *data)
+pango_cairo_context_get_shape_renderer (PangoContext *context,
+                                        gpointer     *data)
 {
   PangoCairoContextInfo *info;
 
@@ -417,19 +428,21 @@ pango_cairo_context_get_shape_renderer (PangoContext                *context,
  * @cr: a Cairo context
  *
  * Creates a context object set up to match the current transformation
- * and target surface of the Cairo context.  This context can then be
- * used to create a layout using pango_layout_new().
+ * and target surface of the Cairo context.
+ *
+ * This context can then be
+ * used to create a layout using [ctor@Pango.Layout.new].
  *
  * This function is a convenience function that creates a context using
- * the default font map, then updates it to @cr.  If you just need to
- * create a layout for use with @cr and do not need to access #PangoContext
- * directly, you can use pango_cairo_create_layout() instead.
+ * the default font map, then updates it to @cr. If you just need to
+ * create a layout for use with @cr and do not need to access `PangoContext`
+ * directly, you can use [func@create_layout] instead.
  *
- * Return value: (transfer full): the newly created #PangoContext. Free with
- *   g_object_unref().
+ * Return value: (transfer full): the newly created `PangoContext`.
+ *   Free with g_object_unref().
  *
  * Since: 1.22
- **/
+ */
 PangoContext *
 pango_cairo_create_context (cairo_t *cr)
 {
@@ -450,24 +463,26 @@ pango_cairo_create_context (cairo_t *cr)
  * @cr: a Cairo context
  *
  * Creates a layout object set up to match the current transformation
- * and target surface of the Cairo context.  This layout can then be
+ * and target surface of the Cairo context.
+ *
+ * This layout can then be
  * used for text measurement with functions like
- * pango_layout_get_size() or drawing with functions like
- * pango_cairo_show_layout(). If you change the transformation
- * or target surface for @cr, you need to call pango_cairo_update_layout()
+ * [method@Pango.Layout.get_size] or drawing with functions like
+ * [func@show_layout]. If you change the transformation or target
+ * surface for @cr, you need to call [func@update_layout].
  *
  * This function is the most convenient way to use Cairo with Pango,
  * however it is slightly inefficient since it creates a separate
- * #PangoContext object for each layout. This might matter in an
+ * `PangoContext` object for each layout. This might matter in an
  * application that was laying out large amounts of text.
  *
- * Return value: (transfer full): the newly created #PangoLayout. Free with
- *   g_object_unref().
+ * Return value: (transfer full): the newly created `PangoLayout`.
+ *   Free with g_object_unref().
  *
  * Since: 1.10
- **/
+ */
 PangoLayout *
-pango_cairo_create_layout  (cairo_t *cr)
+pango_cairo_create_layout (cairo_t *cr)
 {
   PangoContext *context;
   PangoLayout *layout;
@@ -484,14 +499,14 @@ pango_cairo_create_layout  (cairo_t *cr)
 /**
  * pango_cairo_update_layout:
  * @cr: a Cairo context
- * @layout: a #PangoLayout, from pango_cairo_create_layout()
+ * @layout: a `PangoLayout`, from [func@create_layout]
  *
- * Updates the private #PangoContext of a #PangoLayout created with
- * pango_cairo_create_layout() to match the current transformation
- * and target surface of a Cairo context.
+ * Updates the private `PangoContext` of a `PangoLayout` created with
+ * [func@create_layout] to match the current transformation and target
+ * surface of a Cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_update_layout (cairo_t     *cr,
 			   PangoLayout *layout)
diff --git a/pango/pangocairo-font.c b/pango/pangocairo-font.c
index 1cadd005..c4155f68 100644
--- a/pango/pangocairo-font.c
+++ b/pango/pangocairo-font.c
@@ -137,17 +137,17 @@ done:
 
 /**
  * pango_cairo_font_get_scaled_font:
- * @font: a #PangoFont from a #PangoCairoFontMap
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
  *
- * Gets the #cairo_scaled_font_t used by @font.
+ * Gets the `cairo_scaled_font_t` used by @font.
  * The scaled font can be referenced and kept using
  * cairo_scaled_font_reference().
  *
- * Return value: (transfer none) (nullable): the #cairo_scaled_font_t used by @font,
- *               or %NULL if @font is %NULL.
+ * Return value: (transfer none) (nullable): the `cairo_scaled_font_t`
+ *   used by @font, or %NULL if @font is %NULL.
  *
  * Since: 1.18
- **/
+ */
 cairo_scaled_font_t *
 pango_cairo_font_get_scaled_font (PangoCairoFont *cfont)
 {
@@ -163,14 +163,14 @@ pango_cairo_font_get_scaled_font (PangoCairoFont *cfont)
 
 /**
  * _pango_cairo_font_install:
- * @font: a #PangoCairoFont
+ * @font: a `PangoCairoFont`
  * @cr: a #cairo_t
  *
  * Makes @font the current font for rendering in the specified
  * Cairo context.
  *
  * Return value: %TRUE if font was installed successfully, %FALSE otherwise.
- **/
+ */
 gboolean
 _pango_cairo_font_install (PangoFont *font,
 			   cairo_t   *cr)
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 120ccb89..524102ba 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -47,29 +47,30 @@ pango_cairo_font_map_default_init (PangoCairoFontMapIface *iface)
 /**
  * pango_cairo_font_map_new:
  *
- * Creates a new #PangoCairoFontMap object; a fontmap is used
- * to cache information about available fonts, and holds
- * certain global parameters such as the resolution.
- * In most cases, you can use pango_cairo_font_map_get_default()
+ * Creates a new `PangoCairoFontMap` object.
+ *
+ * A fontmap is used to cache information about available fonts,
+ * and holds certain global parameters such as the resolution.
+ * In most cases, you can use `func@PangoCairo.font_map_get_default]
  * instead.
  *
  * Note that the type of the returned object will depend
  * on the particular font backend Cairo was compiled to use;
- * You generally should only use the #PangoFontMap and
- * #PangoCairoFontMap interfaces on the returned object.
+ * You generally should only use the `PangoFontMap` and
+ * `PangoCairoFontMap` interfaces on the returned object.
  *
  * You can override the type of backend returned by using an
- * environment variable %PANGOCAIRO_BACKEND.  Supported types,
+ * environment variable %PANGOCAIRO_BACKEND. Supported types,
  * based on your build, are fc (fontconfig), win32, and coretext.
  * If requested type is not available, NULL is returned. Ie.
  * this is only useful for testing, when at least two backends
  * are compiled in.
  *
- * Return value: (transfer full): the newly allocated #PangoFontMap,
- *               which should be freed with g_object_unref().
+ * Return value: (transfer full): the newly allocated `PangoFontMap`,
+ *   which should be freed with g_object_unref().
  *
  * Since: 1.10
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_new (void)
 {
@@ -110,20 +111,19 @@ pango_cairo_font_map_new (void)
  * pango_cairo_font_map_new_for_font_type:
  * @fonttype: desired #cairo_font_type_t
  *
- * Creates a new #PangoCairoFontMap object of the type suitable
+ * Creates a new `PangoCairoFontMap` object of the type suitable
  * to be used with cairo font backend of type @fonttype.
  *
- * In most cases one should simply use @pango_cairo_font_map_new(),
- * or in fact in most of those cases, just use
- * @pango_cairo_font_map_get_default().
+ * In most cases one should simply use [type_func@PangoCairo.FontMap.new], or
+ * in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default].
  *
  * Return value: (transfer full) (nullable): the newly allocated
- *               #PangoFontMap of suitable type which should be freed
- *               with g_object_unref(), or %NULL if the requested
- *               cairo font backend is not supported / compiled in.
+ *   `PangoFontMap` of suitable type which should be freed with
+ *   g_object_unref(), or %NULL if the requested cairo font backend
+ *   is not supported / compiled in.
  *
  * Since: 1.18
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_new_for_font_type (cairo_font_type_t fonttype)
 {
@@ -151,27 +151,28 @@ static GPrivate default_font_map = G_PRIVATE_INIT (g_object_unref); /* MT-safe *
 /**
  * pango_cairo_font_map_get_default:
  *
- * Gets a default #PangoCairoFontMap to use with Cairo.
+ * Gets a default `PangoCairoFontMap` to use with Cairo.
  *
- * Note that the type of the returned object will depend
- * on the particular font backend Cairo was compiled to use;
- * You generally should only use the #PangoFontMap and
- * #PangoCairoFontMap interfaces on the returned object.
+ * Note that the type of the returned object will depend on the
+ * particular font backend Cairo was compiled to use; you generally
+ * should only use the `PangoFontMap` and `PangoCairoFontMap`
+ * interfaces on the returned object.
  *
  * The default Cairo fontmap can be changed by using
- * pango_cairo_font_map_set_default().  This can be used to
- * change the Cairo font backend that the default fontmap
- * uses for example.
+ * [method@PangoCairo.FontMap.set_default]. This can be used to
+ * change the Cairo font backend that the default fontmap uses
+ * for example.
  *
  * Note that since Pango 1.32.6, the default fontmap is per-thread.
- * Each thread gets its own default fontmap.  In this way,
- * PangoCairo can be used safely from multiple threads.
+ * Each thread gets its own default fontmap. In this way, PangoCairo
+ * can be used safely from multiple threads.
  *
  * Return value: (transfer none): the default PangoCairo fontmap
- *  for the current thread. This object is owned by Pango and must not be freed.
+ *  for the current thread. This object is owned by Pango and must
+ *  not be freed.
  *
  * Since: 1.10
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_get_default (void)
 {
@@ -190,24 +191,24 @@ pango_cairo_font_map_get_default (void)
  * pango_cairo_font_map_set_default:
  * @fontmap: (nullable): The new default font map, or %NULL
  *
- * Sets a default #PangoCairoFontMap to use with Cairo.
+ * Sets a default `PangoCairoFontMap` to use with Cairo.
  *
  * This can be used to change the Cairo font backend that the
- * default fontmap uses for example.  The old default font map
+ * default fontmap uses for example. The old default font map
  * is unreffed and the new font map referenced.
  *
  * Note that since Pango 1.32.6, the default fontmap is per-thread.
  * This function only changes the default fontmap for
- * the current thread.  Default fontmaps of existing threads
+ * the current thread. Default fontmaps of existing threads
  * are not changed. Default fontmaps of any new threads will
- * still be created using pango_cairo_font_map_new().
+ * still be created using [type_func@PangoCairo.FontMap.new].
  *
  * A value of %NULL for @fontmap will cause the current default
- * font map to be released and a new default font
- * map to be created on demand, using pango_cairo_font_map_new().
+ * font map to be released and a new default font map to be created
+ * on demand, using [type_func@PangoCairo.FontMap.new].
  *
  * Since: 1.22
- **/
+ */
 void
 pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap)
 {
@@ -221,20 +222,22 @@ pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_set_resolution:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  * @dpi: the resolution in "dots per inch". (Physical inches aren't actually
  *   involved; the terminology is conventional.)
  *
- * Sets the resolution for the fontmap. This is a scale factor between
- * points specified in a #PangoFontDescription and Cairo units. The
+ * Sets the resolution for the fontmap.
+ *
+ * This is a scale factor between
+ * points specified in a `PangoFontDescription` and Cairo units. The
  * default value is 96, meaning that a 10 point font will be 13
  * units high. (10 * 96. / 72. = 13.3).
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
-				     double             dpi)
+                                     double             dpi)
 {
   g_return_if_fail (PANGO_IS_CAIRO_FONT_MAP (fontmap));
 
@@ -243,9 +246,11 @@ pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
 
 /**
  * pango_cairo_font_map_get_resolution:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
+ *
+ * Gets the resolution for the fontmap.
  *
- * Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution()
+ * See [method@PangoCairo.FontMap.set_resolution].
  *
  * Return value: the resolution in "dots per inch"
  *
@@ -261,16 +266,16 @@ pango_cairo_font_map_get_resolution (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_create_context: (skip)
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  *
- * Create a #PangoContext for the given fontmap.
+ * Create a `PangoContext` for the given fontmap.
  *
  * Return value: the newly created context; free with g_object_unref().
  *
  * Since: 1.10
  *
  * Deprecated: 1.22: Use pango_font_map_create_context() instead.
- **/
+ */
 PangoContext *
 pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap)
 {
@@ -281,14 +286,14 @@ pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_get_font_type:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  *
- * Gets the type of Cairo font backend that @fontmap uses.  
+ * Gets the type of Cairo font backend that @fontmap uses.
  *
- * Return value: the #cairo_font_type_t cairo font backend type
+ * Return value: the `cairo_font_type_t` cairo font backend type
  *
  * Since: 1.18
- **/
+ */
 cairo_font_type_t
 pango_cairo_font_map_get_font_type (PangoCairoFontMap *fontmap)
 {
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 614a3a44..9e3cfab8 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -19,139 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pangocairo
- * @short_description:Font handling and rendering with Cairo
- * @title:Cairo Fonts and Rendering
- *
- * The <ulink url="http://cairographics.org">Cairo library</ulink> is a
- * vector graphics library with a powerful rendering model. It has such
- * features as anti-aliased primitives, alpha-compositing, and
- * gradients. Multiple backends for Cairo are available, to allow
- * rendering to images, to PDF files, and to the screen on X and on other
- * windowing systems. The functions in this section allow using Pango
- * to render to Cairo surfaces.
- *
- * Using Pango with Cairo is straightforward. A #PangoContext created
- * with pango_cairo_font_map_create_context() can be used on any
- * Cairo context (cairo_t), but needs to be updated to match the
- * current transformation matrix and target surface of the Cairo context
- * using pango_cairo_update_context(). The convenience functions
- * pango_cairo_create_layout() and pango_cairo_update_layout() handle
- * the common case where the program doesn't need to manipulate the
- * properties of the #PangoContext.
- *
- * When you get the metrics of a layout or of a piece of a layout using
- * functions such as pango_layout_get_extents(), the reported metrics
- * are in user-space coordinates. If a piece of text is 10 units long,
- * and you call cairo_scale (cr, 2.0), it still is more-or-less 10
- * units long. However, the results will be affected by hinting
- * (that is, the process of adjusting the text to look good on the
- * pixel grid), so you shouldn't assume they are completely independent
- * of the current transformation matrix. Note that the basic metrics
- * functions in Pango report results in integer Pango units. To get
- * to the floating point units used in Cairo divide by %PANGO_SCALE.
- *
- * ## Using Pango with Cairo ## {#rotated-example}
- *
- * |[<!-- language="C" -->
- * #include <math.h>
- * #include <pango/pangocairo.h>
- *
- * static void
- * draw_text (cairo_t *cr)
- * {
- * #define RADIUS 150
- * #define N_WORDS 10
- * #define FONT "Sans Bold 27"
- *
- *   PangoLayout *layout;
- *   PangoFontDescription *desc;
- *   int i;
- *
- *   /&ast; Center coordinates on the middle of the region we are drawing
- *    &ast;/
- *   cairo_translate (cr, RADIUS, RADIUS);
- *
- *   /&ast; Create a PangoLayout, set the font and text &ast;/
- *   layout = pango_cairo_create_layout (cr);
- *
- *   pango_layout_set_text (layout, "Text", -1);
- *   desc = pango_font_description_from_string (FONT);
- *   pango_layout_set_font_description (layout, desc);
- *   pango_font_description_free (desc);
- *
- *   /&ast; Draw the layout N_WORDS times in a circle &ast;/
- *   for (i = 0; i &lt; N_WORDS; i++)
- *     {
- *       int width, height;
- *       double angle = (360. * i) / N_WORDS;
- *       double red;
- *
- *       cairo_save (cr);
- *
- *       /&ast; Gradient from red at angle == 60 to blue at angle == 240 &ast;/
- *       red   = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
- *       cairo_set_source_rgb (cr, red, 0, 1.0 - red);
- *
- *       cairo_rotate (cr, angle * G_PI / 180.);
- *
- *       /&ast; Inform Pango to re-layout the text with the new transformation &ast;/
- *       pango_cairo_update_layout (cr, layout);
- *
- *       pango_layout_get_size (layout, &amp;width, &amp;height);
- *       cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
- *       pango_cairo_show_layout (cr, layout);
- *
- *       cairo_restore (cr);
- *     }
- *
- *   /&ast; free the layout object &ast;/
- *   g_object_unref (layout);
- * }
- *
- * int main (int argc, char **argv)
- * {
- *   cairo_t *cr;
- *   char *filename;
- *   cairo_status_t status;
- *   cairo_surface_t *surface;
- *
- *   if (argc != 2)
- *     {
- *       g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
- *       return 1;
- *     }
- *
- *      filename = argv[1];
- *
- *   surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
- *                                         2 * RADIUS, 2 * RADIUS);
- *   cr = cairo_create (surface);
- *
- *   cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
- *   cairo_paint (cr);
- *   draw_text (cr);
- *   cairo_destroy (cr);
- *
- *   status = cairo_surface_write_to_png (surface, filename);
- *   cairo_surface_destroy (surface);
- *
- *   if (status != CAIRO_STATUS_SUCCESS)
- *     {
- *       g_printerr ("Could not save png to '%s'\n", filename);
- *       return 1;
- *     }
- *
- *   return 0;
- * }
- * ]|
- *
- * Once you build and run the example code above, you should see the
- * following result:
- *
- * ![Output of rotated-example](rotated-text.png)
- */
 #include "config.h"
 
 #include <math.h>
@@ -1174,15 +1041,16 @@ _pango_cairo_do_error_underline (cairo_t *cr,
 /**
  * pango_cairo_show_glyph_string:
  * @cr: a Cairo context
- * @font: a #PangoFont from a #PangoCairoFontMap
- * @glyphs: a #PangoGlyphString
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
+ * @glyphs: a `PangoGlyphString`
  *
  * Draws the glyphs in @glyphs in the specified cairo context.
+ *
  * The origin of the glyphs (the left edge of the baseline) will
  * be drawn at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_glyph_string (cairo_t          *cr,
 			       PangoFont        *font,
@@ -1199,21 +1067,22 @@ pango_cairo_show_glyph_string (cairo_t          *cr,
  * pango_cairo_show_glyph_item:
  * @cr: a Cairo context
  * @text: the UTF-8 text that @glyph_item refers to
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  *
  * Draws the glyphs in @glyph_item in the specified cairo context,
+ *
  * embedding the text associated with the glyphs in the output if the
  * output format supports it (PDF for example), otherwise it acts
- * similar to pango_cairo_show_glyph_string().
+ * similar to [func@show_glyph_string].
  *
  * The origin of the glyphs (the left edge of the baseline) will
  * be drawn at the current point of the cairo context.
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by <literal>@glyph_item->item->offset</literal>.
+ * indexed by `glyph_item->item->offset`.
  *
  * Since: 1.22
- **/
+ */
 void
 pango_cairo_show_glyph_item (cairo_t          *cr,
 			     const char       *text,
@@ -1229,14 +1098,15 @@ pango_cairo_show_glyph_item (cairo_t          *cr,
 /**
  * pango_cairo_show_layout_line:
  * @cr: a Cairo context
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
+ *
+ * Draws a `PangoLayoutLine` in the specified cairo context.
  *
- * Draws a #PangoLayoutLine in the specified cairo context.
  * The origin of the glyphs (the left edge of the line) will
  * be drawn at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_layout_line (cairo_t          *cr,
 			      PangoLayoutLine  *line)
@@ -1252,12 +1122,13 @@ pango_cairo_show_layout_line (cairo_t          *cr,
  * @cr: a Cairo context
  * @layout: a Pango layout
  *
- * Draws a #PangoLayout in the specified cairo context.
- * The top-left corner of the #PangoLayout will be drawn
+ * Draws a `PangoLayout` in the specified cairo context.
+ *
+ * The top-left corner of the `PangoLayout` will be drawn
  * at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_layout (cairo_t     *cr,
 			 PangoLayout *layout)
@@ -1278,12 +1149,14 @@ pango_cairo_show_layout (cairo_t     *cr,
  *
  * Draw a squiggly line in the specified cairo context that approximately
  * covers the given rectangle in the style of an underline used to indicate a
- * spelling error.  (The width of the underline is rounded to an integer
+ * spelling error.
+ *
+ * The width of the underline is rounded to an integer
  * number of up/down segments and the resulting rectangle is centered in the
- * original rectangle)
+ * original rectangle.
  *
  * Since: 1.14
- **/
+ */
 void
 pango_cairo_show_error_underline (cairo_t *cr,
 				  double  x,
@@ -1300,15 +1173,17 @@ pango_cairo_show_error_underline (cairo_t *cr,
 /**
  * pango_cairo_glyph_string_path:
  * @cr: a Cairo context
- * @font: a #PangoFont from a #PangoCairoFontMap
- * @glyphs: a #PangoGlyphString
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
+ * @glyphs: a `PangoGlyphString`
  *
  * Adds the glyphs in @glyphs to the current path in the specified
- * cairo context. The origin of the glyphs (the left edge of the baseline)
+ * cairo context.
+ *
+ * The origin of the glyphs (the left edge of the baseline)
  * will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_glyph_string_path (cairo_t          *cr,
 			       PangoFont        *font,
@@ -1323,14 +1198,16 @@ pango_cairo_glyph_string_path (cairo_t          *cr,
 /**
  * pango_cairo_layout_line_path:
  * @cr: a Cairo context
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  *
- * Adds the text in #PangoLayoutLine to the current path in the
- * specified cairo context.  The origin of the glyphs (the left edge
+ * Adds the text in `PangoLayoutLine` to the current path in the
+ * specified cairo context.
+ *
+ * The origin of the glyphs (the left edge
  * of the line) will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_layout_line_path (cairo_t          *cr,
 			      PangoLayoutLine  *line)
@@ -1346,12 +1223,14 @@ pango_cairo_layout_line_path (cairo_t          *cr,
  * @cr: a Cairo context
  * @layout: a Pango layout
  *
- * Adds the text in a #PangoLayout to the current path in the
- * specified cairo context.  The top-left corner of the #PangoLayout
+ * Adds the text in a `PangoLayout` to the current path in the
+ * specified cairo context.
+ *
+ * The top-left corner of the `PangoLayout`
  * will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_layout_path (cairo_t     *cr,
 			 PangoLayout *layout)
@@ -1372,12 +1251,14 @@ pango_cairo_layout_path (cairo_t     *cr,
  *
  * Add a squiggly line to the current path in the specified cairo context that
  * approximately covers the given rectangle in the style of an underline used
- * to indicate a spelling error.  (The width of the underline is rounded to an
+ * to indicate a spelling error.
+ *
+ * The width of the underline is rounded to an
  * integer number of up/down segments and the resulting rectangle is centered
- * in the original rectangle)
+ * in the original rectangle.
  *
  * Since: 1.14
- **/
+ */
 void
 pango_cairo_error_underline_path (cairo_t *cr,
 				  double   x,
diff --git a/pango/pangocairo.h b/pango/pangocairo.h
index 633ccf9d..7e860554 100644
--- a/pango/pangocairo.h
+++ b/pango/pangocairo.h
@@ -30,9 +30,11 @@ G_BEGIN_DECLS
 /**
  * PangoCairoFont:
  *
- * #PangoCairoFont is an interface exported by fonts for
- * use with Cairo. The actual type of the font will depend
- * on the particular font technology Cairo was compiled to use.
+ * `PangoCairoFont` is an interface exported by fonts for
+ * use with Cairo.
+ *
+ * The actual type of the font will depend on the particular
+ * font technology Cairo was compiled to use.
  *
  * Since: 1.18
  **/
@@ -55,9 +57,11 @@ typedef struct _PangoCairoFont      PangoCairoFont;
 /**
  * PangoCairoFontMap:
  *
- * #PangoCairoFontMap is an interface exported by font maps for
- * use with Cairo. The actual type of the font map will depend
- * on the particular font technology Cairo was compiled to use.
+ * `PangoCairoFontMap` is an interface exported by font maps for
+ * use with Cairo.
+ *
+ * The actual type of the font map will depend on the particular
+ * font technology Cairo was compiled to use.
  *
  * Since: 1.10
  **/
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index b6941c05..5f9cf2df 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -20,14 +20,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:coretext-fonts
- * @short_description:Font handling and rendering on OS X
- * @title:CoreText Fonts and Rendering
- *
- * The macros and functions in this section are used to access fonts natively on
- * OS X using the CoreText text rendering subsystem.
- */
 #include "config.h"
 
 #include "pangocoretext.h"
diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c
index 7af4cdfc..0d3b00a0 100644
--- a/pango/pangofc-decoder.c
+++ b/pango/pangofc-decoder.c
@@ -19,14 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pangofc-decoder
- * @short_description:Custom font encoding handling
- * @title:PangoFcDecoder
- *
- * PangoFcDecoder represents a decoder that an application provides
- * for handling a font that is encoded in a custom way.
- */
 #include "config.h"
 #include "pangofc-decoder.h"
 
@@ -44,15 +36,17 @@ pango_fc_decoder_class_init (PangoFcDecoderClass *klass G_GNUC_UNUSED)
 
 /**
  * pango_fc_decoder_get_charset:
- * @decoder: a #PangoFcDecoder
- * @fcfont: the #PangoFcFont to query.
+ * @decoder: a `PangoFcDecoder`
+ * @fcfont: the `PangoFcFont` to query.
  *
- * Generates an #FcCharSet of supported characters for the fcfont
- * given.  The returned #FcCharSet will be a reference to an
- * internal value stored by the #PangoFcDecoder and must not
+ * Generates an `FcCharSet` of supported characters for the @fcfont
+ * given.
+ *
+ * The returned `FcCharSet` will be a reference to an
+ * internal value stored by the `PangoFcDecoder` and must not
  * be modified or freed.
  *
- * Returns: (transfer none): the #FcCharset for @fcfont; must not
+ * Returns: (transfer none): the `FcCharset` for @fcfont; must not
  *   be modified or freed.
  *
  * Since: 1.6
@@ -68,12 +62,14 @@ pango_fc_decoder_get_charset (PangoFcDecoder *decoder,
 
 /**
  * pango_fc_decoder_get_glyph:
- * @decoder: a #PangoFcDecoder
- * @fcfont: a #PangoFcFont to query.
- * @wc: the Unicode code point to convert to a single #PangoGlyph.
+ * @decoder: a `PangoFcDecoder`
+ * @fcfont: a `PangoFcFont` to query.
+ * @wc: the Unicode code point to convert to a single `PangoGlyph`.
+ *
+ * Generates a `PangoGlyph` for the given Unicode point using the
+ * custom decoder.
  *
- * Generates a #PangoGlyph for the given Unicode point using the
- * custom decoder. For complex scripts where there can be multiple
+ * For complex scripts where there can be multiple
  * glyphs for a single character, the decoder will return whatever
  * glyph is most convenient for it. (Usually whatever glyph is directly
  * in the fonts character map table.)
diff --git a/pango/pangofc-decoder.h b/pango/pangofc-decoder.h
index 7c78958c..6268c428 100644
--- a/pango/pangofc-decoder.h
+++ b/pango/pangofc-decoder.h
@@ -48,13 +48,14 @@ typedef struct _PangoFcDecoderClass PangoFcDecoderClass;
 /**
  * PangoFcDecoder:
  *
- * #PangoFcDecoder is a virtual base class that implementations will
- * inherit from.  It's the interface that is used to define a custom
- * encoding for a font.  These objects are created in your code from a
- * function callback that was originally registered with
- * pango_fc_font_map_add_decoder_find_func().  Pango requires
- * information about the supported charset for a font as well as the
- * individual character to glyph conversions.  Pango gets that
+ * `PangoFcDecoder` is a virtual base class that implementations will
+ * inherit from.
+ *
+ * It's the interface that is used to define a custom encoding for a font.
+ * These objects are created in your code from a function callback that was
+ * originally registered with [method@PangoFc.FontMap.add_decoder_find_func].
+ * Pango requires information about the supported charset for a font as well
+ * as the individual character to glyph conversions. Pango gets that
  * information via the #get_charset and #get_glyph callbacks into your
  * object implementation.
  *
@@ -68,16 +69,16 @@ struct _PangoFcDecoder
 
 /**
  * PangoFcDecoderClass:
- * @get_charset: This returns an #FcCharset given a #PangoFcFont that
+ * @get_charset: This returns an `FcCharset` given a `PangoFcFont` that
  *  includes a list of supported characters in the font.  The
  *  #FcCharSet that is returned should be an internal reference to your
  *  code.  Pango will not free this structure.  It is important that
  *  you make this callback fast because this callback is called
  *  separately for each character to determine Unicode coverage.
- * @get_glyph: This returns a single #PangoGlyph for a given Unicode
+ * @get_glyph: This returns a single `PangoGlyph` for a given Unicode
  *  code point.
  *
- * Class structure for #PangoFcDecoder.
+ * Class structure for `PangoFcDecoder`.
  *
  * Since: 1.6
  **/
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index cf6b427f..5a164343 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -19,24 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pangofc-font
- * @short_description:Base font class for Fontconfig-based backends
- * @title:PangoFcFont
- * @see_also:
- * <variablelist><varlistentry><term>#PangoFcFontMap</term> <listitem>The base class for font maps; creating a new
- * Fontconfig-based backend involves deriving from both
- * #PangoFcFontMap and #PangoFcFont.</listitem></varlistentry></variablelist>
- *
- * #PangoFcFont is a base class for font implementation using the
- * Fontconfig and FreeType libraries. It is used in the
- * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
- * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
- * backends shipped with Pango, but can also be used when creating
- * new backends. Any backend deriving from this base class will
- * take advantage of the wide range of shapers implemented using
- * FreeType that come with Pango.
- */
 #include "config.h"
 
 #include "pangofc-font-private.h"
@@ -116,12 +98,23 @@ pango_fc_font_class_init (PangoFcFontClass *class)
   font_class->create_hb_font = pango_fc_font_create_hb_font;
   font_class->get_features = pango_fc_font_get_features;
 
+  /**
+   * PangoFcFont:pattern:
+   *
+   * The fontconfig pattern for this font.
+   */
   g_object_class_install_property (object_class, PROP_PATTERN,
 				   g_param_spec_pointer ("pattern",
 							 "Pattern",
 							 "The fontconfig pattern for this font",
 							 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
 							 G_PARAM_STATIC_STRINGS));
+
+  /**
+   * PangoFcFont:fontmap:
+   *
+   * The PangoFc font map this font is associated with.
+   */
   g_object_class_install_property (object_class, PROP_FONTMAP,
 				   g_param_spec_object ("fontmap",
 							"Font Map",
@@ -534,17 +527,18 @@ pango_fc_font_real_get_glyph (PangoFcFont *font,
 
 /**
  * pango_fc_font_lock_face: (skip)
- * @font: a #PangoFcFont.
+ * @font: a `PangoFcFont`.
+ *
+ * Gets the FreeType `FT_Face` associated with a font.
  *
- * Gets the FreeType `FT_Face` associated with a font,
  * This face will be kept around until you call
- * pango_fc_font_unlock_face().
+ * [method@PangoFc.Font.unlock_face].
  *
  * Return value: the FreeType `FT_Face` associated with @font.
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_get_hb_font() instead
- **/
+ */
 FT_Face
 pango_fc_font_lock_face (PangoFcFont *font)
 {
@@ -555,14 +549,14 @@ pango_fc_font_lock_face (PangoFcFont *font)
 
 /**
  * pango_fc_font_unlock_face:
- * @font: a #PangoFcFont.
+ * @font: a `PangoFcFont`.
  *
  * Releases a font previously obtained with
- * pango_fc_font_lock_face().
+ * [method@PangoFc.Font.lock_face].
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_get_hb_font() instead
- **/
+ */
 void
 pango_fc_font_unlock_face (PangoFcFont *font)
 {
@@ -582,7 +576,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_has_char()
- **/
+ */
 gboolean
 pango_fc_font_has_char (PangoFcFont *font,
 			gunichar     wc)
@@ -607,14 +601,16 @@ pango_fc_font_has_char (PangoFcFont *font,
  * @wc: Unicode character to look up
  *
  * Gets the glyph index for a given Unicode character
- * for @font. If you only want to determine
- * whether the font has the glyph, use pango_fc_font_has_char().
+ * for @font.
+ *
+ * If you only want to determine whether the font has
+ * the glyph, use [method@PangoFc.Font.has_char].
  *
  * Return value: the glyph index, or 0, if the Unicode
  *   character doesn't exist in the font.
  *
  * Since: 1.4
- **/
+ */
 PangoGlyph
 pango_fc_font_get_glyph (PangoFcFont *font,
 			 gunichar     wc)
@@ -647,7 +643,7 @@ pango_fc_font_get_glyph (PangoFcFont *font,
  * Return value: a glyph index into @font.
  *
  * Since: 1.4
- **/
+ */
 PangoGlyph
 pango_fc_font_get_unknown_glyph (PangoFcFont *font,
 				 gunichar     wc)
@@ -670,17 +666,16 @@ _pango_fc_font_shutdown (PangoFcFont *font)
 /**
  * pango_fc_font_kern_glyphs:
  * @font: a #PangoFcFont
- * @glyphs: a #PangoGlyphString
+ * @glyphs: a `PangoGlyphString`
  *
  * This function used to adjust each adjacent pair of glyphs
  * in @glyphs according to kerning information in @font.
  *
  * Since 1.44, it does nothing.
  *
- *
  * Since: 1.4
  * Deprecated: 1.32
- **/
+ */
 void
 pango_fc_font_kern_glyphs (PangoFcFont      *font,
 			   PangoGlyphString *glyphs)
@@ -689,15 +684,14 @@ pango_fc_font_kern_glyphs (PangoFcFont      *font,
 
 /**
  * _pango_fc_font_get_decoder:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * This will return any custom decoder set on this font.
  *
  * Return value: The custom decoder
  *
  * Since: 1.6
- **/
-
+ */
 PangoFcDecoder *
 _pango_fc_font_get_decoder (PangoFcFont *font)
 {
@@ -708,15 +702,15 @@ _pango_fc_font_get_decoder (PangoFcFont *font)
 
 /**
  * _pango_fc_font_set_decoder:
- * @font: a #PangoFcFont
- * @decoder: a #PangoFcDecoder to set for this font
+ * @font: a `PangoFcFont`
+ * @decoder: a `PangoFcDecoder` to set for this font
+ *
+ * This sets a custom decoder for this font.
  *
- * This sets a custom decoder for this font.  Any previous decoder
- * will be released before this one is set.
+ * Any previous decoder will be released before this one is set.
  *
  * Since: 1.6
- **/
-
+ */
 void
 _pango_fc_font_set_decoder (PangoFcFont    *font,
 			    PangoFcDecoder *decoder)
@@ -751,16 +745,17 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
 
 /**
  * pango_fc_font_get_raw_extents:
- * @fcfont: a #PangoFcFont
+ * @fcfont: a `PangoFcFont`
  * @glyph: the glyph index to load
  * @ink_rect: (out) (optional): location to store ink extents of the
  *   glyph, or %NULL
  * @logical_rect: (out) (optional): location to store logical extents
  *   of the glyph or %NULL
  *
- * Gets the extents of a single glyph from a font. The extents are in
- * user space; that is, they are not transformed by any matrix in effect
- * for the font.
+ * Gets the extents of a single glyph from a font.
+ *
+ * The extents are in user space; that is, they are not transformed
+ * by any matrix in effect for the font.
  *
  * Long term, this functionality probably belongs in the default
  * implementation of the get_glyph_extents() virtual function.
@@ -769,7 +764,7 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
  * caching functionality similar to pango_ft2_font_set_glyph_info().
  *
  * Since: 1.6
- **/
+ */
 void
 pango_fc_font_get_raw_extents (PangoFcFont    *fcfont,
 			       PangoGlyph      glyph,
@@ -1038,7 +1033,7 @@ done:
 
 /**
  * pango_fc_font_get_languages:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * Returns the languages that are supported by @font.
  *
@@ -1048,7 +1043,7 @@ done:
  * and its fontmap are valid.
  *
  * Returns: (transfer none) (nullable): a %NULL-terminated
- *    array of PangoLanguage*
+ *    array of `PangoLanguage`*
  *
  * Since: 1.48
  */
@@ -1070,7 +1065,7 @@ pango_fc_font_get_languages (PangoFcFont *font)
 
 /**
  * pango_fc_font_get_pattern: (skip)
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * Returns the FcPattern that @font is based on.
  *
diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h
index fbae5e10..b4aa399e 100644
--- a/pango/pangofc-font.h
+++ b/pango/pangofc-font.h
@@ -60,13 +60,14 @@ typedef struct _PangoFcFontClass PangoFcFontClass;
 /**
  * PangoFcFont:
  *
- * #PangoFcFont is a base class for font implementations
- * using the Fontconfig and FreeType libraries and is used in
- * conjunction with #PangoFcFontMap. When deriving from this
- * class, you need to implement all of its virtual functions
- * other than shutdown() along with the get_glyph_extents()
- * virtual function from #PangoFont.
- **/
+ * `PangoFcFont` is a base class for font implementations
+ * using the Fontconfig and FreeType libraries.
+ *
+ * It is used in onjunction with [class@PangoFc.FontMap].
+ * When deriving from this class, you need to implement all
+ * of its virtual functions other than shutdown() along with
+ * the get_glyph_extents() virtual function from `PangoFont`.
+ */
 struct _PangoFcFont
 {
   PangoFont parent_instance;
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index fef3394a..358b33fb 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -20,25 +20,15 @@
  */
 
 /**
- * SECTION:pangofc-fontmap
- * @short_description:Base fontmap class for Fontconfig-based backends
- * @title:PangoFcFontMap
- * @see_also:
- * <variablelist><varlistentry>
- * <term>#PangoFcFont</term>
- * <listitem>The base class for fonts; creating a new
- * Fontconfig-based backend involves deriving from both
- * #PangoFcFontMap and #PangoFcFont.</listitem>
- * </varlistentry></variablelist>
- *
- * PangoFcFontMap is a base class for font map implementations using the
- * Fontconfig and FreeType libraries. It is used in the
- * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
- * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
- * backends shipped with Pango, but can also be used when creating
- * new backends. Any backend deriving from this base class will
- * take advantage of the wide range of shapers implemented using
- * FreeType that come with Pango.
+ * PangoFcFontMap:
+ *
+ * `PangoFcFontMap` is a base class for font map implementations using the
+ * Fontconfig and FreeType libraries.
+ *
+ * It is used in the Xft and FreeType backends shipped with Pango,
+ * but can also be used when creating new backends. Any backend
+ * deriving from this base class will take advantage of the wide
+ * range of shapers implemented using FreeType that come with Pango.
  */
 #define FONTSET_CACHE_SIZE 256
 
@@ -514,7 +504,7 @@ pango_fc_fontset_key_copy (const PangoFcFontsetKey *old)
  * Returns: the language
  *
  * Since: 1.24
- **/
+ */
 PangoLanguage *
 pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key)
 {
@@ -530,7 +520,7 @@ pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key)
  * Returns: the font description, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoFontDescription *
 pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key)
 {
@@ -546,9 +536,9 @@ pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key)
  * Returns: the matrix, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoMatrix *
-pango_fc_fontset_key_get_matrix      (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key)
 {
   return &key->matrix;
 }
@@ -557,15 +547,16 @@ pango_fc_fontset_key_get_matrix      (const PangoFcFontsetKey *key)
  * pango_fc_fontset_key_get_absolute_size:
  * @key: the fontset key
  *
- * Gets the absolute font size of @key in Pango units.  This is adjusted
- * for both resolution and transformation matrix.
+ * Gets the absolute font size of @key in Pango units.
+ *
+ * This is adjusted for both resolution and transformation matrix.
  *
  * Returns: the pixel size of @key.
  *
  * Since: 1.24
- **/
+ */
 double
-pango_fc_fontset_key_get_absolute_size   (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_absolute_size (const PangoFcFontsetKey *key)
 {
   return key->pixelsize;
 }
@@ -579,9 +570,9 @@ pango_fc_fontset_key_get_absolute_size   (const PangoFcFontsetKey *key)
  * Returns: the resolution of @key
  *
  * Since: 1.24
- **/
+ */
 double
-pango_fc_fontset_key_get_resolution  (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key)
 {
   return key->resolution;
 }
@@ -595,7 +586,7 @@ pango_fc_fontset_key_get_resolution  (const PangoFcFontsetKey *key)
  * Returns: the context key, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 gpointer
 pango_fc_fontset_key_get_context_key (const PangoFcFontsetKey *key)
 {
@@ -702,7 +693,7 @@ pango_fc_font_key_init (PangoFcFontKey    *key,
  * Returns: the pattern, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const FcPattern *
 pango_fc_font_key_get_pattern (const PangoFcFontKey *key)
 {
@@ -718,7 +709,7 @@ pango_fc_font_key_get_pattern (const PangoFcFontKey *key)
  * Returns: the matrix, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoMatrix *
 pango_fc_font_key_get_matrix (const PangoFcFontKey *key)
 {
@@ -734,7 +725,7 @@ pango_fc_font_key_get_matrix (const PangoFcFontKey *key)
  * Returns: the context key, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 gpointer
 pango_fc_font_key_get_context_key (const PangoFcFontKey *key)
 {
@@ -1483,21 +1474,22 @@ pango_fc_font_map_class_init (PangoFcFontMapClass *class)
 
 /**
  * pango_fc_font_map_add_decoder_find_func:
- * @fcfontmap: The #PangoFcFontMap to add this method to.
- * @findfunc: The #PangoFcDecoderFindFunc callback function
+ * @fcfontmap: The `PangoFcFontMap` to add this method to.
+ * @findfunc: The `PangoFcDecoderFindFunc` callback function
  * @user_data: User data.
- * @dnotify: A #GDestroyNotify callback that will be called when the
- *  fontmap is finalized and the decoder is released.
- *
- * This function saves a callback method in the #PangoFcFontMap that
- * will be called whenever new fonts are created.  If the
- * function returns a #PangoFcDecoder, that decoder will be used to
- * determine both coverage via a #FcCharSet and a one-to-one mapping of
- * characters to glyphs.  This will allow applications to have
+ * @dnotify: A `GDestroyNotify` callback that will be called when the
+ *   fontmap is finalized and the decoder is released.
+ *
+ * This function saves a callback method in the `PangoFcFontMap` that
+ * will be called whenever new fonts are created.
+ *
+ * If the function returns a `PangoFcDecoder`, that decoder will be used
+ * to determine both coverage via a `FcCharSet` and a one-to-one mapping
+ * of characters to glyphs. This will allow applications to have
  * application-specific encodings for various fonts.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
 					 PangoFcDecoderFindFunc findfunc,
@@ -1522,20 +1514,22 @@ pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
 
 /**
  * pango_fc_font_map_find_decoder:
- * @fcfontmap: The #PangoFcFontMap to use.
- * @pattern: The #FcPattern to find the decoder for.
+ * @fcfontmap: The `PangoFcFontMap` to use.
+ * @pattern: The `FcPattern` to find the decoder for.
  *
- * Finds the decoder to use for @pattern.  Decoders can be added to
- * a font map using pango_fc_font_map_add_decoder_find_func().
+ * Finds the decoder to use for @pattern.
  *
- * Returns: (transfer full) (nullable): a newly created #PangoFcDecoder
+ * Decoders can be added to a font map using
+ * [method@PangoFc.FontMap.add_decoder_find_func].
+ *
+ * Returns: (transfer full) (nullable): a newly created `PangoFcDecoder`
  *   object or %NULL if no decoder is set for @pattern.
  *
  * Since: 1.26
- **/
+ */
 PangoFcDecoder *
-pango_fc_font_map_find_decoder  (PangoFcFontMap *fcfontmap,
-				 FcPattern      *pattern)
+pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap,
+                                FcPattern      *pattern)
 {
   GSList *l;
 
@@ -2222,16 +2216,17 @@ pango_fc_font_map_load_fontset (PangoFontMap                 *fontmap,
 
 /**
  * pango_fc_font_map_cache_clear:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
- * Clear all cached information and fontsets for this font map;
- * this should be called whenever there is a change in the
+ * Clear all cached information and fontsets for this font map.
+ *
+ * This should be called whenever there is a change in the
  * output of the default_substitute() virtual function of the
  * font map, or if fontconfig has been reinitialized to new
  * configuration.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_fc_font_map_cache_clear (PangoFcFontMap *fcfontmap)
 {
@@ -2262,15 +2257,17 @@ pango_fc_font_map_changed (PangoFontMap *fontmap)
 
 /**
  * pango_fc_font_map_config_changed:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
+ *
+ * Informs font map that the fontconfig configuration (i.e., FcConfig
+ * object) used by this font map has changed.
  *
- * Informs font map that the fontconfig configuration (ie, FcConfig object)
- * used by this font map has changed.  This currently calls
- * pango_fc_font_map_cache_clear() which ensures that list of fonts, etc
- * will be regenerated using the updated configuration.
+ * This currently calls [method@PangoFc.FontMap.cache_clear] which
+ * ensures that list of fonts, etc will be regenerated using the
+ * updated configuration.
  *
  * Since: 1.38
- **/
+ */
 void
 pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
 {
@@ -2279,26 +2276,28 @@ pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
 
 /**
  * pango_fc_font_map_set_config: (skip)
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  * @fcconfig: (nullable): a `FcConfig`, or %NULL
  *
- * Set the FcConfig for this font map to use.  The default value
+ * Set the `FcConfig` for this font map to use.
+ *
+ * The default value
  * is %NULL, which causes Fontconfig to use its global "current config".
- * You can create a new FcConfig object and use this API to attach it
+ * You can create a new `FcConfig` object and use this API to attach it
  * to a font map.
  *
  * This is particularly useful for example, if you want to use application
- * fonts with Pango.  For that, you would create a fresh FcConfig, add your
+ * fonts with Pango. For that, you would create a fresh `FcConfig`, add your
  * app fonts to it, and attach it to a new Pango font map.
  *
  * If @fcconfig is different from the previous config attached to the font map,
- * pango_fc_font_map_config_changed() is called.
+ * [method@PangoFc.FontMap.config_changed] is called.
  *
- * This function acquires a reference to the FcConfig object; the caller
- * does NOT need to retain a reference.
+ * This function acquires a reference to the `FcConfig` object; the caller
+ * does **not** need to retain a reference.
  *
  * Since: 1.38
- **/
+ */
 void
 pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap,
                               FcConfig       *fcconfig)
@@ -2328,17 +2327,17 @@ pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap,
 
 /**
  * pango_fc_font_map_get_config: (skip)
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
  * Fetches the `FcConfig` attached to a font map.
  *
- * See also: pango_fc_font_map_set_config()
+ * See also: [method@PangoFc.FontMap.set_config].
  *
- * Returns: (nullable): the `FcConfig` object attached to @fcfontmap, which
- *          might be %NULL.
+ * Returns: (nullable): the `FcConfig` object attached to
+ *   @fcfontmap, which might be %NULL.
  *
  * Since: 1.38
- **/
+ */
 FcConfig *
 pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap)
 {
@@ -2502,13 +2501,14 @@ _pango_fc_font_map_get_coverage (PangoFcFontMap *fcfontmap,
 
 /**
  * _pango_fc_font_map_fc_to_coverage:
- * @charset: #FcCharSet to convert to a #PangoCoverage object.
+ * @charset: `FcCharSet` to convert to a `PangoCoverage` object.
  *
- * Convert the given #FcCharSet into a new #PangoCoverage object.  The
- * caller is responsible for freeing the newly created object.
+ * Convert the given `FcCharSet` into a new `PangoCoverage` object.
+ *
+ * The caller is responsible for freeing the newly created object.
  *
  * Since: 1.6
- **/
+ */
 PangoCoverage  *
 _pango_fc_font_map_fc_to_coverage (FcCharSet *charset)
 {
@@ -2571,22 +2571,24 @@ _pango_fc_font_map_get_languages (PangoFcFontMap *fcfontmap,
 
   return data->languages;
 }
+
 /**
  * pango_fc_font_map_create_context:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
+ *
+ * Creates a new context for this fontmap.
  *
- * Creates a new context for this fontmap. This function is intended
- * only for backend implementations deriving from #PangoFcFontMap;
- * it is possible that a backend will store additional information
- * needed for correct operation on the #PangoContext after calling
- * this function.
+ * This function is intended only for backend implementations deriving
+ * from `PangoFcFontMap`; it is possible that a backend will store
+ * additional information needed for correct operation on the `PangoContext`
+ * after calling this function.
  *
- * Return value: (transfer full): a new #PangoContext
+ * Return value: (transfer full): a new `PangoContext`
  *
  * Since: 1.4
  *
  * Deprecated: 1.22: Use pango_font_map_create_context() instead.
- **/
+ */
 PangoContext *
 pango_fc_font_map_create_context (PangoFcFontMap *fcfontmap)
 {
@@ -2608,17 +2610,20 @@ shutdown_font (gpointer        key,
 
 /**
  * pango_fc_font_map_shutdown:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
  * Clears all cached information for the fontmap and marks
- * all fonts open for the fontmap as dead. (See the shutdown()
- * virtual function of #PangoFcFont.) This function might be used
- * by a backend when the underlying windowing system for the font
- * map exits. This function is only intended to be called
- * only for backend implementations deriving from #PangoFcFontMap.
+ * all fonts open for the fontmap as dead.
+ *
+ * See the shutdown() virtual function of `PangoFcFont`.
+ *
+ * This function might be used by a backend when the underlying
+ * windowing system for the font map exits. This function is only
+ * intended to be called only for backend implementations deriving
+ * from `PangoFcFontMap`.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_fc_font_map_shutdown (PangoFcFontMap *fcfontmap)
 {
@@ -2704,21 +2709,23 @@ pango_fc_convert_width_to_pango (int fc_stretch)
 
 /**
  * pango_fc_font_description_from_pattern:
- * @pattern: a #FcPattern
+ * @pattern: a `FcPattern`
  * @include_size: if %TRUE, the pattern will include the size from
  *   the @pattern; otherwise the resulting pattern will be unsized.
  *   (only %FC_SIZE is examined, not %FC_PIXEL_SIZE)
  *
- * Creates a #PangoFontDescription that matches the specified
- * Fontconfig pattern as closely as possible. Many possible Fontconfig
- * pattern values, such as %FC_RASTERIZER or %FC_DPI, don't make sense in
- * the context of #PangoFontDescription, so will be ignored.
+ * Creates a `PangoFontDescription` that matches the specified
+ * Fontconfig pattern as closely as possible.
  *
- * Return value: a new #PangoFontDescription. Free with
- *  pango_font_description_free().
+ * Many possible Fontconfig pattern values, such as %FC_RASTERIZER
+ * or %FC_DPI, don't make sense in the context of `PangoFontDescription`,
+ * so will be ignored.
+ *
+ * Return value: a new `PangoFontDescription`. Free with
+ *   pango_font_description_free().
  *
  * Since: 1.4
- **/
+ */
 PangoFontDescription *
 pango_fc_font_description_from_pattern (FcPattern *pattern, gboolean include_size)
 {
@@ -3347,12 +3354,13 @@ pango_fc_family_init (PangoFcFamily *fcfamily)
 
 /**
  * pango_fc_font_map_get_hb_face: (skip)
- * @fcfontmap: a #PangoFcFontMap
- * @fcfont: a #PangoFcFont
+ * @fcfontmap: a `PangoFcFontMap`
+ * @fcfont: a `PangoFcFont`
  *
- * Retrieves the `hb_face_t` for the given #PangoFcFont.
+ * Retrieves the `hb_face_t` for the given `PangoFcFont`.
  *
- * Returns: (transfer none) (nullable): the `hb_face_t` for the given Pango font
+ * Returns: (transfer none) (nullable): the `hb_face_t`
+ *   for the given font
  *
  * Since: 1.44
  */
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 6fdf32d2..8ae9250e 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -69,10 +69,11 @@ pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap);
 
 /**
  * PangoFcDecoderFindFunc:
- * @pattern: a fully resolved #FcPattern specifying the font on the system
- * @user_data: user data passed to pango_fc_font_map_add_decoder_find_func()
+ * @pattern: a fully resolved `FcPattern` specifying the font on the system
+ * @user_data: user data passed to
+ *   [method@PangoFc.FontMap.add_decoder_find_func]
  *
- * Callback function passed to pango_fc_font_map_add_decoder_find_func().
+ * Callback function passed to [method@PangoFc.FontMap.add_decoder_find_func].
  *
  * Return value: a new reference to a custom decoder for this pattern,
  *  or %NULL if the default decoder handling should be used.
@@ -110,22 +111,24 @@ hb_face_t * pango_fc_font_map_get_hb_face (PangoFcFontMap *fcfontmap,
  * @pattern: the FcPattern to tweak.
  * @data: user data.
  *
- * Function type for doing final config tweaking on prepared FcPatterns.
+ * Function type for doing final config tweaking on prepared `FcPattern`s.
  */
 typedef void (*PangoFcSubstituteFunc) (FcPattern *pattern,
 				       gpointer   data);
 
 /**
  * pango_fc_font_map_set_default_substitute:
- * @fontmap: a #PangoFcFontMap
+ * @fontmap: a `PangoFcFontMap`
  * @func: function to call to to do final config tweaking
- *        on #FcPattern objects.
+ *        on `FcPattern` objects.
  * @data: data to pass to @func
  * @notify: function to call when @data is no longer used.
  *
  * Sets a function that will be called to do final configuration
- * substitution on a #FcPattern before it is used to load
- * the font. This function can be used to do things like set
+ * substitution on a `FcPattern` before it is used to load
+ * the font.
+ *
+ * This function can be used to do things like set
  * hinting and antialiasing options.
  *
  * Since: 1.48
@@ -138,11 +141,12 @@ void pango_fc_font_map_set_default_substitute (PangoFcFontMap        *fontmap,
 
 /**
  * pango_fc_font_map_substitute_changed:
- * @fontmap: a #PangoFcFontMap
+ * @fontmap: a `PangoFcFontMap`
+ *
+ * Call this function any time the results of the default
+ * substitution function set with
+ * [method@PangoFc.FontMap.set_default_substitute] change.
  *
- * Call this function any time the results of the
- * default substitution function set with
- * pango_fc_font_map_set_default_substitute() change.
  * That is, if your substitution function will return different
  * results for the same input pattern, you must call this function.
  *
@@ -154,13 +158,15 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_GRAVITY:
  *
- * String representing a fontconfig property name that Pango sets on any
- * fontconfig pattern it passes to fontconfig if a #PangoGravity other
- * than %PANGO_GRAVITY_SOUTH is desired.
+ * Fontconfig property that Pango sets on any
+ * fontconfig pattern it passes to fontconfig
+ * if a `PangoGravity` other than %PANGO_GRAVITY_SOUTH
+ * is desired.
  *
- * The property will have a #PangoGravity value as a string, like "east".
- * This can be used to write fontconfig configuration rules to choose
- * different fonts for horizontal and vertical writing directions.
+ * The property will have a `PangoGravity` value as a string,
+ * like "east". This can be used to write fontconfig configuration
+ * rules to choose different fonts for horizontal and vertical
+ * writing directions.
  *
  * Since: 1.20
  */
@@ -169,13 +175,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_VERSION:
  *
- * String representing a fontconfig property name that Pango sets on any
+ * Fontconfig property that Pango sets on any
  * fontconfig pattern it passes to fontconfig.
  *
  * The property will have an integer value equal to what
- * pango_version() returns.
- * This can be used to write fontconfig configuration rules that only affect
- * certain pango versions (or only pango-using applications, or only
+ * [func@Pango.version] returns. This can be used to write
+ * fontconfig configuration rules that only affect certain
+ * pango versions (or only pango-using applications, or only
  * non-pango-using applications).
  *
  * Since: 1.20
@@ -185,15 +191,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_PRGNAME:
  *
- * String representing a fontconfig property name that Pango sets on any
+ * Fontconfig property that Pango sets on any
  * fontconfig pattern it passes to fontconfig.
  *
  * The property will have a string equal to what
- * g_get_prgname() returns.
- * This can be used to write fontconfig configuration rules that only affect
+ * g_get_prgname() returns. This can be used to write
+ * fontconfig configuration rules that only affect
  * certain applications.
  *
- * This is equivalent to FC_PRGNAME in versions of fontconfig that have that.
+ * This is equivalent to FC_PRGNAME in versions of
+ * fontconfig that have that.
  *
  * Since: 1.24
  */
@@ -202,14 +209,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_FONT_FEATURES:
  *
- * String representing a fontconfig property name that Pango reads from font
- * patterns to populate list of OpenType features to be enabled for the font
- * by default.
+ * Fontconfig property that Pango reads from font
+ * patterns to populate list of OpenType features
+ * to be enabled for the font by default.
  *
- * The property will have a number of string elements, each of which is the
- * OpenType feature tag of one feature to enable.
+ * The property will have a number of string elements,
+ * each of which is the OpenType feature tag of one feature
+ * to enable.
  *
- * This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that.
+ * This is equivalent to FC_FONT_FEATURES in versions of
+ * fontconfig that have that.
  *
  * Since: 1.34
  */
@@ -218,11 +227,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_FONT_VARIATIONS:
  *
- * String representing a fontconfig property name that Pango reads from font
- * patterns to populate list of OpenType font variations to be used for a font.
+ * Fontconfig property that Pango reads from font
+ * patterns to populate list of OpenType font variations
+ * to be used for a font.
  *
- * The property will have a string elements, each of which a comma-separated
- * list of OpenType axis setting of the form AXIS=VALUE.
+ * The property will have a string elements, each of which
+ * a comma-separated list of OpenType axis setting of the
+ * form AXIS=VALUE.
  */
 #define PANGO_FC_FONT_VARIATIONS "fontvariations"
 
diff --git a/pango/pangoft2-fontmap.c b/pango/pangoft2-fontmap.c
index 4fb64616..ca09a2ad 100644
--- a/pango/pangoft2-fontmap.c
+++ b/pango/pangoft2-fontmap.c
@@ -40,7 +40,7 @@ typedef struct _PangoFT2FontMapClass PangoFT2FontMapClass;
 /**
  * PangoFT2FontMap:
  *
- * The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts.
+ * The `PangoFT2FontMap` is the `PangoFontMap` implementation for FreeType fonts.
  */
 struct _PangoFT2FontMap
 {
@@ -118,11 +118,12 @@ pango_ft2_font_map_finalize (GObject *object)
 /**
  * pango_ft2_font_map_new:
  *
- * Create a new #PangoFT2FontMap object; a fontmap is used
- * to cache information about available fonts, and holds
- * certain global parameters such as the resolution and
+ * Create a new `PangoFT2FontMap` object.
+ *
+ * A fontmap is used to cache information about available fonts,
+ * and holds certain global parameters such as the resolution and
  * the default substitute function (see
- * pango_ft2_font_map_set_default_substitute()).
+ * [method@PangoFT2.FontMap.set_default_substitute]).
  *
  * Return value: the newly created fontmap object. Unref
  * with g_object_unref() when you are finished with it.
@@ -155,18 +156,20 @@ pango_ft2_font_map_changed (PangoFontMap *fontmap)
 
 /**
  * pango_ft2_font_map_set_default_substitute:
- * @fontmap: a #PangoFT2FontMap
+ * @fontmap: a `PangoFT2FontMap`
  * @func: function to call to to do final config tweaking
  *        on #FcPattern objects.
  * @data: data to pass to @func
  * @notify: function to call when @data is no longer used.
  *
  * Sets a function that will be called to do final configuration
- * substitution on a #FcPattern before it is used to load
- * the font. This function can be used to do things like set
+ * substitution on a `FcPattern` before it is used to load
+ * the font.
+ *
+ * This function can be used to do things like set
  * hinting and antialiasing options.
  *
- * Deprecated: 1.46: Use pango_fc_font_map_set_default_substitute()
+ * Deprecated: 1.46: Use [method@PangoFc.FontMap.set_default_substitute]
  * instead.
  *
  * Since: 1.2
@@ -183,15 +186,16 @@ pango_ft2_font_map_set_default_substitute (PangoFT2FontMap        *fontmap,
 
 /**
  * pango_ft2_font_map_substitute_changed:
- * @fontmap: a #PangoFT2FontMap
+ * @fontmap: a `PangoFT2FontMap`
  *
  * Call this function any time the results of the
  * default substitution function set with
  * pango_ft2_font_map_set_default_substitute() change.
+ *
  * That is, if your substitution function will return different
  * results for the same input pattern, you must call this function.
  *
- * Deprecated: 1.46: Use pango_fc_font_map_substitute_changed()
+ * Deprecated: 1.46: Use [method@PangoFc.FontMap.substitute_changed]
  * instead.
  *
  * Since: 1.2
@@ -204,7 +208,7 @@ pango_ft2_font_map_substitute_changed (PangoFT2FontMap *fontmap)
 
 /**
  * pango_ft2_font_map_set_resolution:
- * @fontmap: a #PangoFT2FontMap
+ * @fontmap: a `PangoFT2FontMap`
  * @dpi_x: dots per inch in the X direction
  * @dpi_y: dots per inch in the Y direction
  *
@@ -227,16 +231,16 @@ pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap,
 
 /**
  * pango_ft2_font_map_create_context: (skip)
- * @fontmap: a #PangoFT2FontMap
+ * @fontmap: a `PangoFT2FontMap`
  *
- * Create a #PangoContext for the given fontmap.
+ * Create a `PangoContext` for the given fontmap.
  *
  * Return value: (transfer full): the newly created context; free with
  *     g_object_unref().
  *
  * Since: 1.2
  *
- * Deprecated: 1.22: Use pango_font_map_create_context() instead.
+ * Deprecated: 1.22: Use [method@Pango.FontMap.create_context] instead.
  **/
 PangoContext *
 pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap)
@@ -251,13 +255,13 @@ pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap)
  * @dpi_x:  the horizontal DPI of the target device
  * @dpi_y:  the vertical DPI of the target device
  *
- * Retrieves a #PangoContext for the default PangoFT2 fontmap
+ * Retrieves a `PangoContext` for the default PangoFT2 fontmap
  * (see pango_ft2_font_map_for_display()) and sets the resolution
  * for the default fontmap to @dpi_x by @dpi_y.
  *
- * Return value: (transfer full): the new #PangoContext
+ * Return value: (transfer full): the new `PangoContext`
  *
- * Deprecated: 1.22: Use pango_font_map_create_context() instead.
+ * Deprecated: 1.22: Use [method@Pango.FontMap.create_context] instead.
  **/
 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 PangoContext *
@@ -275,13 +279,15 @@ G_GNUC_END_IGNORE_DEPRECATIONS
 /**
  * pango_ft2_font_map_for_display: (skip)
  *
- * Returns a #PangoFT2FontMap. This font map is cached and should
+ * Returns a `PangoFT2FontMap`.
+ *
+ * This font map is cached and should
  * not be freed. If the font map is no longer needed, it can
  * be released with pango_ft2_shutdown_display(). Use of the
  * global PangoFT2 fontmap is deprecated; use pango_ft2_font_map_new()
  * instead.
  *
- * Return value: (transfer none): a #PangoFT2FontMap.
+ * Return value: (transfer none): a `PangoFT2FontMap`.
  **/
 PangoFontMap *
 pango_ft2_font_map_for_display (void)
@@ -322,7 +328,7 @@ _pango_ft2_font_map_get_library (PangoFontMap *fontmap)
 
 /**
  * _pango_ft2_font_map_get_renderer:
- * @fontmap: a #PangoFT2FontMap
+ * @fontmap: a `PangoFT2FontMap`
  *
  * Gets the singleton PangoFT2Renderer for this fontmap.
  *
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 6d299392..45230fdb 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -20,17 +20,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pango-renderer
- * @short_description:Rendering driver base class
- * @title:PangoRenderer
- *
- * #PangoRenderer is a base class that contains the necessary logic for
- * rendering a #PangoLayout or #PangoLayoutLine. By subclassing
- * #PangoRenderer and overriding operations such as @draw_glyphs and
- * @draw_rectangle, renderers for particular font backends and
- * destinations can be created.
- */
 #include "config.h"
 #include <math.h>
 
@@ -589,7 +578,7 @@ pango_ft2_renderer_draw_trapezoid (PangoRenderer   *renderer,
 
 /**
  * pango_ft2_render_layout_subpixel:
- * @bitmap:    a <type>FT_Bitmap</type> to render the layout onto
+ * @bitmap:    a FT_Bitmap to render the layout onto
  * @layout:    a #PangoLayout
  * @x:         the X position of the left of the layout (in Pango units)
  * @y:         the Y position of the top of the layout (in Pango units)
@@ -626,7 +615,7 @@ pango_ft2_render_layout_subpixel (FT_Bitmap   *bitmap,
 
 /**
  * pango_ft2_render_layout:
- * @bitmap:    a <type>FT_Bitmap</type> to render the layout onto
+ * @bitmap:    a FT_Bitmap to render the layout onto
  * @layout:    a #PangoLayout
  * @x:         the X position of the left of the layout (in pixels)
  * @y:         the Y position of the top of the layout (in pixels)
@@ -644,7 +633,7 @@ pango_ft2_render_layout (FT_Bitmap   *bitmap,
 
 /**
  * pango_ft2_render_layout_line_subpixel:
- * @bitmap:    a <type>FT_Bitmap</type> to render the line onto
+ * @bitmap:    a FT_Bitmap to render the line onto
  * @line:      a #PangoLayoutLine
  * @x:         the x position of start of string (in Pango units)
  * @y:         the y position of baseline (in Pango units)
@@ -681,7 +670,7 @@ pango_ft2_render_layout_line_subpixel (FT_Bitmap       *bitmap,
 
 /**
  * pango_ft2_render_layout_line:
- * @bitmap:    a <type>FT_Bitmap</type> to render the line onto
+ * @bitmap:    a FT_Bitmap to render the line onto
  * @line:      a #PangoLayoutLine
  * @x:         the x position of start of string (in pixels)
  * @y:         the y position of baseline (in pixels)
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index 2fe49171..efaf853d 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -20,14 +20,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:freetype-fonts
- * @short_description:Font handling and rendering with FreeType
- * @title:FreeType Fonts and Rendering
- *
- * The macros and functions in this section are used to access fonts and render
- * text to bitmaps using the FreeType 2 library.
- */
 #include "config.h"
 
 #include <string.h>
diff --git a/pango/pangoft2.h b/pango/pangoft2.h
index 96228316..239eb05e 100644
--- a/pango/pangoft2.h
+++ b/pango/pangoft2.h
@@ -62,7 +62,7 @@ typedef struct _PangoFT2FontMap      PangoFT2FontMap;
 
 /**
  * PangoFT2SubstituteFunc:
- * @pattern: the <type>FcPattern</type> to tweak.
+ * @pattern: the FcPattern to tweak.
  * @data: user data.
  *
  * Function type for doing final config tweaking on prepared FcPatterns.
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 6bc10a7a..f69ce1f9 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -816,7 +816,7 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class)
 /**
  * pango_win32_font_map_for_display:
  *
- * Returns a <type>PangoWin32FontMap</type>. Font maps are cached and should
+ * Returns a PangoWin32FontMap. Font maps are cached and should
  * not be freed. If the font map is no longer needed, it can
  * be released with pango_win32_shutdown_display().
  *
@@ -1800,7 +1800,7 @@ pango_win32_face_list_sizes (PangoFontFace  *face,
 
 /**
  * pango_win32_font_map_get_font_cache:
- * @font_map: a <type>PangoWin32FontMap</type>.
+ * @font_map: a PangoWin32FontMap
  *
  * Obtains the font cache associated with the given font map.
  *
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index 213a665e..0a90182f 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -22,14 +22,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:win32-fonts
- * @short_description:Font handling and rendering on Windows
- * @title:Win32 Fonts and Rendering
- *
- * The macros and functions in this section are used to access fonts natively on
- * Win32 systems and to render text in conjunction with Win32 APIs.
- */
 #include "config.h"
 
 #include <string.h>
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 38198bc0..ac4e6f39 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -19,36 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:xft-fonts
- * @short_description:Font handling and rendering with the Xft backend
- * @title:Xft Fonts and Rendering
- *
- * The Xft library is a library for displaying fonts on the X window
- * system; internally it uses the fontconfig library to locate font
- * files, and the FreeType library to load and render fonts. The
- * Xft backend is the recommended Pango font backend for screen
- * display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.)
- *
- * Using the Xft backend is generally straightforward;
- * pango_xft_get_context() creates a context for a specified display
- * and screen. You can then create a #PangoLayout with that context
- * and render it with pango_xft_render_layout(). At a more advanced
- * level, the low-level fontconfig options used for rendering fonts
- * can be affected using pango_xft_set_default_substitute(), and
- * pango_xft_substitute_changed().
- *
- * A range of functions for drawing pieces of a layout, such as
- * individual layout lines and glyphs strings are provided.  You can also
- * directly create a #PangoXftRenderer. Finally, in some advanced cases, it
- * is useful to derive from #PangoXftRenderer. Deriving from
- * #PangoXftRenderer is useful for two reasons. One reason is be to
- * support custom attributes by overriding #PangoRendererClass virtual
- * functions like 'prepare_run' or 'draw_shape'. The reason is to
- * customize exactly how the final bits are drawn to the destination by
- * overriding the #PangoXftRendererClass virtual functions
- * 'composite_glyphs' and 'composite_trapezoids'.
- */
 #include "config.h"
 
 #include <stdlib.h>
diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c
index 2e862dd5..a2584f3c 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -828,14 +828,14 @@ pango_xft_render_transformed (XftDraw          *draw,
 
 /**
  * pango_xft_render:
- * @draw:    the <type>XftDraw</type> object.
+ * @draw:    the XftDraw object.
  * @color:   the color in which to draw the string
  * @font:    the font in which to draw the string
  * @glyphs:  the glyph string to draw
  * @x:       the x position of start of string (in pixels)
  * @y:       the y position of baseline (in pixels)
  *
- * Renders a #PangoGlyphString onto an <type>XftDraw</type> object wrapping an X drawable.
+ * Renders a #PangoGlyphString onto an XftDraw object wrapping an X drawable.
  */
 void
 pango_xft_render (XftDraw          *draw,
@@ -864,7 +864,7 @@ pango_xft_render (XftDraw          *draw,
  * @x:            the x position of start of string (in pixels)
  * @y:            the y position of baseline (in pixels)
  *
- * Renders a #PangoGlyphString onto an Xrender <type>Picture</type> object.
+ * Renders a #PangoGlyphString onto an Xrender Picture object.
  */
 void
 pango_xft_picture_render (Display          *display,
diff --git a/pango/reorder-items.c b/pango/reorder-items.c
index 62a6a8f9..d00fee4c 100644
--- a/pango/reorder-items.c
+++ b/pango/reorder-items.c
@@ -31,11 +31,13 @@ static GList *reorder_items_recurse (GList *items, int n_items);
 
 /**
  * pango_reorder_items:
- * @logical_items: (element-type Pango.Item): a #GList of #PangoItem in logical order.
+ * @logical_items: (element-type Pango.Item): a `GList` of `PangoItem`
+ *   in logical order.
  *
- * From a list of items in logical order and the associated
- * directional levels, produce a list in visual order.
- * The original list is unmodified.
+ * Reorder items from logical order to visual order.
+ *
+ * The visual order is determined from the associated directional
+ * levels of the items. The original list is unmodified.
  *
  * Returns: (transfer full) (element-type Pango.Item): a #GList
  *          of #PangoItem structures in visual order.
diff --git a/pango/shape.c b/pango/shape.c
index 04624b00..1b2986c4 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -19,16 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:glyphs
- * @short_description:Structures for storing information about glyphs
- * @title:Glyphs
- *
- * pango_shape() produces a string of glyphs which
- * can be measured or drawn to the screen. The following
- * structures are used to store information about
- * glyphs.
- */
 #include "config.h"
 
 #include "pango-impl-utils.h"
@@ -40,23 +30,25 @@
 
 /**
  * pango_shape:
- * @text:      the text to process
- * @length:    the length (in bytes) of @text
- * @analysis:  #PangoAnalysis structure from pango_itemize()
- * @glyphs:    glyph string in which to store results
+ * @text: the text to process
+ * @length: the length (in bytes) of @text
+ * @analysis: `PangoAnalysis` structure from [func@itemize]
+ * @glyphs: glyph string in which to store results
  *
- * Given a segment of text and the corresponding #PangoAnalysis structure
- * returned from pango_itemize(), convert the characters into glyphs. You
- * may also pass in only a substring of the item from pango_itemize().
+ * Convert the characters in @text into glyphs.
  *
- * It is recommended that you use pango_shape_full() instead, since
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You
+ * may also pass in only a substring of the item from [func@itemize].
+ *
+ * It is recommended that you use [func@shape_full] instead, since
  * that API allows for shaping interaction happening across text item
  * boundaries.
  *
  * Note that the extra attributes in the @analyis that is returned from
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@itemize] have indices that are relative to the entire paragraph,
  * so you need to subtract the item offset from their indices before
- * calling pango_shape().
+ * calling [func@shape].
  */
 void
 pango_shape (const gchar         *text,
@@ -69,28 +61,29 @@ pango_shape (const gchar         *text,
 
 /**
  * pango_shape_full:
- * @item_text:        valid UTF-8 text to shape.
- * @item_length:      the length (in bytes) of @item_text. -1 means nul-terminated text.
+ * @item_text: valid UTF-8 text to shape.
+ * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text.
  * @paragraph_text: (allow-none): text of the paragraph (see details).  May be %NULL.
  * @paragraph_length: the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
- * @analysis:  #PangoAnalysis structure from pango_itemize().
- * @glyphs:    glyph string in which to store results.
+ * @analysis: `PangoAnalysis` structure from [func@itemize].
+ * @glyphs: glyph string in which to store results.
+ *
+ * Convert the characters in @text into glyphs.
  *
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You may
+ * also pass in only a substring of the item from [func@itemize].
  *
- * This is similar to pango_shape(), except it also can optionally take
+ * This is similar to [func@shape], except it also can optionally take
  * the full paragraph text as input, which will then be used to perform
- * certain cross-item shaping interactions.  If you have access to the broader
+ * certain cross-item shaping interactions. If you have access to the broader
  * text of which @item_text is part of, provide the broader text as
- * @paragraph_text.  If @paragraph_text is %NULL, item text is used instead.
+ * @paragraph_text. If @paragraph_text is %NULL, item text is used instead.
  *
  * Note that the extra attributes in the @analyis that is returned from
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@itemize] have indices that are relative to the entire paragraph,
  * so you do not pass the full paragraph text as @paragraph_text, you need
- * to subtract the item offset from their indices before calling pango_shape_full().
+ * to subtract the item offset from their indices before calling [func@shape_full].
  *
  * Since: 1.32
  */
@@ -167,23 +160,24 @@ fallback_shape (const char          *text,
  *     May be %NULL.
  * @paragraph_length: the length (in bytes) of @paragraph_text.
  *     -1 means nul-terminated text.
- * @analysis:  #PangoAnalysis structure from pango_itemize()
+ * @analysis:  `PangoAnalysis` structure from [func@itemize]
  * @glyphs: glyph string in which to store results
  * @flags: flags influencing the shaping process
  *
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Convert the characters in @text into glyphs.
+ *
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You may
+ * also pass in only a substring of the item from [func@itemize].
  *
- * This is similar to pango_shape_full(), except it also takes
- * flags that can influence the shaping process.
+ * This is similar to [func@shape_full], except it also takes flags that can
+ * influence the shaping process.
  *
  * Note that the extra attributes in the @analyis that is returned from
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@itemize] have indices that are relative to the entire paragraph,
  * so you do not pass the full paragraph text as @paragraph_text, you need
  * to subtract the item offset from their indices before calling
- * pango_shape_with_flags().
+ * [func@shape_with_flags].
  *
  * Since: 1.44
  */
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 00000000..e9c78c1e
--- /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