docs: Port PangoFont to the new doc format

Replace gtk-doc'isms and use gi-docgen links instead.

2 files changed, 587 insertions, 643 deletions

diff --git a/pango/fonts.c b/pango/fonts.c
index 3ee21b0c..1ab6e816 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
@@ -56,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 */
 };
 
 /**
@@ -78,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)
 {
@@ -93,18 +93,18 @@ 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
  * 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);
 
@@ -115,19 +115,18 @@ 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
+ * 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);
 
@@ -153,16 +152,15 @@ 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. See
- * pango_font_description_set_family().
+ * Gets the family name field of a font description.
+ * 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)
 {
@@ -173,21 +171,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);
 
@@ -197,15 +197,15 @@ 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. See
- * pango_font_description_set_style().
+ * Gets the style field of a `PangoFontDescription`.
+ * 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)
 {
@@ -216,15 +216,16 @@ 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);
 
@@ -234,15 +235,15 @@ 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. See
- * pango_font_description_set_variant().
+ * Gets the variant field of a `PangoFontDescription`.
+ * 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)
 {
@@ -253,17 +254,17 @@ 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
  * 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);
 
@@ -273,15 +274,15 @@ 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. See
- * pango_font_description_set_weight().
+ * Gets the weight field of a font description.
+ * 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)
 {
@@ -292,15 +293,16 @@ 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);
 
@@ -310,15 +312,15 @@ 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().
+ * See [method@Pango.FontDescription.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.
- **/
+ * 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)
 {
@@ -329,21 +331,23 @@ 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);
@@ -355,18 +359,19 @@ 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)
 {
@@ -377,20 +382,20 @@ 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. This is mutually
- * exclusive with pango_font_description_set_size() which sets the font size
- * in points.
+ * Sets the size field of a font description, in device units.
+ * 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);
@@ -402,17 +407,19 @@ 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).
- * See pango_font_description_set_size() and pango_font_description_set_absolute_size().
+ * Determines whether the size of the font is in points (not absolute)
+ * or device units (absolute). 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)
 {
@@ -423,22 +430,22 @@ 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
+ * 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);
 
@@ -454,17 +461,17 @@ 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.
+ * See [method@Pango.FontDescription.set_gravity].
  *
- * 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.
+ * 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)
 {
@@ -475,18 +482,18 @@ 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
+ * 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)
@@ -515,14 +522,17 @@ 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.
  *
- * 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.
@@ -531,7 +541,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)
@@ -545,18 +555,17 @@ 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. See
- * pango_font_description_set_variations().
+ * Gets the variations field of a font description.
+ * 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)
 {
@@ -567,13 +576,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)
 {
@@ -584,15 +593,15 @@ 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;
 
@@ -608,23 +617,24 @@ 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;
@@ -654,21 +664,21 @@ 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.
- **/
+ * 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;
 
@@ -705,14 +715,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
        */
@@ -724,28 +734,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);
@@ -758,7 +768,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;
@@ -766,17 +776,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;
 
@@ -801,18 +810,17 @@ 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
+ *
+ * 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)
 {
@@ -836,34 +844,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.
  *
- * 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.)
+ * 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);
 }
 
@@ -879,7 +888,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;
@@ -887,14 +896,14 @@ case_insensitive_hash (const char *key)
 
 /**
  * pango_font_description_hash:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
- * Computes a hash of a #PangoFontDescription structure suitable
+ * 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.
  *
  * Return value: the hash value.
- **/
+ */
 guint
 pango_font_description_hash (const PangoFontDescription *desc)
 {
@@ -919,12 +928,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;
@@ -941,14 +950,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;
 
@@ -1027,8 +1036,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;
 
@@ -1041,10 +1050,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--;
@@ -1055,8 +1064,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);
@@ -1075,11 +1084,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;
@@ -1088,21 +1097,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)
@@ -1120,10 +1129,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
@@ -1158,9 +1167,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);
@@ -1171,10 +1180,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;
     }
@@ -1206,7 +1215,7 @@ parse_variations (const char  *word,
  * Creates a new font description from a string representation in 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
@@ -1244,10 +1253,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)
 {
@@ -1260,9 +1269,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;
@@ -1272,8 +1281,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;
         }
     }
 
@@ -1283,11 +1292,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
@@ -1296,12 +1305,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
@@ -1332,7 +1341,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);
@@ -1354,11 +1363,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;
     }
 
@@ -1369,18 +1378,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 [method@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;
 
@@ -1401,14 +1411,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) \
@@ -1431,13 +1441,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)
@@ -1451,17 +1461,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. 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.
+ * Creates a filename representation of a font description.
+ *
+ * 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;
@@ -1476,23 +1488,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);
@@ -1507,10 +1518,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;
@@ -1520,21 +1531,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;
@@ -1546,8 +1557,7 @@ 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",
@@ -1555,11 +1565,11 @@ parse_field (const char *what,
  * 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);
 }
@@ -1567,8 +1577,7 @@ 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"
@@ -1576,11 +1585,11 @@ pango_parse_style (const char *str,
  * 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);
 }
@@ -1588,8 +1597,7 @@ 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",
@@ -1597,11 +1605,11 @@ pango_parse_variant (const char   *str,
  * 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);
 }
