From b3b58ffa8373d8420df6b79334a9f98ecd855e01 Mon Sep 17 00:00:00 2001
From: Chris Anderson <jchris@grabb.it>
Date: Mon, 29 Sep 2008 23:39:57 -0700
Subject: [PATCH] polished documentation

---
 lib/couchrest.rb                 |  1 +
 lib/couchrest/core/database.rb   |  7 +++++++
 lib/couchrest/core/model.rb      |  2 +-
 lib/couchrest/core/server.rb     | 12 +++++++-----
 lib/couchrest/helper/streamer.rb |  1 +
 lib/couchrest/monkeypatches.rb   |  8 +++-----
 6 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/lib/couchrest.rb b/lib/couchrest.rb
index 27a9837..d8bd3f0 100644
--- a/lib/couchrest.rb
+++ b/lib/couchrest.rb
@@ -24,6 +24,7 @@ $:.unshift File.dirname(__FILE__) unless
   
 require 'couchrest/monkeypatches'
 
+# = CouchDB, close to the metal
 module CouchRest
   autoload :Server,       'couchrest/core/server'
   autoload :Database,     'couchrest/core/database'
diff --git a/lib/couchrest/core/database.rb b/lib/couchrest/core/database.rb
index 941f9cc..1376078 100644
--- a/lib/couchrest/core/database.rb
+++ b/lib/couchrest/core/database.rb
@@ -5,6 +5,12 @@ module CouchRest
   class Database
     attr_reader :server, :host, :name, :root
      
+    # Create a CouchRest::Database adapter for the supplied CouchRest::Server and database name.
+    # 
+    # ==== Parameters
+    # server<CouchRest::Server>:: database host
+    # name<String>:: database name
+    #
     def initialize server, name
       @name = name
       @server = server
@@ -12,6 +18,7 @@ module CouchRest
       @root = "#{host}/#{name}"
     end
     
+    # returns the database's uri
     def to_s
       @root
     end
diff --git a/lib/couchrest/core/model.rb b/lib/couchrest/core/model.rb
index c5c264f..2af8d6f 100644
--- a/lib/couchrest/core/model.rb
+++ b/lib/couchrest/core/model.rb
@@ -114,7 +114,7 @@ module CouchRest
       end
     end # module InstanceMethods
     
-    # these show up as class methods on models that include CouchRest::Model
+    # Class methods for models that include CouchRest::Model
     module ClassMethods
       # override the CouchRest::Model-wide default_database
       def use_database db
diff --git a/lib/couchrest/core/server.rb b/lib/couchrest/core/server.rb
index 0091041..3e62ee2 100644
--- a/lib/couchrest/core/server.rb
+++ b/lib/couchrest/core/server.rb
@@ -6,37 +6,39 @@ module CouchRest
       @uuid_batch_count = uuid_batch_count
     end
   
-    # list all databases on the server
+    # List all databases on the server
     def databases
       CouchRest.get "#{@uri}/_all_dbs"
     end
   
+    # Returns a CouchRest::Database for the given name
     def database name
       CouchRest::Database.new(self, name)
     end
   
-    # creates the database if it doesn't exist
+    # Creates the database if it doesn't exist
     def database! name
       create_db(name) rescue nil
       database name
     end
   
-    # get the welcome message
+    # GET the welcome message
     def info
       CouchRest.get "#{@uri}/"
     end
 
-    # create a database
+    # Create a database
     def create_db name
       CouchRest.put "#{@uri}/#{name}"
       database name
     end
 
-    # restart the couchdb instance
+    # Restart the CouchDB instance
     def restart!
       CouchRest.post "#{@uri}/_restart"
     end
 
+    # Retrive an unused UUID from CouchDB. Server instances manage caching a list of unused UUIDs.
     def next_uuid count = @uuid_batch_count
       @uuids ||= []
       if @uuids.empty?
diff --git a/lib/couchrest/helper/streamer.rb b/lib/couchrest/helper/streamer.rb
index ee7d4c0..8a8065c 100644
--- a/lib/couchrest/helper/streamer.rb
+++ b/lib/couchrest/helper/streamer.rb
@@ -5,6 +5,7 @@ module CouchRest
       @db = db
     end
     
+    # Stream a view, yielding one row at a time. Shells out to <tt>curl</tt> to keep RAM usage low when you have millions of rows.
     def view name, params = nil
       urlst = /^_/.match(name) ? "#{@db.root}/#{name}" : "#{@db.root}/_view/#{name}"
       url = CouchRest.paramify_url urlst, params
diff --git a/lib/couchrest/monkeypatches.rb b/lib/couchrest/monkeypatches.rb
index 060add3..58b8fe9 100644
--- a/lib/couchrest/monkeypatches.rb
+++ b/lib/couchrest/monkeypatches.rb
@@ -1,11 +1,9 @@
-
-# this file must be loaded after the JSON gem
-
+# This file must be loaded after the JSON gem and any other library that beats up the Time class.
 class Time
   # This date format sorts lexicographically
-  # and is compatible with Javascript's new Date(time_string) constructor.
+  # and is compatible with Javascript's <tt>new Date(time_string)</tt> constructor.
   # Note this this format stores all dates in UTC so that collation 
-  # order is preserved. (There's no longer a need to set ENV['TZ'] = 'UTC' 
+  # order is preserved. (There's no longer a need to set <tt>ENV['TZ'] = 'UTC'</tt>
   # in your application.)
 
   def to_json(options = nil)