Merge branch 'gi-docs' into 'master'

Gi docs

See merge request GNOME/pango!281

1 files changed, 424 insertions, 427 deletions

diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 8f23fe77..225dc654 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -10,7 +10,7 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -19,17 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:text-attributes
- * @short_description:Font and other attributes for annotating text
- * @title:Attributes
- *
- * Attributed text is used in a number of places in Pango. It
- * is used as the input to the itemization process and also when
- * creating a #PangoLayout. The data types and functions in
- * this section are used to represent and manipulate sets
- * of attributes applied to a portion of text.
- */
 #include "config.h"
 #include <string.h>
 
@@ -38,17 +27,17 @@
 #include "pango-impl-utils.h"
 
 static PangoAttribute *pango_attr_color_new         (const PangoAttrClass *klass,
-						     guint16               red,
-						     guint16               green,
-						     guint16               blue);
+                                                     guint16               red,
+                                                     guint16               green,
+                                                     guint16               blue);
 static PangoAttribute *pango_attr_string_new        (const PangoAttrClass *klass,
-						     const char           *str);
+                                                     const char           *str);
 static PangoAttribute *pango_attr_int_new           (const PangoAttrClass *klass,
-						     int                   value);
+                                                     int                   value);
 static PangoAttribute *pango_attr_float_new         (const PangoAttrClass *klass,
-						     double                value);
+                                                     double                value);
 static PangoAttribute *pango_attr_size_new_internal (int                   size,
-						     gboolean              absolute);
+                                                     gboolean              absolute);
 
 
 G_LOCK_DEFINE_STATIC (attr_type);
@@ -58,11 +47,12 @@ static GHashTable *name_map = NULL; /* MT-safe */
  * pango_attr_type_register:
  * @name: an identifier for the type
  *
- * Allocate a new attribute type ID.  The attribute type name can be accessed
- * later by using pango_attr_type_get_name().
+ * Allocate a new attribute type ID.
+ *
+ * The attribute type name can be accessed later by using [type_func@Pango.AttrType.get_name].
  *
  * Return value: the new type ID.
