[couchdb-glib] Add CouchdbDocument API documentation

[Rodrigo Moya <rodrigo src gnome org>]

commit 9abb8e1e922a7dc776a1ff1986d9462e31ac210a
Author: Rodrigo Moya <rodrigo gnome-db org>
Date:   Tue Feb 9 17:38:09 2010 +0100

    Add CouchdbDocument API documentation

 couchdb-glib/couchdb-document.c |  210 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 210 insertions(+), 0 deletions(-)
---
diff --git a/couchdb-glib/couchdb-document.c b/couchdb-glib/couchdb-document.c
index 49475ae..7ff5749 100644
--- a/couchdb-glib/couchdb-document.c
+++ b/couchdb-glib/couchdb-document.c
@@ -65,6 +65,15 @@ couchdb_document_init (CouchdbDocument *document)
 	document->dbname = NULL;
 }
 
+/**
+ * couchdb_document_new:
+ * @couchdb: A #CouchdbSession object
+ *
+ * Create an empty #CouchdbDocument object, which can then be populated with data
+ * and added to a database on the specified CouchDB instance.
+ *
+ * Return value: A newly-created #CouchdbDocument object, with no data on it.
+ */
 CouchdbDocument *
 couchdb_document_new (CouchdbSession *couchdb)
 {
@@ -80,6 +89,18 @@ couchdb_document_new (CouchdbSession *couchdb)
 	return document;
 }
 
+/**
+ * couchdb_document_get:
+ * @couchdb: A #CouchdbSession object
+ * @dbname: Name of the database to retrieve the document from
+ * @docid: Unique ID of the document to be retrieved
+ * @error: Placeholder for error information
+ *
+ * Retrieve the last revision of a document from the given database.
+ *
+ * Return value: A #CouchdbDocument object if successful, NULL otherwise, in
+ * which case, the error argument will contain information about the error.
+ */
 CouchdbDocument *
 couchdb_document_get (CouchdbSession *couchdb,
 		      const char *dbname,
@@ -111,6 +132,24 @@ couchdb_document_get (CouchdbSession *couchdb,
 	return document;
 }
 
+/**
+ * couchdb_document_put:
+ * @document: A #CouchdbDocument object
+ * @dbname: Name of the database where the document will be stored
+ * @error: Placeholder for error information
+ *
+ * Store a document on a CouchDB database.
+ *
+ * If it is a new document, and hence does not have a unique ID, a unique ID
+ * will be generated and stored on the #CouchdbDocument object. Likewise,
+ * whether the document is new or just an update to an existing one, the
+ * #CouchdbDocument object passed to this function will be updated to contain
+ * the latest revision of the document, as returned by CouchDB (revision that
+ * can be retrieved by calling #couchdb_document_get_revision).
+ *
+ * Return value: TRUE if successful, FALSE otherwise, in which case the error
+ * argument will contain information about the error.
+ */
 gboolean
 couchdb_document_put (CouchdbDocument *document,
 		      const char *dbname,
@@ -169,6 +208,24 @@ couchdb_document_put (CouchdbDocument *document,
 	return result;
 }
 
+/**
+ * couchdb_document_delete:
+ * @document: A #CouchdbDocument object
+ * @error: Placeholder for error information
+ *
+ * Delete an existing document from a CouchDB instance.
+ *
+ * Please take note that this operation can fail if there was an update to the
+ * document and that last revision was not retrieved by the calling application.
+ * This is due to the fact that, to remove a document from CouchDB, the latest
+ * revision needs to be sent, so if the #CouchdbDocument object passed to this
+ * function does not contain the last revision, the operation will fail. In that
+ * case, retrieving the latest revision from CouchDB (with #couchdb_document_get)
+ * and trying the delete operation again should fix the issue.
+ *
+ * Return value: TRUE if successful, FALSE otherwise, in which case the error
+ * argument will contain information about the error.
+ */
 gboolean
 couchdb_document_delete (CouchdbDocument *document, GError **error)
 {
@@ -197,6 +254,14 @@ couchdb_document_delete (CouchdbDocument *document, GError **error)
 	return result;
 }
 
+/**
+ * couchdb_document_get_id:
+ * @document: A #CouchdbDocument object
+ *
+ * Retrieve the unique ID of the given document.
+ *
+ * Return value: The unique ID of the given document.
+ */
 const char *
 couchdb_document_get_id (CouchdbDocument *document)
 {
@@ -214,6 +279,19 @@ couchdb_document_get_id (CouchdbDocument *document)
 	return NULL;
 }
 
+/**
+ * couchdb_document_set_id:
+ * @document: A #CouchdbDocument object
+ * @id: New unique ID for the given document.
+ *
+ * Set the unique ID for a given document.
+ *
+ * This usually is not needed by calling applications, unless they want to
+ * force IDs on the CouchDB documents created/updated for some reason, like
+ * compatibility with 3rd party applications. In most cases, the autogenerated
+ * IDs from CouchDB when new documents are created (see #couchdb_document_put)
+ * should be ok for most applications.
+ */
 void
 couchdb_document_set_id (CouchdbDocument *document, const char *id)
 {
@@ -225,6 +303,20 @@ couchdb_document_set_id (CouchdbDocument *document, const char *id)
 				       id);
 }
 
+/**
+ * couchdb_document_get_revision:
+ * @document: A #CouchdbDocument object
+ *
+ * Retrieve the revision of a given document.
+ *
+ * CouchDB does not overwrite updated documents in place, instead it creates a
+ * new document at the end of the database file, with the same ID but a new revision.
+ *
+ * Document revisions are used for optimistic concurrency control and applications
+ * should not rely on document revisions for any other purpose than concurrency control.
+ *
+ * Return value: Revision of the given document.
+ */
 const char *
 couchdb_document_get_revision (CouchdbDocument *document)
 {
@@ -240,6 +332,15 @@ couchdb_document_get_revision (CouchdbDocument *document)
 	return NULL;
 }
 
+/**
+ * couchdb_document_set_revision:
+ * @document: A #CouchdbDocument object
+ * @revision: String specifying the revision to set the document to
+ *
+ * Set the revision of the given document. This should never be used by applications,
+ * unless they really know what they are doing, since using a wrong revision string
+ * will confuse CouchDB when doing updates to the document.
+ */
 void
 couchdb_document_set_revision (CouchdbDocument *document, const char *revision)
 {
@@ -251,6 +352,15 @@ couchdb_document_set_revision (CouchdbDocument *document, const char *revision)
 				       revision);
 }
 
