[evolution/wip/webkit-composer: 116/262] Document e_spell_dictionary_compare().

[Tomas Popela <tpopela src gnome org>]

commit ee41bbf411450c43f07b83f10c6ebbcb655a7a9a
Author: Matthew Barnes <mbarnes redhat com>
Date:   Thu Jan 17 07:44:33 2013 -0500

    Document e_spell_dictionary_compare().

 .../evolution-util/evolution-util-sections.txt     |    2 +-
 e-util/e-spell-dictionary.c                        |   36 ++++++++++++++------
 e-util/e-spell-dictionary.h                        |    4 +-
 3 files changed, 28 insertions(+), 14 deletions(-)
---
diff --git a/doc/reference/evolution-util/evolution-util-sections.txt 
b/doc/reference/evolution-util/evolution-util-sections.txt
index 47f1be0..4b5e810 100644
--- a/doc/reference/evolution-util/evolution-util-sections.txt
+++ b/doc/reference/evolution-util/evolution-util-sections.txt
@@ -3938,6 +3938,7 @@ ESpellDictionary
 e_spell_dictionary_new
 e_spell_dictionary_hash
 e_spell_dictionary_equal
+e_spell_dictionary_compare
 e_spell_dictionary_get_name
 e_spell_dictionary_get_code
 e_spell_dictionary_check
@@ -3947,7 +3948,6 @@ e_spell_dictionary_get_suggestions
 e_spell_dictionary_free_suggestions
 e_spell_dictionary_store_correction
 e_spell_dictionary_get_parent_checker
-e_spell_dictionary_compare
 <SUBSECTION Standard>
 E_SPELL_DICTIONARY
 E_IS_SPELL_DICTIONARY
diff --git a/e-util/e-spell-dictionary.c b/e-util/e-spell-dictionary.c
index fa53816..e2c7000 100644
--- a/e-util/e-spell-dictionary.c
+++ b/e-util/e-spell-dictionary.c
@@ -531,6 +531,31 @@ e_spell_dictionary_equal (ESpellDictionary *dictionary1,
 }
 
 /**
+ * e_spell_dictionary_compare:
+ * @dictionary1: an #ESpellDictionary
+ * @dictionary2: another #ESpellDictionary
+ *
+ * Compares @dictionary1 and @dictionary2 by their display names for
+ * the purpose of lexicographical sorting.  Use this function where a
+ * #GCompareFunc callback is required, such as g_list_sort().
+ *
+ * Returns: 0 if the names match,
+ *          a negative value if @dictionary1 < @dictionary2,
+ *          or a positive value of @dictionary1 > @dictionary2
+ **/
+gint
+e_spell_dictionary_compare (ESpellDictionary *dictionary1,
+                            ESpellDictionary *dictionary2)
+{
+       g_return_val_if_fail (E_IS_SPELL_DICTIONARY (dictionary1), 0);
+       g_return_val_if_fail (E_IS_SPELL_DICTIONARY (dictionary2), 0);
+
+       return strcmp (
+               dictionary1->priv->collate_key,
+               dictionary2->priv->collate_key);
+}
+
+/**
  * e_spell_dictionary_get_name:
  * @dictionary: an #ESpellDictionary
  *
@@ -722,14 +747,3 @@ e_spell_dictionary_get_parent_checker (ESpellDictionary *dictionary)
        return dictionary->priv->spell_checker;
 }
 
-gint
-e_spell_dictionary_compare (ESpellDictionary *dictionary1,
-                            ESpellDictionary *dictionary2)
-{
-       g_return_val_if_fail (E_IS_SPELL_DICTIONARY (dictionary1), 0);
-       g_return_val_if_fail (E_IS_SPELL_DICTIONARY (dictionary2), 0);
-
-       return strcmp (
-               dictionary1->priv->collate_key,
-               dictionary2->priv->collate_key);
-}
diff --git a/e-util/e-spell-dictionary.h b/e-util/e-spell-dictionary.h
index ec8bfff..caf4b87 100644
--- a/e-util/e-spell-dictionary.h
+++ b/e-util/e-spell-dictionary.h
@@ -68,6 +68,8 @@ ESpellDictionary *
 guint          e_spell_dictionary_hash         (ESpellDictionary *dictionary);
 gboolean       e_spell_dictionary_equal        (ESpellDictionary *dictionary1,
                                                 ESpellDictionary *dictionary2);
+gint           e_spell_dictionary_compare      (ESpellDictionary *dictionary1,
+                                                ESpellDictionary *dictionary2);
 const gchar *  e_spell_dictionary_get_name     (ESpellDictionary *dictionary);
 const gchar *  e_spell_dictionary_get_code     (ESpellDictionary *dictionary);
 gboolean       e_spell_dictionary_check        (ESpellDictionary *dictionary,
@@ -93,8 +95,6 @@ void          e_spell_dictionary_store_correction
                                                 gsize correction_length);
 ESpellChecker *        e_spell_dictionary_get_parent_checker
                                                (ESpellDictionary *dictionary);
-gint           e_spell_dictionary_compare      (ESpellDictionary *dictionary1,
-                                                ESpellDictionary *dictionary2);
 
 G_END_DECLS