[pango/simple-fontmap: 3/22] font: Clarify docs

[Matthias Clasen <matthiasc src gnome org>]

commit 1e07ed1e18ecc2c43fca03ff17cf9c9fe75d32df
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Dec 29 12:49:03 2021 -0500

    font: Clarify docs
    
    Spell out that monospace or variable families may contain
    a mixture of faces.

 pango/fonts.c | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index 28363ecd..3fbd43ad 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -2501,18 +2501,24 @@ pango_font_family_get_face (PangoFontFamily *family,
  * A monospace font is a font designed for text display where the the
  * 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.
- * g_unichar_iswide() returns a result that indicates whether a
- * character is typically double-width in a monospace font.
+ * 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. [function@GLib.unichar_iswide] returns a result that
+ * indicates whether a character is typically double-width in a monospace
+ * font.
  *
  * The best way to find out the grid-cell size is to call
  * [method@Pango.FontMetrics.get_approximate_digit_width], since the
  * results of [method@Pango.FontMetrics.get_approximate_char_width] may
  * be affected by double-width characters.
  *
+ * Note that a font family can in principle contain a mixture of
+ * monospace and non-monospace faces (although well-behaved families
+ * won't). Use [method@Pango.FontFace.is_monospace] to examine individual
+ * faces. This function will return `TRUE` as long as the family contains
+ * any monospace faces.
+ *
  * Return value: %TRUE if the family is monospace.
  *
  * Since: 1.4
@@ -2535,6 +2541,12 @@ pango_font_family_is_monospace (PangoFontFamily  *family)
  * Such axes are also known as _variations_; see
  * [method@Pango.FontDescription.set_variations] for more information.
  *
+ * Note that a font family can in principle contain a mixture of
+ * variable and non-variable faces, and even variable and non-variable
+ * versions of the same face. Use [method@Pango.FontFace.is_variable]
+ * to examine individual faces. This function will return `TRUE` as
+ * long as the family contains any variable faces.
+ *
  * Return value: %TRUE if the family is variable
  *
  * Since: 1.44