[evolution-data-server] Finish documenting the libebackend API.

From: Matthew Barnes <mbarnes src gnome org>
To: commits-list gnome org
Cc:
Subject: [evolution-data-server] Finish documenting the libebackend API.
Date: Sat, 12 Mar 2011 19:20:41 +0000 (UTC)
commit da30c123bb577d53f2d754c02748e871075714e8
Author: Matthew Barnes <mbarnes redhat com>
Date:   Sat Mar 12 14:19:09 2011 -0500

    Finish documenting the libebackend API.
    
    Starting small; trying to work bottom-up.

 docs/reference/libebackend/Makefile.am             |    2 +-
 .../reference/libebackend/libebackend-sections.txt |   10 +-
 docs/reference/libebackend/libebackend.types       |    2 +
 .../libebackend/tmpl/e-data-server-module.sgml     |    2 +-
 docs/reference/libebackend/tmpl/e-dbhash.sgml      |   14 +--
 docs/reference/libebackend/tmpl/e-file-cache.sgml  |    6 -
 .../libebackend/tmpl/e-offline-listener.sgml       |    9 +-
 libebackend/e-data-server-module.c                 |   62 +++++++-
 libebackend/e-data-server-module.h                 |   29 +++-
 libebackend/e-db3-utils.c                          |   42 +++++-
 libebackend/e-dbhash.c                             |   83 +++++++++-
 libebackend/e-dbhash.h                             |   59 +++++--
 libebackend/e-file-cache.c                         |  162 +++++++++++++-------
 libebackend/e-file-cache.h                         |   76 ++++++---
 libebackend/e-offline-listener.c                   |   66 +++++---
 libebackend/e-offline-listener.h                   |   56 +++++---
 16 files changed, 493 insertions(+), 187 deletions(-)
---
diff --git a/docs/reference/libebackend/Makefile.am b/docs/reference/libebackend/Makefile.am
index 7cc7e16..2a97a43 100644
--- a/docs/reference/libebackend/Makefile.am
+++ b/docs/reference/libebackend/Makefile.am
@@ -29,6 +29,6 @@ GTKDOC_LIBS = 							\
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
 
-#TESTS = $(GTKDOC_CHECK)
+TESTS = $(GTKDOC_CHECK)
 
 -include $(top_srcdir)/git.mk
diff --git a/docs/reference/libebackend/libebackend-sections.txt b/docs/reference/libebackend/libebackend-sections.txt
index 38e57ba..dcde70d 100644
--- a/docs/reference/libebackend/libebackend-sections.txt
+++ b/docs/reference/libebackend/libebackend-sections.txt
@@ -1,6 +1,5 @@
 <SECTION>
 <FILE>e-file-cache</FILE>
-EFileCachePrivate
 <TITLE>EFileCache</TITLE>
 EFileCache
 e_file_cache_new
@@ -22,14 +21,16 @@ E_TYPE_FILE_CACHE
 e_file_cache_get_type
 E_FILE_CACHE_CLASS
 E_IS_FILE_CACHE_CLASS
+E_FILE_CACHE_GET_CLASS
 EFileCacheClass
+<SUBSECTION Private>
+EFileCachePrivate
 </SECTION>
 
 <SECTION>
 <FILE>e-dbhash</FILE>
-EDbHashStatus
 EDbHash
-EDbHashPrivate
+EDbHashStatus
 EDbHashFunc
 e_dbhash_new
 e_dbhash_add
@@ -38,6 +39,8 @@ e_dbhash_compare
 e_dbhash_foreach_key
 e_dbhash_write
 e_dbhash_destroy
+<SUBSECTION Private>
+EDbHashPrivate
 </SECTION>
 
 <SECTION>
@@ -71,6 +74,7 @@ E_IS_OFFLINE_LISTENER
 E_TYPE_OFFLINE_LISTENER
 E_OFFLINE_LISTENER_CLASS
 E_IS_OFFLINE_LISTENER_CLASS
+E_OFFLINE_LISTENER_GET_CLASS
 EOfflineListenerClass
 <SUBSECTION Private>
 EOfflineListenerPrivate
diff --git a/docs/reference/libebackend/libebackend.types b/docs/reference/libebackend/libebackend.types
index 1a89530..2e4baa0 100644
--- a/docs/reference/libebackend/libebackend.types
+++ b/docs/reference/libebackend/libebackend.types
@@ -1,3 +1,5 @@
 #include <libebackend/e-file-cache.h>
+#include <libebackend/e-offline-listener.h>
 
 e_file_cache_get_type
+e_offline_listener_get_type
diff --git a/docs/reference/libebackend/tmpl/e-data-server-module.sgml b/docs/reference/libebackend/tmpl/e-data-server-module.sgml
index f13a5be..8f1e69e 100644
--- a/docs/reference/libebackend/tmpl/e-data-server-module.sgml
+++ b/docs/reference/libebackend/tmpl/e-data-server-module.sgml
@@ -44,7 +44,7 @@ e-data-server-module
 
 </para>
 
- list: 
+ extensions: 
 
 
 <!-- ##### FUNCTION e_data_server_module_remove_unused ##### -->
diff --git a/docs/reference/libebackend/tmpl/e-dbhash.sgml b/docs/reference/libebackend/tmpl/e-dbhash.sgml
index ab2ef64..a137b08 100644
--- a/docs/reference/libebackend/tmpl/e-dbhash.sgml
+++ b/docs/reference/libebackend/tmpl/e-dbhash.sgml
@@ -20,15 +20,6 @@ e-dbhash
 <!-- ##### SECTION Image ##### -->
 
 
-<!-- ##### ENUM EDbHashStatus ##### -->
-<para>
-
-</para>
-
- E_DBHASH_STATUS_SAME: 
- E_DBHASH_STATUS_DIFFERENT: 
- E_DBHASH_STATUS_NOT_FOUND: 
-
 <!-- ##### STRUCT EDbHash ##### -->
 <para>
 
@@ -36,11 +27,14 @@ e-dbhash
 
 @priv: 
 
-<!-- ##### STRUCT EDbHashPrivate ##### -->
+<!-- ##### ENUM EDbHashStatus ##### -->
 <para>
 
 </para>
 
