[gedit: 3/4] spell: write remaining API documentation

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

commit 334e9bef321e133f936ec914ed8040d6c6134e99
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Aug 8 14:01:22 2015 +0200

    spell: write remaining API documentation

 plugins/spell/gedit-spell-checker-dialog.c  |   22 ++++++++++++++
 plugins/spell/gedit-spell-language-dialog.c |   23 ++++++++++++++
 plugins/spell/gedit-spell-navigator-gtv.c   |   39 ++++++++++++++++++++++++
 plugins/spell/gedit-spell-navigator.c       |   43 ++++++++++++++++++++++++++-
 4 files changed, 126 insertions(+), 1 deletions(-)
---
diff --git a/plugins/spell/gedit-spell-checker-dialog.c b/plugins/spell/gedit-spell-checker-dialog.c
index 36268dd..54f4a92 100644
--- a/plugins/spell/gedit-spell-checker-dialog.c
+++ b/plugins/spell/gedit-spell-checker-dialog.c
@@ -23,6 +23,16 @@
 #include <glib/gi18n.h>
 #include "gedit-spell-checker.h"
 
+/**
+ * SECTION:spell-checker-dialog
+ * @Short_description: Spell checker dialog
+ * @Title: GeditSpellCheckerDialog
+ * @See_also: #GeditSpellNavigator
+ *
+ * #GeditSpellCheckerDialog is a #GtkDialog to spell check a document one word
+ * at a time. It uses a #GeditSpellNavigator.
+ */
+
 typedef struct _GeditSpellCheckerDialogPrivate GeditSpellCheckerDialogPrivate;
 
 struct _GeditSpellCheckerDialogPrivate
@@ -381,6 +391,11 @@ gedit_spell_checker_dialog_class_init (GeditSpellCheckerDialogClass *klass)
 
        widget_class->show = gedit_spell_checker_dialog_show;
 
