[couchdb-glib] Add API documentation for CouchdbSession

[Rodrigo Moya <rodrigo src gnome org>]

commit ae947a5f9e072dd7bb79af2cd6ea4c3e94e6580f
Author: Rodrigo Moya <rodrigo gnome-db org>
Date:   Tue Feb 9 16:56:39 2010 +0100

    Add API documentation for CouchdbSession

 couchdb-glib/couchdb-session.c |  127 +++++++++++++++++++++++++++++++++++++--
 couchdb-glib/couchdb-session.h |    7 ++-
 2 files changed, 126 insertions(+), 8 deletions(-)
---
diff --git a/couchdb-glib/couchdb-session.c b/couchdb-glib/couchdb-session.c
index aac65e1..c4fe8cc 100644
--- a/couchdb-glib/couchdb-session.c
+++ b/couchdb-glib/couchdb-session.c
@@ -25,6 +25,7 @@
 #include <libsoup/soup-gnome.h>
 #include <libsoup/soup-message.h>
 #include "couchdb-session.h"
+#include "couchdb-document.h"
 #include "couchdb-document-info.h"
 #include "couchdb-marshal.h"
 #include "dbwatch.h"
@@ -234,12 +235,29 @@ couchdb_session_init (CouchdbSession *couchdb)
 #endif
 }
 
+/**
+ * couchdb_session_new:
+ * @uri: URI of the CouchDB instance to connect to
+ *
+ * Create a new #CouchdbSession object, which is the entry point for operations on a
+ * CouchDB instance.
+ *
+ * Return value: A newly-created #CouchdbSession object.
+ */
 CouchdbSession *
 couchdb_session_new (const char *uri)
 {
 	return g_object_new (COUCHDB_TYPE_SESSION, "uri", uri, NULL);
 }
 
+/**
+ * couchdb_session_get_uri:
+ * @couchdb: A #CouchdbSession object
+ *
+ * Retrieve the URI of the CouchDB instance a #CouchdbSession object is bound to.
+ *
+ * Return value: the URI of the CouchDB instance used by this #CouchdbSession object.
+ */
 const char *
 couchdb_session_get_uri (CouchdbSession *couchdb)
 {
@@ -248,6 +266,17 @@ couchdb_session_get_uri (CouchdbSession *couchdb)
 	return (const char *) couchdb->priv->uri;
 }
 
+/**
+ * couchdb_session_list_databases:
+ * @couchdb: A #CouchdbSession object
+ * @error: Placeholder for error information
+ *
+ * Retrieve the list of databases that exist in the CouchDB instance being used.
+ *
+ * Return value: A #GSList of strings containing the names of all the databases
+ * that exist in the CouchDB instance connected to. Once no longer needed, this
+ * list can be freed by calling #couchdb_session_free_database_list.
+ */
 GSList *
 couchdb_session_list_databases (CouchdbSession *couchdb, GError **error)
 {
@@ -275,14 +304,25 @@ couchdb_session_list_databases (CouchdbSession *couchdb, GError **error)
 			}
 		}		
 	}
-	g_object_unref (G_OBJECT (parser));
 
 	/* Free memory */
+	g_object_unref (G_OBJECT (parser));
 	g_free (url);
 
 	return dblist;
 }
 
