[couchdb-glib/wip/query-response] Add the iniial documentation for methods

[Krzysztof Klimonda <kklimonda src gnome org>]

commit f60b226af730b1977777fed24c8a185c8f268b78
Author: Krzysztof Klimonda <kklimonda syntaxhighlighted com>
Date:   Sun Nov 21 08:40:15 2010 +0100

    Add the iniial documentation for methods

 couchdb-glib/couchdb-query.c |  117 ++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 113 insertions(+), 4 deletions(-)
---
diff --git a/couchdb-glib/couchdb-query.c b/couchdb-glib/couchdb-query.c
index 130809f..930216a 100644
--- a/couchdb-glib/couchdb-query.c
+++ b/couchdb-glib/couchdb-query.c
@@ -118,7 +118,7 @@ couchdb_query_class_init (CouchdbQueryClass *klass)
 	gobject_class->get_property = couchdb_query_get_property;
 
 	g_type_class_add_private (klass, sizeof (CouchdbQueryPrivate));
-  
+
 	pspec = g_param_spec_boxed ("query-options",
 				    "Query Options",
 				    "Query options associated with the query",
@@ -136,7 +136,7 @@ couchdb_query_class_init (CouchdbQueryClass *klass)
 	g_object_class_install_property (gobject_class,
 					 PROP_PATH,
 					 pspec);
-									      
+
 }
 
 static void
@@ -153,12 +153,29 @@ couchdb_query_init (CouchdbQuery *self)
 	self->priv->method = g_strdup ("GET");
 }
 
+/**
+ * couchdb_query_new
+ *
+ * Creates and returns a new #CouchdbQuery object
+ *
+ * Return value: A new #CouchdbQuery object, to be unreferenced
+ * when no longer needed.
+ */
 CouchdbQuery *
 couchdb_query_new ()
 {
 	return g_object_new (COUCHDB_TYPE_QUERY, NULL);
 }
 
+/**
+ * couchdb_query_new_for_path
+ * @path: a path for query
+ *
+ * Creates and returns a new #CouchdbQuery object for a given path
+ *
+ * Return value: A new #CouchdbQuery object, to be unreferenced
+ * when no longer needed.
+ */
 CouchdbQuery *
 couchdb_query_new_for_path (const gchar *path)
 {
@@ -167,6 +184,28 @@ couchdb_query_new_for_path (const gchar *path)
 			     NULL);
 }
 
+/**
+ * couchdb_query_new_for_path
+ * @design_doc: A document's ID. You can ommit the _design/ part if you want to.
+ * @view_name: Name of the view to call.
+ *
+ * Creates and returns a new #CouchdbQuery object for a give design document
+ * and view. It's a shortcut for this code:
+ * [[[
+ * const gchar *design_doc, *view_name;
+ * CouchdbQuery *query;
+ *
+ * design_doc = "document";
+ * view_name = "view";
+ * path = g_str_concat ("_design/", design_doc, "_view", view_name);
+ * query = couchdb_query_new ();
+ * couchdb_query_set_path (query, path);
+ * g_free (path);
+ * ]]]
+ *
+ * Return value: A new #CouchdbQuery object, to be unreferenced
+ * when no longer needed.
+ */
 CouchdbQuery *
 couchdb_query_new_for_view (const gchar *design_doc, const gchar *view_name)
 {
@@ -184,13 +223,21 @@ couchdb_query_new_for_view (const gchar *design_doc, const gchar *view_name)
 	query = g_object_new (COUCHDB_TYPE_QUERY,
 			      "path", path,
 			      NULL);
-	
+
 	g_free (path);
 
 	return query;
 
 }
 
+/**
+ * couchdb_query_get_option
+ *
+ * Returns the value of the given key, or %NULL if it wasn't set
+ *
+ * Return value: (transfer none) (allow-none): the value of the given key,
+ * or %NULL if it hasn't been set.
+ */
 const char *
 couchdb_query_get_option (CouchdbQuery *self, const gchar *name)
 {
@@ -199,6 +246,12 @@ couchdb_query_get_option (CouchdbQuery *self, const gchar *name)
 	return g_hash_table_lookup (self->priv->query_options, name);
 }
 
