Documentation for error codes.

[Murray Cumming <murrayc murrayc com>]

Approval for this documentation patch?

I also think the error code enums should be split up, and the values
removed, as in GTK+, but I am a bit afraid of doing that immediately,
because the compiler wouldn't tell us where we are using one error code
in the wrong domain.
 
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 1935)
+++ ChangeLog	(working copy)
@@ -1,3 +1,12 @@
+2007-05-10  Murray Cumming  <murrayc murrayc com>
+
+	* libtinymail/tny-account-store.c: tny_account_store_alert(): 
+	Document that the vfunc might receive TNY_ACCOUNT_STORE_ERROR as well 
+	as just TNY_ACCOUNT_ERROR.
+	* libtinymail/tny-error.h: Document the TNY_ACCOUNT_ERROR_TRY_CONNECT 
+	and TNY_ACCOUNT_STORE_ERROR_UNKNOWN_ALERT error codes, including their 
+	awkward realities, based on discussion with Philip.
+	
 2007-05-09  Philip Van Hoof  <pvanhoof gnome org>
 
 	* libtinymailui-gtk/tny-gtk-header-list-model.c: Moved the private API
Index: libtinymail/tny-account-store.c
===================================================================
--- libtinymail/tny-account-store.c	(revision 1935)
+++ libtinymail/tny-account-store.c	(working copy)
@@ -80,7 +80,8 @@
  * tny_account_store_alert:
  * @self: a #TnyAccountStore object
  * @type: the message type (severity)
- * @error: A GError, of domain TNY_ACCOUNT_ERROR, which should be used to determine what to show to the user.
+ * @error: A GError, of domain TNY_ACCOUNT_ERROR or TNY_ACCOUNT_STORE_ERROR, 
+ * which should be used to determine what to show to the user.
  *
  * This jump-to-the-ui method implements showing a message dialog appropriate for the @error
  * and @type as message type. It will return TRUE if the reply was 
Index: libtinymail/tny-error.h
===================================================================
--- libtinymail/tny-error.h	(revision 1935)
+++ libtinymail/tny-error.h	(working copy)
@@ -37,6 +37,42 @@
 
 #define TNY_TYPE_ERROR (tny_error_get_type())
 
+/* TODO: These should probably be split into separate enums, one for each 
+ * error domain. Error codes from one error domain should not be used with 
+ * a separate error domain. The hard-coding of the numbers should then not 
+ * be necessary or useful.
+ */
+ 
+/**
+ * TnyError:
+ *
+ * An GError error code.
+ * 
+ * TODO: Ideally, we would have more error codes, one for each specific error, 
+ * such as "hostname not accepted", so that the application can identify the 
+ * exact error, and respond accordingly. However, these error codes are not 
+ * yet present because the implementations do not yet provide such 
+ * fine-grained information.
+ * TODO: Document the other error codes.
+ * 
+ * TNY_ACCOUNT_ERROR_TRY_CONNECT: This can possibly indicate such errors as 
+ * "hostname not resolved", "no network", or "password not accepted", 
+ * though some implementations might return TNY_ACCOUNT_STORE_ERROR_UNKNOWN_ALERT 
+ * (in the TNY_ACCOUNT_STORE_ERROR error domain) in these cases
+ * Currently, the application must know whether it is using our camel 
+ * implementation, in order to know whether it can expect to receive a 
+ * TNY_ACCOUNT_ERROR_TRY_CONNECT (in the TNY_ACCOUNT_ERROR error domain) rather 
+ * than a TNY_ACCOUNT_ERROR_UNKNOWN_ALERT (in the TNY_ACCOUNT_STORE_ERROR 
+ * error domain) in these situations. If using our camel implementation then 
+ * even this level of exact detection of the particular error is not currently 
+ * possible, so a generic error dialog should probably be shown, though the 
+ * application could choose to suggest possible causes for the error.
+ * 
+ * TNY_ACCOUNT_STORE_ERROR_UNKNOWN_ALERT: This indicates that an unknown error 
+ * has occurred. Depending on the implementation being used, and the server 
+ * being used, this could have multiple possible causes. More exact error 
+ * information is only possible with other servers, and/or othre implementations.
+ */
 enum _TnyError 
 {
 	TNY_ERROR_UNSPEC = 1,