Add documentation to clarify mail-folder-cache functionality

Added a bunch of gtk-doc documentation as well as a variety of small comments in
the code.  Also added documentation and renamed a couple of mail_vfolder_*
functions that are only used by mail-folder-cache to make things a lot more
understandable.

https://bugzilla.gnome.org/show_bug.cgi?id=604627

4 files changed, 119 insertions, 32 deletions

diff --git a/mail/mail-folder-cache.c b/mail/mail-folder-cache.c
index 2bba2485d8..39ef7d2074 100644
--- a/mail/mail-folder-cache.c
+++ b/mail/mail-folder-cache.c
@@ -36,6 +36,7 @@
 #include <time.h>
 
 #include <glib.h>
+#include <glib-object.h>
 #include <glib/gstdio.h>
 
 #include <glib/gi18n.h>
@@ -47,7 +48,6 @@
 #include <camel/camel-disco-store.h>
 
 #include <libedataserver/e-data-server-util.h>
-#include "e-util/e-util.h"
 #include "shell/e-shell.h"
 
 #include "mail-mt.h"
@@ -66,7 +66,6 @@
 #include "em-utils.h"
 
 #include "e-mail-local.h"
-#include "e-mail-store.h"
 
 #define w(x)
 #define d(x)
@@ -80,12 +79,15 @@ G_DEFINE_TYPE (MailFolderCache, mail_folder_cache, G_TYPE_OBJECT)
 
 struct _MailFolderCachePrivate
 {
+	/* source id for the ping timeout callback */
 	guint ping_id;
 	/* Store to storeinfo table, active stores */
 	GHashTable *stores;
+	/* mutex to protect access to the stores hash */
 	GMutex *stores_mutex;
 	/* List of folder changes to be executed in gui thread */
 	GQueue updates;
+	/* event id for the async event of flushing all pending updates */
 	gint update_id;
 	/* hack for people who LIKE to have unsent count */
 	gint count_sent;
@@ -173,13 +175,14 @@ real_flush_updates (gpointer o, gpointer event_data, gpointer data)
 		g_mutex_unlock (self->priv->stores_mutex);
 
 		if (up->remove) {
+			/* XXX: what's going on here? */
 			if (up->delete) {
 				mail_vfolder_delete_uri(up->store, up->uri);
 				mail_filter_delete_uri(up->store, up->uri);
 				mail_config_uri_deleted(CAMEL_STORE_CLASS(CAMEL_OBJECT_GET_CLASS(up->store))->compare_folder_name, up->uri);
 
 			} else
-				mail_vfolder_add_uri(up->store, up->uri, TRUE);
+				mail_vfolder_notify_uri_unavailable (up->store, up->uri);
 		} else {
 			/* We can tell the vfolder code though */
 			if (up->olduri && up->add) {
@@ -191,7 +194,7 @@ real_flush_updates (gpointer o, gpointer event_data, gpointer data)
 			}
 
 			if (!up->olduri && up->add)
-				mail_vfolder_add_uri(up->store, up->uri, FALSE);
+				mail_vfolder_notify_uri_available (up->store, up->uri);
 		}
 
 		/* update unread counts */
@@ -533,6 +536,13 @@ folder_renamed(CamelObject *o, gpointer event_data, gpointer user_data)
 	/* Dont do anything, do it from the store rename event? */
 }
 
+/**
+ * mail_folder_cache_note_folder:
+ *
+ * When a folder has been opened, notify it for watching.  The folder must have
+ * already been created on the store (which has already been noted) before the
+ * folder can be opened
+ */
 void mail_folder_cache_note_folder(MailFolderCache *self, CamelFolder *folder)
 {
 	CamelStore *store = folder->parent_store;
@@ -815,6 +825,11 @@ free_folder_info_hash(gchar *path, struct _folder_info *mfi, gpointer data)
 	free_folder_info(mfi);
 }
 
+/**
+ * mail_folder_cache_note_store_remove:
+ *
+ * Notify the cache that the specified @store can be removed from the cache
+ */
 void
 mail_folder_cache_note_store_remove(MailFolderCache *self, CamelStore *store)
 {
@@ -987,9 +1002,16 @@ store_online_cb (CamelStore *store, gpointer data)
 	g_mutex_unlock (ud->cache->priv->stores_mutex);
 }
 