+/**
+ * couchdb_document_has_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to check existence for in the document
+ *
+ * Check whether the given document has a field with a specific name.
+ *
+ * Return value: TRUE if the field exists in the document, FALSE if not.
+ */
 gboolean
 couchdb_document_has_field (CouchdbDocument *document, const char *field)
 {
@@ -262,6 +372,13 @@ couchdb_document_has_field (CouchdbDocument *document, const char *field)
 	return json_object_has_member (json_node_get_object (document->root_node), field);
 }
 
+/**
+ * couchdb_document_remove_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to remove from the document
+ *
+ * Remove a field from the given document.
+ */
 void
 couchdb_document_remove_field (CouchdbDocument *document, const char *field)
 {
@@ -271,6 +388,15 @@ couchdb_document_remove_field (CouchdbDocument *document, const char *field)
 	json_object_remove_member (json_node_get_object (document->root_node), field);
 }
 
+/**
+ * couchdb_document_get_boolean_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to retrieve
+ *
+ * Retrieve the value of a boolean field from the given document.
+ *
+ * Return value: The value of the given boolean field.
+ */
 gboolean
 couchdb_document_get_boolean_field (CouchdbDocument *document, const char *field)
 {
@@ -284,6 +410,14 @@ couchdb_document_get_boolean_field (CouchdbDocument *document, const char *field
 					       field);
 }
 
