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

1 files changed, 17 insertions, 20 deletions

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);