+       /**
+        * GeditSpellCheckerDialog:spell-navigator:
+        *
+        * The #GeditSpellNavigator to use.
+        */
        g_object_class_install_property (object_class,
                                         PROP_SPELL_NAVIGATOR,
                                         g_param_spec_object ("spell-navigator",
@@ -685,6 +700,13 @@ gedit_spell_checker_dialog_init (GeditSpellCheckerDialog *dialog)
        gtk_widget_grab_default (priv->change_button);
 }
 
+/**
+ * gedit_spell_checker_dialog_new:
+ * @parent: transient parent of the dialog.
+ * @navigator: the #GeditSpellNavigator to use.
+ *
+ * Returns: a new #GeditSpellCheckerDialog widget.
+ */
 GtkWidget *
 gedit_spell_checker_dialog_new (GtkWindow           *parent,
                                GeditSpellNavigator *navigator)
diff --git a/plugins/spell/gedit-spell-language-dialog.c b/plugins/spell/gedit-spell-language-dialog.c
index b3156eb..383426f 100644
--- a/plugins/spell/gedit-spell-language-dialog.c
+++ b/plugins/spell/gedit-spell-language-dialog.c
@@ -21,6 +21,16 @@
 
 #include "gedit-spell-language-dialog.h"
 
+/**
+ * SECTION:spell-language-dialog
+ * @Short_description: Dialog to choose a spell language.
+ * @Title: GeditSpellLanguageDialog
+ * @See_also: #GeditSpellCheckerLanguage.
+ *
+ * #GeditSpellLanguageDialog is a #GtkDialog to choose an available
+ * #GeditSpellCheckerLanguage.
+ */
+
 enum
 {
        COLUMN_LANGUAGE_NAME,
@@ -155,6 +165,13 @@ populate_language_list (GeditSpellLanguageDialog        *dialog,
        }
 }
 
+/**
+ * gedit_spell_language_dialog_new:
+ * @parent: transient parent of the dialog.
+ * @cur_lang: the #GeditSpellCheckerLanguage to select initially.
+ *
+ * Returns: a new #GeditSpellLanguageDialog widget.
+ */
 GtkWidget *
 gedit_spell_language_dialog_new (GtkWindow                       *parent,
                                 const GeditSpellCheckerLanguage *cur_lang)
@@ -172,6 +189,12 @@ gedit_spell_language_dialog_new (GtkWindow                       *parent,
        return GTK_WIDGET (dialog);
 }
 
+/**
+ * gedit_spell_language_get_selected_language:
+ * @dialog: a #GeditSpellLanguageDialog.
+ *
+ * Returns: the currently selected language.
+ */
 const GeditSpellCheckerLanguage *
 gedit_spell_language_get_selected_language (GeditSpellLanguageDialog *dialog)
 {
diff --git a/plugins/spell/gedit-spell-navigator-gtv.c b/plugins/spell/gedit-spell-navigator-gtv.c
index 8e0f171..d9b8266 100644
--- a/plugins/spell/gedit-spell-navigator-gtv.c
+++ b/plugins/spell/gedit-spell-navigator-gtv.c
@@ -21,6 +21,27 @@
 #include "gedit-spell-navigator-gtv.h"
 #include "gedit-spell-utils.h"
 
+/**
+ * SECTION:spell-navigator-gtv
+ * @Short_description: A GeditSpellNavigator implementation for GtkTextView.
+ * @Title: GeditSpellNavigatorGtv
+ * @See_also: #GeditSpellNavigator, #GeditSpellCheckerDialog
+ *
+ * #GeditSpellNavigatorGtv is a simple implementation of the
+ * #GeditSpellNavigator interface.
+ *
+ * If a selection exists in the #GtkTextView, only the selected text is spell
+ * checked. Otherwise the whole buffer is checked. The same #GeditSpellChecker
+ * is used throughout the navigation.
+ *
+ * If only the selected text is spell checked, the implementation of
+ * gedit_spell_navigator_change_all() changes only the occurrences that were
+ * present in the selection.
+ *
+ * The implementation of gedit_spell_navigator_goto_next() selects the
+ * misspelled word and scrolls to it.
+ */
+
 typedef struct _GeditSpellNavigatorGtvPrivate GeditSpellNavigatorGtvPrivate;
 
 struct _GeditSpellNavigatorGtvPrivate
@@ -222,6 +243,12 @@ gedit_spell_navigator_gtv_class_init (GeditSpellNavigatorGtvClass *klass)
        object_class->set_property = gedit_spell_navigator_gtv_set_property;
        object_class->dispose = gedit_spell_navigator_gtv_dispose;
 
+       /**
+        * GeditSpellNavigatorGtv:view:
+        *
+        * The #GtkTextView. The buffer is not sufficient, the view is needed to
+        * scroll to the misspelled words.
+        */
        g_object_class_install_property (object_class,
                                         PROP_VIEW,
                                         g_param_spec_object ("view",
@@ -232,6 +259,11 @@ gedit_spell_navigator_gtv_class_init (GeditSpellNavigatorGtvClass *klass)
                                                              G_PARAM_CONSTRUCT_ONLY |
                                                              G_PARAM_STATIC_STRINGS));
 
+       /**
+        * GeditSpellNavigatorGtv:spell-checker:
+        *
+        * The #GeditSpellChecker to use.
+        */
        g_object_class_install_property (object_class,
                                         PROP_SPELL_CHECKER,
                                         g_param_spec_object ("spell-checker",
@@ -489,6 +521,13 @@ gedit_spell_navigator_iface_init (gpointer g_iface,
        iface->change_all = gedit_spell_navigator_gtv_change_all;
 }
 
+/**
+ * gedit_spell_navigator_gtv_new:
+ * @view: a #GtkTextView.
+ * @spell_checker: a #GeditSpellChecker.
+ *
+ * Returns: a new #GeditSpellNavigatorGtv object.
+ */
 GeditSpellNavigator *
 gedit_spell_navigator_gtv_new (GtkTextView       *view,
                               GeditSpellChecker *spell_checker)
diff --git a/plugins/spell/gedit-spell-navigator.c b/plugins/spell/gedit-spell-navigator.c
index 5d7a712..4b83d58 100644
--- a/plugins/spell/gedit-spell-navigator.c
+++ b/plugins/spell/gedit-spell-navigator.c
@@ -20,6 +20,23 @@
 
 #include "gedit-spell-navigator.h"
 
+/**
+ * SECTION:spell-navigator
+ * @Short_description: Interface to navigate through misspelled words
+ * @Title: GeditSpellNavigator
+ * @See_also: #GeditSpellNavigatorGtv, #GeditSpellCheckerDialog
+ *
+ * #GeditSpellNavigator is an interface to navigate through misspelled words,
+ * and correct the mistakes.
+ *
+ * It is used by widgets like #GeditSpellCheckerDialog. The purpose is to
+ * spell check a document one word at a time.
+ *
+ * It is not mandatory to navigate through all the text. Depending on the
+ * context, an implementation could spell check only the current page, or the
+ * selection, etc.
+ */
+
 G_DEFINE_INTERFACE (GeditSpellNavigator, gedit_spell_navigator, G_TYPE_OBJECT)
 
 static gboolean
@@ -59,7 +76,8 @@ gedit_spell_navigator_default_init (GeditSpellNavigatorInterface *iface)
  * @word: (out) (optional): a location to store an allocated string, or %NULL.
  *   Use g_free() to free the returned string.
  * @spell_checker: (out) (optional) (transfer full): a location to store the
- *   #GeditSpellChecker used, or %NULL.
+ *   #GeditSpellChecker used, or %NULL. Use g_object_unref() when no longer
+ *   needed.
  * @error: (out) (optional): a location to a %NULL #GError, or %NULL.
  *
  * Goes to the next misspelled word. When called the first time, goes to the
@@ -93,6 +111,18 @@ gedit_spell_navigator_goto_next (GeditSpellNavigator  *navigator,
                                                                       error);
 }
 
+/**
+ * gedit_spell_navigator_change:
+ * @navigator: a #GeditSpellNavigator.
+ * @word: the word to change.
+ * @change_to: the replacement.
+ *
+ * Changes the current @word by @change_to. @word is the same as returned by the
+ * last gedit_spell_navigator_goto_next().
+ *
+ * gedit_spell_checker_set_correction() has already been called, this function
+ * is to make the change in the text. Only the current word should be changed.
+ */
 void
 gedit_spell_navigator_change (GeditSpellNavigator *navigator,
                              const gchar         *word,
@@ -103,6 +133,17 @@ gedit_spell_navigator_change (GeditSpellNavigator *navigator,
        GEDIT_SPELL_NAVIGATOR_GET_IFACE (navigator)->change (navigator, word, change_to);
 }
 
+/**
+ * gedit_spell_navigator_change_all:
+ * @navigator: a #GeditSpellNavigator.
+ * @word: the word to change.
+ * @change_to: the replacement.
+ *
+ * Changes all occurrences of @word by @change_to.
+ *
+ * gedit_spell_checker_set_correction() has already been called, this function
+ * is to make the change in the text.
+ */
 void
 gedit_spell_navigator_change_all (GeditSpellNavigator *navigator,
                                  const gchar         *word,