[geary/wip/default-spellcheck-lang: 2/4] Add some doc comments for Util.International functions

[Michael Gratton <mjog src gnome org>]

commit adea4618d66476dde054504d6a67e0057b5a41c3
Author: Michael Gratton <mike vee net>
Date:   Thu May 23 00:03:22 2019 +0200

    Add some doc comments for Util.International functions

 src/client/util/util-international.vala | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
---
diff --git a/src/client/util/util-international.vala b/src/client/util/util-international.vala
index 4f63fbea..ac2d7a56 100644
--- a/src/client/util/util-international.vala
+++ b/src/client/util/util-international.vala
@@ -28,6 +28,15 @@ namespace Util.International {
         return LANGUAGE_SUPPORT_DIRECTORY;
     }
 
+    /**
+     * Returns a sorted list of installed spell-check dictionary languages.
+     *
+     * Each language is a POSIX-style locale name (ISO/IEC 15897).
+     * The list is generated by obtaining the list from Enchant via
+     * {@link Enchant.Broker.list_dicts}, discarding generic languages
+     * if a regional variant exists (for example, discard "en" if
+     * "en_US" is included), then sorted.
+     */
     public string[] get_available_dictionaries() {
         string[] dictionaries = {};
 
@@ -64,6 +73,12 @@ namespace Util.International {
         return dictionaries;
     }
 
+    /**
+     * Returns a list of installed locale languages.
+     *
+     * Each language is a POSIX-style locale name (ISO/IEC 15897).
+     * The list is generated by executing `locale -a`.
+     */
     public string[] get_available_locales() {
         string[] locales = {};
 
@@ -94,6 +109,17 @@ namespace Util.International {
         return locale.substring(0, dot);
     }
 
+    /**
+     * Returns a list of preferred spell-check languages.
+     *
+     * Each language is a POSIX-style locale name (ISO/IEC 15897).
+     * The list is generated by obtaining the list of POSIX locales
+     * specified by the `LANGUAGE` environment variable, and including
+     * each that has both an available dictionary and locale.
+     *
+     * @see get_available_dictionaries
+     * @see get_available_locales
+     */
     public string[] get_user_preferred_languages() {
         GLib.GenericSet<string> dicts = new GLib.GenericSet<string>(GLib.str_hash, GLib.str_equal);
         foreach (string dict in get_available_dictionaries()) {