docs: Tweak font docs

Give doc comments summaries, etc.

2 files changed, 135 insertions, 71 deletions

diff --git a/pango/fonts.c b/pango/fonts.c
index 1ab6e816..8323760f 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -96,7 +96,9 @@ pango_font_description_new (void)
  * @desc: a `PangoFontDescription`.
  * @family: a string representing the family name.
  *
- * Sets the family name field of a font description. The family
+ * 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
@@ -118,7 +120,9 @@ pango_font_description_set_family (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  * @family: a string representing the family name
  *
- * Like [method@Pango.FontDescription.set_family], except that no
+ * Sets the family name field of a font description, without copying the string.
+ *
+ * This is 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
@@ -155,6 +159,7 @@ pango_font_description_set_family_static (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`.
  *
  * 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
@@ -200,6 +205,7 @@ pango_font_description_set_style (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Gets the style field of a `PangoFontDescription`.
+ *
  * See [method@Pango.FontDescription.set_style].
  *
  * Return value: the style field for the font description.
@@ -219,8 +225,9 @@ pango_font_description_get_style (const PangoFontDescription *desc)
  * @desc: a `PangoFontDescription`
  * @variant: the variant type for the font description.
  *
- * Sets the variant field of a font description. The
- * [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL
+ * Sets the variant field of a font description.
+ *
+ * The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL
  * or %PANGO_VARIANT_SMALL_CAPS.
  */
 void
@@ -238,6 +245,7 @@ pango_font_description_set_variant (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`.
  *
  * Gets the variant field of a `PangoFontDescription`.
+ *
  * See [method@Pango.FontDescription.set_variant].
  *
  * Return value: the variant field for the font description.
@@ -257,7 +265,9 @@ pango_font_description_get_variant (const PangoFontDescription *desc)
  * @desc: a `PangoFontDescription`
  * @weight: the weight for the font description.
  *
- * Sets the weight field of a font description. The weight field
+ * 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 [enum@Pango.Weight] enumeration, other
  * intermediate numeric values are possible.
@@ -277,6 +287,7 @@ pango_font_description_set_weight (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Gets the weight field of a font description.
+ *
  * See [method@Pango.FontDescription.set_weight].
  *
  * Return value: the weight field for the font description.
@@ -296,8 +307,9 @@ pango_font_description_get_weight (const PangoFontDescription *desc)
  * @desc: a `PangoFontDescription`
  * @stretch: the stretch for the font description
  *
- * Sets the stretch field of a font description. The
- * [enum@Pango.Stretch] field specifies how narrow or
+ * Sets the stretch field of a font description.
+ *
+ * The [enum@Pango.Stretch] field specifies how narrow or
  * wide the font should be.
  */
 void
@@ -315,6 +327,7 @@ pango_font_description_set_stretch (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`.
  *
  * Gets the stretch field of a font description.
+ *
  * See [method@Pango.FontDescription.set_stretch].
  *
  * Return value: the stretch field for the font description.
@@ -342,6 +355,7 @@ pango_font_description_get_stretch (const PangoFontDescription *desc)
  *   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].
  */
@@ -362,6 +376,7 @@ pango_font_description_set_size (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Gets the size field of a font description.
+ *
  * See [method@Pango.FontDescription.set_size].
  *
  * Return value: the size field for the font description in points
@@ -388,6 +403,7 @@ pango_font_description_get_size (const PangoFontDescription *desc)
  *   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 [method@Pango.FontDescription.set_size]
  * which sets the font size in points.
  *
@@ -410,7 +426,9 @@ pango_font_description_set_absolute_size (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Determines whether the size of the font is in points (not absolute)
- * or device units (absolute). See [method@Pango.FontDescription.set_size]
+ * 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
@@ -433,7 +451,9 @@ pango_font_description_get_size_is_absolute (const PangoFontDescription *desc)
  * @desc: a `PangoFontDescription`
  * @gravity: the gravity for the font description.
  *
- * Sets the gravity field of a font description. The gravity field
+ * Sets the gravity field of a font description.
+ *
+ * The gravity field
  * specifies how the glyphs should be rotated. If @gravity is
  * %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on
  * the font description.
@@ -464,6 +484,7 @@ pango_font_description_set_gravity (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Gets the gravity field of a font description.
+ *
  * See [method@Pango.FontDescription.set_gravity].
  *
  * Return value: the gravity field for the font description.
@@ -485,8 +506,10 @@ pango_font_description_get_gravity (const PangoFontDescription *desc)
  * @desc: a `PangoFontDescription`
  * @variations: a string representing the variations
  *
- * Like [method@Pango.FontDescription.set_variations], except that
- * no copy of @variations is made. The caller must make sure that
+ * Sets the variations field of a font description.
+ *
+ * This is 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,
@@ -525,9 +548,10 @@ pango_font_description_set_variations_static (PangoFontDescription *desc,
  * @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.
+ * 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
  *
@@ -558,6 +582,7 @@ pango_font_description_set_variations (PangoFontDescription *desc,
  * @desc: a `PangoFontDescription`
  *
  * Gets the variations field of a font description.
+ *
  * See [method@Pango.FontDescription.set_variations].
  *
  * Return value: (nullable): the variations field for the font
@@ -597,6 +622,7 @@ pango_font_description_get_set_fields (const PangoFontDescription *desc)
  * @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.
  */
 void
@@ -625,7 +651,9 @@ pango_font_description_unset_fields (PangoFontDescription *desc,
  *   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.
  *
@@ -670,7 +698,10 @@ pango_font_description_merge (PangoFontDescription       *desc,
  *   corresponding values from @desc_to_merge, even if they
  *   are already exist.
  *
- * Like [method@Pango.FontDescription.merge], but only a shallow copy
+ * Merges the fields that are set in @desc_to_merge into the fields in
+ * @desc, without copying allocated fields.
+ *
+ * This is 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.
@@ -812,8 +843,11 @@ pango_font_description_copy (const PangoFontDescription *desc)
  * pango_font_description_copy_static:
  * @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
+ * Make a copy of a `PangoFontDescription`, but don't duplicate
+ * allocated fields.
+ *
+ * This is 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.
  *
@@ -898,9 +932,10 @@ case_insensitive_hash (const char *key)
  * pango_font_description_hash:
  * @desc: a `PangoFontDescription`
  *
- * 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.
+ * Computes a hash of a `PangoFontDescription` structure.
+ *
+ * This is 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.
  */
@@ -1212,8 +1247,9 @@ parse_variations (const char  *word,
  * pango_font_description_from_string:
  * @str: string representation of a font description.
  *
- * Creates a new font description from a string representation in the
- * form
+ * Creates a new font description from a string representation.
+ *
+ * The string must have the form
  *
  *     "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]",
  *
@@ -1560,8 +1596,10 @@ parse_field (const char *what,
  * @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",
- * "italic" and "oblique", case variations being
+ * Parses a font style.
+ *
+ * The allowed values are "normal", "italic" and "oblique", case
+ * variations being
  * ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
@@ -1580,9 +1618,10 @@ pango_parse_style (const char *str,
  * @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"
- * and "smallcaps" or "small_caps", case variations being
- * ignored.
+ * Parses a font variant.
+ *
+ * The allowed values are "normal" and "smallcaps" or "small_caps",
+ * case variations being ignored.
  *
  * Return value: %TRUE if @str was successfully parsed.
  */
@@ -1600,7 +1639,9 @@ pango_parse_variant (const char   *str,
  * @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",
+ * Parses a font weight.
+ *
+ * The allowed values are "heavy",
  * "ultrabold", "bold", "normal", "light", "ultraleight"
  * and integers. Case variations are ignored.
  *
@@ -1620,7 +1661,9 @@ pango_parse_weight (const char  *str,
  * @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
+ * Parses a font stretch.
+ *
+ * The allowed values are
  * "ultra_condensed", "extra_condensed", "condensed",
  * "semi_condensed", "normal", "semi_expanded", "expanded",
  * "extra_expanded" and "ultra_expanded". Case variations are
@@ -1676,6 +1719,7 @@ pango_font_init (PangoFont *font G_GNUC_UNUSED)
  * @font: a `PangoFont`
  *
  * Returns a description of the font, with font size set in points.
+ *
  * Use [method@Pango.Font.describe_with_absolute_size] if you want
  * the font size in device units.
  *
@@ -1694,8 +1738,9 @@ pango_font_describe (PangoFont *font)
  * @font: a `PangoFont`
  *
  * Returns a description of the font, with absolute font size set
- * (in device units). Use [method@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.
  *
@@ -1763,8 +1808,9 @@ pango_font_find_shaper (PangoFont     *font,
  * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of
  *            the glyph or %NULL to indicate that the result is not needed.
  *
- * Gets the logical and ink extents of a glyph within a font. The
- * coordinate system for each rectangle has its origin at the
+ * Gets the logical and ink extents of a glyph within a font.
+ *
+ * The coordinate system for each rectangle has its origin at the
  * base line and horizontal origin of the character with increasing
  * coordinates extending to the right and down. The macros PANGO_ASCENT(),
  * PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
@@ -2245,9 +2291,11 @@ pango_font_family_init (PangoFontFamily *family G_GNUC_UNUSED)
  * pango_font_family_get_name:
  * @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`
- * to specify that a face from this family is desired.
+ * Gets the name of the family.
+ *
+ * The name is unique among all 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.
@@ -2269,8 +2317,9 @@ pango_font_family_get_name (PangoFontFamily  *family)
  *   longer needed.
  * @n_faces: (out): location to store number of elements in @faces.
  *
- * Lists the different font faces that make up @family. The faces
- * in a family share a common design, but differ in slant, weight,
+ * 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
@@ -2344,7 +2393,9 @@ pango_font_family_get_face (PangoFontFamily *family,
  * @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
+ * characters form a regular grid.
+ *
+ * For Western languages this would
  * mean that the advance width of all characters are the same, but
  * this categorization also includes Asian fonts which include
  * double-width characters: characters that occupy two grid cells.
@@ -2556,6 +2607,7 @@ pango_font_has_char (PangoFont *font,
  * @num_features: (inout): the number of used items in @features
  *
  * Obtain the OpenType features that are provided by the font.
+ *
  * These are passed to the rendering system, together with features
  * that have been explicitly set via attributes.
  *
diff --git a/pango/pango-font.h b/pango/pango-font.h
index 76aa59a1..13f8a222 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -33,20 +33,25 @@ G_BEGIN_DECLS
 /**
  * PangoFontDescription:
  *
- * 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.
+ * A `PangoFontDescription` describes a font in an implementation-independent
+ * manner.
+ *
+ * `PangoFontDescription` structures are used both to list what fonts are
+ * available on the system and also for specifying the characteristics of
+ * a font to load.
  */
 typedef struct _PangoFontDescription PangoFontDescription;
+
 /**
  * PangoFontMetrics:
  *
  * 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
- * of their meaning.
+ * for a font.
+ *
+ * The information in a `PangoFontMetrics` structure may be 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 of their meaning.
  */
 typedef struct _PangoFontMetrics PangoFontMetrics;
 
@@ -92,8 +97,10 @@ typedef enum {
  * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
  * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24)
  *
- * An enumeration specifying the weight (boldness) of a font. This is a numerical
- * value ranging from 100 to 1000, but there are some predefined values:
+ * An enumeration specifying the weight (boldness) of a font.
+ *
+ * This is a numerical value ranging from 100 to 1000, but there
+ * are some predefined values.
  */
 typedef enum {
   PANGO_WEIGHT_THIN = 100,
@@ -148,8 +155,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
- * [struct@Pango.FontDescription] that have been set.
+ * The bits in a `PangoFontMask` correspond to the set fields in a
+ * `PangoFontDescription`.
  */
 typedef enum {
   PANGO_FONT_MASK_FAMILY  = 1 << 0,
@@ -379,9 +386,11 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
 /**
  * PangoFontFamily:
  *
- * 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.
+ * A `PangoFontFamily` is used to represent a family of related
+ * font faces.
+ *
+ * The font faces in a family share a common design, but differ in
+ * slant, weight, width or other aspects.
  */
 struct _PangoFontFamily
 {
@@ -450,8 +459,8 @@ typedef struct _PangoFontFaceClass   PangoFontFaceClass;
 /**
  * PangoFontFace:
  *
- * The `PangoFontFace` structure is used to represent a group of fonts with
- * the same family, slant, weight, width, but varying sizes.
+ * A `PangoFontFace` is used to represent a group of fonts with
+ * the same family, slant, weight, and width, but varying sizes.
  */
 struct _PangoFontFace
 {
@@ -516,8 +525,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.
+ * A `PangoFont` is used to represent a font in a
+ * rendering-system-independent manner.
  */
 struct _PangoFont
 {
@@ -595,31 +604,32 @@ 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
- * example in shaper modules, to use as the glyph for various zero-width
- * Unicode characters (those passing [func@is_zero_width]).
+ * A `PangoGlyph` value that indicates a zero-width empty glpyh.
+ *
+ * This is useful for example in shaper modules, to use as the glyph for
+ * various 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
- * per invalid input UTF-8 byte and such a glyph is rendered as a crossed
- * box.
+ * A `PangoGlyph` value for invalid input.
+ *
+ * `PangoLayout` produces one such glyph per invalid input UTF-8 byte and such
+ * a glyph is rendered as a crossed box.
  *
  * Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG
- * on.
+ * set.
  *
  * Since: 1.20
  */
 /**
  * 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`.
+ * Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode
+ * character into an unknown-character glyph for that `gunichar`.
+ *
+ * Such unknown-character glyphs may be rendered as a 'hex box'.
  */
 /**
  * PANGO_GET_UNKNOWN_GLYPH:
@@ -636,10 +646,12 @@ hb_font_t *           pango_font_get_hb_font       (PangoFont        *font);
 #define PANGO_GLYPH_UNKNOWN_FLAG    ((PangoGlyph)0x10000000)
 #define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG)
 
+#ifndef __GI_SCANNER__
 #ifndef PANGO_DISABLE_DEPRECATED
 #define PANGO_UNKNOWN_GLYPH_WIDTH  10
 #define PANGO_UNKNOWN_GLYPH_HEIGHT 14
 #endif
+#endif
 
 G_END_DECLS