From 26c4db7fc64191d383b22a4f6ff683ff2f2ca869 Mon Sep 17 00:00:00 2001
From: Chris Anderson <jchris@grabb.it>
Date: Mon, 29 Sep 2008 23:26:34 -0700
Subject: [PATCH] documenting CouchRest::Model

---
 lib/couchrest/core/database.rb | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/lib/couchrest/core/database.rb b/lib/couchrest/core/database.rb
index aea133f..941f9cc 100644
--- a/lib/couchrest/core/database.rb
+++ b/lib/couchrest/core/database.rb
@@ -16,48 +16,43 @@ module CouchRest
       @root
     end
     
+    # GET the database info from CouchDB
     def info
       CouchRest.get @root
     end
     
+    # Query the <tt>_all_docs</tt> view. Accepts all the same arguments as view.
     def documents params = nil
       url = CouchRest.paramify_url "#{@root}/_all_docs", params
       CouchRest.get url  
     end
   
+    # POST a temporary view function to CouchDB for querying. This is not recommended, as you don't get any performance benefit from CouchDB's materialized views. Can be quite slow on large databases.
     def temp_view funcs, params = nil
       url = CouchRest.paramify_url "#{@root}/_temp_view", params
       JSON.parse(RestClient.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
     end
   
+    # Query a CouchDB view as defined by a <tt>_design</tt> document. Accepts paramaters as described in http://wiki.apache.org/couchdb/HttpViewApi
     def view name, params = nil
       url = CouchRest.paramify_url "#{@root}/_view/#{name}", params
       CouchRest.get url
     end
-
-    # experimental
-    def search params = nil
-      url = CouchRest.paramify_url "#{@root}/_search", params
-      CouchRest.get url
-    end
-    # experimental
-    def action action, params = nil
-      url = CouchRest.paramify_url "#{@root}/_action/#{action}", params
-      CouchRest.get url
-    end
     
+    # GET a document from CouchDB, by id. Returns a Ruby Hash.
     def get id
       slug = CGI.escape(id) 
       CouchRest.get "#{@root}/#{slug}"
     end
     
+    # GET an attachment directly from CouchDB
     def fetch_attachment doc, name
       doc = CGI.escape(doc)
       name = CGI.escape(name)
       RestClient.get "#{@root}/#{doc}/#{name}"
     end
     
-    # PUT or POST depending on presence of _id attribute
+    # Save a document to CouchDB. This will use the <tt>_id</tt> field from the document as the id for PUT, or request a new UUID from CouchDB, if no <tt>_id</tt> is present on the document. IDs are attached to documents on the client side because POST has the curious property of being automatically retried by proxies in the event of network segmentation and lost responses.
     def save doc
       if doc['_attachments']
         doc['_attachments'] = encode_attachments(doc['_attachments'])
@@ -75,6 +70,7 @@ module CouchRest
       end
     end
     
+    # POST an array of documents to CouchDB. If any of the documents are missing ids, supply one from the uuid cache.
     def bulk_save docs
       ids, noids = docs.partition{|d|d['_id']}
       uuid_count = [noids.length, @server.uuid_batch_count].max
@@ -85,11 +81,13 @@ module CouchRest
       CouchRest.post "#{@root}/_bulk_docs", {:docs => docs}
     end
     
+    # DELETE the document from CouchDB that has the given <tt>_id</tt> and <tt>_rev</tt>.
     def delete doc
       slug = CGI.escape(doc['_id'])
       CouchRest.delete "#{@root}/#{slug}?rev=#{doc['_rev']}"
     end
     
+    # DELETE the database itself. This is not undoable and could be rather catastrophic. Use with care!
     def delete!
       CouchRest.delete @root
     end