Merge branch 'misc-doc-fixups' into 'main'

docs: Various improvements

See merge request GNOME/pango!545

25 files changed, 224 insertions, 179 deletions

diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index b3ca2bc6..77b860a2 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-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",
@@ -72,6 +72,7 @@ content_images = [
   "pipeline-dark.png",
   "rects1.png",
   "rects2.png",
+  "rects3.png",
   "arabic-markup.png",
   "blue-text.png",
   "align-left.png",
@@ -103,3 +104,5 @@ content_images = [
   "baseline-shift-light.png",
   "baseline-shift-dark.png",
 ]
+
+urlmap_file = "urlmap.js"
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
index dcabad93..6a6cc3c2 100644
--- a/docs/pango_markup.md
+++ b/docs/pango_markup.md
@@ -98,7 +98,9 @@ weight
 
 font_variant
 variant
-: One of 'normal' or 'smallcaps'.
+: One of 'normal', 'small-caps', 'all-small-caps', 'petite-caps', 'all-petite-caps',
+  'unicase', 'title-caps'. Values other than 'normal' and 'small-caps' are available
+  since 1.50.
 
 font_stretch
 stretch
diff --git a/docs/pangocairo.toml.in b/docs/pangocairo.toml.in
index 2c552714..1e45744b 100644
--- a/docs/pangocairo.toml.in
+++ b/docs/pangocairo.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-2.1-or-later"
 description = "Cairo support for Pango"
 dependencies = [ "Pango-1.0", "cairo-1.0" ]
 devhelp = true
@@ -38,3 +38,5 @@ content_images = [
   "pango-name.png",
   "rotated-text.png"
 ]
+
+urlmap_file = "urlmap.js"
diff --git a/docs/pangofc.toml.in b/docs/pangofc.toml.in
index f78e7d0a..2eafa239 100644
--- a/docs/pangofc.toml.in
+++ b/docs/pangofc.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-2.1-or-later"
 description = "Fontconfig support for Pango"
 dependencies = [ "Pango-1.0", "fontconfig-2.0" ]
 devhelp = true
@@ -34,3 +34,6 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/main/"
 content_images = [
   "pango-name.png"
 ]
+
+urlmap_file = "urlmap.js"
+
diff --git a/docs/pangoft2.toml.in b/docs/pangoft2.toml.in
index ad6bdcd2..881d49fc 100644
--- a/docs/pangoft2.toml.in
+++ b/docs/pangoft2.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-2.1-or-later"
 description = "Freetype support for Pango"
 dependencies = [ "Pango-1.0", "freetype2-2.0" ]
 devhelp = true
@@ -34,3 +34,6 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/main/"
 content_images = [
   "pango-name.png"
 ]
+
+urlmap_file = "urlmap.js"
+
diff --git a/docs/pangoot.toml.in b/docs/pangoot.toml.in
index c319ca79..b2a23b19 100644
--- a/docs/pangoot.toml.in
+++ b/docs/pangoot.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-2.1-or-later"
 description = "OpenType support for Pango"
 dependencies = [ "Pango-1.0" ]
 devhelp = true
@@ -29,3 +29,5 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/main/"
 content_images = [
   "pango-name.png"
 ]
+
+urlmap_file = "urlmap.js"
diff --git a/docs/pangoxft.toml.in b/docs/pangoxft.toml.in
index 6b87476d..baf583e3 100644
--- a/docs/pangoxft.toml.in
+++ b/docs/pangoxft.toml.in
@@ -6,7 +6,7 @@ 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"
+license = "LGPL-2.1-or-later"
 description = "Xft support for Pango"
 dependencies = [ "Pango-1.0", "xft-2.0" ]
 devhelp = true
@@ -37,3 +37,5 @@ content_files = [
 content_images = [
   "pango-name.png"
 ]
+
+urlmap_file = "urlmap.js"
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 00000000..5d60b064
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+]
diff --git a/pango/break.c b/pango/break.c
index 5622ca21..9027d6d6 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -2168,8 +2168,8 @@ tailor_break (const char    *text,
  *
  * This is the default break algorithm.
  *
- * It applies Unicode rules without language-specific
- * tailoring, therefore the @analyis argument is unused
+ * It applies rules from the [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/)
+ * without language-specific tailoring, therefore the @analyis argument is unused
  * and can be %NULL.
  *
  * See [func@Pango.tailor_break] for language-specific breaks.
@@ -2203,11 +2203,10 @@ pango_default_break (const char    *text,
  * 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
- * [func@Pango.get_log_attrs].
+ * For most purposes you may want to use [func@Pango.get_log_attrs].
  *
  * Deprecated: 1.44: Use [func@Pango.default_break],
- *   [func@Pango.tailor_break] and func@Pango.attr_break].
+ *   [func@Pango.tailor_break] and [func@Pango.attr_break].
  */
 void
 pango_break (const char    *text,
@@ -2236,15 +2235,13 @@ pango_break (const char    *text,
  *
  * Apply language-specific tailoring to the breaks in @attrs.
  *
- * The line breaks are assumed to have been produced
- * by [func@Pango.default_break].
+ * The line breaks are assumed to have been produced by [func@Pango.default_break].
  *
- * If @offset is not -1, it is used to apply attributes
- * from @analysis that are relevant to line breaking.
+ * If @offset is not -1, it is used to apply attributes from @analysis that are
+ * relevant to line breaking.
  *
- * Note that it is better to pass -1 for @offset and
- * use [func@Pango.attr_break] to apply attributes to
- * the whole paragraph.
+ * Note that it is better to pass -1 for @offset and use [func@Pango.attr_break]
+ * to apply attributes to the whole paragraph.
  *
  * Since: 1.44
  */
diff --git a/pango/fonts.c b/pango/fonts.c
index 129e84d3..fd4dba21 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -562,7 +562,8 @@ pango_font_description_set_variations_static (PangoFontDescription *desc,
  * and values are clamped to their allowed range.
  *
  * Pango does not currently have a way to find supported axes of
- * a font. Both harfbuzz or freetype have API for this.
+ * a font. Both harfbuzz and freetype have API for this. See
+ * for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot-var.html#hb-ot-var-get-axis-infos).
  *
  * Since: 1.42
  */
@@ -1627,7 +1628,8 @@ pango_parse_style (const char *str,
  *
  * Parses a font variant.
  *
- * The allowed values are "normal" and "smallcaps" or "small_caps",
+ * The allowed values are "normal", "small-caps", "all-small-caps",
+ * "petite-caps", "all-petite-caps", "unicase" and "title-caps",
  * case variations being ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
@@ -2016,7 +2018,7 @@ pango_font_get_face (PangoFont *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().
+ * use [hb_font_create_sub_font()](https://harfbuzz.github.io/harfbuzz-hb-font.html#hb-font-create-sub-font).
  *
  * Returns: (transfer none) (nullable): the `hb_font_t` object
  *   backing the font
@@ -2088,6 +2090,7 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
  * @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.
  */
 void
@@ -2508,6 +2511,9 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
  * A variable font is a font which has axes that can be modified to
  * produce different faces.
  *
+ * Such axes are also known as _variations_; see
+ * [method@Pango.FontDescription.set_variations] for more information.
+ *
  * Return value: %TRUE if the family is variable
  *
  * Since: 1.44
@@ -2540,8 +2546,10 @@ pango_font_face_init (PangoFontFace *face G_GNUC_UNUSED)
  * pango_font_face_describe:
  * @face: a `PangoFontFace`
  *
- * Returns the family, style, variant, weight and stretch of
- * a `PangoFontFace`. The size field of the resulting font description
+ * Returns a font description that matches the face.
+ *
+ * The resulting font description will have the family, style,
+ * variant, weight and stretch of the face, but its size field
  * will be unset.
  *
  * Return value: a newly-created `PangoFontDescription` structure
@@ -2560,11 +2568,13 @@ pango_font_face_describe (PangoFontFace *face)
  * pango_font_face_is_synthesized:
  * @face: a `PangoFontFace`
  *
- * Returns whether a `PangoFontFace` is synthesized by the underlying
- * font rendering engine from another face, perhaps by shearing, emboldening,
- * or lightening it.
+ * Returns whether a `PangoFontFace` is synthesized.
  *
- * Return value: whether @face is synthesized.
+ * This will be the case if the underlying font rendering engine
+ * creates this face from another face, by shearing, emboldening,
+ * lightening or modifying it in some other way.
+ *
+ * Return value: whether @face is synthesized
  *
  * Since: 1.18
  */
@@ -2583,9 +2593,11 @@ pango_font_face_is_synthesized (PangoFontFace  *face)
  * pango_font_face_get_face_name:
  * @face: a `PangoFontFace`.
  *
- * Gets a name representing the style of this face among the
- * different faces in the `PangoFontFamily` for the face. The
- * name is suitable for displaying to users.
+ * Gets a name representing the style of this face.
+ *
+ * The name identifies the face among the different faces
+ * in the `PangoFontFamily` for the face. It 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.
diff --git a/pango/itemize.c b/pango/itemize.c
index 77e86507..1d71b5c6 100644
--- a/pango/itemize.c
+++ b/pango/itemize.c
@@ -1575,12 +1575,12 @@ pango_itemize_post_process_items (PangoContext *context,
  * Like `pango_itemize()`, but with an explicitly specified base direction.
  *
  * 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`.
+ * [func@itemize] gets the base direction from the `PangoContext`
+ * (see [method@Pango.Context.set_base_dir]).
  *
  * 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().
+ *   [method@Pango.Item.free] probably in combination with [func@GLib.List.free_full].
  *
  * Since: 1.4
  */
@@ -1634,7 +1634,7 @@ pango_itemize_with_base_dir (PangoContext      *context,
  *
  * 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().
+ *   [method@Pango.Item.free] in combination with [func@GLib.List.free_full].
  */
 GList *
 pango_itemize (PangoContext      *context,
@@ -1654,6 +1654,6 @@ pango_itemize (PangoContext      *context,
                                       attrs, cached_iter);
 }
 
- /* }}} */ 
+/* }}} */
 
 /* vim:set foldmethod=marker expandtab: */
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index f1bd5635..a324d7f2 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -253,7 +253,7 @@ typedef enum {
  * @PANGO_FONT_SCALE_NONE: Leave the font size unchanged
  * @PANGO_FONT_SCALE_SUPERSCRIPT: Change the font to a size suitable for superscripts
  * @PANGO_FONT_SCALE_SUBSCRIPT: Change the font to a size suitable for subscripts
- * @PANGO_FONT_SCALE_SMALL_CAPS: Change the font to a size suitable for Small Caps. Since: 1.50
+ * @PANGO_FONT_SCALE_SMALL_CAPS: Change the font to a size suitable for Small Caps
  *
  * An enumeration that affects font sizes for superscript
  * and subscript positioning and for (emulated) Small Caps.
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index 40123a60..f854a1b8 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -96,16 +96,14 @@ pango_bidi_type_for_unichar (gunichar ch)
  *
  * 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/
+ * The bidirectional embedding levels are defined by the [Unicode Bidirectional
+ * Algorithm](http://www.unicode.org/reports/tr9/).
  *
  * If the input base direction is a weak direction, the direction of the
  * 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 [func@GLib.free].
  *
  * Since: 1.4
  */
@@ -248,13 +246,13 @@ resolved:
  *
  * Determines the inherent direction of a character.
  *
- * The inherent direction is either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL,
- * or %PANGO_DIRECTION_NEUTRAL.
+ * 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,
- * [func@Pango.BidiType.for_unichar] can be used instead.
+ * bidirectional type of a character is needed, [func@Pango.BidiType.for_unichar]
+ * can be used instead.
  *
  * Return value: the direction of the character.
  */
@@ -288,8 +286,8 @@ pango_unichar_direction (gunichar ch)
  * Return value: %TRUE if @ch has a mirrored character and @mirrored_ch is
  * filled in, %FALSE otherwise
  *
- * Deprecated: 1.30: Use g_unichar_get_mirror_char() instead; the docs for that function
- * provide full details.
+ * Deprecated: 1.30: Use [func@GLib.unichar_get_mirror_char] instead;
+ *   the docs for that function provide full details.
  */
 gboolean
 pango_get_mirror_char (gunichar  ch,
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index 331cd1dc..35041521 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -238,7 +238,7 @@ pango_coverage_to_bytes (PangoCoverage  *coverage,
  *   representing a `PangoCoverage`
  * @n_bytes: the size of @bytes in bytes
  *
- * Convert data generated from pango_coverage_to_bytes()
+ * Convert data generated from [method@Pango.Coverage.to_bytes]
  * back to a `PangoCoverage`.
  *
  * Return value: (transfer full) (nullable): a newly allocated `PangoCoverage`
diff --git a/pango/pango-direction.h b/pango/pango-direction.h
index 7da14175..24d3c50e 100644
--- a/pango/pango-direction.h
+++ b/pango/pango-direction.h
@@ -31,9 +31,9 @@ G_BEGIN_DECLS
  * @PANGO_DIRECTION_LTR: A strong left-to-right direction
  * @PANGO_DIRECTION_RTL: A strong right-to-left direction
  * @PANGO_DIRECTION_TTB_LTR: Deprecated value; treated the
- *   same as %PANGO_DIRECTION_RTL.
+ *   same as `PANGO_DIRECTION_RTL`.
  * @PANGO_DIRECTION_TTB_RTL: Deprecated value; treated the
- *   same as %PANGO_DIRECTION_LTR
+ *   same as `PANGO_DIRECTION_LTR`
  * @PANGO_DIRECTION_WEAK_LTR: A weak left-to-right direction
  * @PANGO_DIRECTION_WEAK_RTL: A weak right-to-left direction
  * @PANGO_DIRECTION_NEUTRAL: No direction specified
@@ -43,14 +43,14 @@ G_BEGIN_DECLS
  *
  * 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
+ * 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
+ * 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
+ * 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
diff --git a/pango/pango-font.h b/pango/pango-font.h
index f4e619a1..de638c4d 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -84,23 +84,21 @@ typedef enum {
  *   replaced by smaller variants of the capital characters.
  * @PANGO_VARIANT_ALL_SMALL_CAPS: A font with all characters
  *   replaced by smaller variants of the capital characters.
- *   Since: 1.50
  * @PANGO_VARIANT_PETITE_CAPS: A font with the lower case characters
  *   replaced by smaller variants of the capital characters.
  *   Petite Caps can be even smaller than Small Caps.
- *   Since: 1.50
  * @PANGO_VARIANT_ALL_PETITE_CAPS: A font with all characters
  *   replaced by smaller variants of the capital characters.
  *   Petite Caps can be even smaller than Small Caps.
- *   Since: 1.50
  * @PANGO_VARIANT_UNICASE: A font with the upper case characters
  *   replaced by smaller variants of the capital letters.
- *   Since: 1.50
  * @PANGO_VARIANT_TITLE_CAPS: A font with capital letters that
  *   are more suitable for all-uppercase titles.
- *   Since: 1.50
  *
  * An enumeration specifying capitalization variant of the font.
+ *
+ * Values other than `PANGO_VARIANT_NORMAL` and `PANGO_VARIANT_SMALL_CAPS` are
+ * available since 1.50.
  */
 typedef enum {
   PANGO_VARIANT_NORMAL,
@@ -114,23 +112,23 @@ typedef enum {
 
 /**
  * PangoWeight:
- * @PANGO_WEIGHT_THIN: the thin weight (= 100; Since: 1.24)
+ * @PANGO_WEIGHT_THIN: the thin weight (= 100) Since: 1.24
  * @PANGO_WEIGHT_ULTRALIGHT: the ultralight weight (= 200)
  * @PANGO_WEIGHT_LIGHT: the light weight (= 300)
- * @PANGO_WEIGHT_SEMILIGHT: the semilight weight (= 350; Since: 1.36.7)
- * @PANGO_WEIGHT_BOOK: the book weight (= 380; Since: 1.24)
+ * @PANGO_WEIGHT_SEMILIGHT: the semilight weight (= 350) Since: 1.36.7
+ * @PANGO_WEIGHT_BOOK: the book weight (= 380) Since: 1.24)
  * @PANGO_WEIGHT_NORMAL: the default weight (= 400)
- * @PANGO_WEIGHT_MEDIUM: the normal weight (= 500; Since: 1.24)
+ * @PANGO_WEIGHT_MEDIUM: the normal weight (= 500) Since: 1.24
  * @PANGO_WEIGHT_SEMIBOLD: the semibold weight (= 600)
  * @PANGO_WEIGHT_BOLD: the bold weight (= 700)
  * @PANGO_WEIGHT_ULTRABOLD: the ultrabold weight (= 800)
  * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
- * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24)
+ * @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.
+ * Weight is specified as a numeric value ranging from 100 to 1000.
+ * This enumeration simply provides some common, predefined values.
  */
 typedef enum {
   PANGO_WEIGHT_THIN = 100,
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 82ee47c6..788cf3cd 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -40,12 +40,14 @@ typedef struct _PangoGlyphString PangoGlyphString;
  * The `PangoGlyphUnit` type is used to store dimensions within
  * Pango.
  *
- * Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * 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
+ * a point on a printer.) PANGO_SCALE is currently 1024, and
  * may change in the future (unlikely though), but you should not
- * depend on its exact value. The PANGO_PIXELS() macro can be used
- * to convert from glyph units into device units with correct rounding.
+ * depend on its exact value.
+ *
+ * The PANGO_PIXELS() macro can be used to convert from glyph units
+ * into device units with correct rounding.
  */
 typedef gint32 PangoGlyphUnit;
 
@@ -68,10 +70,10 @@ typedef gint32 PangoGlyphUnit;
  * The information in this struct is intended for rendering the glyphs,
  * as follows:
  *
- * 1. Render the current glyph at (x + x_offset, y + y_offset),
- *    where (x, y) is the current point
- * 2. Advance the current point to (x + xoffset, y)
- * 3. Render the next glyph...
+ * 1. Assume the current point is (x, y)
+ * 2. Render the current glyph at (x + x_offset, y + y_offset),
+ * 3. Advance the current point to (x + width, y)
+ * 4. Render the next glyph
  */
 struct _PangoGlyphGeometry
 {
@@ -85,10 +87,6 @@ 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_color: set if the the font will render this glyph with color. Since 1.50
  *
  * A `PangoGlyphVisAttr` structure communicates information between
@@ -96,6 +94,11 @@ struct _PangoGlyphGeometry
  *
  * Currently, it contains cluster start and color information.
  * More attributes may be added in the future.
+ *
+ * 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.
  */
 struct _PangoGlyphVisAttr
 {
@@ -123,11 +126,10 @@ struct _PangoGlyphInfo
 
 /**
  * PangoGlyphString:
- * @num_glyphs: number of the glyphs in this glyph string.
+ * @num_glyphs: number of glyphs in this glyph string
  * @glyphs: (array length=num_glyphs): array of glyph information
- *   for the glyph string.
  * @log_clusters: logical cluster info, indexed by the byte index
- *   within the text corresponding to the glyph string.
+ *   within the text corresponding to the glyph string
  *
  * A `PangoGlyphString` is used to store strings of glyphs with geometry
  * and visual attribute information.
@@ -215,11 +217,9 @@ void                    pango_glyph_string_index_to_x_full      (PangoGlyphStrin
 
 /**
  * PangoShapeFlags:
- * @PANGO_SHAPE_NONE: Default value.
- * @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions
- *   and widths to whole device units. This option should
- *   be set if the target renderer can't do subpixel
- *   positioning of glyphs.
+ * @PANGO_SHAPE_NONE: Default value
+ * @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions and widths to whole device units
+ *   This option should be set if the target renderer can't do subpixel positioning of glyphs
  *
  * Flags influencing the shaping process.
  *
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index abc45ca6..12fc76cd 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -53,10 +53,10 @@ typedef PangoGlyphItem PangoLayoutRun;
  * within the available space.
  *
  * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify],
- * this only has effect for partial lines.
+ * this only affects partial lines.
  *
  * See [method@Pango.Layout.set_auto_dir] for how text direction affects
- * the interpretation of `PangoAlignment values.
+ * the interpretation of `PangoAlignment` values.
  */
 typedef enum {
   PANGO_ALIGN_LEFT,
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index 791e71fd..9a3bde55 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -601,7 +601,7 @@ pango_markup_parser_new_internal (char       accel_marker,
 
 /**
  * pango_parse_markup:
- * @markup_text: markup to parse (see the Pango Markup docs)
+ * @markup_text: markup to parse (see the [Pango Markup](pango_markup.html) 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) (optional): address of return location for a `PangoAttrList`
@@ -696,17 +696,17 @@ pango_parse_markup (const char                 *markup_text,
  * 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 feed markup to the parser, use [method@GLib.MarkupParseContext.parse]
+ * on the returned [struct@GLib.MarkupParseContext]. 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.
+ * of it, and then use [method@GLib.MarkupParseContext.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 [func@parse_markup] API is recommended instead.
+ * the [func@Pango.parse_markup] API is recommended instead.
  *
  * Return value: (transfer none): a `GMarkupParseContext` that should be
- * destroyed with g_markup_parse_context_free().
+ * destroyed with [method@GLib.MarkupParseContext.free].
  *
  * Since: 1.31.0
  **/
@@ -726,9 +726,9 @@ pango_markup_parser_new (gunichar accel_marker)
  *
  * Finishes parsing markup.
  *
- * After feeding a Pango markup parser some data with g_markup_parse_context_parse(),
+ * After feeding a Pango markup parser some data with [method@GLib.MarkupParseContext.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()
+ * markup. This function will not free @context, use [method@GLib.MarkupParseContext.free]
  * to do so.
  *
  * Return value: %FALSE if @error is set, otherwise %TRUE
diff --git a/pango/pango-script.c b/pango/pango-script.c
index fc7c6332..71c519fd 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -66,13 +66,15 @@
  *
  * Looks up the script for a particular character.
  *
- * The script of a character is defined by Unicode Standard Annex \#24.
+ * The script of a character is defined by
+ * [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/).
+ *
  * 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
- * the return value of g_unichar_get_script(). Callers must be
+ * the return value of [func@GLib.unichar_get_script]. Callers must be
  * prepared to handle unknown values.
  *
  * Return value: the `PangoScript` for the character.
@@ -120,7 +122,7 @@ _pango_script_iter_init (PangoScriptIter *iter,
 /**
  * pango_script_iter_new:
  * @text: a UTF-8 string
- * @length: length of @text, or -1 if @text is nul-terminated.
+ * @length: length of @text, or -1 if @text is nul-terminated
  *
  * Create a new `PangoScriptIter`, used to break a string of
  * Unicode text into runs by Unicode script.
@@ -177,12 +179,13 @@ pango_script_iter_free (PangoScriptIter *iter)
  * @script: (out) (optional): location to store script for range
  *
  * Gets information about the range to which @iter currently points.
+ *
  * The range is the set of locations p where *start <= p < *end.
  * (That is, it doesn't include the character stored at *end)
  *
  * Note that while the type of the @script argument is declared
  * as `PangoScript`, as of Pango 1.18, this function simply returns
- * GUnicodeScript values. Callers must be prepared to handle unknown
+ * `GUnicodeScript` values. Callers must be prepared to handle unknown
  * values.
  *
  * Since: 1.4
diff --git a/pango/pango-script.h b/pango/pango-script.h
index c1579982..e453301d 100644
--- a/pango/pango-script.h
+++ b/pango/pango-script.h
@@ -40,71 +40,71 @@ typedef struct _PangoScriptIter PangoScriptIter;
  * @PANGO_SCRIPT_COMMON: a character used by multiple different scripts
  * @PANGO_SCRIPT_INHERITED: a mark glyph that takes its script from the
  * base glyph to which it is attached
- * @PANGO_SCRIPT_ARABIC: 	Arabic
+ * @PANGO_SCRIPT_ARABIC:        Arabic
  * @PANGO_SCRIPT_ARMENIAN: Armenian
- * @PANGO_SCRIPT_BENGALI: 	Bengali
+ * @PANGO_SCRIPT_BENGALI:       Bengali
  * @PANGO_SCRIPT_BOPOMOFO: Bopomofo
- * @PANGO_SCRIPT_CHEROKEE: 	Cherokee
- * @PANGO_SCRIPT_COPTIC: 	Coptic
- * @PANGO_SCRIPT_CYRILLIC: 	Cyrillic
- * @PANGO_SCRIPT_DESERET: 	Deseret
- * @PANGO_SCRIPT_DEVANAGARI: 	Devanagari
- * @PANGO_SCRIPT_ETHIOPIC: 	Ethiopic
- * @PANGO_SCRIPT_GEORGIAN: 	Georgian
- * @PANGO_SCRIPT_GOTHIC: 	Gothic
- * @PANGO_SCRIPT_GREEK: 	Greek
- * @PANGO_SCRIPT_GUJARATI: 	Gujarati
- * @PANGO_SCRIPT_GURMUKHI: 	Gurmukhi
- * @PANGO_SCRIPT_HAN: 	Han
- * @PANGO_SCRIPT_HANGUL: 	Hangul
- * @PANGO_SCRIPT_HEBREW: 	Hebrew
- * @PANGO_SCRIPT_HIRAGANA: 	Hiragana
- * @PANGO_SCRIPT_KANNADA: 	Kannada
- * @PANGO_SCRIPT_KATAKANA: 	Katakana
- * @PANGO_SCRIPT_KHMER: 	Khmer
- * @PANGO_SCRIPT_LAO: 	Lao
- * @PANGO_SCRIPT_LATIN: 	Latin
- * @PANGO_SCRIPT_MALAYALAM: 	Malayalam
- * @PANGO_SCRIPT_MONGOLIAN: 	Mongolian
- * @PANGO_SCRIPT_MYANMAR: 	Myanmar
- * @PANGO_SCRIPT_OGHAM: 	Ogham
- * @PANGO_SCRIPT_OLD_ITALIC: 	Old Italic
- * @PANGO_SCRIPT_ORIYA: 	Oriya
- * @PANGO_SCRIPT_RUNIC: 	Runic
- * @PANGO_SCRIPT_SINHALA: 	Sinhala
- * @PANGO_SCRIPT_SYRIAC: 	Syriac
- * @PANGO_SCRIPT_TAMIL: 	Tamil
- * @PANGO_SCRIPT_TELUGU: 	Telugu
- * @PANGO_SCRIPT_THAANA: 	Thaana
- * @PANGO_SCRIPT_THAI: 	Thai
- * @PANGO_SCRIPT_TIBETAN: 	Tibetan
- * @PANGO_SCRIPT_CANADIAN_ABORIGINAL: 	Canadian Aboriginal
- * @PANGO_SCRIPT_YI: 	Yi
- * @PANGO_SCRIPT_TAGALOG: 	Tagalog
- * @PANGO_SCRIPT_HANUNOO: 	Hanunoo
- * @PANGO_SCRIPT_BUHID: 	Buhid
- * @PANGO_SCRIPT_TAGBANWA: 	Tagbanwa
- * @PANGO_SCRIPT_BRAILLE: 	Braille
- * @PANGO_SCRIPT_CYPRIOT: 	Cypriot
- * @PANGO_SCRIPT_LIMBU: 	Limbu
- * @PANGO_SCRIPT_OSMANYA: 	Osmanya
- * @PANGO_SCRIPT_SHAVIAN: 	Shavian
- * @PANGO_SCRIPT_LINEAR_B: 	Linear B
- * @PANGO_SCRIPT_TAI_LE: 	Tai Le
- * @PANGO_SCRIPT_UGARITIC: 	Ugaritic
- * @PANGO_SCRIPT_NEW_TAI_LUE: 	New Tai Lue. Since 1.10
- * @PANGO_SCRIPT_BUGINESE: 	Buginese. Since 1.10
- * @PANGO_SCRIPT_GLAGOLITIC: 	Glagolitic. Since 1.10
- * @PANGO_SCRIPT_TIFINAGH: 	Tifinagh. Since 1.10
- * @PANGO_SCRIPT_SYLOTI_NAGRI: 	Syloti Nagri. Since 1.10
- * @PANGO_SCRIPT_OLD_PERSIAN: 	Old Persian. Since 1.10
- * @PANGO_SCRIPT_KHAROSHTHI: 	Kharoshthi. Since 1.10
- * @PANGO_SCRIPT_UNKNOWN: 		an unassigned code point. Since 1.14
- * @PANGO_SCRIPT_BALINESE: 		Balinese. Since 1.14
- * @PANGO_SCRIPT_CUNEIFORM: 	Cuneiform. Since 1.14
- * @PANGO_SCRIPT_PHOENICIAN: 	Phoenician. Since 1.14
- * @PANGO_SCRIPT_PHAGS_PA: 		Phags-pa. Since 1.14
- * @PANGO_SCRIPT_NKO: 		N'Ko. Since 1.14
+ * @PANGO_SCRIPT_CHEROKEE:      Cherokee
+ * @PANGO_SCRIPT_COPTIC:        Coptic
+ * @PANGO_SCRIPT_CYRILLIC:      Cyrillic
+ * @PANGO_SCRIPT_DESERET:       Deseret
+ * @PANGO_SCRIPT_DEVANAGARI:    Devanagari
+ * @PANGO_SCRIPT_ETHIOPIC:      Ethiopic
+ * @PANGO_SCRIPT_GEORGIAN:      Georgian
+ * @PANGO_SCRIPT_GOTHIC:        Gothic
+ * @PANGO_SCRIPT_GREEK:         Greek
+ * @PANGO_SCRIPT_GUJARATI:      Gujarati
+ * @PANGO_SCRIPT_GURMUKHI:      Gurmukhi
+ * @PANGO_SCRIPT_HAN:   Han
+ * @PANGO_SCRIPT_HANGUL:        Hangul
+ * @PANGO_SCRIPT_HEBREW:        Hebrew
+ * @PANGO_SCRIPT_HIRAGANA:      Hiragana
+ * @PANGO_SCRIPT_KANNADA:       Kannada
+ * @PANGO_SCRIPT_KATAKANA:      Katakana
+ * @PANGO_SCRIPT_KHMER:         Khmer
+ * @PANGO_SCRIPT_LAO:   Lao
+ * @PANGO_SCRIPT_LATIN:         Latin
+ * @PANGO_SCRIPT_MALAYALAM:     Malayalam
+ * @PANGO_SCRIPT_MONGOLIAN:     Mongolian
+ * @PANGO_SCRIPT_MYANMAR:       Myanmar
+ * @PANGO_SCRIPT_OGHAM:         Ogham
+ * @PANGO_SCRIPT_OLD_ITALIC:    Old Italic
+ * @PANGO_SCRIPT_ORIYA:         Oriya
+ * @PANGO_SCRIPT_RUNIC:         Runic
+ * @PANGO_SCRIPT_SINHALA:       Sinhala
+ * @PANGO_SCRIPT_SYRIAC:        Syriac
+ * @PANGO_SCRIPT_TAMIL:         Tamil
+ * @PANGO_SCRIPT_TELUGU:        Telugu
+ * @PANGO_SCRIPT_THAANA:        Thaana
+ * @PANGO_SCRIPT_THAI:  Thai
+ * @PANGO_SCRIPT_TIBETAN:       Tibetan
+ * @PANGO_SCRIPT_CANADIAN_ABORIGINAL:   Canadian Aboriginal
+ * @PANGO_SCRIPT_YI:    Yi
+ * @PANGO_SCRIPT_TAGALOG:       Tagalog
+ * @PANGO_SCRIPT_HANUNOO:       Hanunoo
+ * @PANGO_SCRIPT_BUHID:         Buhid
+ * @PANGO_SCRIPT_TAGBANWA:      Tagbanwa
+ * @PANGO_SCRIPT_BRAILLE:       Braille
+ * @PANGO_SCRIPT_CYPRIOT:       Cypriot
+ * @PANGO_SCRIPT_LIMBU:         Limbu
+ * @PANGO_SCRIPT_OSMANYA:       Osmanya
+ * @PANGO_SCRIPT_SHAVIAN:       Shavian
+ * @PANGO_SCRIPT_LINEAR_B:      Linear B
+ * @PANGO_SCRIPT_TAI_LE:        Tai Le
+ * @PANGO_SCRIPT_UGARITIC:      Ugaritic
+ * @PANGO_SCRIPT_NEW_TAI_LUE:   New Tai Lue. Since 1.10
+ * @PANGO_SCRIPT_BUGINESE:      Buginese. Since 1.10
+ * @PANGO_SCRIPT_GLAGOLITIC:    Glagolitic. Since 1.10
+ * @PANGO_SCRIPT_TIFINAGH:      Tifinagh. Since 1.10
+ * @PANGO_SCRIPT_SYLOTI_NAGRI:  Syloti Nagri. Since 1.10
+ * @PANGO_SCRIPT_OLD_PERSIAN:   Old Persian. Since 1.10
+ * @PANGO_SCRIPT_KHAROSHTHI:    Kharoshthi. Since 1.10
+ * @PANGO_SCRIPT_UNKNOWN:               an unassigned code point. Since 1.14
+ * @PANGO_SCRIPT_BALINESE:              Balinese. Since 1.14
+ * @PANGO_SCRIPT_CUNEIFORM:     Cuneiform. Since 1.14
+ * @PANGO_SCRIPT_PHOENICIAN:    Phoenician. Since 1.14
+ * @PANGO_SCRIPT_PHAGS_PA:              Phags-pa. Since 1.14
+ * @PANGO_SCRIPT_NKO:           N'Ko. Since 1.14
  * @PANGO_SCRIPT_KAYAH_LI:   Kayah Li. Since 1.20.1
  * @PANGO_SCRIPT_LEPCHA:     Lepcha. Since 1.20.1
  * @PANGO_SCRIPT_REJANG:     Rejang. Since 1.20.1
@@ -162,9 +162,9 @@ typedef struct _PangoScriptIter PangoScriptIter;
  * 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,
+ * 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
+ * [enum@GLib.UnicodeScript] enumeration instead,
  * whose values are interchangeable with `PangoScript`.
  */
 typedef enum {                         /* ISO 15924 code */
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 947b7e9b..bc8a7cb4 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -549,9 +549,11 @@ success:
  * @tab_index: the index of a tab stop
  * @decimal_point: the decimal point to use
  *
- * Sets the decimal point to use.
+ * Sets the Unicode character to use as decimal point.
  *
- * This is only relevant for %PANGO_TAB_DECIMAL.
+ * This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment,
+ * which align content at the first occurrence of the decimal point
+ * character.
  *
  * By default, Pango uses the decimal point according
  * to the current locale.
@@ -577,9 +579,11 @@ pango_tab_array_set_decimal_point (PangoTabArray *tab_array,
  * @tab_array: a `PangoTabArray`
  * @tab_index: the index of a tab stop
  *
- * Gets the decimal point to use.
+ * Gets the Unicode character to use as decimal point.
  *
- * This is only relevant for %PANGO_TAB_DECIMAL.
+ * This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment,
+ * which align content at the first occurrence of the decimal point
+ * character.
  *
  * The default value of 0 means that Pango will use the
  * decimal point according to the current locale.
diff --git a/pango/pango-tabs.h b/pango/pango-tabs.h
index a804977b..40837ba0 100644
--- a/pango/pango-tabs.h
+++ b/pango/pango-tabs.h
@@ -35,9 +35,9 @@ typedef struct _PangoTabArray PangoTabArray;
  *   until the available space is filled
  * @PANGO_TAB_CENTER: the text is centered at the tab stop position
  *   until the available space is filled
- * @PANGO_TAB_DECIMAL: text before the first '.' appears to the left of the
- *   tab stop position (until the available space is filled), the rest to
- *   the right
+ * @PANGO_TAB_DECIMAL: text before the first occurrence of the decimal point
+ *   character appears to the left of the tab stop position (until the available
+ *   space is filled), the rest to the right
  *
  * `PangoTabAlign` specifies where the text appears relative to the tab stop
  * position.
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 412f417a..886e3d1d 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -897,8 +897,9 @@ pango_find_base_dir (const gchar *text,
  * 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.
+ * as well as *bidi* formatting characters, and a few other ones.
+ *
+ * This is totally different from [func@GLib.unichar_iszerowidth] and is at best misnamed.
  *
  * Return value: %TRUE if @ch is a zero-width character, %FALSE otherwise
  *
diff --git a/pango/serializer.c b/pango/serializer.c
index a41ef28c..4780a633 100644
--- a/pango/serializer.c
+++ b/pango/serializer.c
@@ -1621,8 +1621,10 @@ pango_layout_serialize (PangoLayout               *layout,
  * @filename: (type filename): the file to save it to
  * @error: Return location for a potential error
  *
- * This function is equivalent to calling [method@Pango.Layout.serialize]
- * followed by g_file_set_contents().
+ * A convenience method to serialize a layout to a file.
+ *
+ * It is equivalent to calling [method@Pango.Layout.serialize]
+ * followed by [func@GLib.file_set_contents].
  *
  * See those two functions for details on the arguments.
  *
@@ -1732,6 +1734,8 @@ pango_layout_deserialize (PangoContext                 *context,
  * The intended use of this function is testing, benchmarking and debugging.
  * The format is not meant as a permanent storage format.
  *
+ * To recreate a font from its serialized form, use [func@Pango.Font.deserialize].
+ *
  * Returns: a `GBytes` containing the serialized form of @font
  *
  * Since: 1.50