[gedit/wip/spell-checking] spell: write remaining API documentation

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

commit 03f739a12f2a4e6405cea5c14786f6c4396640b9
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-navigator-gtv.c |   39 ++++++++++++++++++++++++++
 plugins/spell/gedit-spell-navigator.c     |   43 ++++++++++++++++++++++++++++-
 2 files changed, 81 insertions(+), 1 deletions(-)
---
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,