[couchdb-glib] Add CouchdbStructField API documentation

[Rodrigo Moya <rodrigo src gnome org>]

commit 8a9bf5136671e34d8f98ec974e3e4fb1c2e1e182
Author: Rodrigo Moya <rodrigo gnome-db org>
Date:   Wed Feb 10 17:02:14 2010 +0100

    Add CouchdbStructField API documentation

 couchdb-glib/couchdb-struct-field.c |  187 +++++++++++++++++++++++++++++++++++
 1 files changed, 187 insertions(+), 0 deletions(-)
---
diff --git a/couchdb-glib/couchdb-struct-field.c b/couchdb-glib/couchdb-struct-field.c
index b7d3d4a..6b0ce3a 100644
--- a/couchdb-glib/couchdb-struct-field.c
+++ b/couchdb-glib/couchdb-struct-field.c
@@ -44,6 +44,14 @@ couchdb_struct_field_get_type (void)
 	return object_type;
 }
 
+/**
+ * couchdb_struct_field_new:
+ *
+ * Create a new struct field object, to be added to a #CouchdbDocument or to
+ * another #CouchdbStructField.
+ *
+ * Return value: A newly-created #CouchdbStructField object.
+ */
 CouchdbStructField *
 couchdb_struct_field_new (void)
 {
@@ -57,6 +65,15 @@ couchdb_struct_field_new (void)
 	return sf;
 }
 
+/**
+ * couchdb_struct_field_new_from_string:
+ * @str: A JSON string
+ *
+ * Create a new struct field object, filling it with values taken from a string
+ * representing a JSON object.
+ *
+ * Return value: A newly-created #CouchdbStructField object.
+ */
 CouchdbStructField *
 couchdb_struct_field_new_from_string (const char *str)
 {
@@ -82,6 +99,14 @@ couchdb_struct_field_new_from_string (const char *str)
 	return sf;
 }
 
+/**
+ * couchdb_struct_field_new_from_json_object:
+ * @json_object: A JsonObject
+ *
+ * Create a new struct field object, filling it with values taken from a JsonObject.
+ *
+ * Return value: A newly-created #CouchdbStructField object.
+ */
 CouchdbStructField *
 couchdb_struct_field_new_from_json_object (JsonObject *json_object)
 {
@@ -95,6 +120,14 @@ couchdb_struct_field_new_from_json_object (JsonObject *json_object)
 	return sf;
 }
 
+/**
+ * couchdb_struct_field_ref:
+ * @sf: A #CouchdbStructField object
+ *
+ * Increments reference count of a #CouchdbStructField object.
+ *
+ * Return value: A pointer to the referenced object.
+ */
 CouchdbStructField *
 couchdb_struct_field_ref (CouchdbStructField *sf)
 {
@@ -106,6 +139,14 @@ couchdb_struct_field_ref (CouchdbStructField *sf)
 	return sf;
 }
 
+/**
+ * couchdb_struct_field_unref:
+ * @sf: A #CouchdbStructField object
+ *
+ * Decrements reference count of a #CouchdbStructField object. When
+ * the reference count is equal to 0, the object will be destroyed and
+ * the memory it uses freed.
+ */
 void
 couchdb_struct_field_unref (CouchdbStructField *sf)
 {
@@ -123,6 +164,15 @@ couchdb_struct_field_unref (CouchdbStructField *sf)
 	}
 }
 