+/**
+ * couchdb_document_set_boolean_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to set
+ * @value: Value to set the field to
+ *
+ * Set the value of a boolean field in the given document.
+ */
 void
 couchdb_document_set_boolean_field (CouchdbDocument *document, const char *field, gboolean value)
 {
@@ -295,6 +429,15 @@ couchdb_document_set_boolean_field (CouchdbDocument *document, const char *field
 					value);
 }
 
+/**
+ * couchdb_document_get_int_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to retrieve
+ *
+ * Retrieve the value of an integer field from the given document.
+ *
+ * Return value: The value of the given integer field.
+ */
 gint
 couchdb_document_get_int_field (CouchdbDocument *document, const char *field)
 {
@@ -308,6 +451,14 @@ couchdb_document_get_int_field (CouchdbDocument *document, const char *field)
 					   field);
 }
 
+/**
+ * couchdb_document_set_int_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to set
+ * @value: Value to set the field to
+ *
+ * Set the value of an integer field in the given document.
+ */
 void
 couchdb_document_set_int_field (CouchdbDocument *document, const char *field, gint value)
 {
@@ -319,6 +470,15 @@ couchdb_document_set_int_field (CouchdbDocument *document, const char *field, gi
 				    value);
 }
 
+/**
+ * couchdb_document_get_double_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to retrieve
+ *
+ * Retrieve the value of a decimal number field from the given document.
+ *
+ * Return value: The value of the given decimal number field.
+ */
 gdouble
 couchdb_document_get_double_field (CouchdbDocument *document, const char *field)
 {
@@ -331,6 +491,14 @@ couchdb_document_get_double_field (CouchdbDocument *document, const char *field)
 					      field);
 }
 
+/**
+ * couchdb_document_set_double_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to set
+ * @value: Value to set the field to
+ *
+ * Set the value of a decimal number field in the given document.
+ */
 void
 couchdb_document_set_double_field (CouchdbDocument *document, const char *field, gdouble value)
 {
@@ -342,6 +510,15 @@ couchdb_document_set_double_field (CouchdbDocument *document, const char *field,
 				       value);
 }
 
+/**
+ * couchdb_document_get_string_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to retrieve
+ *
+ * Retrieve the value of a string field from the given document.
+ *
+ * Return value: The value of the given string field.
+ */
 const char *
 couchdb_document_get_string_field (CouchdbDocument *document, const char *field)
 {
@@ -355,6 +532,14 @@ couchdb_document_get_string_field (CouchdbDocument *document, const char *field)
 					      field);
 }
 
+/**
+ * couchdb_document_set_string_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to set
+ * @value: Value to set the field to
+ *
+ * Set the value of a string field in the given document.
+ */
 void
 couchdb_document_set_string_field (CouchdbDocument *document, const char *field, const char *value)
 {
@@ -371,6 +556,15 @@ couchdb_document_set_string_field (CouchdbDocument *document, const char *field,
 	}
 }
 
+/**
+ * couchdb_document_get_struct_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to retrieve
+ *
+ * Retrieve the value of a struct field from the given document.
+ *
+ * Return value: The value of the given struct field.
+ */
 CouchdbStructField *
 couchdb_document_get_struct_field (CouchdbDocument *document, const char *field)
 {
@@ -385,6 +579,14 @@ couchdb_document_get_struct_field (CouchdbDocument *document, const char *field)
 								field)));
 }
 
+/**
+ * couchdb_document_set_struct_field:
+ * @document: A #CouchdbDocument object
+ * @field: Name of the field to set
+ * @value: Value to set the field to
+ *
+ * Set the value of a struct field in the given document.
+ */
 void
 couchdb_document_set_struct_field (CouchdbDocument *document, const char *field, CouchdbStructField *value)
 {
@@ -397,6 +599,14 @@ couchdb_document_set_struct_field (CouchdbDocument *document, const char *field,
 				       json_object_ref (couchdb_struct_field_get_json_object (value)));
 }
 
+/**
+ * couchdb_document_to_string:
+ * @document: A #CouchdbDocument object
+ *
+ * Convert the given #CouchdbDocument to a JSON string.
+ *
+ * Return value: A string containing the given document in JSON format.
+ */
 char *
 couchdb_document_to_string (CouchdbDocument *document)
 {