@@ -1609,8 +1617,7 @@ 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
@@ -1620,18 +1627,16 @@ pango_parse_weight (const char  *str,
  * 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
  */
@@ -1668,16 +1673,16 @@ 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.
+ * Use [method@Pango.Font.describe_with_absolute_size] if you want
+ * the font size in device units.
  *
- * Return value: a newly-allocated #PangoFontDescription object.
- **/
+ * 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);
 
@@ -1686,18 +1691,18 @@ 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). Use [method@Pango.Font.describe] if you want
+ * the font size in points.
  *
- * Return value: a newly-allocated #PangoFontDescription object.
+ * 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);
 
@@ -1712,17 +1717,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);
 
@@ -1731,7 +1736,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.
  *
@@ -1740,18 +1745,18 @@ 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.
@@ -1768,29 +1773,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;
     }
 
@@ -1799,24 +1804,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))
     {
@@ -1840,23 +1847,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 *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.
+ * 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)
 {
@@ -1871,11 +1879,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
  */
@@ -1889,16 +1897,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
  */
@@ -1926,13 +1933,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.
+ *
+ * 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
+ * Return value: a newly-created `PangoFontMetrics` structure
  *   with a reference count of 1.
- **/
+ */
 PangoFontMetrics *
 pango_font_metrics_new (void)
 {
@@ -1944,12 +1952,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)
 {
@@ -1963,12 +1971,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)
 {
@@ -1983,16 +1990,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. 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.)
+ * 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.)
  *
  * Return value: the ascent, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
 {
@@ -2003,16 +2011,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. 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.)
+ * 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.)
  *
  * Return value: the descent, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_descent (PangoFontMetrics *metrics)
 {
@@ -2023,10 +2032,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.
  *
- * Gets the line height from a font metrics structure. The
- * line height is the distance between successive baselines
+ * The line height is the distance between successive baselines
  * in wrapped text.
  *
  * If the line height is not available, 0 is returned.
@@ -2045,15 +2055,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)
 {
@@ -2064,9 +2075,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
@@ -2074,7 +2086,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)
 {
@@ -2085,18 +2097,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 *above* 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)
 {
@@ -2107,14 +2119,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)
 {
@@ -2125,16 +2137,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 *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)
 {
@@ -2145,14 +2158,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)
 {
@@ -2230,15 +2243,15 @@ 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
+ * 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)
 {
@@ -2249,9 +2262,9 @@ 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.
@@ -2259,11 +2272,11 @@ pango_font_family_get_name (PangoFontFamily  *family)
  * 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));
 
@@ -2305,14 +2318,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
@@ -2328,7 +2341,7 @@ 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
@@ -2339,14 +2352,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)
 {
@@ -2360,7 +2373,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.
@@ -2368,7 +2381,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)
 {
@@ -2398,16 +2411,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)
 {
@@ -2418,16 +2431,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)
 {
@@ -2441,15 +2454,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)
 {
@@ -2460,23 +2473,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);
@@ -2489,19 +2504,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
  */
@@ -2515,7 +2529,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.
@@ -2536,7 +2550,7 @@ 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
diff --git a/pango/pango-font.h b/pango/pango-font.h
index cc12a295..1fbade27 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,7 +33,7 @@ G_BEGIN_DECLS
 /**
  * PangoFontDescription:
  *
- * The #PangoFontDescription structure represents the description
+ * 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.
@@ -42,7 +42,7 @@ typedef struct _PangoFontDescription PangoFontDescription;
 /**
  * PangoFontMetrics:
  *
- * A #PangoFontMetrics structure holds the overall metric information
+ * 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
@@ -148,8 +148,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 fields in a
+ * [struct@Pango.FontDescription] that have been set.
  */
 typedef enum {
   PANGO_FONT_MASK_FAMILY  = 1 << 0,
@@ -210,11 +210,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 +224,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 +288,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 +315,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 +363,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,7 +379,7 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
 /**
  * PangoFontFamily:
  *
- * The #PangoFontFamily structure is used to represent a family of related
+ * 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.
  */
@@ -445,8 +418,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 +436,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,7 +450,7 @@ typedef struct _PangoFontFaceClass   PangoFontFaceClass;
 /**
  * PangoFontFace:
  *
- * The #PangoFontFace structure is used to represent a group of fonts with
+ * The `PangoFontFace` structure is used to represent a group of fonts with
  * the same family, slant, weight, width, but varying sizes.
  */
 struct _PangoFontFace
@@ -534,8 +490,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 +503,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 +516,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 `klass` 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.
+ * The `PangoFont` structure is used to represent a font in a
+ * rendering-system-independent matter.
  */
 struct _PangoFont
 {
@@ -631,19 +560,19 @@ 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);
 PANGO_DEPRECATED_IN_1_44
 PangoEngineShape *    pango_font_find_shaper       (PangoFont        *font,
-						    PangoLanguage    *language,
-						    guint32           ch);
+                                                    PangoLanguage    *language,
+                                                    guint32           ch);
 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,16 +593,17 @@ 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
+ * 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()).
+ * 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
+ * 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.
  *
@@ -686,18 +616,18 @@ hb_font_t *           pango_font_get_hb_font       (PangoFont        *font);
  * 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.
+ * a `gunichar` value of a valid Unicode character, to produce a `PangoGlyph`
+ * value, representing an unknown-character glyph for the respective `gunichar`.
  */
 /**
  * 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)