docs: Tweak attributes docs

Give doc comments summaries, etc.

2 files changed, 57 insertions, 45 deletions

diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index b607445a..32f373c7 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -47,8 +47,9 @@ 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 [func@attr_type_get_name].
+ * Allocate a new attribute type ID.
+ *
+ * The attribute type name can be accessed later by using [func@attr_type_get_name].
  *
  * Return value: the new type ID.
  */
@@ -79,8 +80,10 @@ 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
- * [func@attr_type_register].
+ * Fetches the attribute type name.
+ *
+ * The attribute type name is the string passed in when registering the type
+ * using [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.
@@ -681,9 +684,10 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1,
  * 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.
+ *
+ * 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].
@@ -734,8 +738,9 @@ 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`,
@@ -786,9 +791,10 @@ 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 [method@Pango.Attribute.destroy].
@@ -837,8 +843,10 @@ 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.
+ *
+ * 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].
@@ -965,6 +973,8 @@ pango_attr_shape_equal (const PangoAttribute *attr1,
  * @destroy_func: (allow-none): function to free @data when the
  *   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.
  *
@@ -1008,10 +1018,11 @@ pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
  * @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.
+ *
+ * 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].
@@ -1260,8 +1271,9 @@ 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`,
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index 5ef7a132..fccd4575 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -100,28 +100,29 @@ typedef struct _PangoAttrFontFeatures PangoAttrFontFeatures;
 /**
  * PangoAttrIterator:
  *
- * The `PangoAttrIterator` structure is used to represent an
- * iterator through a [struct@Pango.AttrList]. A new iterator
- * is created with [method@Pango.AttrList.get_iterator]. Once
- * the iterator is created, it can be advanced through the style
- * changes in the text using [method@Pango.AttrIterator.next].
- * At each style change, the range of the current style segment
- * and the attributes currently in effect can be queried.
+ * A `PangoAttrIterator` is used to iterate through a `PangoAttrList`.
+ *
+ * A new iterator is created with [method@Pango.AttrList.get_iterator].
+ * Once the iterator is created, it can be advanced through the style
+ * changes in the text using [method@Pango.AttrIterator.next]. At each
+ * style change, the range of the current style segment and the attributes
+ * currently in effect can be queried.
  */
 
 /**
  * PangoAttrList:
  *
- * The `PangoAttrList` structure represents a list of attributes
- * that apply to a section of text. The attributes are, in general,
- * allowed to overlap in an arbitrary fashion, however, if the
- * attributes are manipulated only through [method@Pango.AttrList.change],
- * the overlap between properties will meet stricter criteria.
+ * A `PangoAttrList` represents a list of attributes that apply to a section
+ * of text.
+ *
+ * The attributes in a `PangoAttrList` are, in general, allowed to overlap in
+ * an arbitrary fashion. However, if the attributes are manipulated only through
+ * [method@Pango.AttrList.change], the overlap between properties will meet
+ * stricter criteria.
  *
- * Since the `PangoAttrList` structure is stored as a linear list,
- * it is not suitable for storing attributes for large amounts
- * of text. In general, you should not use a single `PangoAttrList`
- * for more than one paragraph of text.
+ * Since the `PangoAttrList` structure is stored as a linear list, it is not
+ * suitable for storing attributes for large amounts of text. In general, you
+ * should not use a single `PangoAttrList` for more than one paragraph of text.
  */
 typedef struct _PangoAttrList     PangoAttrList;
 typedef struct _PangoAttrIterator PangoAttrIterator;
@@ -262,9 +263,8 @@ typedef enum {
 /**
  * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING:
  *
- * This value can be used to set the start_index member of a
- * `PangoAttribute` such that the attribute covers from the
- * beginning of the text.
+ * Value for @start_index in `PangoAttribute` that indicates
+ * the beginning of the text.
  *
  * Since: 1.24
  */
@@ -273,9 +273,8 @@ typedef enum {
 /**
  * PANGO_ATTR_INDEX_TO_TEXT_END: (value 4294967295)
  *
- * This value can be used to set the end_index member of a
- * `PangoAttribute` such that the attribute covers to the
- * end of the text.
+ * Value for @end_index in `PangoAttribute` that indicates
+ * the end of the text.
  *
  * Since: 1.24
  */
@@ -338,9 +337,10 @@ typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
  *   (see [method@Pango.Attribute.equal])
  *
  * The `PangoAttrClass` structure stores the type and operations for
- * a particular type of attribute. The functions in this structure should
- * not be called directly. Instead, one should use the wrapper functions
- * provided for `PangoAttribute`.
+ * a particular type of attribute.
+ *
+ * The functions in this structure should not be called directly. Instead,
+ * one should use the wrapper functions provided for `PangoAttribute`.
  */
 struct _PangoAttrClass
 {