+/**
+ * mail_folder_cache_note_store:
+ *
+ * Add a store whose folders should appear in the shell The folders are scanned
+ * from the store, and/or added at runtime via the folder_created event.  The
+ * @done function returns if we can free folder info.
+ */
 void
 mail_folder_cache_note_store(MailFolderCache *self, CamelStore *store, CamelOperation *op,
-		NoteDoneFunc done, gpointer data)
+			     NoteDoneFunc done, gpointer data)
 {
 	struct _store_info *si;
 	struct _update_data *ud;
@@ -1078,8 +1100,14 @@ static void storeinfo_find_folder_info(CamelStore *store, struct _store_info *si
 	}
 }
 
-/* returns TRUE if the uri is available, folderp is set to a
-   reffed folder if the folder has also already been opened */
+/**
+ * mail_folder_cache_get_folder_from_uri:
+ *
+ * Gets the #CamelFolder for the supplied @uri.
+ *
+ * Return value: TRUE if the uri is available, folderp is set to a reffed folder if
+ * the folder has also already been opened
+ */
 gboolean
 mail_folder_cache_get_folder_from_uri(MailFolderCache *self, const gchar *uri, CamelFolder **folderp)
 {
diff --git a/mail/mail-folder-cache.h b/mail/mail-folder-cache.h
index 762152ffdd..8a7b82eada 100644
--- a/mail/mail-folder-cache.h
+++ b/mail/mail-folder-cache.h
@@ -23,8 +23,6 @@
  *
  */
 
-/* mail-folder-cache.h: Stores information about open folders */
-
 #ifndef _MAIL_FOLDER_CACHE_H
 #define _MAIL_FOLDER_CACHE_H
 
@@ -33,7 +31,10 @@
 
 G_BEGIN_DECLS
 
-/* Stores information about open folders */
+/**
+ * SECTION: mail-folder-cache
+ * @short_description: Stores information about open folders
+ **/
 
 #define MAIL_TYPE_FOLDER_CACHE            mail_folder_cache_get_type()
 #define MAIL_FOLDER_CACHE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAIL_TYPE_FOLDER_CACHE, MailFolderCache))
@@ -46,6 +47,12 @@ typedef struct _MailFolderCache MailFolderCache;
 typedef struct _MailFolderCacheClass MailFolderCacheClass;
 typedef struct _MailFolderCachePrivate MailFolderCachePrivate;
 
+/**
+ * MailFolderCache:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
 struct _MailFolderCache
 {
 	GObject parent;
@@ -64,26 +71,16 @@ MailFolderCache *mail_folder_cache_new (void);
 
 MailFolderCache *mail_folder_cache_get_default (void);
 
+/**
+ * NoteDoneFunc:
+ *
+ * The signature of a function to be registered as a callback for
+ * mail_folder_cache_note_store()
+ */
 typedef gboolean (*NoteDoneFunc)(CamelStore *store, CamelFolderInfo *info, gpointer data);
-/* Add a store whose folders should appear in the shell
-   The folders are scanned from the store, and/or added at
-   runtime via the folder_created event.
-   The 'done' function returns if we can free folder info. */
-void mail_folder_cache_note_store (MailFolderCache *self,
-				 CamelStore *store, CamelOperation *op,
-				 NoteDoneFunc func, gpointer data);
-
-/* de-note a store */
+void mail_folder_cache_note_store (MailFolderCache *self, CamelStore *store, CamelOperation *op, NoteDoneFunc done, gpointer data);
 void mail_folder_cache_note_store_remove (MailFolderCache *self, CamelStore *store);
-
-/* When a folder has been opened, notify it for watching.
-   The folder must have already been created on the store (which has already been noted)
-   before the folder can be opened
- */
 void mail_folder_cache_note_folder (MailFolderCache *self, CamelFolder *folder);
-
-/* Returns true if a folder is available (yet), and also sets *folderp (if supplied)
-   to a (referenced) copy of the folder if it has already been opened */
 gboolean mail_folder_cache_get_folder_from_uri (MailFolderCache *self, const gchar *uri, CamelFolder **folderp);
 gboolean mail_folder_cache_get_folder_info_flags (MailFolderCache *self, CamelFolder *folder, gint *flags);
 
diff --git a/mail/mail-vfolder.c b/mail/mail-vfolder.c
index f58886b214..9380922d26 100644
--- a/mail/mail-vfolder.c
+++ b/mail/mail-vfolder.c
@@ -425,8 +425,24 @@ uri_is_spethal(CamelStore *store, const gchar *uri)
 	return res;
 }
 
