[pango/gi-docs: 6/14] docs: Start porting PangoFont to the new doc format




commit 318c2c5adf55f2d3be401bf53fba570bada08a84
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 14 23:20:05 2021 -0500

    docs: Start porting PangoFont to the new doc format
    
    Replace gtk-doc'isms and use gi-docgen links instead.

 pango/fonts.c      | 1075 ++++++++++++++++++++++++++--------------------------
 pango/pango-font.h |  166 +++-----
 2 files changed, 592 insertions(+), 649 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index a778facd..10c6ca12 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
@@ -24,12 +24,11 @@
  * @short_description:Structures representing abstract fonts
  * @title: Fonts
  *
- * Pango supports a flexible architecture where a
- * particular rendering architecture can supply an
- * implementation of fonts. The #PangoFont structure
- * represents an abstract rendering-system-independent font.
- * Pango provides routines to list available fonts, and
- * to load a font matching a given description.
+ * Pango supports a flexible architecture where a particular rendering
+ * architecture can supply an implementation of fonts. The `PangoFont`
+ * structure represents an abstract rendering-system-independent font.
+ * Pango provides routines to list available fonts, and to load a font
+ * matching a given description.
  */
 
 #include "config.h"
@@ -69,21 +68,21 @@ G_DEFINE_BOXED_TYPE (PangoFontDescription, pango_font_description,
                      pango_font_description_free);
 
 static const PangoFontDescription pfd_defaults = {
-  NULL,                        /* family_name */
+  NULL,                 /* family_name */
 
-  PANGO_STYLE_NORMAL,  /* style */
-  PANGO_VARIANT_NORMAL,        /* variant */
-  PANGO_WEIGHT_NORMAL, /* weight */
-  PANGO_STRETCH_NORMAL,        /* stretch */
+  PANGO_STYLE_NORMAL,   /* style */
+  PANGO_VARIANT_NORMAL, /* variant */
+  PANGO_WEIGHT_NORMAL,  /* weight */
+  PANGO_STRETCH_NORMAL, /* stretch */
   PANGO_GRAVITY_SOUTH,  /* gravity */
   NULL,                 /* variations */
 
-  0,                   /* mask */
-  0,                   /* static_family */
-  0,                   /* static_variations*/
-  0,                   /* size_is_absolute */
+  0,                    /* mask */
+  0,                    /* static_family */
+  0,                    /* static_variations*/
+  0,                    /* size_is_absolute */
 
-  0,                   /* size */
+  0,                    /* size */
 };
 
 /**
@@ -91,9 +90,9 @@ static const PangoFontDescription pfd_defaults = {
  *
  * Creates a new font description structure with all fields unset.
  *
- * Return value: the newly allocated #PangoFontDescription, which
- *               should be freed using pango_font_description_free().
- **/
+ * Return value: the newly allocated `PangoFontDescription`, which
+ *   should be freed using [method Pango FontDescription free].
+ */
 PangoFontDescription *
 pango_font_description_new (void)
 {
@@ -106,18 +105,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);
 
@@ -128,19 +127,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);
 
@@ -166,16 +164,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)
 {
@@ -186,21 +183,23 @@ pango_font_description_get_family (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_set_style:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  * @style: the style for the font description
  *
- * Sets the style field of a #PangoFontDescription. The
- * #PangoStyle enumeration describes whether the font is slanted and
- * the manner in which it is slanted; it can be either
+ * Sets the style field of a `PangoFontDescription`.
+ *
+ * The [enum@Pango.Style] enumeration describes whether the font is
+ * slanted and the manner in which it is slanted; it can be either
  * #PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE.
- * Most fonts will either have a italic style or an oblique
- * style, but not both, and font matching in Pango will
- * match italic specifications with oblique fonts and vice-versa
- * if an exact match is not found.
- **/
+ *
+ * Most fonts will either have a italic style or an oblique style,
+ * but not both, and font matching in Pango will match italic
+ * specifications with oblique fonts and vice-versa if an exact
+ * match is not found.
+ */
 void
 pango_font_description_set_style (PangoFontDescription *desc,
-                                 PangoStyle            style)
+                                  PangoStyle            style)
 {
   g_return_if_fail (desc != NULL);
 
@@ -210,15 +209,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)
 {
@@ -229,15 +228,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);
 
@@ -247,15 +247,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)
 {
@@ -266,17 +266,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);
 
@@ -286,15 +286,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)
 {
@@ -305,15 +305,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);
 