+/**
+ * couchdb_struct_field_has_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field to check
+ *
+ * Check whether a given field exists in the given #CouchdbStructField object.
+ *
+ * Return value: TRUE if the field exists, FALSE if not.
+ */
 gboolean
 couchdb_struct_field_has_field (CouchdbStructField *sf, const char *field)
 {
@@ -132,6 +182,13 @@ couchdb_struct_field_has_field (CouchdbStructField *sf, const char *field)
 	return json_object_has_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_remove_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field to remove
+ *
+ * Remove a field from the given #CouchdbStructField object.
+ */
 void
 couchdb_struct_field_remove_field (CouchdbStructField *sf, const char *field)
 {
@@ -141,6 +198,15 @@ couchdb_struct_field_remove_field (CouchdbStructField *sf, const char *field)
 	json_object_remove_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_get_boolean_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ *
+ * Retrieve the value of a boolean field from the given struct field.
+ *
+ * Return value: The value of the given field.
+ */
 gboolean
 couchdb_struct_field_get_boolean_field (CouchdbStructField *sf, const char *field)
 {
@@ -150,6 +216,14 @@ couchdb_struct_field_get_boolean_field (CouchdbStructField *sf, const char *fiel
 	return json_object_get_boolean_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_set_boolean_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ * @calue: Value to set the field to
+ *
+ * Set the value of a boolean field in the given struct field.
+ */
 void
 couchdb_struct_field_set_boolean_field (CouchdbStructField *sf, const char *field, gboolean value)
 {
@@ -159,6 +233,15 @@ couchdb_struct_field_set_boolean_field (CouchdbStructField *sf, const char *fiel
 	json_object_set_boolean_member (sf->json_object, field, value);
 }
 
+/**
+ * couchdb_struct_field_get_double_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ *
+ * Retrieve the value of a decimal number field from the given struct field.
+ *
+ * Return value: The value of the given field.
+ */
 gdouble
 couchdb_struct_field_get_double_field (CouchdbStructField *sf, const char *field)
 {
@@ -168,6 +251,14 @@ couchdb_struct_field_get_double_field (CouchdbStructField *sf, const char *field
 	return json_object_get_double_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_set_double_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ * @calue: Value to set the field to
+ *
+ * Set the value of a decimal number field in the given struct field.
+ */
 void
 couchdb_struct_field_set_double_field (CouchdbStructField *sf, const char *field, gdouble value)
 {
@@ -177,6 +268,15 @@ couchdb_struct_field_set_double_field (CouchdbStructField *sf, const char *field
 	json_object_set_double_member (sf->json_object, field, value);
 }
 
+/**
+ * couchdb_struct_field_get_int_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ *
+ * Retrieve the value of an integer field from the given struct field.
+ *
+ * Return value: The value of the given field.
+ */
 gint
 couchdb_struct_field_get_int_field (CouchdbStructField *sf, const char *field)
 {
@@ -186,6 +286,14 @@ couchdb_struct_field_get_int_field (CouchdbStructField *sf, const char *field)
 	return json_object_get_int_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_set_int_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ * @calue: Value to set the field to
+ *
+ * Set the value of an integer field in the given struct field.
+ */
 void
 couchdb_struct_field_set_int_field (CouchdbStructField *sf, const char *field, gint value)
 {
@@ -195,6 +303,15 @@ couchdb_struct_field_set_int_field (CouchdbStructField *sf, const char *field, g
 	json_object_set_int_member (sf->json_object, field, value);
 }
 
+/**
+ * couchdb_struct_field_get_string_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ *
+ * Retrieve the value of a string field from the given struct field.
+ *
+ * Return value: The value of the given field.
+ */
 const char *
 couchdb_struct_field_get_string_field (CouchdbStructField *sf, const char *field)
 {
@@ -204,6 +321,14 @@ couchdb_struct_field_get_string_field (CouchdbStructField *sf, const char *field
 	return json_object_get_string_member (sf->json_object, field);
 }
 
+/**
+ * couchdb_struct_field_set_string_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ * @calue: Value to set the field to
+ *
+ * Set the value of a string field in the given struct field.
+ */
 void
 couchdb_struct_field_set_string_field (CouchdbStructField *sf, const char *field, const char *value)
 {
@@ -218,6 +343,15 @@ couchdb_struct_field_set_string_field (CouchdbStructField *sf, const char *field
 	}
 }
 
+/**
+ * couchdb_struct_field_get_struct_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ *
+ * Retrieve the value of a struct field from the given struct field.
+ *
+ * Return value: The value of the given field.
+ */
 CouchdbStructField *
 couchdb_struct_field_get_struct_field (CouchdbStructField *sf, const char *field)
 {
@@ -231,6 +365,14 @@ couchdb_struct_field_get_struct_field (CouchdbStructField *sf, const char *field
 		json_object_get_object_member (sf->json_object, field));
 }
 
+/**
+ * couchdb_struct_field_set_string_field:
+ * @sf: A #CouchdbStructField object
+ * @field: Name of the field
+ * @calue: Value to set the field to
+ *
+ * Set the value of a string field in the given struct field.
+ */
 void
 couchdb_struct_field_set_struct_field (CouchdbStructField *sf, const char *field, CouchdbStructField *value)
 {
@@ -241,6 +383,23 @@ couchdb_struct_field_set_struct_field (CouchdbStructField *sf, const char *field
 	json_object_set_object_member (sf->json_object, field, json_object_ref (value->json_object));
 }
 
+/**
+ * couchdb_struct_field_get_uuid:
+ * @sf: A #CouchdbStructField object
+ *
+ * Retrieve the unique ID of the given struct field. Note that this is a convenience
+ * function to allow documents with a format similar to:
+ *
+ * "list": {
+ *        "unique-id-1": { "field": "value" },
+ *        "unique-id-2": { "field": "value" }
+ * }
+ *
+ * So, not all #CouchdbStructField objects would have a value for this, unless explicitly
+ * used by the applications storing the documents on the CouchDB database.
+ *
+ * Return value: The unique ID of the given struct field.
+ */
 const char *
 couchdb_struct_field_get_uuid (CouchdbStructField *sf)
 {
@@ -249,6 +408,14 @@ couchdb_struct_field_get_uuid (CouchdbStructField *sf)
 	return (const char *) sf->uuid;
 }
 
+/**
+ * couchdb_struct_field_set_uuid:
+ * @sf: A #CouchdbStructField object
+ * @uuid: Unique ID
+ *
+ * Set the unique ID for the given struct field. See the explanation for #couchdb_struct_field_get_uuid
+ * for knowing when to use this function.
+ */
 void
 couchdb_struct_field_set_uuid (CouchdbStructField *sf, const char *uuid)
 {
@@ -260,6 +427,15 @@ couchdb_struct_field_set_uuid (CouchdbStructField *sf, const char *uuid)
 	sf->uuid = g_strdup (uuid);
 }
 
+/**
+ * couchdb_struct_field_to_string:
+ * @sf: A #CouchdbStructField object
+ *
+ * Convert a #CouchdbStructField to a JSON string.
+ *
+ * Return value: A string representing the contents of the given #CouchdbStructField
+ * object in JSON format.
+ */
 char *
 couchdb_struct_field_to_string (CouchdbStructField *sf)
 {
@@ -284,6 +460,17 @@ couchdb_struct_field_to_string (CouchdbStructField *sf)
 	return str;
 }
 
+/**
+ * couchdb_struct_field_get_json_object:
+ * @sf: A #CouchdbStructField object
+ *
+ * Retrieve the JsonObject used internally by the given #CouchdbStructField object.
+ * This is internal API, and should not be used by applications unless they really
+ * need to deal with the internal aspects of the #CouchdbStructField object, which
+ * developers are advised not to do.
+ *
+ * Return value: The internal JsonObject.
+ */
 JsonObject *
 couchdb_struct_field_get_json_object (CouchdbStructField *sf)
 {