[tepl] LanguageChoosers: write more docs

[Sébastien Wilmet <swilmet src gnome org>]

commit 88bc168ef26d9125e6eb2b2e52634da91e5f3c54
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Nov 6 05:19:33 2020 +0100

    LanguageChoosers: write more docs

 tepl/tepl-language-chooser-dialog.c |  3 +++
 tepl/tepl-language-chooser-widget.c |  5 +++++
 tepl/tepl-language-chooser.c        | 21 +++++++++++++++++++--
 3 files changed, 27 insertions(+), 2 deletions(-)
---
diff --git a/tepl/tepl-language-chooser-dialog.c b/tepl/tepl-language-chooser-dialog.c
index 61d71c8..67e731b 100644
--- a/tepl/tepl-language-chooser-dialog.c
+++ b/tepl/tepl-language-chooser-dialog.c
@@ -12,6 +12,9 @@
  * SECTION:language-chooser-dialog
  * @Title: TeplLanguageChooserDialog
  * @Short_description: A dialog for choosing a #GtkSourceLanguage
+ *
+ * #TeplLanguageChooserDialog is a #GtkDialog to choose a #GtkSourceLanguage.
+ * #TeplLanguageChooserDialog implements the #TeplLanguageChooser interface.
  */
 
 struct _TeplLanguageChooserDialogPrivate
diff --git a/tepl/tepl-language-chooser-widget.c b/tepl/tepl-language-chooser-widget.c
index 347f3fc..0fcc97e 100644
--- a/tepl/tepl-language-chooser-widget.c
+++ b/tepl/tepl-language-chooser-widget.c
@@ -12,6 +12,11 @@
  * SECTION:language-chooser-widget
  * @Title: TeplLanguageChooserWidget
  * @Short_description: A widget for choosing a #GtkSourceLanguage
+ *
+ * #TeplLanguageChooserWidget is a #GtkWidget to choose a #GtkSourceLanguage.
+ * #TeplLanguageChooserWidget implements the #TeplLanguageChooser interface.
+ *
+ * In addition to the list, it contains a #GtkSearchEntry to search the list.
  */
 
 struct _TeplLanguageChooserWidgetPrivate
diff --git a/tepl/tepl-language-chooser.c b/tepl/tepl-language-chooser.c
index bef6867..f999743 100644
--- a/tepl/tepl-language-chooser.c
+++ b/tepl/tepl-language-chooser.c
@@ -8,6 +8,18 @@
  * SECTION:language-chooser
  * @Title: TeplLanguageChooser
  * @Short_description: Interface implemented by widgets for choosing a #GtkSourceLanguage
+ *
+ * A #TeplLanguageChooser widget shows a list of available #GtkSourceLanguage's,
+ * as returned by gtk_source_language_manager_get_default(). The list contains a
+ * "Plain Text" item for the %NULL language.
+ *
+ * The typical workflow when using a #TeplLanguageChooser widget in an
+ * application is:
+ * 1. Create a #TeplLanguageChooser widget.
+ * 2. Call tepl_language_chooser_select_language() with the value of the
+ *    #GtkSourceBuffer:language property.
+ * 3. Wait for the #TeplLanguageChooser::language-activated signal to be emitted
+ *    and/or destroy the #TeplLanguageChooser widget.
  */
 
 /* API design:
@@ -45,7 +57,10 @@ tepl_language_chooser_default_init (TeplLanguageChooserInterface *interface)
        /**
         * TeplLanguageChooser::language-activated:
         * @chooser: the #TeplLanguageChooser emitting the signal.
-        * @language: the #GtkSourceLanguage object that has been selected.
+        * @language: (nullable): the #GtkSourceLanguage object that has been
+        *   selected, or %NULL if "Plain Text" has been selected.
+        *
+        * This signal is emitted when the user has chosen a language.
         *
         * Since: 5.2
         */
@@ -64,7 +79,9 @@ tepl_language_chooser_default_init (TeplLanguageChooserInterface *interface)
 /**
  * tepl_language_chooser_select_language:
  * @chooser: a #TeplLanguageChooser.
- * @language: (nullable): a #GtkSourceLanguage, or %NULL.
+ * @language: (nullable): a #GtkSourceLanguage, or %NULL for "Plain Text".
+ *
+ * Selects @language in the list of available languages.
  *
  * Since: 5.2
  */