-/* called when a new uri becomes (un)available */
-void
+/**
+ * mail_vfolder_add_uri:
+ *
+ * @store: a #CamelStore containing the uri
+ * @curi: an email uri to be added/removed
+ * @remove: Whether the uri should be removed or added
+ *
+ * Called when a new uri becomes (un)available.  If @store is not a
+ * CamelVeeStore, the uri is added/removed from the list of cached source
+ * folders.  Then each vfolder rule is checked to see if the specified uri
+ * matches a source of the rule.  It builds a list of vfolders that use (or
+ * would use) the specified uri as a source.  It then adds (or removes) this uri
+ * to (from) those vfolders via camel_vee_folder_add/remove_folder() but does
+ * not modify the actual filters or write changes to disk.
+ *
+ * NOTE: This function must be called from the main thread.
+ */
+static void
 mail_vfolder_add_uri(CamelStore *store, const gchar *curi, gint remove)
 {
 	EFilterRule *rule;
@@ -525,7 +541,53 @@ done:
 	g_free(uri);
 }
 
-/* called when a uri is deleted from a store */
+/**
+ * mail_vfolder_uri_available:
+ * @store: a #CamelStore containing the uri
+ * @uri: uri of a folder that became available
+ *
+ * Adds @uri to the list of folders searched if any vfolder source matches the
+ * uri.  This function has a transient effect and does not permanently modify
+ * the vfolder filter rules on disk.
+ */
+void
+mail_vfolder_notify_uri_available (CamelStore *store, const gchar *uri)
+{
+	mail_vfolder_add_uri (store, uri, FALSE);
+}
+
+/**
+ * mail_vfolder_uri_available:
+ * @store: a #CamelStore containing the uri
+ * @uri: uri of a folder that became unavailable
+ *
+ * Removes @uri from the list of folders searched if any vfolder source matches the
+ * uri.  This function has a transient effect and does not permanently modify
+ * the vfolder filter rules on disk.
+ */
+void
+mail_vfolder_notify_uri_unavailable (CamelStore *store, const gchar *uri)
+{
+	mail_vfolder_add_uri (store, uri, TRUE);
+}
+
+/**
+ * mail_vfolder_delete_uri:
+ *
+ * @store: a #CamelStore containing the uri
+ * @curi: an email uri that has been deleted
+ *
+ * Looks through all vfolder rules to see if @curi is listed as a source for any
+ * vfolder rules.  If the uri is found in the source for any rule, it is removed
+ * and the user is alerted to the fact that the vfolder rules have been updated.
+ * The new vfolder rules are written to disk.
+ *
+ * XXX: It doesn't appear that the changes to the vfolder rules are sent down to
+ * the camel level, however. So the actual vfolders will not change behavior
+ * until evolution is restarted (?)
+ *
+ * NOTE: This function must be called from the main thread.
+ */
 void
 mail_vfolder_delete_uri(CamelStore *store, const gchar *curi)
 {
diff --git a/mail/mail-vfolder.h b/mail/mail-vfolder.h
index 725f7ec348..8e44ec44d5 100644
--- a/mail/mail-vfolder.h
+++ b/mail/mail-vfolder.h
@@ -44,8 +44,8 @@ void vfolder_gui_add_from_address (CamelInternetAddress *addr, gint flags, const
 GList * mail_vfolder_get_sources_local (void);
 GList * mail_vfolder_get_sources_remote (void);
 
-/* add a uri that is now (un)available to vfolders in a transient manner */
-void mail_vfolder_add_uri(CamelStore *store, const gchar *uri, gint remove);
+void mail_vfolder_notify_uri_available(CamelStore *store, const gchar *uri);
+void mail_vfolder_notify_uri_unavailable(CamelStore *store, const gchar *uri);
 
 /* note that a folder has changed name (uri) */
 void mail_vfolder_rename_uri(CamelStore *store, const gchar *from, const gchar *to);