summaryrefslogtreecommitdiff
path: root/pango
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-19 08:02:49 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:36 -0500
commit848c25a1b102fa6363863a9adb9b14ee5215a4b4 (patch)
tree94722499512476354550c1e2a6e99f05ce6a1c44 /pango
parente6cfe18008b2c096c286ff35bdb3de01530a9713 (diff)
downloadpango-848c25a1b102fa6363863a9adb9b14ee5215a4b4.tar.gz
docs: Tweak attributes docs
Give doc comments summaries, etc.
Diffstat (limited to 'pango')
-rw-r--r--pango/pango-attributes.c52
-rw-r--r--pango/pango-attributes.h50
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
{