[pango] Add detail to docs

[Matthias Clasen <matthiasc src gnome org>]

commit 22dfeef4a26984ba81c6ff30117017dac372b706
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Aug 4 16:29:35 2019 -0400

    Add detail to docs
    
    Explain variation syntax and allowed values for
    other components of pango_font_description_from_string().

 pango/fonts.c | 52 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 11 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index 2abe504e..4ffa0378 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -1215,17 +1215,47 @@ parse_variations (const char  *word,
  * @str: string representation of a font description.
  *
  * Creates a new font description from a string representation in the
- * form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a
- * comma separated list of families optionally terminated by a comma,
- * STYLE_OPTIONS is a whitespace separated list of words where each word
- * describes one of style, variant, weight, stretch, or gravity, and SIZE
- * is a decimal number (size in points) or optionally followed by the
- * unit modifier "px" for absolute size. Any one of the options may
- * be absent.  If FAMILY-LIST is absent, then the family_name field of
- * the resulting font description will be initialized to %NULL.  If
- * STYLE-OPTIONS is missing, then all style options will be set to the
- * default values. If SIZE is missing, the size in the resulting font
- * description will be set to 0.
+ * form
+ *
+ * "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]",
+ *
+ * where FAMILY-LIST is a comma-separated list of families optionally
+ * terminated by a comma, STYLE_OPTIONS is a whitespace-separated list
+ * of words where each word describes one of style, variant, weight,
+ * stretch, or gravity, and SIZE is a decimal number (size in points)
+ * or optionally followed by the unit modifier "px" for absolute size.
+ * VARIATIONS is a comma-separated list of font variation
+ * specifications of the form "\@axis=value" (the = sign is optional).
+ *
+ * The following words are understood as styles:
+ * "Normal", "Roman", "Oblique", "Italic".
+ *
+ * The following words are understood as variants:
+ * "Small-Caps".
+ *
+ * The following words are understood as weights:
+ * "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light",
+ * "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold",
+ * "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black",
+ * "Extra-Black".
+ *
+ * The following words are understood as stretch values:
+ * "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed",
+ * "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded".
+ *
+ * The following words are understood as gravity values:
+ * "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left",
+ * "East", "Rotated-Right", "West".
+ *
+ * Any one of the options may be absent. If FAMILY-LIST is absent, then
+ * the family_name field of the resulting font description will be
+ * initialized to %NULL. If STYLE-OPTIONS is missing, then all style
+ * options will be set to the default values. If SIZE is missing, the
+ * size in the resulting font description will be set to 0.
+ *
+ * A typical example:
+ *
+ * "Cantarell Italic Light 15 \@wght=200"
  *
  * Return value: a new #PangoFontDescription.
  **/