+/**
+ * couchdb_query_set_option
+ *
+ * Set's the value of the given key, overwriting the current one if it's
+ * already set
+ */
 void
 couchdb_query_set_option (CouchdbQuery *self, const gchar *name,
 			  const gchar *value)
@@ -214,6 +267,15 @@ couchdb_query_set_option (CouchdbQuery *self, const gchar *name,
 			     g_strdup (name), g_strdup (value));
 }
 
+/**
+ * couchdb_query_get_query_options_string
+ * @self: A #CouchdbQuery object
+ *
+ * Returns options as a query string that can be used to create
+ * a complete uri for querying server.
+ *
+ * Return value: A string containing all query options.
+ */
 const char *
 couchdb_query_get_query_options_string (CouchdbQuery *self)
 {
@@ -232,7 +294,7 @@ couchdb_query_get_query_options_string (CouchdbQuery *self)
 	g_hash_table_iter_init (&iter, (GHashTable *) self->priv->query_options);
 
 	while (g_hash_table_iter_next (&iter, &key, &value)) {
-		/* key, startkey and endkey must be a properly url 
+		/* key, startkey and endkey must be a properly url
 		 * encoded JSON values */
 		if (g_str_equal (key, "key") || g_str_equal (key, "startkey") ||
 		    g_str_equal (key, "endkey")) {
@@ -267,6 +329,14 @@ couchdb_query_get_query_options_string (CouchdbQuery *self)
 	}
 }
 
+/**
+ * couchdb_query_get_json_object
+ *
+ * Returns the Json body of the query.
+ *
+ * Return value: (transfer none) (allow none): A JsonObject set as a body
+ * of a query.
+ */
 JsonObject *
 couchdb_query_get_json_object (CouchdbQuery *self)
 {
@@ -275,6 +345,15 @@ couchdb_query_get_json_object (CouchdbQuery *self)
 	return self->priv->body;
 }
 
+/**
+ * couchdb_query_get_json_object
+ *
+ * Sets the given Json object as a body of the query that is going to be
+ * send to the CouchDB server. It doesn't change the query's method so it has
+ * to be set to either PUT or POST by calling #couchdb_query_set_method.
+ *
+ * Return value: (transfer full): A JsonObject to be set as a Query's body.
+ */
 void
 couchdb_query_set_json_object (CouchdbQuery *self, JsonObject *body)
 {
@@ -285,6 +364,13 @@ couchdb_query_set_json_object (CouchdbQuery *self, JsonObject *body)
 	self->priv->body = json_object_ref (body);
 }
 
+/**
+ * couchdb_query_set_path
+ * @self: A #CouchdbQuery object
+ * @method: A path for query.
+ *
+ * Sets path for the Query.
+ */
 void
 couchdb_query_set_path (CouchdbQuery *self, const char *path)
 {
@@ -294,6 +380,14 @@ couchdb_query_set_path (CouchdbQuery *self, const char *path)
 	self->priv->path = g_strdup (path);
 }
 
+/**
+ * couchdb_query_get_path
+ * @self: A #CouchdbQuery object
+ *
+ * Returns path set for the query.
+ *
+ * Return value: string containing path set for the query.
+ */
 const char *
 couchdb_query_get_path (CouchdbQuery *self)
 {
@@ -302,6 +396,13 @@ couchdb_query_get_path (CouchdbQuery *self)
 	return (const gchar *) self->priv->path;
 }
 
+/**
+ * couchdb_query_set_method
+ * @self: A #CouchdbQuery object
+ * @method: A method for query.
+ *
+ * Sets method for the Query.
+ */
 void
 couchdb_query_set_method (CouchdbQuery *self, const gchar *method)
 {
@@ -311,6 +412,14 @@ couchdb_query_set_method (CouchdbQuery *self, const gchar *method)
 	self->priv->method = g_strdup (method);
 }
 
+/**
+ * couchdb_query_get_method
+ * @self: A #CouchdbQuery object
+ *
+ * Returns method set for the query.
+ *
+ * Return value: string containing method set for the query.
+ */
 const char *
 couchdb_query_get_method (CouchdbQuery *self)
 {