documentation, add+export an ordering method

git-svn-id: svn+ssh://svn.abisource.com/svnroot/enchant/trunk@20748 bcba8976-2d24-0410-9c9c-aab3bd5fdfd6

5 files changed, 54 insertions, 15 deletions

diff --git a/src/aspell/aspell_provider.c b/src/aspell/aspell_provider.c
index 2922472..8ae99ce 100644
--- a/src/aspell/aspell_provider.c
+++ b/src/aspell/aspell_provider.c
@@ -180,7 +180,7 @@ aspell_provider_dictionary_status (struct str_enchant_provider * me,
 {
 	/* TODO: get kevina to apply my patch */
 	g_warning ("pspell_provider_dictionary_status stub - unimplemented\n");
-	return ED_UNKNOWN;
+	return EDS_UNKNOWN;
 }
 
 static void
diff --git a/src/enchant.c b/src/enchant.c
index b03bda1..a6a5918 100644
--- a/src/enchant.c
+++ b/src/enchant.c
@@ -501,16 +501,16 @@ enchant_broker_dictionary_status (EnchantBroker * broker,
 				  const char * const tag)
 {
 	/* start off pessimistic */
-	EnchantDictStatus best_status = ED_DOESNT_EXIST, status = ED_DOESNT_EXIST;
+	EnchantDictStatus best_status = EDS_DOESNT_EXIST, status = EDS_DOESNT_EXIST;
 	EnchantProvider *provider;
 	GSList *list;
 
-	g_return_val_if_fail (broker, ED_UNKNOWN);
-	g_return_val_if_fail (tag, ED_UNKNOWN);
+	g_return_val_if_fail (broker, EDS_UNKNOWN);
+	g_return_val_if_fail (tag, EDS_UNKNOWN);
 
 	/* don't query the providers if we can just do a quick map lookup */
 	if (g_hash_table_lookup (broker->dict_map, (gpointer) tag) != NULL)
-		return ED_EXISTS;
+		return EDS_EXISTS;
 
 	for (list = broker->provider_list; list != NULL; list = g_slist_next (list))
 		{
@@ -519,18 +519,43 @@ enchant_broker_dictionary_status (EnchantBroker * broker,
 			if (provider->dictionary_status)
 				{
 					status = (*provider->dictionary_status) (provider, tag);
-					if (status == ED_EXISTS)
-						return ED_EXISTS;
-					else if (status == ED_UNKNOWN)
-						best_status = ED_UNKNOWN;
+					if (status == EDS_EXISTS)
+						return EDS_EXISTS;
+					else if (status == EDS_UNKNOWN)
+						best_status = EDS_UNKNOWN;
 				}
 			else
 				{
 					/* no query routine implemented, return so-so value */
-					best_status = ED_UNKNOWN;
+					best_status = EDS_UNKNOWN;
 				}
 		}
 
 
 	return best_status;
 }
+
+/**
+ * enchant_broker_declare_ordering
+ * @broker: A non-null #EnchantBroker
+ * @tag: A non-null language tag (en_US)
+ * @ordering: A non-null ordering (aspell,myspell,ispell,uspell,hspell)
+ *
+ * Declares a preference of dictionaries to use for the language
+ * described/referred to by @tag. The ordering is a comma delimited
+ * list of provider names. As a special exception, the "*" tag can
+ * be used as a language tag to declare a default ordering for any
+ * language that does not explictly declare an ordering.
+ */
+ENCHANT_MODULE_EXPORT (void)
+enchant_broke_set_ordering (EnchantBroker * broker,
+			    const char * const tag,
+			    const char * const ordering)
+{
+	g_return_if_fail (broker);
+	g_return_if_fail (tag);
+	g_return_if_fail (ordering);
+
+	g_hash_table_insert (broker->provider_ordering, (gpointer)tag,
+			     g_strdup (ordering));
+}
diff --git a/src/enchant.h b/src/enchant.h
index 4edfdd9..355e02f 100644
--- a/src/enchant.h
+++ b/src/enchant.h
@@ -49,9 +49,9 @@ typedef struct str_enchant_provider EnchantProvider;
 
 typedef enum
 	{
-		ED_EXISTS,
-		ED_DOESNT_EXIST,
-		ED_UNKNOWN
+		EDS_EXISTS, /* Dictionary definitely exists */
+		EDS_DOESNT_EXIST, /* Dictionary definitely doesn't exist */
+		EDS_UNKNOWN /* Unknown if dict exists or not */
 	} EnchantDictStatus;
 
 ENCHANT_MODULE_EXPORT (int)
@@ -86,6 +86,20 @@ ENCHANT_MODULE_EXPORT (EnchantDictStatus)
      enchant_broker_dictionary_status (EnchantBroker * broker,
 				       const char * const tag);
 
+ENCHANT_MODULE_EXPORT (void)
+enchant_broke_set_ordering (EnchantBroker * broker,
+			    const char * const tag,
+			    const char * const ordering);
+
+/**
+ * EnchantBrokerDescribeFn
+ * @name: The provider's identifier, such as "ispell" or "aspell"
+ * @desc: A description of the provider, such as "Aspell 0.53"
+ * @file: The provider's DLL filename
+ * @user_data: Supplied user_data, or %null if you don't care
+ *
+ * Callback used to enumerate and describe Enchant's various providers
+ */
 typedef void (*EnchantBrokerDescribeFn) (const char * name,
 					 const char * desc,
 					 const char * file,
diff --git a/src/ispell/ispell_checker.cpp b/src/ispell/ispell_checker.cpp
index 7027680..7815e3d 100644
--- a/src/ispell/ispell_checker.cpp
+++ b/src/ispell/ispell_checker.cpp
@@ -584,7 +584,7 @@ ispell_provider_dictionary_status (struct str_enchant_provider * me,
 {
 	// TODO: use g_file_test to test existance
 	g_warning ("ispell_provider_dictionary_status stub - unimplemented\n");
-	return ED_UNKNOWN;
+	return EDS_UNKNOWN;
 }
 
 static void
diff --git a/src/uspell/uspell_provider.cpp b/src/uspell/uspell_provider.cpp
index 80789bf..1a567a2 100644
--- a/src/uspell/uspell_provider.cpp
+++ b/src/uspell/uspell_provider.cpp
@@ -279,7 +279,7 @@ EnchantDictStatus uspell_provider_dictionary_status(struct str_enchant_provider
 {
 	// TODO: a g_file_exists check on the dictionary associated with the tag
 	g_warning ("uspell_provider_dictionary_status stub - unimplemented\n");
-	return(ED_UNKNOWN);
+	return(EDS_UNKNOWN);
 }
 
 static void