+ E_DBHASH_STATUS_SAME: 
+ E_DBHASH_STATUS_DIFFERENT: 
+ E_DBHASH_STATUS_NOT_FOUND: 
 
 <!-- ##### USER_FUNCTION EDbHashFunc ##### -->
 <para>
diff --git a/docs/reference/libebackend/tmpl/e-file-cache.sgml b/docs/reference/libebackend/tmpl/e-file-cache.sgml
index 7820e03..53c652d 100644
--- a/docs/reference/libebackend/tmpl/e-file-cache.sgml
+++ b/docs/reference/libebackend/tmpl/e-file-cache.sgml
@@ -20,12 +20,6 @@ EFileCache
 <!-- ##### SECTION Image ##### -->
 
 
-<!-- ##### STRUCT EFileCachePrivate ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### STRUCT EFileCache ##### -->
 <para>
 
diff --git a/docs/reference/libebackend/tmpl/e-offline-listener.sgml b/docs/reference/libebackend/tmpl/e-offline-listener.sgml
index 9485b90..3dd952b 100644
--- a/docs/reference/libebackend/tmpl/e-offline-listener.sgml
+++ b/docs/reference/libebackend/tmpl/e-offline-listener.sgml
@@ -33,8 +33,13 @@ EOfflineListener
 
 </para>
 
- parent: 
- priv: 
+
+<!-- ##### SIGNAL EOfflineListener::changed ##### -->
+<para>
+
+</para>
+
+ eofflinelistener: the object which received the signal.
 
 <!-- ##### FUNCTION e_offline_listener_new ##### -->
 <para>
diff --git a/libebackend/e-data-server-module.c b/libebackend/e-data-server-module.c
index fe5a10f..5495845 100644
--- a/libebackend/e-data-server-module.c
+++ b/libebackend/e-data-server-module.c
@@ -23,6 +23,18 @@
  *
  */
 
+/**
+ * SECTION: e-data-server-module
+ * @short_description: Backend module loader
+ *
+ * An #EDataServerModule loads backend modules from the directory given
+ * in e_data_server_module_init().  Each backend module must export three
+ * functions.  The first two -- eds_module_initialize() and
+ * eds_module_list_types() -- are called immediately after the backend
+ * module is loaded.  The last one -- eds_module_shutdown() -- is called
+ * when the backend module is unloaded.
+ **/
+
 #include <config.h>
 #include "e-data-server-module.h"
 
@@ -182,6 +194,16 @@ e_data_server_module_load_file (const gchar *filename)
 	}
 }
 
+/**
+ * e_data_server_module_init:
+ * @module_path: directory of backend modules
+ * @error: return location for a #GError, or %NULL
+ *
+ * Loads all backend modules in @module_path.  If an error occurs,
+ * the function sets @error and returns %FALSE.
+ *
+ * Returns: %TRUE on success, %FALSE on failure
+ **/
 gboolean
 e_data_server_module_init (const gchar *module_path,
                            GError **error)
@@ -216,6 +238,17 @@ e_data_server_module_init (const gchar *module_path,
 	return TRUE;
 }
 
+/**
+ * e_data_server_get_extensions_for_type:
+ * @type: a #GType
+ *
+ * Returns a list of objects derived from @type which have been registered
+ * through eds_module_list_types() or e_data_server_module_add_type().
+ *
+ * Free the returned list using e_data_server_extension_list_free().
+ *
+ * Returns: a list of extension objects
+ **/
 GList *
 e_data_server_get_extensions_for_type (GType type)
 {
@@ -234,17 +267,26 @@ e_data_server_get_extensions_for_type (GType type)
 	return ret;
 }
 
+/**
+ * e_data_server_extension_list_free:
+ * @extensions: a list of extension objects
+ *
+ * Frees a list of objects returned by
+ * e_data_server_get_extensions_for_type().
+ **/
 void
 e_data_server_extension_list_free (GList *extensions)
 {
-	GList *l;
-
-	for (l = extensions; l != NULL; l = l->next) {
-		g_object_unref (l->data);
-	}
-	g_list_free (extensions);
+	g_list_free_full (extensions, (GDestroyNotify) g_object_unref);
 }
 
+/**
+ * e_data_server_module_add_type:
+ * @type: a #GType
+ *
+ * Creates an instance of @type and adds the instance to an internal list
+ * which can be queried using e_data_server_get_extensions_for_type().
+ **/
 void
 e_data_server_module_add_type (GType type)
 {
@@ -258,10 +300,12 @@ e_data_server_module_add_type (GType type)
 	module_objects = g_list_prepend (module_objects, object);
 }
 