- **/
+ */
 PangoAttrType
 pango_attr_type_register (const gchar *name)
 {
@@ -76,7 +66,7 @@ pango_attr_type_register (const gchar *name)
   if (name)
     {
       if (G_UNLIKELY (!name_map))
-	name_map = g_hash_table_new (NULL, NULL);
+        name_map = g_hash_table_new (NULL, NULL);
 
       g_hash_table_insert (name_map, GUINT_TO_POINTER (type), (gpointer) g_intern_string (name));
     }
@@ -90,17 +80,19 @@ pango_attr_type_register (const gchar *name)
  * pango_attr_type_get_name:
  * @type: an attribute type ID to fetch the name for
  *
- * Fetches the attribute type name passed in when registering the type using
- * pango_attr_type_register().
+ * Fetches the attribute type name.
+ *
+ * The attribute type name is the string passed in when registering the type
+ * using [type_func@attr_type_register].
  *
  * The returned value is an interned string (see g_intern_string() for what
  * that means) that should not be modified or freed.
  *
  * Return value: (nullable): the type ID name (which may be %NULL), or
- * %NULL if @type is a built-in Pango attribute type or invalid.
+ *   %NULL if @type is a built-in Pango attribute type or invalid.
  *
  * Since: 1.22
- **/
+ */
 const char *
 pango_attr_type_get_name (PangoAttrType type)
 {
@@ -118,20 +110,19 @@ pango_attr_type_get_name (PangoAttrType type)
 
 /**
  * pango_attribute_init:
- * @attr: a #PangoAttribute
- * @klass: a #PangoAttrClass
+ * @attr: a `PangoAttribute`
+ * @klass: a `PangoAttrClass`
  *
- * Initializes @attr's klass to @klass,
- * it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
- * and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END
- * such that the attribute applies
+ * Initializes @attr's klass to @klass, it's start_index to
+ * %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to
+ * %PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies
  * to the entire text by default.
  *
  * Since: 1.20
- **/
+ */
 void
 pango_attribute_init (PangoAttribute       *attr,
-		      const PangoAttrClass *klass)
+                      const PangoAttrClass *klass)
 {
   g_return_if_fail (attr != NULL);
   g_return_if_fail (klass != NULL);
@@ -143,13 +134,13 @@ pango_attribute_init (PangoAttribute       *attr,
 
 /**
  * pango_attribute_copy:
- * @attr: a #PangoAttribute
+ * @attr: a `PangoAttribute`
  *
  * Make a copy of an attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attribute_copy (const PangoAttribute *attr)
 {
@@ -166,10 +157,10 @@ pango_attribute_copy (const PangoAttribute *attr)
 
 /**
  * pango_attribute_destroy:
- * @attr: a #PangoAttribute.
+ * @attr: a `PangoAttribute`.
  *
- * Destroy a #PangoAttribute and free all associated memory.
- **/
+ * Destroy a `PangoAttribute` and free all associated memory.
+ */
 void
 pango_attribute_destroy (PangoAttribute *attr)
 {
@@ -184,18 +175,18 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute,
 
 /**
  * pango_attribute_equal:
- * @attr1: a #PangoAttribute
- * @attr2: another #PangoAttribute
+ * @attr1: a `PangoAttribute`
+ * @attr2: another `PangoAttribute`
  *
  * Compare two attributes for equality. This compares only the
  * actual value of the two attributes and not the ranges that the
  * attributes apply to.
  *
  * Return value: %TRUE if the two attributes have the same value.
- **/
+ */
 gboolean
 pango_attribute_equal (const PangoAttribute *attr1,
-		       const PangoAttribute *attr2)
+                       const PangoAttribute *attr2)
 {
   g_return_val_if_fail (attr1 != NULL, FALSE);
   g_return_val_if_fail (attr2 != NULL, FALSE);
@@ -223,14 +214,14 @@ pango_attr_string_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_string_equal (const PangoAttribute *attr1,
-			 const PangoAttribute *attr2)
+                         const PangoAttribute *attr2)
 {
   return strcmp (((PangoAttrString *)attr1)->value, ((PangoAttrString *)attr2)->value) == 0;
 }
 
 static PangoAttribute *
 pango_attr_string_new (const PangoAttrClass *klass,
-		       const char           *str)
+                       const char           *str)
 {
   PangoAttrString *result = g_slice_new (PangoAttrString);
   pango_attribute_init (&result->attr, klass);
@@ -245,9 +236,9 @@ pango_attr_string_new (const PangoAttrClass *klass,
  *
  * Create a new font family attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_family_new (const char *family)
 {
@@ -279,7 +270,7 @@ pango_attr_language_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_language_equal (const PangoAttribute *attr1,
-			   const PangoAttribute *attr2)
+                           const PangoAttribute *attr2)
 {
   return ((PangoAttrLanguage *)attr1)->value == ((PangoAttrLanguage *)attr2)->value;
 }
@@ -290,9 +281,9 @@ pango_attr_language_equal (const PangoAttribute *attr1,
  *
  * Create a new language tag attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_language_new (PangoLanguage *language)
 {
@@ -318,9 +309,9 @@ pango_attr_color_copy (const PangoAttribute *attr)
   const PangoAttrColor *color_attr = (PangoAttrColor *)attr;
 
   return pango_attr_color_new (attr->klass,
-			       color_attr->color.red,
-			       color_attr->color.green,
-			       color_attr->color.blue);
+                               color_attr->color.red,
+                               color_attr->color.green,
+                               color_attr->color.blue);
 }
 
 static void
@@ -333,21 +324,21 @@ pango_attr_color_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_color_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrColor *color_attr1 = (const PangoAttrColor *)attr1;
   const PangoAttrColor *color_attr2 = (const PangoAttrColor *)attr2;
 
   return (color_attr1->color.red == color_attr2->color.red &&
-	  color_attr1->color.blue == color_attr2->color.blue &&
-	  color_attr1->color.green == color_attr2->color.green);
+          color_attr1->color.blue == color_attr2->color.blue &&
+          color_attr1->color.green == color_attr2->color.green);
 }
 
 static PangoAttribute *
 pango_attr_color_new (const PangoAttrClass *klass,
-		      guint16               red,
-		      guint16               green,
-		      guint16               blue)
+                      guint16               red,
+                      guint16               green,
+                      guint16               blue)
 {
   PangoAttrColor *result = g_slice_new (PangoAttrColor);
   pango_attribute_init (&result->attr, klass);
@@ -366,13 +357,13 @@ pango_attr_color_new (const PangoAttrClass *klass,
  *
  * Create a new foreground color attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_foreground_new (guint16 red,
-			   guint16 green,
-			   guint16 blue)
+                           guint16 green,
+                           guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_FOREGROUND,
@@ -392,13 +383,13 @@ pango_attr_foreground_new (guint16 red,
  *
  * Create a new background color attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_background_new (guint16 red,
-			   guint16 green,
-			   guint16 blue)
+                           guint16 green,
+                           guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_BACKGROUND,
@@ -428,7 +419,7 @@ pango_attr_int_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_int_equal (const PangoAttribute *attr1,
-		      const PangoAttribute *attr2)
+                      const PangoAttribute *attr2)
 {
   const PangoAttrInt *int_attr1 = (const PangoAttrInt *)attr1;
   const PangoAttrInt *int_attr2 = (const PangoAttrInt *)attr2;
@@ -438,7 +429,7 @@ pango_attr_int_equal (const PangoAttribute *attr1,
 
 static PangoAttribute *
 pango_attr_int_new (const PangoAttrClass *klass,
-		    int                   value)
+                    int                   value)
 {
   PangoAttrInt *result = g_slice_new (PangoAttrInt);
   pango_attribute_init (&result->attr, klass);
@@ -465,7 +456,7 @@ pango_attr_float_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_float_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrFloat *float_attr1 = (const PangoAttrFloat *)attr1;
   const PangoAttrFloat *float_attr2 = (const PangoAttrFloat *)attr2;
@@ -475,7 +466,7 @@ pango_attr_float_equal (const PangoAttribute *attr1,
 
 static PangoAttribute*
 pango_attr_float_new  (const PangoAttrClass *klass,
-		       double                value)
+                       double                value)
 {
   PangoAttrFloat *result = g_slice_new (PangoAttrFloat);
   pango_attribute_init (&result->attr, klass);
@@ -505,7 +496,7 @@ pango_attr_size_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_size_equal (const PangoAttribute *attr1,
-		       const PangoAttribute *attr2)
+                       const PangoAttribute *attr2)
 {
   const PangoAttrSize *size_attr1 = (const PangoAttrSize *)attr1;
   const PangoAttrSize *size_attr2 = (const PangoAttrSize *)attr2;
@@ -515,7 +506,7 @@ pango_attr_size_equal (const PangoAttribute *attr1,
 
 static PangoAttribute *
 pango_attr_size_new_internal (int size,
-			      gboolean absolute)
+                              gboolean absolute)
 {
   PangoAttrSize *result;
 
@@ -546,9 +537,9 @@ pango_attr_size_new_internal (int size,
  *
  * Create a new font-size attribute in fractional points.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_size_new (int size)
 {
@@ -561,11 +552,11 @@ pango_attr_size_new (int size)
  *
  * Create a new font-size attribute in device units.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_size_new_absolute (int size)
 {
@@ -578,9 +569,9 @@ pango_attr_size_new_absolute (int size)
  *
  * Create a new font slant style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_style_new (PangoStyle style)
 {
@@ -600,9 +591,9 @@ pango_attr_style_new (PangoStyle style)
  *
  * Create a new font weight attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_weight_new (PangoWeight weight)
 {
@@ -620,11 +611,11 @@ pango_attr_weight_new (PangoWeight weight)
  * pango_attr_variant_new:
  * @variant: the variant
  *
- * Create a new font variant attribute (normal or small caps)
+ * Create a new font variant attribute (normal or small caps).
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_variant_new (PangoVariant variant)
 {
@@ -642,11 +633,11 @@ pango_attr_variant_new (PangoVariant variant)
  * pango_attr_stretch_new:
  * @stretch: the stretch
  *
- * Create a new font stretch attribute
+ * Create a new font stretch attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_stretch_new (PangoStretch  stretch)
 {
@@ -679,27 +670,28 @@ pango_attr_font_desc_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_font_desc_equal (const PangoAttribute *attr1,
-			    const PangoAttribute *attr2)
+                            const PangoAttribute *attr2)
 {
   const PangoAttrFontDesc *desc_attr1 = (const PangoAttrFontDesc *)attr1;
   const PangoAttrFontDesc *desc_attr2 = (const PangoAttrFontDesc *)attr2;
 
   return pango_font_description_get_set_fields (desc_attr1->desc) ==
          pango_font_description_get_set_fields (desc_attr2->desc) &&
-	 pango_font_description_equal (desc_attr1->desc, desc_attr2->desc);
+         pango_font_description_equal (desc_attr1->desc, desc_attr2->desc);
 }
 
 /**
  * pango_attr_font_desc_new:
  * @desc: the font description
  *
- * Create a new font description attribute. This attribute
- * allows setting family, style, weight, variant, stretch,
- * and size simultaneously.
+ * Create a new font description attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * This attribute allows setting family, style, weight, variant,
+ * stretch, and size simultaneously.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_font_desc_new (const PangoFontDescription *desc)
 {
@@ -724,9 +716,9 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
  *
  * Create a new underline-style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_underline_new (PangoUnderline underline)
 {
@@ -746,19 +738,20 @@ pango_attr_underline_new (PangoUnderline underline)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new underline color attribute. This attribute
- * modifies the color of underlines. If not set, underlines
+ * Create a new underline color attribute.
+ *
+ * This attribute modifies the color of underlines. If not set, underlines
  * will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_underline_color_new (guint16 red,
-				guint16 green,
-				guint16 blue)
+                                guint16 green,
+                                guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_UNDERLINE_COLOR,
@@ -776,9 +769,9 @@ pango_attr_underline_color_new (guint16 red,
  *
  * Create a new strike-through attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_strikethrough_new (gboolean strikethrough)
 {
@@ -798,19 +791,20 @@ pango_attr_strikethrough_new (gboolean strikethrough)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new strikethrough color attribute. This attribute
- * modifies the color of strikethrough lines. If not set, strikethrough
- * lines will use the foreground color.
+ * Create a new strikethrough color attribute.
+ *
+ * This attribute modifies the color of strikethrough lines. If not set,
+ * strikethrough lines will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_strikethrough_color_new (guint16 red,
-				    guint16 green,
-				    guint16 blue)
+                                    guint16 green,
+                                    guint16 blue)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_STRIKETHROUGH_COLOR,
@@ -825,13 +819,13 @@ pango_attr_strikethrough_color_new (guint16 red,
 /**
  * pango_attr_rise_new:
  * @rise: the amount that the text should be displaced vertically,
- *        in Pango units. Positive values displace the text upwards.
+ *   in Pango units. Positive values displace the text upwards.
  *
  * Create a new baseline displacement attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_rise_new (int rise)
 {
@@ -849,12 +843,14 @@ pango_attr_rise_new (int rise)
  * pango_attr_scale_new:
  * @scale_factor: factor to scale the font
  *
- * Create a new font size scale attribute. The base font for the
- * affected text will have its size multiplied by @scale_factor.
+ * Create a new font size scale attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * The base font for the affected text will have its size multiplied
+ * by @scale_factor.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute*
 pango_attr_scale_new (double scale_factor)
 {
@@ -871,7 +867,7 @@ pango_attr_scale_new (double scale_factor)
 /**
  * pango_attr_fallback_new:
  * @enable_fallback: %TRUE if we should fall back on other fonts
- *                   for characters the active font is missing.
+ *   for characters the active font is missing.
  *
  * Create a new font fallback attribute.
  *
@@ -880,11 +876,11 @@ pango_attr_scale_new (double scale_factor)
  * other fonts on the system that might contain the characters in the
  * text.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.4
- **/
+ */
 PangoAttribute *
 pango_attr_fallback_new (gboolean enable_fallback)
 {
@@ -905,11 +901,11 @@ pango_attr_fallback_new (gboolean enable_fallback)
  *
  * Create a new letter-spacing attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.6
- **/
+ */
 PangoAttribute *
 pango_attr_letter_spacing_new (int letter_spacing)
 {
@@ -935,7 +931,7 @@ pango_attr_shape_copy (const PangoAttribute *attr)
     data = shape_attr->data;
 
   return pango_attr_shape_new_with_data (&shape_attr->ink_rect, &shape_attr->logical_rect,
-					 data, shape_attr->copy_func, shape_attr->destroy_func);
+                                         data, shape_attr->copy_func, shape_attr->destroy_func);
 }
 
 static void
@@ -951,48 +947,48 @@ pango_attr_shape_destroy (PangoAttribute *attr)
 
 static gboolean
 pango_attr_shape_equal (const PangoAttribute *attr1,
-			const PangoAttribute *attr2)
+                        const PangoAttribute *attr2)
 {
   const PangoAttrShape *shape_attr1 = (const PangoAttrShape *)attr1;
   const PangoAttrShape *shape_attr2 = (const PangoAttrShape *)attr2;
 
   return (shape_attr1->logical_rect.x == shape_attr2->logical_rect.x &&
-	  shape_attr1->logical_rect.y == shape_attr2->logical_rect.y &&
-	  shape_attr1->logical_rect.width == shape_attr2->logical_rect.width &&
-	  shape_attr1->logical_rect.height == shape_attr2->logical_rect.height &&
-	  shape_attr1->ink_rect.x == shape_attr2->ink_rect.x &&
-	  shape_attr1->ink_rect.y == shape_attr2->ink_rect.y &&
-	  shape_attr1->ink_rect.width == shape_attr2->ink_rect.width &&
-	  shape_attr1->ink_rect.height == shape_attr2->ink_rect.height &&
-	  shape_attr1->data == shape_attr2->data);
+          shape_attr1->logical_rect.y == shape_attr2->logical_rect.y &&
+          shape_attr1->logical_rect.width == shape_attr2->logical_rect.width &&
+          shape_attr1->logical_rect.height == shape_attr2->logical_rect.height &&
+          shape_attr1->ink_rect.x == shape_attr2->ink_rect.x &&
+          shape_attr1->ink_rect.y == shape_attr2->ink_rect.y &&
+          shape_attr1->ink_rect.width == shape_attr2->ink_rect.width &&
+          shape_attr1->ink_rect.height == shape_attr2->ink_rect.height &&
+          shape_attr1->data == shape_attr2->data);
 }
 
 /**
  * pango_attr_shape_new_with_data:
- * @ink_rect:     ink rectangle to assign to each character
+ * @ink_rect: ink rectangle to assign to each character
  * @logical_rect: logical rectangle to assign to each character
- * @data:         user data pointer
+ * @data: user data pointer
  * @copy_func: (allow-none): function to copy @data when the
- *                attribute is copied. If %NULL, @data is simply
- *                copied as a pointer.
+ *   attribute is copied. If %NULL, @data is simply copied as a pointer.
  * @destroy_func: (allow-none): function to free @data when the
- *                attribute is freed, or %NULL
+ *   attribute is freed, or %NULL
+ *
+ * Creates a new shape attribute.
  *
  * Like pango_attr_shape_new(), but a user data pointer is also
- * provided; this pointer can be accessed when later
- * rendering the glyph.
+ * provided; this pointer can be accessed when later rendering the glyph.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.8
- **/
+ */
 PangoAttribute *
 pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
-				const PangoRectangle  *logical_rect,
-				gpointer               data,
-				PangoAttrDataCopyFunc  copy_func,
-				GDestroyNotify         destroy_func)
+                                const PangoRectangle  *logical_rect,
+                                gpointer               data,
+                                PangoAttrDataCopyFunc  copy_func,
+                                GDestroyNotify         destroy_func)
 {
   static const PangoAttrClass klass = {
     PANGO_ATTR_SHAPE,
@@ -1019,26 +1015,27 @@ pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
 
 /**
  * pango_attr_shape_new:
- * @ink_rect:     ink rectangle to assign to each character
+ * @ink_rect: ink rectangle to assign to each character
  * @logical_rect: logical rectangle to assign to each character
  *
- * Create a new shape attribute. A shape is used to impose a
- * particular ink and logical rectangle on the result of shaping a
- * particular glyph. This might be used, for instance, for
- * embedding a picture or a widget inside a #PangoLayout.
+ * Create a new shape attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
- **/
+ * A shape is used to impose a particular ink and logical rectangle
+ * on the result of shaping a particular glyph. This might be used,
+ * for instance, for embedding a picture or a widget inside a `PangoLayout`.
+ *
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
+ */
 PangoAttribute *
 pango_attr_shape_new (const PangoRectangle *ink_rect,
-		      const PangoRectangle *logical_rect)
+                      const PangoRectangle *logical_rect)
 {
   g_return_val_if_fail (ink_rect != NULL, NULL);
   g_return_val_if_fail (logical_rect != NULL, NULL);
 
   return pango_attr_shape_new_with_data (ink_rect, logical_rect,
-					 NULL, NULL, NULL);
+                                         NULL, NULL, NULL);
 }
 
 /**
@@ -1047,11 +1044,11 @@ pango_attr_shape_new (const PangoRectangle *ink_rect,
  *
  * Create a new gravity attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.16
- **/
+ */
 PangoAttribute *
 pango_attr_gravity_new (PangoGravity gravity)
 {
@@ -1073,11 +1070,11 @@ pango_attr_gravity_new (PangoGravity gravity)
  *
  * Create a new gravity hint attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.16
- **/
+ */
 PangoAttribute *
 pango_attr_gravity_hint_new (PangoGravityHint hint)
 {
@@ -1097,11 +1094,11 @@ pango_attr_gravity_hint_new (PangoGravityHint hint)
  *
  * Create a new font features tag attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
- **/
+ */
 PangoAttribute *
 pango_attr_font_features_new (const gchar *features)
 {
@@ -1123,8 +1120,8 @@ pango_attr_font_features_new (const gchar *features)
  *
  * Create a new foreground alpha attribute.
  *
- * Return value: (transfer full): the new allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
  */
@@ -1147,8 +1144,8 @@ pango_attr_foreground_alpha_new (guint16 alpha)
  *
  * Create a new background alpha attribute.
  *
- * Return value: (transfer full): the new allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.38
  */
@@ -1174,8 +1171,8 @@ pango_attr_background_alpha_new (guint16 alpha)
  * If breaks are disabled, the range will be kept in a
  * single run, as far as possible.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy()
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  */
@@ -1201,8 +1198,8 @@ pango_attr_allow_breaks_new (gboolean allow_breaks)
  * Pango will insert hyphens when breaking lines in the middle
  * of a word. This attribute can be used to suppress the hyphen.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy()
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  */
@@ -1221,13 +1218,13 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens)
 
 /**
  * pango_attr_show_new:
- * @flags: #PangoShowFlags to apply
+ * @flags: `PangoShowFlags` to apply
  *
  * Create a new attribute that influences how invisible
  * characters are rendered.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.44
  **/
@@ -1250,11 +1247,11 @@ pango_attr_show_new (PangoShowFlags flags)
  *
  * Create a new overline-style attribute.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.46
- **/
+ */
 PangoAttribute *
 pango_attr_overline_new (PangoOverline overline)
 {
@@ -1274,15 +1271,16 @@ pango_attr_overline_new (PangoOverline overline)
  * @green: the green value
  * @blue: the blue value
  *
- * Create a new overline color attribute. This attribute
- * modifies the color of overlines. If not set, overlines
+ * Create a new overline color attribute.
+ *
+ * This attribute modifies the color of overlines. If not set, overlines
  * will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated #PangoAttribute,
- *               which should be freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttribute`,
+ *   which should be freed with [method@Pango.Attribute.destroy].
  *
  * Since: 1.46
- **/
+ */
 PangoAttribute *
 pango_attr_overline_color_new (guint16 red,
                                guint16 green,
@@ -1318,9 +1316,9 @@ _pango_attr_list_init (PangoAttrList *list)
  *
  * Create a new empty attribute list with a reference count of one.
  *
- * Return value: (transfer full): the newly allocated #PangoAttrList,
- *               which should be freed with pango_attr_list_unref().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttrList`,
+ *   which should be freed with [method@Pango.AttrList.unref].
+ */
 PangoAttrList *
 pango_attr_list_new (void)
 {
@@ -1333,14 +1331,14 @@ pango_attr_list_new (void)
 
 /**
  * pango_attr_list_ref:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Increase the reference count of the given attribute list by one.
  *
  * Return value: The attribute list passed in
  *
  * Since: 1.10
- **/
+ */
 PangoAttrList *
 pango_attr_list_ref (PangoAttrList *list)
 {
@@ -1372,12 +1370,12 @@ _pango_attr_list_destroy (PangoAttrList *list)
 
 /**
  * pango_attr_list_unref:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Decrease the reference count of the given attribute list by one.
  * If the result is zero, free the attribute list and the attributes
  * it contains.
- **/
+ */
 void
 pango_attr_list_unref (PangoAttrList *list)
 {
@@ -1395,15 +1393,14 @@ pango_attr_list_unref (PangoAttrList *list)
 
 /**
  * pango_attr_list_copy:
- * @list: (nullable): a #PangoAttrList, may be %NULL
+ * @list: (nullable): a `PangoAttrList`, may be %NULL
  *
  * Copy @list and return an identical new list.
  *
- * Return value: (nullable): the newly allocated #PangoAttrList, with a
- *               reference count of one, which should
- *               be freed with pango_attr_list_unref().
- *               Returns %NULL if @list was %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoAttrList`,
+ *   with a reference count of one, which should be freed with
+ *   [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL.
+ */
 PangoAttrList *
 pango_attr_list_copy (PangoAttrList *list)
 {
@@ -1423,8 +1420,8 @@ pango_attr_list_copy (PangoAttrList *list)
 
 static void
 pango_attr_list_insert_internal (PangoAttrList  *list,
-				 PangoAttribute *attr,
-				 gboolean        before)
+                                 PangoAttribute *attr,
+                                 gboolean        before)
 {
   const guint start_index = attr->start_index;
   PangoAttribute *last_attr;
@@ -1467,17 +1464,18 @@ pango_attr_list_insert_internal (PangoAttrList  *list,
 
 /**
  * pango_attr_list_insert:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * be inserted after all other attributes with a matching
- * @start_index.
- **/
+ * Insert the given attribute into the `PangoAttrList`.
+ *
+ * It will be inserted after all other attributes with a
+ * matching @start_index.
+ */
 void
 pango_attr_list_insert (PangoAttrList  *list,
-			PangoAttribute *attr)
+                        PangoAttribute *attr)
 {
   g_return_if_fail (list != NULL);
   g_return_if_fail (attr != NULL);
@@ -1487,17 +1485,18 @@ pango_attr_list_insert (PangoAttrList  *list,
 
 /**
  * pango_attr_list_insert_before:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * be inserted before all other attributes with a matching
- * @start_index.
- **/
+ * Insert the given attribute into the `PangoAttrList`.
+ *
+ * It will be inserted before all other attributes with a
+ * matching @start_index.
+ */
 void
 pango_attr_list_insert_before (PangoAttrList  *list,
-			       PangoAttribute *attr)
+                               PangoAttribute *attr)
 {
   g_return_if_fail (list != NULL);
   g_return_if_fail (attr != NULL);
@@ -1507,20 +1506,21 @@ pango_attr_list_insert_before (PangoAttrList  *list,
 
 /**
  * pango_attr_list_change:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @attr: (transfer full): the attribute to insert. Ownership of this
- *        value is assumed by the list.
+ *   value is assumed by the list.
+ *
+ * Insert the given attribute into the `PangoAttrList`.
  *
- * Insert the given attribute into the #PangoAttrList. It will
- * replace any attributes of the same type on that segment
+ * It will replace any attributes of the same type on that segment
  * and be merged with any adjoining attributes that are identical.
  *
- * This function is slower than pango_attr_list_insert() for
- * creating an attribute list in order (potentially much slower
- * for large lists). However, pango_attr_list_insert() is not
- * suitable for continually changing a set of attributes
- * since it never removes or combines existing attributes.
- **/
+ * This function is slower than [method@Pango.AttrList.insert] for
+ * creating an attribute list in order (potentially much slower for
+ * large lists). However, [method@Pango.AttrList.insert] is not
+ * suitable for continually changing a set of attributes since it
+ * never removes or combines existing attributes.
+ */
 void
 pango_attr_list_change (PangoAttrList  *list,
                         PangoAttribute *attr)
@@ -1665,27 +1665,25 @@ pango_attr_list_change (PangoAttrList  *list,
 
 /**
  * pango_attr_list_update:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @pos: the position of the change
  * @remove: the number of removed bytes
  * @add: the number of added bytes
  *
- * Update indices of attributes in @list for
- * a change in the text they refer to.
+ * Update indices of attributes in @list for a change in the
+ * text they refer to.
  *
- * The change that this function applies is
- * removing @remove bytes at position @pos
- * and inserting @add bytes instead.
+ * The change that this function applies is removing @remove
+ * bytes at position @pos and inserting @add bytes instead.
  *
- * Attributes that fall entirely in the
- * (@pos, @pos + @remove) range are removed.
+ * Attributes that fall entirely in the (@pos, @pos + @remove)
+ * range are removed.
  *
- * Attributes that start or end inside the
- * (@pos, @pos + @remove) range are shortened to
- * reflect the removal.
+ * Attributes that start or end inside the (@pos, @pos + @remove)
+ * range are shortened to reflect the removal.
  *
- * Attributes start and end positions are updated
- * if they are behind @pos + @remove.
+ * Attributes start and end positions are updated if they are
+ * behind @pos + @remove.
  *
  * Since: 1.44
  */
@@ -1743,29 +1741,30 @@ pango_attr_list_update (PangoAttrList *list,
 
 /**
  * pango_attr_list_splice:
- * @list: a #PangoAttrList
- * @other: another #PangoAttrList
+ * @list: a `PangoAttrList`
+ * @other: another `PangoAttrList`
  * @pos: the position in @list at which to insert @other
  * @len: the length of the spliced segment. (Note that this
- *       must be specified since the attributes in @other
- *       may only be present at some subsection of this range)
+ *   must be specified since the attributes in @other may only
+ *   be present at some subsection of this range)
  *
- * This function opens up a hole in @list, fills it in with attributes from
- * the left, and then merges @other on top of the hole.
+ * This function opens up a hole in @list, fills it in with attributes
+ * from the left, and then merges @other on top of the hole.
  *
  * This operation is equivalent to stretching every attribute
  * that applies at position @pos in @list by an amount @len,
- * and then calling pango_attr_list_change() with a copy
- * of each attribute in @other in sequence (offset in position by @pos).
+ * and then calling [method@Pango.AttrList.change] with a copy
+ * of each attribute in @other in sequence (offset in position
+ * by @pos).
  *
  * This operation proves useful for, for instance, inserting
  * a pre-edit string in the middle of an edit buffer.
- **/
+ */
 void
 pango_attr_list_splice (PangoAttrList *list,
-			PangoAttrList *other,
-			gint           pos,
-			gint           len)
+                        PangoAttrList *other,
+                        gint           pos,
+                        gint           len)
 {
   guint i, p;
   guint upos, ulen;
@@ -1827,13 +1826,13 @@ pango_attr_list_splice (PangoAttrList *list,
 
 /**
  * pango_attr_list_get_attributes:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
  * Gets a list of all attributes in @list.
  *
  * Return value: (element-type Pango.Attribute) (transfer full):
  *   a list of all attributes in @list. To free this value, call
- *   pango_attribute_destroy() on each value and g_slist_free()
+ *   [mehod@Pango.Attribute.destroy] on each value and g_slist_free()
  *   on the list.
  *
  * Since: 1.44
@@ -1861,8 +1860,8 @@ pango_attr_list_get_attributes (PangoAttrList *list)
 
 /**
  * pango_attr_list_equal:
- * @list: a #PangoAttrList
- * @other_list: the other #PangoAttrList
+ * @list: a `PangoAttrList`
+ * @other_list: the other `PangoAttrList`
  *
  * Checks whether @list and @other_list contain the same attributes and
  * whether those attributes apply to the same ranges. Beware that this
@@ -1956,13 +1955,13 @@ _pango_attr_list_get_iterator (PangoAttrList     *list,
 
 /**
  * pango_attr_list_get_iterator:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
  * Create a iterator initialized to the beginning of the list.
  * @list must not be modified until this iterator is freed.
  *
- * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should
- *               be freed with pango_attr_iterator_destroy().
+ * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
+ *   which should be freed with [method@Pango.AttrIterator.destroy].
  **/
 PangoAttrIterator *
 pango_attr_list_get_iterator (PangoAttrList  *list)
@@ -1985,14 +1984,14 @@ pango_attr_list_get_iterator (PangoAttrList  *list)
  *
  * Get the range of the current segment. Note that the
  * stored return values are signed, not unsigned like
- * the values in #PangoAttribute. To deal with this API
+ * the values in `PangoAttribute`. To deal with this API
  * oversight, stored return values that wouldn't fit into
  * a signed integer are clamped to %G_MAXINT.
- **/
+ */
 void
 pango_attr_iterator_range (PangoAttrIterator *iterator,
-			   gint              *start,
-			   gint              *end)
+                           gint              *start,
+                           gint              *end)
 {
   g_return_if_fail (iterator != NULL);
 
@@ -2004,12 +2003,13 @@ pango_attr_iterator_range (PangoAttrIterator *iterator,
 
 /**
  * pango_attr_iterator_next:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a `PangoAttrIterator`
  *
  * Advance the iterator until the next change of style.
  *
- * Return value: %FALSE if the iterator is at the end of the list, otherwise %TRUE
- **/
+ * Return value: %FALSE if the iterator is at the end of the list,
+ *   otherwise %TRUE
+ */
 gboolean
 pango_attr_iterator_next (PangoAttrIterator *iterator)
 {
@@ -2074,14 +2074,13 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_copy:
- * @iterator: a #PangoAttrIterator.
+ * @iterator: a `PangoAttrIterator`
  *
- * Copy a #PangoAttrIterator
+ * Copy a `PangoAttrIterator`.
  *
- * Return value: (transfer full): the newly allocated
- *               #PangoAttrIterator, which should be freed with
- *               pango_attr_iterator_destroy().
- **/
+ * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
+ *   which should be freed with [method@Pango.AttrIterator.destroy].
+ */
 PangoAttrIterator *
 pango_attr_iterator_copy (PangoAttrIterator *iterator)
 {
@@ -2110,10 +2109,10 @@ _pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_destroy:
- * @iterator: a #PangoAttrIterator.
+ * @iterator: a `PangoAttrIterator`
  *
- * Destroy a #PangoAttrIterator and free all associated memory.
- **/
+ * Destroy a `PangoAttrIterator` and free all associated memory.
+ */
 void
 pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 {
@@ -2125,21 +2124,21 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator)
 
 /**
  * pango_attr_iterator_get:
- * @iterator: a #PangoAttrIterator
- * @type: the type of attribute to find.
+ * @iterator: a `PangoAttrIterator`
+ * @type: the type of attribute to find
  *
  * Find the current attribute of a particular type at the iterator
  * location. When multiple attributes of the same type overlap,
  * the attribute whose range starts closest to the current location
  * is used.
  *
- * Return value: (nullable) (transfer none): the current attribute of the given type,
- *               or %NULL if no attribute of that type applies to the
- *               current location.
- **/
+ * Return value: (nullable) (transfer none): the current attribute of
+ *   the given type, or %NULL if no attribute of that type applies to
+ *   the current location.
+ */
 PangoAttribute *
 pango_attr_iterator_get (PangoAttrIterator *iterator,
-			 PangoAttrType      type)
+                         PangoAttrType      type)
 {
   int i;
 
@@ -2161,29 +2160,28 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
 
 /**
  * pango_attr_iterator_get_font:
- * @iterator: a #PangoAttrIterator
- * @desc: a #PangoFontDescription to fill in with the current values.
- *        The family name in this structure will be set using
- *        pango_font_description_set_family_static() using values from
- *        an attribute in the #PangoAttrList associated with the iterator,
- *        so if you plan to keep it around, you must call:
- *        <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>.
- * @language: (allow-none): if non-%NULL, location to store language tag for item, or %NULL
- *            if none is found.
- * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): if non-%NULL,
- *           location in which to store a list of non-font
- *           attributes at the the current position; only the highest priority
- *           value of each attribute will be added to this list. In order
- *           to free this value, you must call pango_attribute_destroy() on
- *           each member.
+ * @iterator: a `PangoAttrIterator`
+ * @desc: a `PangoFontDescription` to fill in with the current values.
+ *   The family name in this structure will be set using
+ *   [method@Pango.FontDescription.set_family_static] using values from
+ *   an attribute in the `PangoAttrList` associated with the iterator,
+ *   so if you plan to keep it around, you must call:
+ *   pango_font_description_set_family (desc, pango_font_description_get_family (desc)).
+ * @language: (allow-none): if non-%NULL, location to store language tag
+ *   for item, or %NULL if none is found.
+ * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full):
+ *   if non-%NULL, location in which to store a list of non-font attributes
+ *   at the the current position; only the highest priority value of each
+ *   attribute will be added to this list. In order to free this value, you
+ *   must call [method@Pango.Attribute.destroy] on each member.
  *
  * Get the font and other attributes at the current iterator position.
- **/
+ */
 void
 pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
-			      PangoFontDescription  *desc,
-			      PangoLanguage        **language,
-			      GSList               **extra_attrs)
+                              PangoFontDescription  *desc,
+                              PangoLanguage        **language,
+                              GSList               **extra_attrs)
 {
   PangoFontMask mask = 0;
   gboolean have_language = FALSE;
@@ -2208,91 +2206,91 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
       const PangoAttribute *attr = g_ptr_array_index (iterator->attribute_stack, i);
 
       switch ((int) attr->klass->type)
-	{
-	case PANGO_ATTR_FONT_DESC:
-	  {
-	    PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask;
-	    mask |= new_mask;
-	    pango_font_description_unset_fields (desc, new_mask);
-	    pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE);
-
-	    break;
-	  }
-	case PANGO_ATTR_FAMILY:
-	  if (!(mask & PANGO_FONT_MASK_FAMILY))
-	    {
-	      mask |= PANGO_FONT_MASK_FAMILY;
-	      pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_STYLE:
-	  if (!(mask & PANGO_FONT_MASK_STYLE))
-	    {
-	      mask |= PANGO_FONT_MASK_STYLE;
-	      pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_VARIANT:
-	  if (!(mask & PANGO_FONT_MASK_VARIANT))
-	    {
-	      mask |= PANGO_FONT_MASK_VARIANT;
-	      pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_WEIGHT:
-	  if (!(mask & PANGO_FONT_MASK_WEIGHT))
-	    {
-	      mask |= PANGO_FONT_MASK_WEIGHT;
-	      pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_STRETCH:
-	  if (!(mask & PANGO_FONT_MASK_STRETCH))
-	    {
-	      mask |= PANGO_FONT_MASK_STRETCH;
-	      pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value);
-	    }
-	  break;
-	case PANGO_ATTR_SIZE:
-	  if (!(mask & PANGO_FONT_MASK_SIZE))
-	    {
-	      mask |= PANGO_FONT_MASK_SIZE;
-	      pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size);
-	    }
-	  break;
-	case PANGO_ATTR_ABSOLUTE_SIZE:
-	  if (!(mask & PANGO_FONT_MASK_SIZE))
-	    {
-	      mask |= PANGO_FONT_MASK_SIZE;
-	      pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size);
-	    }
-	  break;
-	case PANGO_ATTR_SCALE:
-	  if (!have_scale)
-	    {
-	      have_scale = TRUE;
-	      scale = ((PangoAttrFloat *)attr)->value;
-	    }
-	  break;
-	case PANGO_ATTR_LANGUAGE:
-	  if (language)
-	    {
-	      if (!have_language)
-		{
-		  have_language = TRUE;
-		  *language = ((PangoAttrLanguage *)attr)->value;
-		}
-	    }
-	  break;
-	default:
-	  if (extra_attrs)
-	    {
-	      gboolean found = FALSE;
-
-	      /* Hack: special-case FONT_FEATURES.  We don't want them to
-	       * override each other, so we never merge them.  This should
-	       * be fixed when we implement attr-merging. */
-	      if (attr->klass->type != PANGO_ATTR_FONT_FEATURES)
+        {
+        case PANGO_ATTR_FONT_DESC:
+          {
+            PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask;
+            mask |= new_mask;
+            pango_font_description_unset_fields (desc, new_mask);
+            pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE);
+
+            break;
+          }
+        case PANGO_ATTR_FAMILY:
+          if (!(mask & PANGO_FONT_MASK_FAMILY))
+            {
+              mask |= PANGO_FONT_MASK_FAMILY;
+              pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_STYLE:
+          if (!(mask & PANGO_FONT_MASK_STYLE))
+            {
+              mask |= PANGO_FONT_MASK_STYLE;
+              pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_VARIANT:
+          if (!(mask & PANGO_FONT_MASK_VARIANT))
+            {
+              mask |= PANGO_FONT_MASK_VARIANT;
+              pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_WEIGHT:
+          if (!(mask & PANGO_FONT_MASK_WEIGHT))
+            {
+              mask |= PANGO_FONT_MASK_WEIGHT;
+              pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_STRETCH:
+          if (!(mask & PANGO_FONT_MASK_STRETCH))
+            {
+              mask |= PANGO_FONT_MASK_STRETCH;
+              pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value);
+            }
+          break;
+        case PANGO_ATTR_SIZE:
+          if (!(mask & PANGO_FONT_MASK_SIZE))
+            {
+              mask |= PANGO_FONT_MASK_SIZE;
+              pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size);
+            }
+          break;
+        case PANGO_ATTR_ABSOLUTE_SIZE:
+          if (!(mask & PANGO_FONT_MASK_SIZE))
+            {
+              mask |= PANGO_FONT_MASK_SIZE;
+              pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size);
+            }
+          break;
+        case PANGO_ATTR_SCALE:
+          if (!have_scale)
+            {
+              have_scale = TRUE;
+              scale = ((PangoAttrFloat *)attr)->value;
+            }
+          break;
+        case PANGO_ATTR_LANGUAGE:
+          if (language)
+            {
+              if (!have_language)
+                {
+                  have_language = TRUE;
+                  *language = ((PangoAttrLanguage *)attr)->value;
+                }
+            }
+          break;
+        default:
+          if (extra_attrs)
+            {
+              gboolean found = FALSE;
+
+              /* Hack: special-case FONT_FEATURES.  We don't want them to
+               * override each other, so we never merge them.  This should
+               * be fixed when we implement attr-merging. */
+              if (attr->klass->type != PANGO_ATTR_FONT_FEATURES)
                 {
                   GSList *tmp_list = *extra_attrs;
                   while (tmp_list)
@@ -2308,10 +2306,10 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
                     }
                 }
 
-	      if (!found)
-		*extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr));
-	    }
-	}
+              if (!found)
+                *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr));
+            }
+        }
     }
 
   if (have_scale)
@@ -2325,24 +2323,23 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
 
 /**
  * pango_attr_list_filter:
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  * @func: (scope call) (closure data): callback function; returns %TRUE
  *        if an attribute should be filtered out.
  * @data: (closure): Data to be passed to @func
  *
- * Given a #PangoAttrList and callback function, removes any elements
- * of @list for which @func returns %TRUE and inserts them into
- * a new list.
+ * Given a `PangoAttrList` and callback function, removes any elements
+ * of @list for which @func returns %TRUE and inserts them into a new list.
  *
- * Return value: (transfer full) (nullable): the new #PangoAttrList or
+ * Return value: (transfer full) (nullable): the new `PangoAttrList` or
  *  %NULL if no attributes of the given types were found.
  *
  * Since: 1.2
- **/
+ */
 PangoAttrList *
 pango_attr_list_filter (PangoAttrList       *list,
-			PangoAttrFilterFunc  func,
-			gpointer             data)
+                        PangoAttrFilterFunc  func,
+                        gpointer             data)
 
 {
   PangoAttrList *new = NULL;
@@ -2378,18 +2375,18 @@ pango_attr_list_filter (PangoAttrList       *list,
 
 /**
  * pango_attr_iterator_get_attrs:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a `PangoAttrIterator`
  *
  * Gets a list of all attributes at the current position of the
  * iterator.
  *
- * Return value: (element-type Pango.Attribute) (transfer full): a list of
- *   all attributes for the current range.
- *   To free this value, call pango_attribute_destroy() on
- *   each value and g_slist_free() on the list.
+ * Return value: (element-type Pango.Attribute) (transfer full):
+ *   a list of all attributes for the current range. To free this value,
+ *   call [method@Pango.Attribute.destroy] on each value and g_slist_free()
+ *   on the list.
  *
  * Since: 1.2
- **/
+ */
 GSList *
 pango_attr_iterator_get_attrs (PangoAttrIterator *iterator)
 {
@@ -2407,17 +2404,17 @@ pango_attr_iterator_get_attrs (PangoAttrIterator *iterator)
       gboolean found = FALSE;
 
       for (tmp_list2 = attrs; tmp_list2; tmp_list2 = tmp_list2->next)
-	{
-	  PangoAttribute *old_attr = tmp_list2->data;
+        {
+          PangoAttribute *old_attr = tmp_list2->data;
           if (attr->klass->type == old_attr->klass->type)
             {
               found = TRUE;
               break;
             }
-	}
+        }
 
       if (!found)
-	attrs = g_slist_prepend (attrs, pango_attribute_copy (attr));
+        attrs = g_slist_prepend (attrs, pango_attribute_copy (attr));
     }
 
   return attrs;