polished documentation

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'

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

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

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?

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

lib/couchrest/monkeypatches.rb

@@ -1,11 +1,9 @@
-
+# This file must be loaded after the JSON gem and any other library that beats up the Time class.
-# this file must be loaded after the JSON gem
-
 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)