[couchdb-glib] Added some API info to the README file

[Rodrigo Moya <rodrigo src gnome org>]

commit d44ccb1235e48b16abb32ff4aaea6203ee1855d2
Author: Rodrigo Moya <rodrigo gnome-db org>
Date:   Tue Sep 1 14:05:59 2009 +0200

    Added some API info to the README file

 README |   72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 72 insertions(+), 0 deletions(-)
---
diff --git a/README b/README
index 77fb83f..56a16f3 100644
--- a/README
+++ b/README
@@ -15,3 +15,75 @@ To actually build it, do the following:
 	./configure (or ./autogen.sh if there is no configure script)
 	make
 	make install
+
+API
+===
+The main entry point in the API is the CouchDB object, which is needed for all
+operations involving access to the CouchDB databases. To create it:
+
+	couchdb = couchdb_new (hostname);
+
+The only argument is to specify the hostname of the CouchDB instance you want
+to connect to. If NULL, it will connect to the default, which is
+http://localhost:5984.
+
+Once you have a valid CouchDB object, you can perform several operations on
+databases:
+	* List databases -> couchdb_list_databases()
+	* Create a database -> couchdb_create_database()
+	* Delete a database -> couchdb_delete_database()
+	* List documents in a database -> couchdb_list_documents()
+
+There is also a polling mechanism, which allows your application to listen
+for changes on a specific database on the CouchDB instance you're connecting
+to. To start listening for changes, you just need to:
+	* Call couchdb_listen_for_changes
+	* And g_signal_connect the CouchDB object to the following signals:
+		- "database_created"
+		- "database_deleted"
+		- "document_created"
+		- "document_updated"
+		- "document_deleted"
+
+Documents can easily be managed by using the CouchDBDocument object, which
+provides an API for creating new documents in memory and save them on a
+database on the CouchDB instance you're connected to:
+	* Create an empty, in-memory document -> couchdb_document_new()
+	* Get an existing document from the database -> couchdb_document_get()
+	* Delete an existing document -> couchdb_document_delete()
+
+Documents' API provides meaningful functions to manage its contents. First of
+all, there are standard fields on each document, which you can set/get easily:
+	* Unique ID -> couchdb_document_get_id() and couchdb_document_set_id()
+	* Revision -> couchdb_document_get_revision() and
+          couchdb_document_set_revision()
+	* Record type -> couchdb_document_get_record_type() and
+	  couchdb_document_set_record_type()
+	* Application annotations (application-specific data) ->
+	  couchdb_document_get_application_annotations() and
+	  couchdb_document_set_application_annotations()
+
+Apart from those standard fields, documents can have whatever fields you need
+to, so the CouchDBDocument API provides functions for setting fields of
+different types:
+	* Booleans -> couchdb_document_get_boolean_field() and
+	  couchdb_document_set_boolean_field()
+	* Integers -> couchdb_document_get_int_field() and
+	  couchdb_document_set_int_field()
+	* Doubles -> couchdb_document_get_double_field() and
+	  couchdb_document_set_double_field()
+	* Strings -> couchdb_document_get_string_field() and
+	  couchdb_document_set_string_field()
+
+There are some structured field types which are also supported:
+	* Structs -> couchdb_document_get_struct_field() and
+	  couchdb_document_set_struct_field(). These use a special type,
+	  CouchDBStructField, which in turn provides the same get/set functions
+	  than the CouchDBDocument functions explained above.
+	* Arrays (not yet supported)
+
+There are also higher level documents management functions, that internally
+deal with specific record types. They are just built on top of the
+CouchDBDocument API but provide an easy way to deal with those specific
+record types:
+	* Contacts -> couchdb_document_contact_*