[gnome-software] gs-plugin: Improve documentation of gs_plugin_get_locale()

[Richard Hughes <rhughes src gnome org>]

commit 223fec78b47e5ea266ef796c66afb76ce3bf431e
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Oct 11 11:20:13 2019 +0100

    gs-plugin: Improve documentation of gs_plugin_get_locale()
    
    And gs_plugin_get_language(), although nothing uses that function.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 lib/gs-plugin.c | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)
---
diff --git a/lib/gs-plugin.c b/lib/gs-plugin.c
index 005e6cdb..5aed1058 100644
--- a/lib/gs-plugin.c
+++ b/lib/gs-plugin.c
@@ -531,9 +531,18 @@ gs_plugin_set_priority (GsPlugin *plugin, guint priority)
  * gs_plugin_get_locale:
  * @plugin: a #GsPlugin
  *
- * Gets the user locale.
- *
- * Returns: the locale string, e.g. "en_GB"
+ * Gets the user locale. This is in the form documented in `man 3 setlocale`:
+ * ```
+ * language[_territory][.codeset][@modifier]
+ * ```
+ * where `language` is an
+ * [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes),
+ * `territory` is an
+ * [ISO 3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1), and
+ * `codeset` is a character set or encoding identifier like `ISO-8859-1` or
+ * `UTF-8`. For a list of all supported locales, run `locale -a`.
+ *
+ * Returns: the locale string, e.g. `en_GB` or `uz_UZ.utf8@cyrillic`
  *
  * Since: 3.22
  **/
@@ -548,9 +557,13 @@ gs_plugin_get_locale (GsPlugin *plugin)
  * gs_plugin_get_language:
  * @plugin: a #GsPlugin
  *
- * Gets the user language from the locale.
+ * Gets the user language from the locale. This is the first component of the
+ * locale.
+ *
+ * Typically you should use the full locale rather than the language, as the
+ * same language can be used quite differently in different territories.
  *
- * Returns: the language string, e.g. "fr"
+ * Returns: the language string, e.g. `fr`
  *
  * Since: 3.22
  **/