-/*
- * Unref all loaded modules, so that unused modules are unloaded from the
+/**
+ * e_data_server_module_remove_unused:
+ *
+ * Unrefs all loaded modules, so that unused modules are unloaded from the
  * system.
- */
+ **/
 void
 e_data_server_module_remove_unused (void)
 {
diff --git a/libebackend/e-data-server-module.h b/libebackend/e-data-server-module.h
index 7220cde..777b205 100644
--- a/libebackend/e-data-server-module.h
+++ b/libebackend/e-data-server-module.h
@@ -32,7 +32,7 @@ gboolean	e_data_server_module_init	(const gchar *module_path,
 GList *		e_data_server_get_extensions_for_type
 						(GType type);
 void		e_data_server_extension_list_free
-						(GList *list);
+						(GList *extensions);
 void		e_data_server_module_remove_unused
 						(void);
 
@@ -40,10 +40,33 @@ void		e_data_server_module_remove_unused
  * without putting them in separate shared libraries */
 void		e_data_server_module_add_type	(GType  type);
 
-/* The following three functions should exist in modules that are
-   written to be dynamically loaded */
+/**
+ * eds_module_initialize:
+ * @module: a #GTypeModule
+ *
+ * Each backend module must define this function.  The module should call
+ * g_type_module_register_type() to register all dynamically-loaded types.
+ **/
 void		eds_module_initialize		(GTypeModule *module);
+
+/**
+ * eds_module_shutdown:
+ *
+ * Each backend module must define this function.  The module should
+ * release resources and perform any necessary cleanup actions prior
+ * to the service being shut down.
+ **/
 void		eds_module_shutdown		(void);
+
+/**
+ * eds_module_list_types:
+ * @types: return location for a #GType list
+ * @num_types: the length of the #GType list
+ *
+ * Each backend module must define this function.  The module should
+ * point @types to a list of types registered in eds_module_initialize()
+ * and also set @num_types to the length of that list.
+ **/
 void		eds_module_list_types		(const GType **types,
 						 gint *num_types);
 
diff --git a/libebackend/e-db3-utils.c b/libebackend/e-db3-utils.c
index d9a620d..9f7d812 100644
--- a/libebackend/e-db3-utils.c
+++ b/libebackend/e-db3-utils.c
@@ -1,5 +1,12 @@
 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
 
+/**
+ * SECTION: e-db3-utils
+ * @short_description: Utilities for Berkeley DB databases
+ *
+ * Utilities for coping with Berkeley DB file format changes.
+ **/
+
 #include "config.h"
 
 #include <errno.h>
@@ -42,7 +49,9 @@ cp_file (const gchar *src, const gchar *dest)
 	i = g_open (src, O_RDONLY | O_BINARY, 0);
 	if (i == -1)
 		return -1;
-	o = g_open (dest, O_WRONLY | O_CREAT | O_TRUNC | O_BINARY, S_IREAD | S_IWRITE);
+	o = g_open (
+		dest, O_WRONLY | O_CREAT | O_TRUNC | O_BINARY,
+		S_IREAD | S_IWRITE);
 	if (o == -1) {
 		close (i);
 		return -1;
@@ -92,16 +101,21 @@ cp_file (const gchar *src, const gchar *dest)
 static gint
 touch_file (const gchar *file)
 {
-	gint o;
-	o = g_open (file, O_WRONLY | O_CREAT | O_TRUNC | O_BINARY, S_IREAD | S_IWRITE);
-	if (o == -1)
+	gint fd;
+
+	fd = g_open (
+		file, O_WRONLY | O_CREAT | O_TRUNC | O_BINARY,
+		S_IREAD | S_IWRITE);
+	if (fd == -1)
 		return -1;
 
-	return close (o);
+	return close (fd);
 }
 
 static gint
-resume_upgrade (const gchar *filename, const gchar *copy_filename, const gchar *check_filename)
+resume_upgrade (const gchar *filename,
+                const gchar *copy_filename,
+                const gchar *check_filename)
 {
 	DB *db;
 	gint ret_val;
@@ -124,6 +138,14 @@ resume_upgrade (const gchar *filename, const gchar *copy_filename, const gchar *
 	return ret_val;
 }
 
+/**
+ * e_db3_utils_maybe_recover:
+ * @filename: path to a Berkeley DB file
+ *
+ * Tries to recover from a failed file format upgrade.
+ *
+ * Returns: 0 if successful, -1 on failure
+ **/
 gint
 e_db3_utils_maybe_recover (const gchar *filename)
 {
@@ -145,6 +167,14 @@ e_db3_utils_maybe_recover (const gchar *filename)
 	return ret_val;
 }
 
+/**
+ * e_db3_utils_upgrade_format:
+ * @filename: path to a Berkeley DB file
+ *
+ * Upgrades the file format of a Berkeley DB file from a previous version.
+ *
+ * Returns: 0 if successful, -1 on failure
+ **/
 gint
 e_db3_utils_upgrade_format (const gchar *filename)
 {
diff --git a/libebackend/e-dbhash.c b/libebackend/e-dbhash.c
index 9371dce..7528caf 100644
--- a/libebackend/e-dbhash.c
+++ b/libebackend/e-dbhash.c
@@ -6,6 +6,14 @@
  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  */
 
+/**
+ * SECTION: e-dbhash
+ * @short_description: Simple DB-based hash table for strings
+ *
+ * An #EDbHash is a simple hash table of strings backed by a Berkeley DB
+ * file for permanent storage.
+ **/
+
 #include <config.h>
 
 #include "e-dbhash.h"
@@ -14,11 +22,19 @@
 #include <fcntl.h>
 #include "db.h"
 
-struct _EDbHashPrivate
-{
+struct _EDbHashPrivate {
 	DB *db;
 };
 
+/**
+ * e_dbhash_new:
+ * @filename: path to a Berkeley DB file
+ *
+ * Creates a new #EDbHash structure and opens the given Berkeley DB file,
+ * creating the DB file if necessary.
+ *
+ * Returns: a new #EDbHash
+ **/
 EDbHash *
 e_dbhash_new (const gchar *filename)
 {
@@ -65,8 +81,18 @@ md5_to_dbt (const guint8 str[16], DBT *dbt)
 	dbt->size = 16;
 }
 
+/**
+ * e_dbhash_add:
+ * @edbh: an #EDbHash
+ * @key: a database key
+ * @data: a database object for @key
+ *
+ * Adds a database object for @key.
+ **/
 void
-e_dbhash_add (EDbHash *edbh, const gchar *key, const gchar *data)
+e_dbhash_add (EDbHash *edbh,
+              const gchar *key,
+              const gchar *data)
 {
 	DB *db;
 	DBT dkey;
@@ -102,8 +128,16 @@ e_dbhash_add (EDbHash *edbh, const gchar *key, const gchar *data)
 	db->put (db, NULL, &dkey, &ddata, 0);
 }
 
+/**
+ * e_dbhash_remove:
+ * @edbh: an #EDbHash
+ * @key: a database key
+ *
+ * Removes the database object corresponding to @key.
+ **/
 void
-e_dbhash_remove (EDbHash *edbh, const gchar *key)
+e_dbhash_remove (EDbHash *edbh,
+                 const gchar *key)
 {
 	DB *db;
 	DBT dkey;
@@ -121,8 +155,18 @@ e_dbhash_remove (EDbHash *edbh, const gchar *key)
 	db->del (db, NULL, &dkey, 0);
 }
 
+/**
+ * e_dbhash_foreach_key:
+ * @edbh: an #EDbHash
+ * @func: a callback function
+ * @user_data: data to pass to @func
+ *
+ * Calls @func for each database object.
+ **/
 void
-e_dbhash_foreach_key (EDbHash *edbh, EDbHashFunc func, gpointer user_data)
+e_dbhash_foreach_key (EDbHash *edbh,
+                      EDbHashFunc func,
+                      gpointer user_data)
 {
 	DB *db;
 	DBT dkey;
@@ -154,8 +198,23 @@ e_dbhash_foreach_key (EDbHash *edbh, EDbHashFunc func, gpointer user_data)
 	dbc->c_close (dbc);
 }
 
+/**
+ * e_dbhash_compare:
+ * @edbh: an #EDbHash
+ * @key: a database key
+ * @compare_data: data to compare against the database
+ *
+ * Compares @compare_data to the database object corresponding to
+ * @key using an MD5 checksum.  Returns #E_DBHASH_STATUS_SAME if the
+ * checksums match, #E_DBHASH_STATUS_DIFFERENT if the checksums differ,
+ * or #E_DBHASH_STATUS_NOT_FOUND if @key is not present in the database.
+ *
+ * Returns: a checksum comparison status
+ **/
 EDbHashStatus
-e_dbhash_compare (EDbHash *edbh, const gchar *key, const gchar *compare_data)
+e_dbhash_compare (EDbHash *edbh,
+                  const gchar *key,
+                  const gchar *compare_data)
 {
 	DB *db;
 	DBT dkey;
@@ -195,6 +254,12 @@ e_dbhash_compare (EDbHash *edbh, const gchar *key, const gchar *compare_data)
 	return E_DBHASH_STATUS_SAME;
 }
 
+/**
+ * e_dbhash_write:
+ * @edbh: an #EDbHash
+ *
+ * Flushes database changes to disk.
+ **/
 void
 e_dbhash_write (EDbHash *edbh)
 {
@@ -209,6 +274,12 @@ e_dbhash_write (EDbHash *edbh)
 	db->sync (db, 0);
 }
 
+/**
+ * e_dbhash_destroy:
+ * @edbh: an #EDbHash
+ *
+ * Closes the database file and frees the #EDbHash.
+ **/
 void
 e_dbhash_destroy (EDbHash *edbh)
 {
diff --git a/libebackend/e-dbhash.h b/libebackend/e-dbhash.h
index 5d84bab..92ed914 100644
--- a/libebackend/e-dbhash.h
+++ b/libebackend/e-dbhash.h
@@ -8,13 +8,24 @@
  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  */
 
-#ifndef __E_DBHASH_H__
-#define __E_DBHASH_H__
+#ifndef E_DBHASH_H
+#define E_DBHASH_H
 
 #include <glib.h>
 
 G_BEGIN_DECLS
 
+/**
+ * EDbHashStatus:
+ * @E_DBHASH_STATUS_SAME:
+ *   The checksums match.
+ * @E_DBHASH_STATUS_DIFFERENT:
+ *   The checksums differ.
+ * @E_DBHASH_STATUS_NOT_FOUND:
+ *   The given key was not found.
+ *
+ * Return codes for e_dbhash_compare().
+ **/
 typedef enum {
 	E_DBHASH_STATUS_SAME,
 	E_DBHASH_STATUS_DIFFERENT,
@@ -24,26 +35,42 @@ typedef enum {
 typedef struct _EDbHash EDbHash;
 typedef struct _EDbHashPrivate EDbHashPrivate;
 
-struct _EDbHash
-{
+/**
+ * EDbHash:
+ * @priv: private data
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
+struct _EDbHash {
 	EDbHashPrivate *priv;
 };
 
+/**
+ * EDbHashFunc:
+ * @key: a database key
+ * @user_data: user data passed to e_dbhash_foreach_key()
+ *
+ * Callback function used in e_dbhash_foreach_key().
+ **/
 typedef void (*EDbHashFunc) (const gchar *key, gpointer user_data);
 
-EDbHash *e_dbhash_new (const gchar *filename);
-
-void e_dbhash_add (EDbHash *edbh, const gchar *key, const gchar *data);
-void e_dbhash_remove (EDbHash *edbh, const gchar *key);
-
-EDbHashStatus e_dbhash_compare (EDbHash *edbh, const gchar *key, const gchar *compare_data);
-void e_dbhash_foreach_key (EDbHash *edbh, EDbHashFunc func, gpointer user_data);
-
-void e_dbhash_write (EDbHash *edbh);
-
-void e_dbhash_destroy (EDbHash *edbh);
+EDbHash *	e_dbhash_new			(const gchar *filename);
+void		e_dbhash_add			(EDbHash *edbh,
+						 const gchar *key,
+						 const gchar *data);
+void		e_dbhash_remove			(EDbHash *edbh,
+						 const gchar *key);
+EDbHashStatus	e_dbhash_compare		(EDbHash *edbh,
+						 const gchar *key,
+						 const gchar *compare_data);
+void		e_dbhash_foreach_key		(EDbHash *edbh,
+						 EDbHashFunc func,
+						 gpointer user_data);
+void		e_dbhash_write			(EDbHash *edbh);
+void		e_dbhash_destroy		(EDbHash *edbh);
 
 G_END_DECLS
 
-#endif /* __E_DBHASH_H__ */
+#endif /* E_DBHASH_H */
 
diff --git a/libebackend/e-file-cache.c b/libebackend/e-file-cache.c
index a4bbf23..2210d71 100644
--- a/libebackend/e-file-cache.c
+++ b/libebackend/e-file-cache.c
@@ -19,6 +19,15 @@
  * Authors: Rodrigo Moya <rodrigo ximian com>
  */
 
+/**
+ * SECTION: e-file-cache
+ * @short_description: Simple file-based hash table for strings
+ *
+ * An #EFileCache is a simple hash table of strings backed by an XML file
+ * for permanent storage.  The XML file is written to disk with every unless
+ * the cache is temporarily frozen with e_file_cache_freeze_changes().
+ **/
+
 #include <config.h>
 #include <string.h>
 #include <unistd.h>
@@ -146,6 +155,11 @@ e_file_cache_class_init (EFileCacheClass *klass)
 	object_class->set_property = e_file_cache_set_property;
 	object_class->get_property = e_file_cache_get_property;
 
+	/**
+	 * EFileCache:filename
+	 *
+	 * The filename of the cache.
+	 **/
 	g_object_class_install_property (object_class, PROP_FILENAME,
 					 g_param_spec_string ("filename", NULL, NULL, "",
 							      G_PARAM_READABLE | G_PARAM_WRITABLE
@@ -165,12 +179,12 @@ e_file_cache_init (EFileCache *cache)
 
 /**
  * e_file_cache_new
- * @filename: filename where the cache is kept.
+ * @filename: filename where the cache is kept
  *
  * Creates a new #EFileCache object, which implements a cache of
- * objects, very useful for remote backends.
+ * objects.  Useful for remote backends.
  *
- * Returns: The newly created object.
+ * Returns: a new #EFileCache
  */
 EFileCache *
 e_file_cache_new (const gchar *filename)
@@ -184,11 +198,11 @@ e_file_cache_new (const gchar *filename)
 
 /**
  * e_file_cache_remove:
- * @cache: A #EFileCache object.
+ * @cache: an #EFileCache
  *
  * Remove the cache from disk.
  *
- * Returns: TRUE if successful, FALSE otherwise.
+ * Returns: %TRUE if successful, %FALSE if a file error occurred
  */
 gboolean
 e_file_cache_remove (EFileCache *cache)
@@ -252,28 +266,28 @@ add_key_to_slist (const gchar *key, const gchar *value, gpointer user_data)
 
 /**
  * e_file_cache_clean:
- * @cache: A #EFileCache object.
+ * @cache: an #EFileCache
  *
  * Clean up the cache's contents.
  *
- * Returns: TRUE if successful, FALSE otherwise.
+ * Returns: %TRUE always
  */
 gboolean
 e_file_cache_clean (EFileCache *cache)
 {
-	EFileCachePrivate *priv;
 	GSList *keys = NULL;
 	gboolean iFroze;
 
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), FALSE);
 
-	priv = cache->priv;
-	iFroze = !priv->frozen;
+	iFroze = !cache->priv->frozen;
 
 	if (iFroze)
 		e_file_cache_freeze_changes (cache);
 
-	e_xmlhash_foreach_key (priv->xml_hash, (EXmlHashFunc) add_key_to_slist, &keys);
+	e_xmlhash_foreach_key (
+		cache->priv->xml_hash,
+		(EXmlHashFunc) add_key_to_slist, &keys);
 	while (keys != NULL) {
 		e_file_cache_remove_object (cache, (const gchar *) keys->data);
 		keys = g_slist_remove (keys, keys->data);
@@ -307,23 +321,30 @@ find_object_in_hash (gpointer key, gpointer value, gpointer user_data)
 
 /**
  * e_file_cache_get_object:
+ * @cache: an #EFileCache
+ * @key: the hash key of the object to find
+ *
+ * Returns the object corresponding to @key.  If no such object exists
+ * in @cache, the function returns %NULL.
+ *
+ * Returns: the object corresponding to @key
  */
 const gchar *
-e_file_cache_get_object (EFileCache *cache, const gchar *key)
+e_file_cache_get_object (EFileCache *cache,
+                         const gchar *key)
 {
 	CacheFindData find_data;
-	EFileCachePrivate *priv;
 
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), NULL);
 	g_return_val_if_fail (key != NULL, NULL);
 
-	priv = cache->priv;
-
 	find_data.key = key;
 	find_data.found = FALSE;
 	find_data.found_value = NULL;
 
-	e_xmlhash_foreach_key (priv->xml_hash, (EXmlHashFunc) find_object_in_hash, &find_data);
+	e_xmlhash_foreach_key (
+		cache->priv->xml_hash,
+		(EXmlHashFunc) find_object_in_hash, &find_data);
 
 	return find_data.found_value;
 }
@@ -338,62 +359,78 @@ add_object_to_slist (const gchar *key, const gchar *value, gpointer user_data)
 
 /**
  * e_file_cache_get_objects:
+ * @cache: an #EFileCache
+ *
+ * Returns a list of objects in @cache.  The objects are owned by @cache and
+ * must not be modified or freed.  Free the returned list with g_slist_free().
+ *
+ * Returns: a list of objects
  */
 GSList *
 e_file_cache_get_objects (EFileCache *cache)
 {
-	EFileCachePrivate *priv;
 	GSList *list = NULL;
 
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), NULL);
 
-	priv = cache->priv;
-
-	e_xmlhash_foreach_key (priv->xml_hash, (EXmlHashFunc) add_object_to_slist, &list);
+	e_xmlhash_foreach_key (
+		cache->priv->xml_hash,
+		(EXmlHashFunc) add_object_to_slist, &list);
 
 	return list;
 }
 
 /**
  * e_file_cache_get_keys:
+ * @cache: an #EFileCache
+ *
+ * Returns a list of keys in @cache.  The keys are owned by @cache and must
+ * not be modified or freed.  Free the returned list with g_slist_free().
+ *
+ * Returns: a list of keys
  */
 GSList *
 e_file_cache_get_keys (EFileCache *cache)
 {
-	EFileCachePrivate *priv;
 	GSList *list = NULL;
 
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), NULL);
 
-	priv = cache->priv;
-
-	e_xmlhash_foreach_key (priv->xml_hash, (EXmlHashFunc) add_key_to_slist, &list);
+	e_xmlhash_foreach_key (
+		cache->priv->xml_hash,
+		(EXmlHashFunc) add_key_to_slist, &list);
 
 	return list;
 }
 
 /**
  * e_file_cache_add_object:
+ * @cache: an #EFileCache
+ * @key: the hash key of the object to add
+ * @value: the object to add
+ *
+ * Adds a new @key / @value entry to @cache.  If an object corresponding
+ * to @key already exists in @cache, the function returns %FALSE.
+ *
+ * Returns: %TRUE if successful, %FALSE if @key already exists
  */
 gboolean
-e_file_cache_add_object (EFileCache *cache, const gchar *key, const gchar *value)
+e_file_cache_add_object (EFileCache *cache,
+                         const gchar *key,
+                         const gchar *value)
 {
-	EFileCachePrivate *priv;
-
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), FALSE);
 	g_return_val_if_fail (key != NULL, FALSE);
 
-	priv = cache->priv;
-
 	if (e_file_cache_get_object (cache, key))
 		return FALSE;
 
-	e_xmlhash_add (priv->xml_hash, key, value);
-	if (priv->frozen)
-		priv->dirty = TRUE;
+	e_xmlhash_add (cache->priv->xml_hash, key, value);
+	if (cache->priv->frozen)
+		cache->priv->dirty = TRUE;
 	else {
-		e_xmlhash_write (priv->xml_hash);
-		priv->dirty = FALSE;
+		e_xmlhash_write (cache->priv->xml_hash);
+		cache->priv->dirty = FALSE;
 	}
 
 	return TRUE;
@@ -401,9 +438,19 @@ e_file_cache_add_object (EFileCache *cache, const gchar *key, const gchar *value
 
 /**
  * e_file_cache_replace_object:
+ * @cache: an #EFileCache
+ * @key: the hash key of the object to replace
+ * @new_value: the new object for @key
+ *
+ * Replaces the object corresponding to @key with @new_value.
+ * If no such object exists in @cache, the function returns %FALSE.
+ *
+ * Returns: %TRUE if successful, %FALSE if @key was not found
  */
 gboolean
-e_file_cache_replace_object (EFileCache *cache, const gchar *key, const gchar *new_value)
+e_file_cache_replace_object (EFileCache *cache,
+                             const gchar *key,
+                             const gchar *new_value)
 {
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), FALSE);
 	g_return_val_if_fail (key != NULL, FALSE);
@@ -419,9 +466,17 @@ e_file_cache_replace_object (EFileCache *cache, const gchar *key, const gchar *n
 
 /**
  * e_file_cache_remove_object:
+ * @cache: an #EFileCache
+ * @key: the hash key of the object to remove
+ *
+ * Removes the object corresponding to @key from @cache.
+ * If no such object exists in @cache, the function returns %FALSE.
+ *
+ * Returns: %TRUE if successful, %FALSE if @key was not found
  */
 gboolean
-e_file_cache_remove_object (EFileCache *cache, const gchar *key)
+e_file_cache_remove_object (EFileCache *cache,
+                            const gchar *key)
 {
 	EFileCachePrivate *priv;
 
@@ -446,44 +501,36 @@ e_file_cache_remove_object (EFileCache *cache, const gchar *key)
 
 /**
  * e_file_cache_freeze_changes:
- * @cache: An #EFileCache object.
+ * @cache: an #EFileCache
  *
- * Disables temporarily all writes to disk for the given cache object.
+ * Disables temporarily all writes to disk for @cache.
  */
 void
 e_file_cache_freeze_changes (EFileCache *cache)
 {
-	EFileCachePrivate *priv;
-
 	g_return_if_fail (E_IS_FILE_CACHE (cache));
 
-	priv = cache->priv;
-
-	priv->frozen++;
-	g_return_if_fail (priv->frozen > 0);
+	cache->priv->frozen++;
+	g_return_if_fail (cache->priv->frozen > 0);
 }
 
 /**
  * e_file_cache_thaw_changes:
- * @cache: An #EFileCache object.
+ * @cache: an #EFileCache
  *
- * Enables again writes to disk on every change.
+ * Reverts the affects of e_file_cache_freeze_changes().
+ * Each change to @cache is once again written to disk.
  */
 void
 e_file_cache_thaw_changes (EFileCache *cache)
 {
-	EFileCachePrivate *priv;
-
 	g_return_if_fail (E_IS_FILE_CACHE (cache));
+	g_return_if_fail (cache->priv->frozen > 0);
 
-	priv = cache->priv;
-
-	g_return_if_fail (priv->frozen > 0);
-
-	priv->frozen--;
-	if (!priv->frozen && priv->dirty) {
-		e_xmlhash_write (priv->xml_hash);
-		priv->dirty = FALSE;
+	cache->priv->frozen--;
+	if (!cache->priv->frozen && cache->priv->dirty) {
+		e_xmlhash_write (cache->priv->xml_hash);
+		cache->priv->dirty = FALSE;
 	}
 }
 
@@ -499,6 +546,7 @@ const gchar *
 e_file_cache_get_filename (EFileCache *cache)
 {
 	g_return_val_if_fail (E_IS_FILE_CACHE (cache), NULL);
-	return (const gchar *) cache->priv->filename;
+
+	return cache->priv->filename;
 }
 
diff --git a/libebackend/e-file-cache.h b/libebackend/e-file-cache.h
index b708c0f..ac5e6fc 100644
--- a/libebackend/e-file-cache.h
+++ b/libebackend/e-file-cache.h
@@ -24,41 +24,65 @@
 
 #include <glib-object.h>
 
-G_BEGIN_DECLS
+/* Standard GObject macros */
+#define E_TYPE_FILE_CACHE \
+	(e_file_cache_get_type ())
+#define E_FILE_CACHE(obj) \
+	(G_TYPE_CHECK_INSTANCE_CAST \
+	((obj), E_TYPE_FILE_CACHE, EFileCache))
+#define E_FILE_CACHE_CLASS(cls) \
+	(G_TYPE_CHECK_CLASS_CAST \
+	((cls), E_TYPE_FILE_CACHE, EFileCacheClass))
+#define E_IS_FILE_CACHE(obj) \
+	(G_TYPE_CHECK_INSTANCE_TYPE \
+	((obj), E_TYPE_FILE_CACHE))
+#define E_IS_FILE_CACHE_CLASS(cls) \
+	(G_TYPE_CHECK_CLASS_TYPE \
+	((cls), E_TYPE_FILE_CACHE))
+#define E_FILE_CACHE_GET_CLASS(obj) \
+	(G_TYPE_INSTANCE_GET_CLASS \
+	((obj), E_TYPE_FILE_CACHE, EFileCacheClass))
 
-#define E_TYPE_FILE_CACHE            (e_file_cache_get_type ())
-#define E_FILE_CACHE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), E_TYPE_FILE_CACHE, EFileCache))
-#define E_FILE_CACHE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), E_TYPE_FILE_CACHE, EFileCacheClass))
-#define E_IS_FILE_CACHE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), E_TYPE_FILE_CACHE))
-#define E_IS_FILE_CACHE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), E_TYPE_FILE_CACHE))
+G_BEGIN_DECLS
 
+typedef struct _EFileCache EFileCache;
+typedef struct _EFileCacheClass EFileCacheClass;
 typedef struct _EFileCachePrivate EFileCachePrivate;
 
-typedef struct {
+/**
+ * EFileCache:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
+struct _EFileCache {
 	GObject parent;
 	EFileCachePrivate *priv;
-} EFileCache;
+};
 
-typedef struct {
+struct _EFileCacheClass {
 	GObjectClass parent_class;
-} EFileCacheClass;
-
-GType       e_file_cache_get_type (void);
-
-EFileCache *e_file_cache_new (const gchar *filename);
-gboolean    e_file_cache_remove (EFileCache *cache);
-gboolean    e_file_cache_clean (EFileCache *cache);
-
-const gchar *e_file_cache_get_object (EFileCache *cache, const gchar *key);
-GSList     *e_file_cache_get_objects (EFileCache *cache);
-GSList     *e_file_cache_get_keys (EFileCache *cache);
-gboolean    e_file_cache_add_object (EFileCache *cache, const gchar *key, const gchar *value);
-gboolean    e_file_cache_replace_object (EFileCache *cache, const gchar *key, const gchar *new_value);
-gboolean    e_file_cache_remove_object (EFileCache *cache, const gchar *key);
+};
 
-void        e_file_cache_freeze_changes (EFileCache *cache);
-void        e_file_cache_thaw_changes (EFileCache *cache);
-const gchar *e_file_cache_get_filename (EFileCache *cache);
+GType		e_file_cache_get_type		(void) G_GNUC_CONST;
+EFileCache *	e_file_cache_new		(const gchar *filename);
+gboolean	e_file_cache_remove		(EFileCache *cache);
+gboolean	e_file_cache_clean		(EFileCache *cache);
+const gchar *	e_file_cache_get_object		(EFileCache *cache,
+						 const gchar *key);
+GSList *	e_file_cache_get_objects	(EFileCache *cache);
+GSList *	e_file_cache_get_keys		(EFileCache *cache);
+gboolean	e_file_cache_add_object		(EFileCache *cache,
+						 const gchar *key,
+						 const gchar *value);
+gboolean	e_file_cache_replace_object	(EFileCache *cache,
+						 const gchar *key,
+						 const gchar *new_value);
+gboolean	e_file_cache_remove_object	(EFileCache *cache,
+						 const gchar *key);
+void		e_file_cache_freeze_changes	(EFileCache *cache);
+void		e_file_cache_thaw_changes	(EFileCache *cache);
+const gchar *	e_file_cache_get_filename	(EFileCache *cache);
 
 G_END_DECLS
 
diff --git a/libebackend/e-offline-listener.c b/libebackend/e-offline-listener.c
index 981e07b..f0e1575 100644
--- a/libebackend/e-offline-listener.c
+++ b/libebackend/e-offline-listener.c
@@ -20,6 +20,19 @@
  * Author: Sivaiah Nallagatla <snallagatla novell com>
  */
 
+/**
+ * SECTION: e-offline-listener
+ * @short_description: Tracks Evolution's online/offline state
+ *
+ * An #EOfflineListener basically just tracks Evolution's online/offline
+ * state and emits a #EOfflineListener:changed signal when a state change
+ * is detected.
+ *
+ * This class is highly Evolution-centric and probably not suitable for
+ * general purpose use.  Frankly it should be deprecated and replaced
+ * with a D-Bus method.
+ **/
+
 /*Note : Copied from src/offline_listener.c . This should be replaced */
 /* with network manager code */
 
@@ -41,8 +54,7 @@ static guint signals[NUM_SIGNALS] = { 0 };
 
 static GObjectClass *parent_class = NULL;
 
-struct _EOfflineListenerPrivate
-{
+struct _EOfflineListenerPrivate {
 	GConfClient *default_client;
 	gboolean is_offline_now;
 };
@@ -54,7 +66,10 @@ set_online_status (EOfflineListener *eol, gboolean is_offline)
 }
 
 static void
-online_status_changed (GConfClient *client, gint cnxn_id, GConfEntry *entry, gpointer data)
+online_status_changed (GConfClient *client,
+                       gint cnxn_id,
+                       GConfEntry *entry,
+                       gpointer data)
 {
 	GConfValue *value;
 	gboolean offline;
@@ -120,52 +135,55 @@ e_offline_listener_dispose (GObject *object)
 		eol->priv->default_client = NULL;
 	}
 
-	(* G_OBJECT_CLASS (parent_class)->dispose) (object);
+	/* Chain up to parent's dispose() method. */
+	G_OBJECT_CLASS (parent_class)->dispose (object);
 }
 
 static void
 e_offline_listener_finalize (GObject *object)
 {
 	EOfflineListener *eol;
-	EOfflineListenerPrivate *priv;
 
 	eol = E_OFFLINE_LISTENER (object);
-	priv = eol->priv;
 
-	g_free (priv);
+	g_free (eol->priv);
 	eol->priv = NULL;
 
-	parent_class->finalize (object);
+	/* Chain up to parent's finalize() method. */
+	G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
 static void
 e_offline_listener_init (EOfflineListener *eol)
 {
-	EOfflineListenerPrivate *priv;
-
-	priv = g_new0 (EOfflineListenerPrivate, 1);
-	eol->priv = priv;
+	eol->priv = g_new0 (EOfflineListenerPrivate, 1);
 }
 
 static void
-e_offline_listener_class_init (EOfflineListenerClass *klass)
+e_offline_listener_class_init (EOfflineListenerClass *class)
 {
 	GObjectClass *object_class;
 
-	parent_class = g_type_class_peek_parent (klass);
+	parent_class = g_type_class_peek_parent (class);
 
-	object_class = G_OBJECT_CLASS (klass);
+	object_class = G_OBJECT_CLASS (class);
 	object_class->dispose = e_offline_listener_dispose;
 	object_class->finalize = e_offline_listener_finalize;
 
-	signals[CHANGED] =
-		g_signal_new ("changed",
-			      G_OBJECT_CLASS_TYPE (object_class),
-			      G_SIGNAL_RUN_LAST,
-			      G_STRUCT_OFFSET (EOfflineListenerClass, changed),
-			      NULL, NULL,
-			      g_cclosure_marshal_VOID__VOID,
-			      G_TYPE_NONE, 0);
+	/**
+	 * EOfflineListener::changed:
+	 * @listener: the #EOfflineListener that received the signal
+	 *
+	 * Emitted when Evolution's online/offline state changes.
+	 **/
+	signals[CHANGED] = g_signal_new (
+		"changed",
+		G_OBJECT_CLASS_TYPE (object_class),
+		G_SIGNAL_RUN_LAST,
+		G_STRUCT_OFFSET (EOfflineListenerClass, changed),
+		NULL, NULL,
+		g_cclosure_marshal_VOID__VOID,
+		G_TYPE_NONE, 0);
 }
 
 /**
@@ -174,6 +192,8 @@ e_offline_listener_class_init (EOfflineListenerClass *klass)
  *
  * FIXME Document me!
  *
+ * Returns: #EOL_STATE_OFFLINE or #EOL_STATE_ONLINE
+ *
  * Since: 2.30
  **/
 EOfflineListenerState
diff --git a/libebackend/e-offline-listener.h b/libebackend/e-offline-listener.h
index d92840c..130fd2f 100644
--- a/libebackend/e-offline-listener.h
+++ b/libebackend/e-offline-listener.h
@@ -20,8 +20,8 @@
  * Author: Sivaiah Nallagatla <snallagatla novell com>
  */
 
-#ifndef _E_OFFLINE_LISTENER_H_
-#define _E_OFFLINE_LISTENER_H_
+#ifndef E_OFFLINE_LISTENER_H
+#define E_OFFLINE_LISTENER_H
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>
@@ -29,22 +29,39 @@
 
 #include <glib-object.h>
 
-G_BEGIN_DECLS
+/* Standard GObject macros */
+#define E_TYPE_OFFLINE_LISTENER \
+	(e_offline_listener_get_type ())
+#define E_OFFLINE_LISTENER(obj) \
+	((G_TYPE_CHECK_INSTANCE_CAST \
+	((obj), E_TYPE_OFFLINE_LISTENER, EOfflineListener)))
+#define E_OFFLINE_LISTENER_CLASS(cls) \
+	(G_TYPE_CHECK_CLASS_CAST \
+	((cls), E_TYPE_OFFLINE_LISTENER, EOfflineListenerClass))
+#define E_IS_OFFLINE_LISTENER(obj) \
+	(G_TYPE_CHECK_INSTANCE_TYPE \
+	((obj), E_TYPE_OFFLINE_LISTENER))
+#define E_IS_OFFLINE_LISTENER_CLASS(cls) \
+	(G_TYPE_CHECK_CLASS_TYPE \
+	((cls), E_TYPE_OFFLINE_LISTENER))
+#define E_OFFLINE_LISTENER_GET_CLASS(obj) \
+	(G_TYPE_INSTANCE_GET_CLASS \
+	((obj), E_TYPE_OFFLINE_LISTENER, EOfflineListenerClass))
 
-#define E_TYPE_OFFLINE_LISTENER			(e_offline_listener_get_type ())
-#define E_OFFLINE_LISTENER(obj)			((G_TYPE_CHECK_INSTANCE_CAST((obj), E_TYPE_OFFLINE_LISTENER, EOfflineListener)))
-#define E_OFFLINE_LISTENER_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST((klass), E_TYPE_OFFLINE_LISTENER, EOfflineListenerClass))
-#define E_IS_OFFLINE_LISTENER(obj)		(G_TYPE_CHECK_INSTANCE_TYPE ((obj), E_TYPE_OFFLINE_LISTENER))
-#define E_IS_OFFLINE_LISTENER_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE ((obj), E_TYPE_OFFLINE_LISTENER))
+G_BEGIN_DECLS
 
-typedef struct _EOfflineListener         EOfflineListener;
-typedef struct _EOfflineListenerPrivate  EOfflineListenerPrivate;
-typedef struct _EOfflineListenerClass    EOfflineListenerClass;
+typedef struct _EOfflineListener EOfflineListener;
+typedef struct _EOfflineListenerClass EOfflineListenerClass;
+typedef struct _EOfflineListenerPrivate EOfflineListenerPrivate;
 
 /**
  * EOfflineListenerState:
  * @EOL_STATE_OFFLINE:
+ *   Evolution is in offline mode.
  * @EOL_STATE_ONLINE:
+ *   Evolution is in online mode.
+ *
+ * Indicates the online/offline state of the listener.
  *
  * Since: 2.30
  **/
@@ -56,6 +73,9 @@ typedef enum {
 /**
  * EOfflineListener:
  *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ *
  * Since: 2.30
  **/
 struct _EOfflineListener {
@@ -64,17 +84,17 @@ struct _EOfflineListener {
 };
 
 struct _EOfflineListenerClass {
-	GObjectClass  parent_class;
+	GObjectClass parent_class;
 
 	void (*changed) (EOfflineListener *eol, EOfflineListenerState state);
 };
 
-GType e_offline_listener_get_type  (void);
-
-EOfflineListener  *e_offline_listener_new (void);
-
-EOfflineListenerState e_offline_listener_get_state (EOfflineListener *eol);
+GType		e_offline_listener_get_type	(void);
+EOfflineListener *
+		e_offline_listener_new		(void);
+EOfflineListenerState
+		e_offline_listener_get_state	(EOfflineListener *eol);
 
 G_END_DECLS
 
-#endif /* _E_OFFLINE_LISTENER_H_ */
+#endif /* E_OFFLINE_LISTENER_H */
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]