@@ -323,15 +324,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)
 {
@@ -342,21 +343,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);
@@ -368,18 +371,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)
 {
@@ -390,20 +394,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);
@@ -415,17 +419,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)
 {
@@ -436,22 +442,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);
 
@@ -467,17 +473,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)
 {
@@ -488,18 +494,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)
@@ -528,14 +534,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.
@@ -544,7 +553,7 @@ pango_font_description_set_variations_static (PangoFontDescription *desc,
  * a font. Both harfbuzz or freetype have API for this.
  *
  * Since: 1.42
- **/
+ */
 void
 pango_font_description_set_variations (PangoFontDescription *desc,
                                        const char           *variations)
@@ -558,18 +567,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)
 {
@@ -580,13 +588,13 @@ pango_font_description_get_variations (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_get_set_fields:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
  *
  * Determines which fields in a font description have been set.
  *
  * Return value: a bitmask with bits set corresponding to the
  *   fields in @desc that have been set.
- **/
+ */
 PangoFontMask
 pango_font_description_get_set_fields (const PangoFontDescription *desc)
 {
@@ -597,15 +605,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;
 
@@ -621,23 +629,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;
@@ -667,21 +676,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;
 
@@ -718,14 +727,14 @@ pango_font_description_merge_static (PangoFontDescription       *desc,
 
 static gint
 compute_distance (const PangoFontDescription *a,
-                 const PangoFontDescription *b)
+                  const PangoFontDescription *b)
 {
   if (a->style == b->style)
     {
       return abs((int)(a->weight) - (int)(b->weight));
     }
   else if (a->style != PANGO_STYLE_NORMAL &&
-          b->style != PANGO_STYLE_NORMAL)
+           b->style != PANGO_STYLE_NORMAL)
     {
       /* Equate oblique and italic, but with a big penalty
        */
@@ -737,28 +746,28 @@ compute_distance (const PangoFontDescription *a,
 
 /**
  * pango_font_description_better_match:
- * @desc: a #PangoFontDescription
- * @old_match: (allow-none): a #PangoFontDescription, or %NULL
- * @new_match: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
+ * @old_match: (allow-none): a `PangoFontDescription`, or %NULL
+ * @new_match: a `PangoFontDescription`
  *
  * Determines if the style attributes of @new_match are a closer match
  * for @desc than those of @old_match are, or if @old_match is %NULL,
  * determines if @new_match is a match at all.
- * Approximate matching is done for
- * weight and style; other style attributes must match exactly.
- * Style attributes are all attributes other than family and size-related
- * attributes.  Approximate matching for style considers PANGO_STYLE_OBLIQUE
- * and PANGO_STYLE_ITALIC as matches, but not as good a match as when the
- * styles are equal.
+ *
+ * Approximate matching is done for weight and style; other style attributes
+ * must match exactly. Style attributes are all attributes other than family
+ * and size-related attributes. Approximate matching for style considers
+ * %PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good
+ * a match as when the styles are equal.
  *
  * Note that @old_match must match @desc.
  *
  * Return value: %TRUE if @new_match is a better match
- **/
+ */
 gboolean
 pango_font_description_better_match (const PangoFontDescription *desc,
-                                    const PangoFontDescription *old_match,
-                                    const PangoFontDescription *new_match)
+                                     const PangoFontDescription *old_match,
+                                     const PangoFontDescription *new_match)
 {
   g_return_val_if_fail (desc != NULL, G_MAXINT);
   g_return_val_if_fail (new_match != NULL, G_MAXINT);
@@ -771,7 +780,7 @@ pango_font_description_better_match (const PangoFontDescription *desc,
       int new_distance = compute_distance (desc, new_match);
 
       if (new_distance < old_distance)
-       return TRUE;
+        return TRUE;
     }
 
   return FALSE;
@@ -779,17 +788,16 @@ pango_font_description_better_match (const PangoFontDescription *desc,
 
 /**
  * pango_font_description_copy:
- * @desc: (nullable): a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a `PangoFontDescription`, may be %NULL
  *
- * Make a copy of a #PangoFontDescription.
+ * Make a copy of a `PangoFontDescription`.
  *
- * Return value: (nullable): the newly allocated
- *               #PangoFontDescription, which should be freed with
- *               pango_font_description_free(), or %NULL if @desc was
- *               %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoFontDescription`,
+ *   which should be freed with [method Pango FontDescription free],
+ *   or %NULL if @desc was %NULL.
+ */
 PangoFontDescription *
-pango_font_description_copy  (const PangoFontDescription  *desc)
+pango_font_description_copy (const PangoFontDescription *desc)
 {
   PangoFontDescription *result;
 
@@ -814,18 +822,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)
 {
@@ -849,34 +856,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);
 }
 
@@ -892,7 +900,7 @@ case_insensitive_hash (const char *key)
   if (h)
     {
       for (p += 1; *p != '\0'; p++)
-       h = (h << 5) - h + TOLOWER (*p);
+        h = (h << 5) - h + TOLOWER (*p);
     }
 
   return h;
@@ -900,14 +908,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)
 {
@@ -932,12 +940,12 @@ pango_font_description_hash (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_free:
- * @desc: (nullable): a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a `PangoFontDescription`, may be %NULL
  *
  * Frees a font description.
- **/
+ */
 void
-pango_font_description_free  (PangoFontDescription  *desc)
+pango_font_description_free (PangoFontDescription *desc)
 {
   if (desc == NULL)
     return;
@@ -954,14 +962,14 @@ pango_font_description_free  (PangoFontDescription  *desc)
 /**
  * pango_font_descriptions_free:
  * @descs: (allow-none) (array length=n_descs) (transfer full): a pointer
- * to an array of #PangoFontDescription, may be %NULL
+ *   to an array of `PangoFontDescription`, may be %NULL
  * @n_descs: number of font descriptions in @descs
  *
  * Frees an array of font descriptions.
- **/
+ */
 void
 pango_font_descriptions_free (PangoFontDescription **descs,
-                             int                    n_descs)
+                              int                    n_descs)
 {
   int i;
 
@@ -1040,8 +1048,8 @@ static const FieldMap gravity_map[] = {
 
 static gboolean
 field_matches (const gchar *s1,
-              const gchar *s2,
-              gsize n)
+               const gchar *s2,
+               gsize n)
 {
   gint c1, c2;
 
@@ -1054,10 +1062,10 @@ field_matches (const gchar *s1,
       c2 = (gint)(guchar) TOLOWER (*s2);
       if (c1 != c2) {
         if (c1 == '-') {
-         s1++;
-         continue;
-       }
-       return FALSE;
+          s1++;
+          continue;
+        }
+        return FALSE;
       }
       s1++; s2++;
       n--;
@@ -1068,8 +1076,8 @@ field_matches (const gchar *s1,
 
 static gboolean
 parse_int (const char *word,
-          size_t      wordlen,
-          int        *out)
+           size_t      wordlen,
+           int        *out)
 {
   char *end;
   long val = strtol (word, &end, 10);
@@ -1088,11 +1096,11 @@ parse_int (const char *word,
 
 static gboolean
 find_field (const char *what,
-           const FieldMap *map,
-           int n_elements,
-           const char *str,
-           int len,
-           int *val)
+            const FieldMap *map,
+            int n_elements,
+            const char *str,
+            int len,
+            int *val)
 {
   int i;
   gboolean had_prefix = FALSE;
@@ -1101,21 +1109,21 @@ find_field (const char *what,
     {
       i = strlen (what);
       if (len > i && 0 == strncmp (what, str, i) && str[i] == '=')
-       {
-         str += i + 1;
-         len -= i + 1;
-         had_prefix = TRUE;
-       }
+        {
+          str += i + 1;
+          len -= i + 1;
+          had_prefix = TRUE;
+        }
     }
 
   for (i=0; i<n_elements; i++)
     {
       if (map[i].str[0] && field_matches (map[i].str, str, len))
-       {
-         if (val)
-           *val = map[i].value;
-         return TRUE;
-       }
+        {
+          if (val)
+            *val = map[i].value;
+          return TRUE;
+        }
     }
 
   if (!what || had_prefix)
@@ -1133,10 +1141,10 @@ find_field_any (const char *str, int len, PangoFontDescription *desc)
 #define FIELD(NAME, MASK) \
   G_STMT_START { \
   if (find_field (G_STRINGIFY (NAME), NAME##_map, G_N_ELEMENTS (NAME##_map), str, len, \
-                 desc ? (int *)(void *)&desc->NAME : NULL)) \
+                  desc ? (int *)(void *)&desc->NAME : NULL)) \
     { \
       if (desc) \
-       desc->mask |= MASK; \
+        desc->mask |= MASK; \
       return TRUE; \
     } \
   } G_STMT_END
@@ -1171,9 +1179,9 @@ getword (const char *str, const char *last, size_t *wordlen, const char *stop)
 
 static gboolean
 parse_size (const char *word,
-           size_t      wordlen,
-           int        *pango_size,
-           gboolean   *size_is_absolute)
+            size_t      wordlen,
+            int        *pango_size,
+            gboolean   *size_is_absolute)
 {
   char *end;
   double size = g_ascii_strtod (word, &end);
@@ -1184,10 +1192,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;
     }
@@ -1219,7 +1227,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
@@ -1257,10 +1265,10 @@ parse_variations (const char  *word,
  *
  * A typical example:
  *
- * "Cantarell Italic Light 15 \@wght=200"
+ *     "Cantarell Italic Light 15 \@wght=200"
  *
- * Return value: a new #PangoFontDescription.
- **/
+ * Return value: a new `PangoFontDescription`.
+ */
 PangoFontDescription *
 pango_font_description_from_string (const char *str)
 {
@@ -1273,9 +1281,9 @@ pango_font_description_from_string (const char *str)
   desc = pango_font_description_new ();
 
   desc->mask = PANGO_FONT_MASK_STYLE |
-              PANGO_FONT_MASK_WEIGHT |
-              PANGO_FONT_MASK_VARIANT |
-              PANGO_FONT_MASK_STRETCH;
+               PANGO_FONT_MASK_WEIGHT |
+               PANGO_FONT_MASK_VARIANT |
+               PANGO_FONT_MASK_STRETCH;
 
   len = strlen (str);
   last = str + len;
@@ -1285,8 +1293,8 @@ pango_font_description_from_string (const char *str)
     {
       if (parse_variations (p, wordlen, &desc->variations))
         {
-         desc->mask |= PANGO_FONT_MASK_VARIATIONS;
-         last = p;
+          desc->mask |= PANGO_FONT_MASK_VARIATIONS;
+          last = p;
         }
     }
 
@@ -1296,11 +1304,11 @@ pango_font_description_from_string (const char *str)
     {
       gboolean size_is_absolute;
       if (parse_size (p, wordlen, &desc->size, &size_is_absolute))
-       {
-         desc->size_is_absolute = size_is_absolute;
-         desc->mask |= PANGO_FONT_MASK_SIZE;
-         last = p;
-       }
+        {
+          desc->size_is_absolute = size_is_absolute;
+          desc->mask |= PANGO_FONT_MASK_SIZE;
+          last = p;
+        }
     }
 
   /* Now parse style words
@@ -1309,12 +1317,12 @@ pango_font_description_from_string (const char *str)
   while (wordlen != 0)
     {
       if (!find_field_any (p, wordlen, desc))
-       break;
+        break;
       else
-       {
-         last = p;
-         p = getword (str, last, &wordlen, ",");
-       }
+        {
+          last = p;
+          p = getword (str, last, &wordlen, ",");
+        }
     }
 
   /* Remainder (str => p) is family list. Trim off trailing commas and leading and trailing white space
@@ -1345,7 +1353,7 @@ pango_font_description_from_string (const char *str)
       families = g_strsplit (desc->family_name, ",", -1);
 
       for (i = 0; families[i]; i++)
-       g_strstrip (families[i]);
+        g_strstrip (families[i]);
 
       g_free (desc->family_name);
       desc->family_name = g_strjoinv (",", families);
@@ -1367,11 +1375,11 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element
         continue;
 
       if (G_LIKELY (map[i].str[0]))
-       {
-         if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' '))
-           g_string_append_c (str, ' ');
-         g_string_append (str, map[i].str);
-       }
+        {
+          if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' '))
+            g_string_append_c (str, ' ');
+          g_string_append (str, map[i].str);
+        }
       return;
     }
 
@@ -1382,18 +1390,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;
 
@@ -1414,14 +1423,14 @@ pango_font_description_to_string (const PangoFontDescription  *desc)
        */
       p = getword (desc->family_name, desc->family_name + strlen(desc->family_name), &wordlen, ",");
       if (wordlen != 0 &&
-         (find_field_any (p, wordlen, NULL) ||
-          (parse_size (p, wordlen, NULL, NULL) &&
-           desc->weight == PANGO_WEIGHT_NORMAL &&
-           desc->style == PANGO_STYLE_NORMAL &&
-           desc->stretch == PANGO_STRETCH_NORMAL &&
-           desc->variant == PANGO_VARIANT_NORMAL &&
-           (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0)))
-       g_string_append_c (result, ',');
+          (find_field_any (p, wordlen, NULL) ||
+           (parse_size (p, wordlen, NULL, NULL) &&
+            desc->weight == PANGO_WEIGHT_NORMAL &&
+            desc->style == PANGO_STYLE_NORMAL &&
+            desc->stretch == PANGO_STRETCH_NORMAL &&
+            desc->variant == PANGO_VARIANT_NORMAL &&
+            (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0)))
+        g_string_append_c (result, ',');
     }
 
 #define FIELD(NAME, MASK) \
@@ -1444,13 +1453,13 @@ pango_font_description_to_string (const PangoFontDescription  *desc)
       char buf[G_ASCII_DTOSTR_BUF_SIZE];
 
       if (result->len > 0 || result->str[result->len -1] != ' ')
-       g_string_append_c (result, ' ');
+        g_string_append_c (result, ' ');
 
       g_ascii_dtostr (buf, sizeof (buf), (double)desc->size / PANGO_SCALE);
       g_string_append (result, buf);
 
       if (desc->size_is_absolute)
-       g_string_append (result, "px");
+        g_string_append (result, "px");
     }
 
   if (desc->variations && desc->mask & PANGO_FONT_MASK_VARIATIONS)
@@ -1464,17 +1473,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;
@@ -1489,23 +1500,22 @@ pango_font_description_to_filename (const PangoFontDescription  *desc)
       if (G_UNLIKELY ((guchar) *p >= 128))
         /* skip over non-ASCII chars */;
       else if (strchr ("-+_.", *p) == NULL && !g_ascii_isalnum (*p))
-       *p = '_';
+        *p = '_';
       else
-       *p = g_ascii_tolower (*p);
+        *p = g_ascii_tolower (*p);
       p++;
     }
 
   return result;
 }
 
-
 static gboolean
 parse_field (const char *what,
-            const FieldMap *map,
-            int n_elements,
-            const char *str,
-            int *val,
-            gboolean warn)
+             const FieldMap *map,
+             int n_elements,
+             const char *str,
+             int *val,
+             gboolean warn)
 {
   gboolean found;
   int len = strlen (str);
@@ -1520,10 +1530,10 @@ parse_field (const char *what,
 
       for (i = 0; i < n_elements; i++)
         if (map[i].str[0] == '\0')
-         {
-           *val = map[i].value;
-           return TRUE;
-         }
+          {
+            *val = map[i].value;
+            return TRUE;
+          }
 
       *val = 0;
       return TRUE;
@@ -1533,21 +1543,21 @@ parse_field (const char *what,
 
   if (!found && warn)
     {
-       int i;
-       GString *s = g_string_new (NULL);
+        int i;
+        GString *s = g_string_new (NULL);
 
-       for (i = 0; i < n_elements; i++)
-         {
-           if (i)
-             g_string_append_c (s, '/');
-           g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str);
-         }
+        for (i = 0; i < n_elements; i++)
+          {
+            if (i)
+              g_string_append_c (s, '/');
+            g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str);
+          }
 
-       g_warning ("%s must be one of %s or a number",
-                  what,
-                  s->str);
+        g_warning ("%s must be one of %s or a number",
+                   what,
+                   s->str);
 
-       g_string_free (s, TRUE);
+        g_string_free (s, TRUE);
     }
 
   return found;
@@ -1559,8 +1569,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",
@@ -1568,11 +1577,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);
 }
@@ -1580,8 +1589,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"
@@ -1589,11 +1597,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);
 }
@@ -1601,8 +1609,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",
@@ -1610,11 +1617,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);
 }
@@ -1622,8 +1629,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
@@ -1633,18 +1639,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
  */
@@ -1681,16 +1685,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);
 
