Documentation improvements

20 files changed, 166 insertions, 132 deletions

diff --git a/NEWS b/NEWS
index 2e554c9f..38a512a9 100644
--- a/NEWS
+++ b/NEWS
@@ -110,6 +110,12 @@ Other API changes
 
 - Most structs have been made private
 
+- Support for trimming the leading of the first and last line in
+  a layout
+
+- Face-ids have been introduced to guarantee lossless
+  font - description - font roundtrips
+
 - Many smaller API cleanups and reductions
 
 
diff --git a/docs/meson.build b/docs/meson.build
index ee58c26a..52ab55c3 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -72,7 +72,7 @@ pango_toml = configure_file(input: 'pango.toml.in',
 
 custom_target('pango-doc',
   input: pango_gir[0],
-  output: 'Pango',
+  output: 'Pango2',
   command: [
     gidocgen,
     'generate',
diff --git a/docs/migrating.md b/docs/migrating.md
index 222adf7e..c7b897d0 100644
--- a/docs/migrating.md
+++ b/docs/migrating.md
@@ -3,16 +3,16 @@ Title: Migrating from Pango 1.x to Pango 2
 ---
 
 Pango 2 is a major new version of Pango that breaks both API and ABI
-compared to Pango 1.x. Thankfully, most of the changes are not hard
-to adapt to.
+compared to Pango 1.x. Therefore, some porting is required when switching
+an application from Pango 1 to Pango 2. Thankfully, most of the changes
+are not hard to adapt to.
 
 ## Preparation in Pango 1.x
 
-The steps outlined in the following sections assume that your
-application is working with a recent version of Pango 1.x, such
-as Pango 1.50. If you are using an older version of Pango, you
-should first get your application to build and work with
-Pango 1.50.
+The steps outlined in the following sections assume that your application
+is working with a recent version of Pango 1.x, such as Pango 1.50. If you
+are using an older version of Pango, you should first get your application
+to build and work with Pango 1.50.
 
 ### Do not use deprecated symbols
 
@@ -51,11 +51,11 @@ the `pangocairo.h` header, and use the APIs that are declared in it.
 There is still a `pangocairo2.pc` file, if you want to be explicit in your
 build configuration about requiring cairo support. If you want to handle
 the possible absence of cairo support at runtime, you can check the
-`PANGO_CAIRO_RENDERING` macro before including `pangocairo.h`.
+[const@Pango.RENDERING_CAIRO] macro before including `pangocairo.h`.
 
 ### PangoFontMap changes
 
-The `PangoFontMap` class has seen some significant changes. It is now possible
+The [class@Pango.FontMap] class has seen some significant changes. It is now possible
 to instantiate a `PangoFontMap`, and populate it manually with `PangoFontFamily`
 and `PangoFontFace` objects. If you simply want to obtain the default fontmap
 that is populated with the native font enumeration APIs, use
@@ -70,7 +70,7 @@ APIs to obtain a suitable fontmap, or set the resolution.
 
 ### Font-related API changes
 
-Some APIs have moved between [class@Pango.Font], [class@Pango.FontFace]
+Some APIs have been moved between [class@Pango.Font], [class@Pango.FontFace]
 and [class@Pango.FontFamily] or renamed.
 
 | Old API | New API |
@@ -101,7 +101,7 @@ and have getters. APIs for creating items have been dropped.
 ### PangoLayout changes
 
 Most APIs that provide information about the formatted output have been
-moved from `PangoLayout` to the new objects [class@Pango.Lines] and
+moved from [class@Pango.Layout] to the new objects [class@Pango.Lines] and
 [struct@Pango.LineIter]. To obtain these from a `PangoLayout`, use
 [method@Pango.Layout.get_lines] and [method@Pango.Layout.get_iter].
 
@@ -134,19 +134,21 @@ The `PangoGlyphItem/PangoLayoutRun` struct has been replaced by a new
 
 ### PangoAttribute changes
 
-`PangoAttribute` is no longer defined with different structs, but is
-an opaque type with getters for the different types of value. To set
-the range of an attribute use [method@Pango.Attribute.set_range]. To
-define your own attribute types, use [func@Pango.AttrType.register].
+[struct@Pango.Attribute] is no longer defined with different structs,
+but is an opaque type with getters for the different types of value.
+To set the range of an attribute use [method@Pango.Attribute.set_range].
+To define your own attribute types, use [func@Pango.AttrType.register].
 
 Some of the existing attribute types have seen changes as well. All the
-color-related attributes now take a [struct@PangoColor] argument in their
-constructor. The line-related attributes have been reorganized. There is now
-a [enum@Pango.LineStyle] enumeration that can be applied to underlines,
-overlines and strikethroughs, and a separate [enum@Pango.UnderlinePosition]
-enumeration. Alpha attributes have been removed, since [struct@Pango.Color]
+color-related attributes now take a [struct@Pango.Color] argument in their
+constructor. Alpha attributes have been removed, since [struct@Pango.Color]
 now contains an alpha field.
 
+The line-related attributes have been reorganized. There is now a
+[enum@Pango.LineStyle] enumeration that can be applied to underlines,
+overlines and strikethroughs, and a separate [enum@Pango.UnderlinePosition]
+enumeration.
+
 ### Markup changes
 
 The attributes 'alpha', 'fgalpha', 'background_alpha' and 'bgalpha' have
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index b1cf26ea..7503e1ec 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -1,23 +1,22 @@
 [library]
 namespace = "Pango"
 version = "@PANGO_VERSION@"
-browse_url = "https://gitlab.gnome.org/GNOME/pango/"
+browse_url = "https://gitlab.gnome.org/GNOME/pango2/"
 repository_url = "https://gitlab.gnome.org/GNOME/pango.git"
 website_url = "https://www.pango.org"
 authors = "Owen Taylor, Behdad Esfahbod, Matthias Clasen"
 logo_url = "pango-name.png"
 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",
-                 "PangoXft-1.0" ]
+dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "Fribidi-0.0",
+                "Cairo-0.0", "Gio-2.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"
+  docs_url = "https://docs.gtk.org/gobject/"
 
   [dependencies."HarfBuzz-0.0"]
   name = "HarfBuzz"
@@ -34,6 +33,11 @@ search_index = true
   description = "A 2D graphics library"
   docs_url = "https://www.cairographics.org/documentation/"
 
+  [dependencies."Gio-2.0"]
+  name = "GIO"
+  description = "Useful classes for general purpose I/O, networking, IPC, etc."
+  docs_url = "https://docs.gtk.org/gio/"
+
 [theme]
 name = "basic"
 show_index_summary = true
diff --git a/docs/urlmap.js b/docs/urlmap.js
index 5d60b064..deae96b9 100644
--- a/docs/urlmap.js
+++ b/docs/urlmap.js
@@ -6,6 +6,4 @@ 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/pango-attr.c b/pango/pango-attr.c
index 8f6f5980..4f4d8fdf 100644
--- a/pango/pango-attr.c
+++ b/pango/pango-attr.c
@@ -26,6 +26,19 @@
 #include "pango-attributes-private.h"
 #include "pango-impl-utils.h"
 
+/**
+ * PangoAttribute:
+ *
+ * A `PangoAttribute` structure associates a named attribute with
+ * a certain range of a text.
+ *
+ * Attributes can have basic types, such as int, float, boolean
+ * `PangoColor`, `PangoFontDescription or `PangoLanguage`. It is
+ * also possible to define new, custom attributes.
+ *
+ * By default, an attribute will have an all-inclusive range of
+ * `[0,G_MAXUINT]`.
+ */
 
 /* {{{ Generic attribute code */
 
diff --git a/pango/pango-attr.h b/pango/pango-attr.h
index abb57130..0617c4cf 100644
--- a/pango/pango-attr.h
+++ b/pango/pango-attr.h
@@ -30,20 +30,20 @@ typedef struct _PangoAttribute PangoAttribute;
 
 /**
  * PangoAttrValueType:
- * @PANGO_ATTR_VALUE_STRING: a string
- * @PANGO_ATTR_VALUE_INT: an integer
- * @PANGO_ATTR_VALUE_BOOLEAN: a boolean
- * @PANGO_ATTR_VALUE_FLOAT: a floating point number
- * @PANGO_ATTR_VALUE_COLOR: a `PangoColor`
- * @PANGO_ATTR_VALUE_LANGUAGE: a `PangoLanguage`
- * @PANGO_ATTR_VALUE_FONT_DESC: a `PangoFontDescription`
- * @PANGO_ATTR_VALUE_POINTER: a generic pointer
- *
- * The `PangoAttrValueType` enumeration describes the various types
- * of values that a `PangoAttribute` can contain.
- *
- * The `PangoAttrValueType` of a `PangoAttribute` is part of its type,
- * and can be obtained with `PANGO_ATTR_VALUE_TYPE()`.
+ * @PANGO_ATTR_VALUE_STRING: A string
+ * @PANGO_ATTR_VALUE_INT: An integer
+ * @PANGO_ATTR_VALUE_BOOLEAN: A boolean
+ * @PANGO_ATTR_VALUE_FLOAT: A floating point number
+ * @PANGO_ATTR_VALUE_COLOR: A `PangoColor`
+ * @PANGO_ATTR_VALUE_LANGUAGE: A `PangoLanguage`
+ * @PANGO_ATTR_VALUE_FONT_DESC: A `PangoFontDescription`
+ * @PANGO_ATTR_VALUE_POINTER: A generic pointer
+ *
+ * `PangoAttrValueType` enumerates the types of values
+ * that a `PangoAttribute` can contain.
+ *
+ * The `PangoAttrValueType` of a `PangoAttribute` is part
+ * of its type, and can be obtained with `PANGO_ATTR_VALUE_TYPE()`.
  */
 typedef enum
 {
@@ -59,14 +59,14 @@ typedef enum
 
 /**
  * PangoAttrAffects:
- * @PANGO_ATTR_AFFECTS_NONE: the attribute does not affect rendering
- * @PANGO_ATTR_AFFECTS_ITEMIZATION: the attribute affecs itemization
- * @PANGO_ATTR_AFFECTS_BREAKING: the attribute affects `PangoLogAttr` determination
- * @PANGO_ATTR_AFFECTS_SHAPING: the attribute affects shaping
- * @PANGO_ATTR_AFFECTS_RENDERING: the attribute affects rendering
+ * @PANGO_ATTR_AFFECTS_NONE: The attribute does not affect rendering
+ * @PANGO_ATTR_AFFECTS_ITEMIZATION: The attribute affecs itemization
+ * @PANGO_ATTR_AFFECTS_BREAKING: The attribute affects `PangoLogAttr` determination
+ * @PANGO_ATTR_AFFECTS_SHAPING: The attribute affects shaping
+ * @PANGO_ATTR_AFFECTS_RENDERING: The attribute affects rendering
  *
- * Flags to indicate what part of Pangos processing pipeline is
- * affected by an attribute.
+ * A `PangoAttrAffects` value indicates what part of Pango's processing
+ * pipeline is affected by an attribute.
  *
  * Marking an attribute with `PANGO_ATTR_AFFECTS_ITEMIZATION` ensures
  * that the attribute values are constant across items.
@@ -82,11 +82,11 @@ typedef enum
 
 /**
  * PangoAttrMerge:
- * @PANGO_ATTR_MERGE_OVERRIDES: only the attribute with the narrowest range is used
- * @PANGO_ATTR_MERGE_ACCUMULATES: all attributes with overlapping range are kept
+ * @PANGO_ATTR_MERGE_OVERRIDES: Only the attribute with the narrowest range is used
+ * @PANGO_ATTR_MERGE_ACCUMULATES: All attributes with overlapping range are kept
  *
- * Options to indicate how overlapping attribute values should be
- * reconciled to determine the effective attribute value.
+ * A `PangoAttrMerge` value indicates how overlapping attribute values
+ * should be reconciled to determine the effective attribute value.
  *
  * These options influence the @extra_attrs returned by
  * [method@Pango.AttrIterator.get_font].
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index ffb3d07f..e97db134 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -69,10 +69,11 @@ G_BEGIN_DECLS
  * @PANGO_ATTR_PARAGRAPH: mark the range of the attribute as a single paragraph
  * @PANGO_ATTR_BASELINE_SHIFT: baseline displacement
  * @PANGO_ATTR_FONT_SCALE: font-relative size change
- * @PANGO_ATTR_LINE_SPACING: extra space to add to the leading from the
- *   font metrics (if not overridden by line height attribute)
+ * @PANGO_ATTR_LINE_SPACING: space to add to the leading from the
+ *   font metrics (if not overridden by a line height attribute)
+ * @PANGO_ATTR_SHAPE: override glyph shapes (requires renderer support)
  *
- * The `PangoAttrType` enumeration contains predefined types for attributes.
+ * `PangoAttrType` contains predefined attribute types.
  *
  * Along with the predefined values, it is possible to allocate additional
  * values for custom attributes using [func@AttrType.register]. The predefined
@@ -148,15 +149,14 @@ PangoAttribute *        pango_attr_font_desc_new                (const PangoFont
 
 /**
  * PangoLineStyle:
- * @PANGO_LINE_STYLE_NONE: no line should be drawn
- * @PANGO_LINE_STYLE_SOLID: a single line should be drawn
- * @PANGO_LINE_STYLE_DOUBLE: a double line should be drawn
- * @PANGO_LINE_STYLE_DASHED: an dashed line should be drawn
- * @PANGO_LINE_STYLE_DOTTED: an dotted line should be drawn
- * @PANGO_LINE_STYLE_WAVY: an wavy line should be drawn
+ * @PANGO_LINE_STYLE_NONE: No visible line
+ * @PANGO_LINE_STYLE_SOLID: A single line
+ * @PANGO_LINE_STYLE_DOUBLE: A double line
+ * @PANGO_LINE_STYLE_DASHED: A dashed line
+ * @PANGO_LINE_STYLE_DOTTED: A dotted line
+ * @PANGO_LINE_STYLE_WAVY: A wavy line
  *
- * The `PangoLineStyle` enumeration is used to specify how
- * lines should be drawn.
+ * `PangoLineStyle specifies how lines should be drawn.
  */
 typedef enum {
   PANGO_LINE_STYLE_NONE,
@@ -173,6 +173,13 @@ PangoAttribute *        pango_attr_underline_new                (PangoLineStyle
 PANGO_AVAILABLE_IN_ALL
 PangoAttribute *        pango_attr_underline_color_new          (PangoColor                 *color);
 
+/**
+ * PangoUnderlinePosition:
+ * @PANGO_UNDERLINE_POSITION_NORMAL: As specified by font metrics
+ * @PANGO_UNDERLINE_POSITION_UNDER: Below the ink extents of the run
+ *
+ * `PangoUnderlinePosition` specifies where underlines should be drawn.
+ */
 typedef enum {
   PANGO_UNDERLINE_POSITION_NORMAL,
   PANGO_UNDERLINE_POSITION_UNDER
@@ -196,7 +203,7 @@ PangoAttribute *        pango_attr_rise_new                     (int
  * @PANGO_BASELINE_SHIFT_SUBSCRIPT: Shift the baseline to the subscript position,
  *   relative to the previous run
  *
- * An enumeration that affects baseline shifts between runs.
+ * `PangoBaselineShift` influences how baselines are changed between runs.
  */
 typedef enum {
   PANGO_BASELINE_SHIFT_NONE,
@@ -214,8 +221,7 @@ PangoAttribute *        pango_attr_baseline_shift_new           (int
  * @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
  *
- * An enumeration that affects font sizes for superscript
- * and subscript positioning and for (emulated) Small Caps.
+ * `PangoFontScale` influences the font size of a run.
  */
 typedef enum {
   PANGO_FONT_SCALE_NONE,
@@ -262,7 +268,7 @@ PangoAttribute *        pango_attr_overline_color_new           (PangoColor
  * @PANGO_SHOW_IGNORABLES: Render default-ignorable Unicode
  *   characters visibly
  *
- * These flags affect how Pango treats characters that are normally
+ * `PangoShowFlags` affect how Pango treats characters that are normally
  * not visible in the output.
  */
 typedef enum {
@@ -281,7 +287,7 @@ PangoAttribute *        pango_attr_line_height_new_absolute     (int
 PANGO_AVAILABLE_IN_ALL
 PangoAttribute *        pango_attr_line_spacing_new             (int                          spacing);
 
-/*
+/**
  * PangoTextTransform:
  * @PANGO_TEXT_TRANSFORM_NONE: Leave text unchanged
  * @PANGO_TEXT_TRANSFORM_LOWERCASE: Display letters and numbers as lowercase
@@ -289,7 +295,8 @@ PangoAttribute *        pango_attr_line_spacing_new             (int
  * @PANGO_TEXT_TRANSFORM_CAPITALIZE: Display the first character of a word
  *   in titlecase
  *
- * An enumeration that affects how Pango treats characters during shaping.
+ * `PangoTextTransform` determines if Pango changes the case of characters
+ * during shaping.
   */
 typedef enum {
   PANGO_TEXT_TRANSFORM_NONE,
diff --git a/pango/pango-context.c b/pango/pango-context.c
index 6503e857..2c926690 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -234,7 +234,7 @@ pango_context_class_init (PangoContextClass *klass)
   /**
    * PangoContext:font-description: (attributes org.gtk.Property.get=pango_context_get_font_description org.gtk.Property.set=pango_context_set_font_description)
    *
-   * The default font descriptoin for the context.
+   * The default font description for the context.
    */
   properties[PROP_FONT_DESCRIPTION] =
     g_param_spec_boxed ("font-description", NULL, NULL, PANGO_TYPE_FONT_DESCRIPTION,
@@ -303,7 +303,7 @@ pango_context_class_init (PangoContextClass *klass)
    *
    * The transformation is needed in cases where the font rendering applies
    * hinting that depends on knowing the position of text with respect to
-   * the pixel grid. If your font rendering does not
+   * the pixel grid.
    */
   properties[PROP_MATRIX] =
     g_param_spec_boxed ("matrix", NULL, NULL, PANGO_TYPE_MATRIX,
diff --git a/pango/pango-font-description.h b/pango/pango-font-description.h
index 7cad766c..6643131c 100644
--- a/pango/pango-font-description.h
+++ b/pango/pango-font-description.h
@@ -96,7 +96,7 @@ typedef enum {
  * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
  * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000)
  *
- * An enumeration specifying the weight (boldness) of a font.
+ * A `PangoWeight` specifes the weight (boldness) of a font.
  *
  * Weight is specified as a numeric value ranging from 100 to 1000.
  * This enumeration simply provides some common, predefined values.
@@ -118,18 +118,18 @@ typedef enum {
 
 /**
  * PangoStretch:
- * @PANGO_STRETCH_ULTRA_CONDENSED: ultra condensed width
- * @PANGO_STRETCH_EXTRA_CONDENSED: extra condensed width
- * @PANGO_STRETCH_CONDENSED: condensed width
- * @PANGO_STRETCH_SEMI_CONDENSED: semi condensed width
- * @PANGO_STRETCH_NORMAL: the normal width
- * @PANGO_STRETCH_SEMI_EXPANDED: semi expanded width
- * @PANGO_STRETCH_EXPANDED: expanded width
- * @PANGO_STRETCH_EXTRA_EXPANDED: extra expanded width
- * @PANGO_STRETCH_ULTRA_EXPANDED: ultra expanded width
+ * @PANGO_STRETCH_ULTRA_CONDENSED: ultra-condensed width (= 500)
+ * @PANGO_STRETCH_EXTRA_CONDENSED: extra-condensed width (= 625)
+ * @PANGO_STRETCH_CONDENSED: condensed width (= 750)
+ * @PANGO_STRETCH_SEMI_CONDENSED: semi-condensed width (= 875)
+ * @PANGO_STRETCH_NORMAL: the normal width (= 1000)
+ * @PANGO_STRETCH_SEMI_EXPANDED: semi-expanded width (= 1125)
+ * @PANGO_STRETCH_EXPANDED: expanded width (= 1250)
+ * @PANGO_STRETCH_EXTRA_EXPANDED: extra-expanded width (= 1500)
+ * @PANGO_STRETCH_ULTRA_EXPANDED: ultra-expanded width (= 2000)
  *
- * An enumeration specifying the width of the font relative to other designs
- * within a family.
+ * A `PangoStretch` specifes the width of the font relative
+ * to other designs within a family.
  *
  * Stretch is specified as a numeric value ranging from 500 to 2000.
  * This enumeration simply provides some common, predefined values.
diff --git a/pango/pango-font-face.c b/pango/pango-font-face.c
index 73c41997..36232694 100644
--- a/pango/pango-font-face.c
+++ b/pango/pango-font-face.c
@@ -223,7 +223,7 @@ pango_font_face_class_init (PangoFontFaceClass *class)
   /**
    * PangoFontFace:family: (attributes org.gtk.Property.get=pango_font_face_get_family)
    *
-   * The `PangoFontFamily` that @face belongs to.
+   * The `PangoFontFamily` that the face belongs to.
    */
   properties[PROP_FAMILY] =
       g_param_spec_object ("family", NULL, NULL,
@@ -412,7 +412,7 @@ pango_font_face_get_name (PangoFontFace *face)
  * pango_font_face_get_family:
  * @face: a `PangoFontFace`
  *
- * Gets the `PangoFontFamily` that @face belongs to.
+ * Gets the `PangoFontFamily` that the face belongs to.
  *
  * Returns: (transfer none): the `PangoFontFamily`
  */
@@ -428,6 +428,8 @@ pango_font_face_get_family (PangoFontFace *face)
  * pango_font_face_is_monospace:
  * @face: a `PangoFontFace`
  *
+ * Returns whether this font face is monospace.
+ *
  * A monospace font is a font designed for text display where the the
  * characters form a regular grid.
  *
@@ -457,6 +459,8 @@ pango_font_face_is_monospace (PangoFontFace *face)
  * pango_font_face_is_variable:
  * @face: a `PangoFontFace`
  *
+ * Returns whether this font face is variable.
+ *
  * A variable font is a font which has axes that can be modified
  * to produce variations.
  *
@@ -478,7 +482,8 @@ pango_font_face_is_variable (PangoFontFace *face)
  * @face: a `PangoFontFace`
  * @language: a `PangoLanguage`
  *
- * Returns whether @face has all the glyphs necessary to write @language.
+ * Returns whether the face has all the glyphs necessary to
+ * support this language.
  *
  * Returns: `TRUE` if @face supports @language
  */
@@ -495,11 +500,11 @@ pango_font_face_supports_language (PangoFontFace *face,
  * pango_font_face_get_languages:
  * @face: a `PangoFontFace`
  *
- * Returns the languages that are supported by @face.
+ * Returns the languages that are supported by the face.
  *
  * If the font backend does not provide this information,
- * %NULL is returned. For the fontconfig backend, this
- * corresponds to the FC_LANG member of the FcPattern.
+ * `NULL` is returned. For the fontconfig backend, this
+ * corresponds to the `FC_LANG` member of the `FcPattern`.
  *
  * The returned array is only valid as long as the face
  * and its fontmap are valid.
diff --git a/pango/pango-font-family.c b/pango/pango-font-family.c
index 789992d8..5c0de724 100644
--- a/pango/pango-font-family.c
+++ b/pango/pango-font-family.c
@@ -242,14 +242,14 @@ pango_font_family_get_name (PangoFontFamily *family)
 /**
  * pango_font_family_get_face:
  * @family: a `PangoFontFamily`
- * @name: (nullable): the name of a face. If the name is %NULL,
+ * @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 the family with the given name.
  *
  * Returns: (transfer none) (nullable): the `PangoFontFace`,
- *   or %NULL if no face with the given name exists.
+ *   or `NULL` if no face with the given name exists.
  */
 PangoFontFace *
 pango_font_family_get_face (PangoFontFamily *family,
diff --git a/pango/pango-font.c b/pango/pango-font.c
index 9552b786..d8f081ad 100644
--- a/pango/pango-font.c
+++ b/pango/pango-font.c
@@ -386,7 +386,7 @@ pango_font_get_metrics (PangoFont     *font,
  * pango_font_get_face:
  * @font: a `PangoFont`
  *
- * Gets the `PangoFontFace` to which @font belongs.
+ * Gets the `PangoFontFace` to which the font belongs.
  *
  * Returns: (transfer none): the `PangoFontFace`
  */
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index 5f42be64..b76a0ded 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -799,10 +799,11 @@ pango_font_map_changed (PangoFontMap *self)
  * @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.
+ * Load the font in the fontmap that is the closest match for
+ * a font description.
  *
- * Returns: (transfer full) (nullable): the `PangoFont` that was found,
- *   or %NULL if no font matched
+ * Returns: (transfer full) (nullable): the `PangoFont` that
+ *   was found
  */
 PangoFont *
 pango_font_map_load_font (PangoFontMap               *self,
@@ -825,10 +826,10 @@ pango_font_map_load_font (PangoFontMap               *self,
  *    or `NULL` to use the language of @context
  *
  * Load a set of fonts in the fontmap that can be used to render
- * a font matching @desc.
+ * a font matching a font description.
  *
  * Returns: (transfer full) (nullable): the `PangoFontset` containing
- *   the fonts that were found, or %NULL if no font matched
+ *   the fonts that were found
  */
 PangoFontset *
 pango_font_map_load_fontset (PangoFontMap               *self,
@@ -847,7 +848,7 @@ pango_font_map_load_fontset (PangoFontMap               *self,
  * pango_font_map_get_serial:
  * @self: a `PangoFontMap`
  *
- * Returns the current serial number of @self.
+ * Returns the current serial number of the 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
@@ -909,7 +910,7 @@ pango_font_map_new (void)
  * @self: a `PangoFontMap`
  * @face: (transfer full): a `PangoFontFace`
  *
- * Adds @face to the `PangoFontMap`.
+ * Adds a face to the fontmap.
  *
  * This is most useful for creating transformed faces or aliases.
  * See [method@Pango.HbFace.new_synthetic] and [method@Pango.HbFace.new_instance].
@@ -953,7 +954,7 @@ pango_font_map_add_face (PangoFontMap  *self,
  * @self: a `PangoFontMap`
  * @face: a `PangoFontFace` that belongs to @map
  *
- * Removes @face from the `PangoFontMap`.
+ * Removes @face from the fontmap.
  *
  * @face must have been added with [method@Pango.FontMap.add_face].
  */
@@ -1009,7 +1010,7 @@ pango_font_map_add_file (PangoFontMap *self,
  * @self: a `PangoFontMap`
  * @family: (transfer full): a `PangoFontFamily`
  *
- * Adds @family to @self.
+ * Adds a family to the `PangoFontMap`.
  *
  * The fontmap must not contain a family with the
  * same name as @family yet.
@@ -1061,7 +1062,7 @@ pango_font_map_add_family (PangoFontMap    *self,
  * @self: a `PangoFontMap`
  * @family: a `PangoFontFamily` that belongs to @self
  *
- * Removes @family from a `PangoFontMap`
+ * Removes a family from the fontmap.
  */
 void
 pango_font_map_remove_family (PangoFontMap    *self,
@@ -1121,7 +1122,7 @@ pango_font_map_set_fallback (PangoFontMap *self,
  * pango_font_map_get_fallback:
  * @self: a `PangoFontMap`
  *
- * Returns the fallback fontmap of @self
+ * Returns the fallback fontmap of the fontmap.
  *
  * See [method@Pango.FontMap.set_fallback].
  *
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 94938b84..8dafd623 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -221,9 +221,9 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(PangoGlyphString, pango_glyph_string_free)
  * @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.
+ * `PangoShapeFlags` influence the shaping process.
  *
- * `PangoShapeFlags` can be passed to [func@Pango.shape].
+ * These flags can be passed to [func@Pango.shape].
  */
 typedef enum {
   PANGO_SHAPE_NONE            = 0,
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 42674881..5a2f50aa 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -453,7 +453,7 @@ pango_layout_class_init (PangoLayoutClass *class)
   /**
    * PangoLayout:wrap: (attributes org.gtk.Property.get=pango_layout_get_wrap org.gtk.Property.set=pango_layout_set_wrap)
    *
-   * The wrap mode of this `PangoLayout.
+   * The wrap mode of this `PangoLayout`.
    *
    * The wrap mode influences how Pango chooses line breaks
    * when text needs to be wrapped.
@@ -468,7 +468,7 @@ pango_layout_class_init (PangoLayoutClass *class)
   /**
    * PangoLayout:indent: (attributes org.gtk.Property.get=pango_layout_get_indent org.gtk.Property.set=pango_layout_set_indent)
    *
-   * The indent of this `PangoLayout.
+   * The indent of this `PangoLayout`.
    *
    * The indent is specified in Pango units.
    *
@@ -485,7 +485,7 @@ pango_layout_class_init (PangoLayoutClass *class)
   /**
    * PangoLayout:alignment: (attributes org.gtk.Property.get=pango_layout_get_alignment org.gtk.Property.set=pango_layout_set_alignment)
    *
-   * The alignment mode of this `PangoLayout.
+   * The alignment mode of this `PangoLayout`.
    *
    * The default value is `PANGO_ALIGN_NATURAL`.
    */
@@ -497,7 +497,7 @@ pango_layout_class_init (PangoLayoutClass *class)
   /**
    * PangoLayout:ellipsize: (attributes org.gtk.Property.get=pango_layout_get_ellipsize org.gtk.Property.set=pango_layout_set_ellipsize)
    *
-   * The ellipsization mode of this `PangoLayout.
+   * The ellipsization mode of this `PangoLayout`.
    *
    * The default value is `PANGO_ELLIPSIZE_NONE`.
    */
@@ -888,7 +888,7 @@ pango_layout_get_serial (PangoLayout *layout)
  * pango_layout_context_changed:
  * @layout: a `PangoLayout`
  *
- * Forces recomputation of any state in the `PangoLayout` that
+ * Forces recomputation of any state in the layout that
  * might depend on the layout's context.
  *
  * This function should be called if you make changes to the
@@ -1507,7 +1507,7 @@ pango_layout_set_ellipsize (PangoLayout        *layout,
  * pango_layout_get_ellipsize:
  * @layout: a `PangoLayout`
  *
- * Gets the type of ellipsization being performed for @layout.
+ * Gets the type of ellipsization being performed for the layout.
  *
  * See [method@Pango.Layout.set_ellipsize].
  *
@@ -1657,7 +1657,7 @@ pango_layout_get_character_count (PangoLayout *layout)
  * pango_layout_get_lines:
  * @layout: a `PangoLayout`
  *
- * Gets the lines of the @layout.
+ * Gets the lines of the layout.
  *
  * The returned object will become invalid when any
  * property of @layout is changed. Take a reference
@@ -1681,8 +1681,7 @@ pango_layout_get_lines (PangoLayout *layout)
  * @layout: a `PangoLayout`
  * @n_attrs: (out): return location for the length of the array
  *
- * Gets the `PangoLogAttr` array for the content
- * of @layout.
+ * Gets the `PangoLogAttr` array for the content of layout.
  *
  * The returned array becomes invalid when
  * any properties of @layout change. Make a
diff --git a/pango/pango-line-breaker.c b/pango/pango-line-breaker.c
index 76d125cc..9d906a08 100644
--- a/pango/pango-line-breaker.c
+++ b/pango/pango-line-breaker.c
@@ -28,7 +28,7 @@
  * A `PangoLineBreaker` breaks text into lines.
  *
  * To use a `PangoLineBreaker`, you must call [method@Pango.LineBreaker.add_text]
- * to provide text that you want to break into lines, plus possibly attribute
+ * to provide text that you want to break into lines, plus possibly attributes
  * to influence the formatting.
  *
  * Then you can call [method@Pango.LineBreaker.next_line] repeatedly to obtain
@@ -2288,7 +2288,7 @@ pango_line_breaker_new (PangoContext *context)
  * pango_line_breaker_get_context:
  * @self: a `PangoLineBreaker`
  *
- * Retrieves the context used for this `PangoLineBreaker`.
+ * Retrieves the context used for the `PangoLineBreaker`.
  *
  * Returns: (transfer none): the `PangoContext` for @self
  */
@@ -2344,7 +2344,7 @@ pango_line_breaker_set_tabs (PangoLineBreaker *self,
  * pango_line_breaker_get_tabs:
  * @self: a `PangoLineBreaker`
  *
- * Gets the current `PangoTabArray` used by this `PangoLineBreaker`.
+ * Gets the current `PangoTabArray` used by the `PangoLineBreaker`.
  *
  * If no `PangoTabArray` has been set, then the default tabs are
  * in use and %NULL is returned. Default tabs are every 8 spaces.
@@ -2367,7 +2367,7 @@ pango_line_breaker_get_tabs (PangoLineBreaker *self)
  * @self: a `PangoLineBreaker`
  * @direction: the direction
  *
- * Sets the base direction for lines produced by this `PangoLineBreaker`.
+ * Sets the base direction for lines produced by the `PangoLineBreaker`.
  *
  * If @direction is `PANGO_DIRECTION_NEUTRAL`, the direction is determined
  * from the content. This is the default behavior.
@@ -2390,7 +2390,7 @@ pango_line_breaker_set_base_dir (PangoLineBreaker *self,
  * pango_line_breaker_get_base_dir:
  * @self: a `PangoLineBreaker`
  *
- * Gets the base direction for lines produced by this `PangoLineBreaker`.
+ * Gets the base direction for lines produced by the `PangoLineBreaker`.
  *
  * See [method@Pango.LineBreaker.set_base_dir].
  */
@@ -2565,7 +2565,7 @@ pango_line_breaker_next_line (PangoLineBreaker   *self,
  * @self: a `PangoLineBreaker`
  * @line: (transfer none): the most recent line produced by @self
  *
- * Re-adds the content of @line to the unprocessed
+ * Re-adds the content of a line to the unprocessed
  * input of the `PangoLineBreaker`.
  *
  * This can be used to try this line again with
diff --git a/pango/pango-lines.c b/pango/pango-lines.c
index 3f0b5faf..fe6f9352 100644
--- a/pango/pango-lines.c
+++ b/pango/pango-lines.c
@@ -392,7 +392,7 @@ pango_lines_get_line_position (PangoLines *lines,
  * pango_lines_get_unknown_glyphs_count:
  * @lines: a `PangoLines` object
  *
- * Counts the number of unknown glyphs in @lines.
+ * Counts the number of unknown glyphs in the `PangoLines`
  *
  * This function can be used to determine if there are any fonts
  * available to render all characters in a certain string, or when
@@ -429,7 +429,7 @@ pango_lines_get_unknown_glyphs_count (PangoLines *lines)
  * pango_lines_is_wrapped:
  * @lines: a `PangoLines` object
  *
- * Returns whether any line in @lines is wrapped.
+ * Returns whether any of the lines is wrapped.
  *
  * Returns: `TRUE` if @lines is wrapped
  */
@@ -450,7 +450,7 @@ pango_lines_is_wrapped (PangoLines *lines)
  * pango_lines_is_ellipsized:
  * @lines: a `PangoLines` object
  *
- * Returns whether any line in @lines is ellipsized.
+ * Returns whether any of the lines is ellipsized.
  *
  * Returns: `TRUE` if @lines is ellipsized
  */
@@ -471,7 +471,7 @@ pango_lines_is_ellipsized (PangoLines *lines)
  * pango_lines_is_hyphenated:
  * @lines: a `PangoLines` object
  *
- * Returns whether any line in @lines is hyphenated.
+ * Returns whether any of the lines is hyphenated.
  *
  * Returns: `TRUE` if @lines is hyphenated
  */
@@ -497,7 +497,7 @@ pango_lines_is_hyphenated (PangoLines *lines)
  * @ink_rect: (out) (optional): return location for the ink extents
  * @logical_rect: (out) (optional): return location for the logical extents
  *
- * Computes the extents of @lines.
+ * Computes the extents of the lines.
  *
  * Logical extents are usually what you want for positioning things. Note
  * that the extents may have non-zero x and y. You may want to use those
@@ -600,7 +600,7 @@ pango_lines_get_size (PangoLines *lines,
  * pango_lines_get_baseline:
  * @lines: a `PangoLines` object
  *
- * Gets the Y position of baseline of the first line in @lines.
+ * Gets the Y position of baseline of the first line.
  *
  * Return value: baseline of first line
  */
@@ -774,7 +774,7 @@ pango_lines_get_x_ranges (PangoLines *lines,
 }
 
 /* }}} */
-  /* {{{ Editing API */
+  /* { {{ Editing API */
 
 /**
  * pango_lines_index_to_line:
diff --git a/pango/pango-types.h b/pango/pango-types.h
index 97344d38..f39f35b2 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -310,7 +310,6 @@ typedef enum
   PANGO_LEADING_TRIM_NONE  = 0,
   PANGO_LEADING_TRIM_START = 1 << 0,
   PANGO_LEADING_TRIM_END   = 1 << 1,
-
 } PangoLeadingTrim;
 
 /**
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 6058ff68..49733a7f 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -603,12 +603,12 @@ pango_fc_font_map_set_config (PangoFcFontMap *self,
  * pango_fc_font_map_get_config: (skip)
  * @self: a `PangoFcFontMap`
  *
- * Fetches the `FcConfig` attached to a font map.
+ * Fetches the fontconfig configuration of the fontmap.
  *
  * See also: [method@PangoFc.FontMap.set_config].
  *
  * Returns: (nullable): the `FcConfig` object attached to
- *   @self, which might be %NULL. The return value is
+ *   @self, which might be `NULL`. The return value is
  *   owned by Pango and should not be freed.
  */
 FcConfig *