[glib: 1/2] gcharset: Expand the documentation for g_get_locale_variants()

[Sebastian Dröge <sdroege src gnome org>]

commit cea8424e8029d7c7fbe5ec1ace15fbd026f3d792
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Oct 11 11:47:42 2019 +0100

    gcharset: Expand the documentation for g_get_locale_variants()
    
    Include some more examples, and a reference to the format of locales.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/gcharset.c | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
---
diff --git a/glib/gcharset.c b/glib/gcharset.c
index 7bce2a15a..9db56f732 100644
--- a/glib/gcharset.c
+++ b/glib/gcharset.c
@@ -549,10 +549,15 @@ append_locale_variants (GPtrArray *array,
  * Returns a list of derived variants of @locale, which can be used to
  * e.g. construct locale-dependent filenames or search paths. The returned
  * list is sorted from most desirable to least desirable.
- * This function handles territory, charset and extra locale modifiers.
+ * This function handles territory, charset and extra locale modifiers. See
+ * [`setlocale(3)`](man:setlocale) for information about locales and their format.
  *
- * For example, if @locale is "fr_BE", then the returned list
- * is "fr_BE", "fr".
+ * @locale itself is guaranteed to be returned in the output.
+ *
+ * For example, if @locale is `fr_BE`, then the returned list
+ * is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
+ * is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
+ * `en.UTF-8`, `en@euro`, `en`.
  *
  * If you need the list of variants for the current locale,
  * use g_get_language_names().