@@ -1699,18 +1703,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);
 
@@ -1725,17 +1729,17 @@ pango_font_describe_with_absolute_size (PangoFont      *font)
 
 /**
  * pango_font_get_coverage:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @language: the language tag
  *
  * Computes the coverage map for a given font and language tag.
  *
- * Return value: (transfer full): a newly-allocated #PangoCoverage
+ * Return value: (transfer full): a newly-allocated `PangoCoverage`
  *   object.
- **/
+ */
 PangoCoverage *
 pango_font_get_coverage (PangoFont     *font,
-                        PangoLanguage *language)
+                         PangoLanguage *language)
 {
   g_return_val_if_fail (font != NULL, NULL);
 
@@ -1744,7 +1748,7 @@ pango_font_get_coverage (PangoFont     *font,
 
 /**
  * pango_font_find_shaper:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @language: the language tag
  * @ch: a Unicode character.
  *
@@ -1753,18 +1757,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.
@@ -1781,29 +1785,29 @@ pango_font_find_shaper (PangoFont     *font,
  *
  * If @font is %NULL, this function gracefully sets some sane values in the
  * output variables and returns.
- **/
+ */
 void
 pango_font_get_glyph_extents  (PangoFont      *font,
-                              PangoGlyph      glyph,
-                              PangoRectangle *ink_rect,
-                              PangoRectangle *logical_rect)
+                               PangoGlyph      glyph,
+                               PangoRectangle *ink_rect,
+                               PangoRectangle *logical_rect)
 {
   if (G_UNLIKELY (!font))
     {
       if (ink_rect)
-       {
-         ink_rect->x = PANGO_SCALE;
-         ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE;
-         ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE;
-         ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE;
-       }
+        {
+          ink_rect->x = PANGO_SCALE;
+          ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE;
+          ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE;
+          ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE;
+        }
       if (logical_rect)
-       {
-         logical_rect->x = 0;
-         logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
-         logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
-         logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE;
-       }
+        {
+          logical_rect->x = 0;
+          logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
+          logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE;
+          logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE;
+        }
       return;
     }
 
@@ -1812,24 +1816,26 @@ pango_font_get_glyph_extents  (PangoFont      *font,
 
 /**
  * pango_font_get_metrics:
- * @font: (nullable): a #PangoFont
- * @language: (allow-none): language tag used to determine which script to get the metrics
- *            for, or %NULL to indicate to get the metrics for the entire font.
+ * @font: (nullable): a `PangoFont`
+ * @language: (allow-none): language tag used to determine which script
+ *   to get the metrics for, or %NULL to indicate to get the metrics for
+ *   the entire font.
+ *
+ * Gets overall metric information for a font.
  *
- * Gets overall metric information for a font. Since the metrics may be
- * substantially different for different scripts, a language tag can
- * be provided to indicate that the metrics should be retrieved that
- * correspond to the script(s) used by that language.
+ * Since the metrics may be substantially different for different scripts,
+ * a language tag can be provided to indicate that the metrics should be
+ * retrieved that correspond to the script(s) used by that language.
  *
  * If @font is %NULL, this function gracefully sets some sane values in the
  * output variables and returns.
  *
- * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref()
- *   when finished using the object.
- **/
+ * Return value: a `PangoFontMetrics` object. The caller must call
+ *   [method@Pango.FontMetrics.unref] when finished using the object.
+ */
 PangoFontMetrics *
-pango_font_get_metrics (PangoFont        *font,
-                       PangoLanguage    *language)
+pango_font_get_metrics (PangoFont     *font,
+                        PangoLanguage *language)
 {
   if (G_UNLIKELY (!font))
     {
@@ -1853,23 +1859,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)
 {
@@ -1884,11 +1891,11 @@ pango_font_get_font_map (PangoFont *font)
 
 /**
  * pango_font_get_face:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Gets the #PangoFontFace to which @font belongs.
+ * Gets the `PangoFontFace` to which @font belongs.
  *
- * Returns: (transfer none): the #PangoFontFace
+ * Returns: (transfer none): the `PangoFontFace`
  *
  * Since: 1.46
  */
@@ -1902,16 +1909,15 @@ pango_font_get_face (PangoFont *font)
 
 /**
  * pango_font_get_hb_font: (skip)
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Get a hb_font_t object backing this font.
+ * Get a `hb_font_t` object backing this font.
  *
- * Note that the objects returned by this function
- * are cached and immutable. If you need to make
- * changes to the hb_font_t, use hb_font_create_sub_font().
+ * Note that the objects returned by this function are cached and immutable.
+ * If you need to make changes to the `hb_font_t`, use hb_font_create_sub_font().
  *
- * Returns: (transfer none) (nullable): the hb_font_t object backing the
- *          font, or %NULL if the font does not have one
+ * Returns: (transfer none) (nullable): the `hb_font_t` object backing the
+ *   font, or %NULL if the font does not have one
  *
  * Since: 1.44
  */
@@ -1939,13 +1945,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)
 {
@@ -1957,12 +1964,12 @@ pango_font_metrics_new (void)
 
 /**
  * pango_font_metrics_ref:
- * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL
  *
  * Increase the reference count of a font metrics structure by one.
  *
  * Return value: (nullable): @metrics
- **/
+ */
 PangoFontMetrics *
 pango_font_metrics_ref (PangoFontMetrics *metrics)
 {
@@ -1976,12 +1983,11 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_unref:
- * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL
  *
- * Decrease the reference count of a font metrics structure by one. If
- * the result is zero, frees the structure and any associated
- * memory.
- **/
+ * Decrease the reference count of a font metrics structure by one.
+ * If the result is zero, frees the structure and any associated memory.
+ */
 void
 pango_font_metrics_unref (PangoFontMetrics *metrics)
 {
@@ -1996,16 +2002,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)
 {
@@ -2016,16 +2023,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)
 {
@@ -2036,10 +2044,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.
@@ -2058,15 +2067,16 @@ pango_font_metrics_get_height (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_approximate_char_width:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the approximate character width for a font metrics structure.
+ *
  * This is merely a representative value useful, for example, for
  * determining the initial size for a window. Actual characters in
  * text will be wider and narrower than this.
  *
  * Return value: the character width, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
 {
@@ -2077,9 +2087,10 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_approximate_digit_width:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the approximate digit width for a font metrics structure.
+ *
  * This is merely a representative value useful, for example, for
  * determining the initial size for a window. Actual digits in
  * text can be wider or narrower than this, though this value
@@ -2087,7 +2098,7 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
  * pango_font_metrics_get_approximate_char_width() for digits.
  *
  * Return value: the digit width, in Pango units.
- **/
+ */
 int
 pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics)
 {
@@ -2098,18 +2109,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)
 {
@@ -2120,14 +2131,14 @@ pango_font_metrics_get_underline_position (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_underline_thickness:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested thickness to draw for the underline.
  *
  * Return value: the suggested underline thickness, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_underline_thickness (PangoFontMetrics *metrics)
 {
@@ -2138,16 +2149,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)
 {
@@ -2158,14 +2170,14 @@ pango_font_metrics_get_strikethrough_position (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_get_strikethrough_thickness:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a `PangoFontMetrics` structure
  *
  * Gets the suggested thickness to draw for the strikethrough.
  *
  * Return value: the suggested strikethrough thickness, in Pango units.
  *
  * Since: 1.6
- **/
+ */
 int
 pango_font_metrics_get_strikethrough_thickness (PangoFontMetrics *metrics)
 {
@@ -2243,15 +2255,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)
 {
@@ -2262,9 +2274,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.
@@ -2272,11 +2284,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));
 
@@ -2318,14 +2330,14 @@ pango_font_family_real_get_face (PangoFontFamily *family,
 
 /**
  * pango_font_family_get_face:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  * @name: (nullable): the name of a face. If the name is %NULL,
  *     the family's default face (fontconfig calls it "Regular")
  *     will be returned.
  *
- * Gets the #PangoFontFace of @family with the given name.
+ * Gets the `PangoFontFace` of @family with the given name.
  *
- * Returns: (transfer none) (nullable): the #PangoFontFace,
+ * Returns: (transfer none) (nullable): the `PangoFontFace`,
  *     or %NULL if no face with the given name exists.
  *
  * Since: 1.46
@@ -2341,7 +2353,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
@@ -2352,14 +2364,14 @@ pango_font_family_get_face (PangoFontFamily *family,
  * character is typically double-width in a monospace font.
  *
  * The best way to find out the grid-cell size is to call
- * pango_font_metrics_get_approximate_digit_width(), since the results
- * of pango_font_metrics_get_approximate_char_width() may be affected
- * by double-width characters.
+ * [method@Pango.FontMetrics.get_approximate_digit_width], since the
+ * results of [method@Pango.FontMetrics.get_approximate_char_width] may
+ * be affected by double-width characters.
  *
  * Return value: %TRUE if the family is monospace.
  *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_font_family_is_monospace (PangoFontFamily  *family)
 {
@@ -2373,7 +2385,7 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
 
 /**
  * pango_font_family_is_variable:
- * @family: a #PangoFontFamily
+ * @family: a `PangoFontFamily`
  *
  * A variable font is a font which has axes that can be modified to
  * produce different faces.
@@ -2381,7 +2393,7 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
  * Return value: %TRUE if the family is variable
  *
  * Since: 1.44
- **/
+ */
 gboolean
 pango_font_family_is_variable (PangoFontFamily  *family)
 {
@@ -2411,16 +2423,16 @@ pango_font_face_init (PangoFontFace *face G_GNUC_UNUSED)
 
 /**
  * pango_font_face_describe:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
  * Returns the family, style, variant, weight and stretch of
- * a #PangoFontFace. The size field of the resulting font description
+ * a `PangoFontFace`. The size field of the resulting font description
  * will be unset.
  *
- * Return value: a newly-created #PangoFontDescription structure
- *  holding the description of the face. Use pango_font_description_free()
- *  to free the result.
- **/
+ * Return value: a newly-created `PangoFontDescription` structure
+ *   holding the description of the face. Use [method Pango FontDescription free]
+ *   to free the result.
+ */
 PangoFontDescription *
 pango_font_face_describe (PangoFontFace *face)
 {
@@ -2431,16 +2443,16 @@ pango_font_face_describe (PangoFontFace *face)
 
 /**
  * pango_font_face_is_synthesized:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
- * Returns whether a #PangoFontFace is synthesized by the underlying
+ * Returns whether a `PangoFontFace` is synthesized by the underlying
  * font rendering engine from another face, perhaps by shearing, emboldening,
  * or lightening it.
  *
  * Return value: whether @face is synthesized.
  *
  * Since: 1.18
- **/
+ */
 gboolean
 pango_font_face_is_synthesized (PangoFontFace  *face)
 {
@@ -2454,15 +2466,15 @@ pango_font_face_is_synthesized (PangoFontFace  *face)
 
 /**
  * pango_font_face_get_face_name:
- * @face: a #PangoFontFace.
+ * @face: a `PangoFontFace`.
  *
  * Gets a name representing the style of this face among the
- * different faces in the #PangoFontFamily for the face. The
+ * different faces in the `PangoFontFamily` for the face. The
  * name is suitable for displaying to users.
  *
  * Return value: the face name for the face. This string is
  *   owned by the face object and must not be modified or freed.
- **/
+ */
 const char *
 pango_font_face_get_face_name (PangoFontFace *face)
 {
@@ -2473,23 +2485,25 @@ pango_font_face_get_face_name (PangoFontFace *face)
 
 /**
  * pango_font_face_list_sizes:
- * @face: a #PangoFontFace.
+ * @face: a `PangoFontFace`.
  * @sizes: (out) (array length=n_sizes) (nullable) (optional):
  *         location to store a pointer to an array of int. This array
  *         should be freed with g_free().
  * @n_sizes: location to store the number of elements in @sizes
  *
- * List the available sizes for a font. This is only applicable to bitmap
- * fonts. For scalable fonts, stores %NULL at the location pointed to by
- * @sizes and 0 at the location pointed to by @n_sizes. The sizes returned
- * are in Pango units and are sorted in ascending order.
+ * List the available sizes for a font.
+ *
+ * This is only applicable to bitmap fonts. For scalable fonts, stores
+ * %NULL at the location pointed to by @sizes and 0 at the location pointed
+ * to by @n_sizes. The sizes returned are in Pango units and are sorted
+ * in ascending order.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_font_face_list_sizes (PangoFontFace  *face,
-                           int           **sizes,
-                           int            *n_sizes)
+                            int           **sizes,
+                            int            *n_sizes)
 {
   g_return_if_fail (PANGO_IS_FONT_FACE (face));
   g_return_if_fail (sizes == NULL || n_sizes != NULL);
@@ -2502,19 +2516,18 @@ pango_font_face_list_sizes (PangoFontFace  *face,
   else
     {
       if (sizes != NULL)
-       *sizes = NULL;
+        *sizes = NULL;
       *n_sizes = 0;
     }
 }
 
 /**
  * pango_font_face_get_family:
- * @face: a #PangoFontFace
+ * @face: a `PangoFontFace`
  *
- * Gets the #PangoFontFamily that @face
- * belongs to.
+ * Gets the `PangoFontFamily` that @face belongs to.
  *
- * Returns: (transfer none): the #PangoFontFamily
+ * Returns: (transfer none): the `PangoFontFamily`
  *
  * Since: 1.46
  */
@@ -2528,7 +2541,7 @@ pango_font_face_get_family (PangoFontFace *face)
 
 /**
  * pango_font_has_char:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @wc: a Unicode character
  *
  * Returns whether the font provides a glyph for this character.
@@ -2549,7 +2562,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)


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]