+/**
+ * couchdb_session_get_database_info:
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the database for which to retrieve the information
+ * @error: Placeholder for error information
+ *
+ * Retrieve information about a given database.
+ *
+ * Return value: A #CouchdbDatabaseInfo object, whose API can be used to retrieve
+ * all the information returned by CouchDB about this database.
+ */
 CouchdbDatabaseInfo *
 couchdb_session_get_database_info (CouchdbSession *couchdb, const char *dbname, GError **error)
 {
@@ -315,6 +355,16 @@ couchdb_session_get_database_info (CouchdbSession *couchdb, const char *dbname,
 	return result;
 }
 
+/**
+ * couchdb_session_create_database
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the database to be created
+ * @error: Placeholder for error information
+ *
+ * Create a new database on a CouchDB instance.
+ *
+ * Return value: TRUE if successful, FALSE otherwise.
+ */
 gboolean
 couchdb_session_create_database (CouchdbSession *couchdb, const char *dbname, GError **error)
 {
@@ -345,6 +395,16 @@ couchdb_session_create_database (CouchdbSession *couchdb, const char *dbname, GE
 	return result;
 }
 
+/**
+ * couchdb_session_delete_database
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the database to be deleted
+ * @error: Placeholder for error information
+ *
+ * Delete an existing database on a CouchDB instance.
+ *
+ * Return value: TRUE if successful, FALSE otherwise.
+ */
 gboolean
 couchdb_session_delete_database (CouchdbSession *couchdb, const char *dbname, GError **error)
 {
@@ -419,6 +479,12 @@ couchdb_session_compact_database (CouchdbSession *couchdb, const char *dbname, G
 	return result;
 }
 
+/**
+ * couchdb_session_free_database_list:
+ * @dblist: A list of databases, as returned by #couchdb_session_list_databases
+ *
+ * Free the list of databases returned by #couchdb_session_list_databases.
+ */
 void
 couchdb_session_free_database_list (GSList *dblist)
 {
@@ -430,8 +496,18 @@ couchdb_session_free_database_list (GSList *dblist)
 
 /**
  * couchdb_session_list_documents:
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the databases to retrieve documents from
+ * @error: Placeholder for error information
+ *
+ * Retrieve the list of all documents from a database on a running CouchDB instance.
+ * For each document, a #CouchdbDocumentInfo object is returned on the list, which
+ * can then be used for retrieving specific information for each document.
  *
- * Return Value: (element-type Couchdb.DocumentInfo) (transfer full)
+ * Return Value: a list of #CouchdbDocumentInfo objects, or NULL if there are none
+ * or there was an error (in which case the error argument will contain information
+ * about the error). Once no longer needed, the list should be freed by calling
+ * #couchdb_session_free_document_list.
  */
 GSList *
 couchdb_session_list_documents (CouchdbSession *couchdb, const char *dbname, GError **error)
@@ -479,6 +555,13 @@ couchdb_session_list_documents (CouchdbSession *couchdb, const char *dbname, GEr
 	return doclist;
 }
 
+/**
+ * couchdb_session_free_document_list:
+ * @doclist: A list of #CouchdbDocumentInfo objects, as returned by
+ * #couchdb_session_list_documents
+ *
+ * Free the list of documents returned by #couchdb_session_list_documents.
+ */
 void
 couchdb_session_free_document_list (GSList *doclist)
 {
@@ -488,6 +571,20 @@ couchdb_session_free_document_list (GSList *doclist)
 	g_slist_free (doclist);
 }
 
+/**
+ * couchdb_session_listen_for_changes:
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the database to poll changes for
+ *
+ * Setup a listener to get information about changes done to a specific database. Please
+ * note that changes done in the application using couchdb-glib will be notified
+ * without the need of calling this function. But if the application wants to receive
+ * notifications of changes done externally (by another application, or by any other
+ * means, like replication with a remote database), it needs to call this function.
+ *
+ * For each change, one of the signals on the #CouchdbSession object will be emitted,
+ * so applications just have to connect to those signals before calling this function.
+ */
 void
 couchdb_session_listen_for_changes (CouchdbSession *couchdb, const char *dbname)
 {
@@ -529,7 +626,8 @@ couchdb_session_listen_for_changes (CouchdbSession *couchdb, const char *dbname)
  * @couchdb: A #CouchdbSession object
  * @credentials: A #CouchdbCredentials object
  *
- * Enables authentication for the given #CouchdbSession object.
+ * Enables authentication for the given #CouchdbSession object. The authentication
+ * mechanism should be specificied when creating the #CouchdbCredentials object.
  */
 void
 couchdb_session_enable_authentication (CouchdbSession *couchdb,
@@ -719,8 +817,23 @@ parse_json_response (CouchdbSession *couchdb, JsonParser *json_parser, SoupMessa
 	return success;
 }
 
+/**
+ * couchdb_session_send_message:
+ * @couchdb: A #CouchdbSession object
+ * @method: HTTP method to use
+ * @url: URL to send the message to
+ * @body: Body of the HTTP request
+ * @output: Placeholder for output information
+ * @error: Placeholder for error information
+ *
+ * This function is used to communicate with CouchDB over HTTP, and should not be used
+ * by applications unless they really have a need (like missing API in couchdb-glib which
+ * the application needs).
+ *
+ * Return value: TRUE if successful, FALSE otherwise.
+ */
 gboolean
-couchdb_session_send_message (CouchdbSession *couchdb, const char *method, const char *url, const char *body, JsonParser *parser, GError **error)
+couchdb_session_send_message (CouchdbSession *couchdb, const char *method, const char *url, const char *body, JsonParser *output, GError **error)
 {
 	SoupMessage *http_message;
 	guint status;
@@ -758,8 +871,8 @@ couchdb_session_send_message (CouchdbSession *couchdb, const char *method, const
 #endif
 	status = soup_session_send_message (couchdb->priv->http_session, http_message);
 	if (SOUP_STATUS_IS_SUCCESSFUL (status)) {
-		if (parser != NULL)
-		       	parse_json_response (couchdb, parser, http_message, real_error);
+		if (output != NULL)
+		       	parse_json_response (couchdb, output, http_message, real_error);
 	       	return TRUE;
 	} else {
 		if (error != NULL)
@@ -779,7 +892,7 @@ static void
 debug_message (const gchar *log_domain, GLogLevelFlags log_level,
 	       const gchar *message, gpointer user_data)
 {
-	gchar* couchdb_env_debug_messages;
+	const gchar* couchdb_env_debug_messages;
 
 	couchdb_env_debug_messages = g_getenv(COUCHDB_ENV_DEBUG_MESSAGES);
 	if (couchdb_env_debug_messages != NULL) {
diff --git a/couchdb-glib/couchdb-session.h b/couchdb-glib/couchdb-session.h
index e393818..3a1a039 100644
--- a/couchdb-glib/couchdb-session.h
+++ b/couchdb-glib/couchdb-session.h
@@ -81,7 +81,12 @@ void                 couchdb_session_enable_authentication (CouchdbSession *couc
 void                 couchdb_session_disable_authentication (CouchdbSession *couchdb);
 gboolean             couchdb_session_is_authentication_enabled (CouchdbSession *couchdb);
 
-gboolean             couchdb_session_send_message (CouchdbSession *couchdb, const char *method, const char *url, const char *body, JsonParser *parser, GError **error);
+gboolean             couchdb_session_send_message (CouchdbSession *couchdb,
+						   const char *method,
+						   const char *url,
+						   const char *body,
+						   JsonParser *output,
+						   GError **error);
 
 GSList              *couchdb_session_list_documents (CouchdbSession *couchdb, const char *dbname, GError **error);
 void                 couchdb_session_free_document_list (GSList *doclist);