Refinements to documentation

lib/recliner.rb

@@ -49,7 +49,7 @@ class << self
     # * +uri+    - the URI of the resource
     # * +params+ - a hash of parameters to serialize with the URI
     #
-    # ==== Examples
+    # ==== Example
     #
     #   >> Recliner.get('http://localhost:5984/my-database/some-document', :rev => '12-3220752267')
     #   => { '_id' => 'some-document', '_rev' => '12-3220752267', 'title' => 'Document title' }
@@ -65,7 +65,7 @@ def get(uri, params={})
     # * +payload+ - a hash of the data to POST
     # * +params+  - a hash of parameters to serialize with the URI
     #
-    # ==== Examples
+    # ==== Example
     #
     #   >> Recliner.post('http://localhost:5984/my-database', { :title => 'Document title' })
     #   => { 'id' => '12eec4c198ef0e843cd16761fc565208', 'rev' => '1-1503678650', 'ok' => true }
@@ -81,7 +81,7 @@ def post(uri, payload={}, params={})
     # * +payload+ - a hash of the data to PUT
     # * +params+  - a hash of parameters to serialize with the URI
     #
-    # ==== Examples
+    # ==== Example
     #
     #   >> Recliner.put('http://localhost:5984/my-database/some-document', { :title => 'Document title' })
     #   => { 'id' => 'some-document', 'rev' => '2-2152886926', 'ok' => true }
@@ -96,7 +96,7 @@ def put(uri, payload={}, params={})
     # * +uri+    - the URI of the resource
     # * +params+ - a hash of parameters to serialize with the URI, in particular the revision :rev
     #
-    # ==== Examples
+    # ==== Example
     #
     #   >> Recliner.delete('http://localhost:5984/my-database/some-document', :rev => '2-2152886926')
     #   => { 'id' => 'some-document', 'rev' => '3-3894620555', 'ok' => true }

lib/recliner/attribute_methods/protected.rb

@@ -110,7 +110,7 @@ def accessible_attributes
         end
       end
 
-      def attributes=(attrs)
+      def attributes=(attrs)#:nodoc:
         super(remove_protected_attributes(attrs))
       end
 

lib/recliner/database.rb

@@ -1,48 +1,104 @@
 module Recliner
   class Database
     attr_reader :uri
-
+
+    # Creates a new database object with the given URI.
+    #
+    # ==== Example
+    #
+    #   >> database = Recliner::Database.new('http://localhost:5984/my-database')
     def initialize(uri)
       @uri = uri
 #       create_database_if_missing!
     end
-
+
+    # Performs a HTTP GET request on a JSON resource from this database, deserializing the response.
+    #
+    # ==== Parameters
+    #
+    # * +path+   - the path of the resource
+    # * +params+ - a hash of parameters to serialize with the URI
+    #
+    # ==== Example
+    #
+    #   >> database.get('some-document', :rev => '12-3220752267')
+    #   => { '_id' => 'some-document', '_rev' => '12-3220752267', 'title' => 'Document title' }
     def get(path=nil, params={})
       Recliner.get(uri_for(path), params)
     end
-
+
+    # Performs a HTTP POST request on a JSON resource from this database, deserializing the response.
+    #
+    # ==== Parameters
+    #
+    # * +path+    - the path of the resource
+    # * +payload+ - a hash of the data to POST
+    # * +params+  - a hash of parameters to serialize with the URI
+    #
+    # ==== Example
+    #
+    #   >> database.post('my-database', { :title => 'Document title' })
+    #   => { 'id' => '12eec4c198ef0e843cd16761fc565208', 'rev' => '1-1503678650', 'ok' => true }
     def post(path, payload, params={})
       Recliner.post(uri_for(path), payload, params)
     end
-
+
+    # Performs a HTTP PUT request on a JSON resource from this database, deserializing the response.
+    #
+    # ==== Parameters
+    #
+    # * +path+    - the path of the resource
+    # * +payload+ - a hash of the data to PUT
+    # * +params+  - a hash of parameters to serialize with the URI
+    #
+    # ==== Example
+    #
+    #   >> database.put('some-document', { :title => 'Document title' })
+    #   => { 'id' => 'some-document', 'rev' => '2-2152886926', 'ok' => true }
     def put(path, payload, params={})
       Recliner.put(uri_for(path), payload, params)
     end
-
+
+    # Performs a HTTP DELETE request on a JSON resource from this database, deserializing the response.
+    #
+    # ==== Parameters
+    #
+    # * +path+   - the path of the resource
+    # * +params+ - a hash of parameters to serialize with the URI, in particular the revision :rev
+    #
+    # ==== Example
+    #
+    #   >> database.delete('some-document', :rev => '2-2152886926')
+    #   => { 'id' => 'some-document', 'rev' => '3-3894620555', 'ok' => true }
     def delete(path, params={})
       Recliner.delete("#{uri}/#{path}", params) if path
     end
-
+
+    # Deletes the database by performing a HTTP DELETE request on the database URI.
     def delete!
       Recliner.delete(uri)
     end
 
+    # Creates the database by performing a HTTP PUT request on the database URI.
     def create!
       Recliner.put(uri)
     end
 
+    # Recreates the database by issuing a HTTP DELETE request followed by a HTTP PUT request to the database URI.
     def recreate!
       delete! rescue nil
       create!
     end
-
+
+    # Clears all documents from the database using the CouchDB bulk document API.
     def clear!
       docs = get("_all_docs")['rows']
       post("_bulk_docs", {
         :docs => docs.map { |doc| { '_id' => doc['id'], '_rev' => doc['value']['rev'], '_deleted' => true } }
       }) unless docs.empty?
     end
-
+
+    # Compares databases for equality. Two databases are considered equal if they have the same URI.
     def ==(other)
       other.is_a?(Recliner::Database) && uri == other.uri
     end

lib/recliner/document.rb

@@ -104,8 +104,7 @@ def read_only?
       attributes.frozen?
     end
 
-    # Compares documents for equality.
-    # Two documents are considered equal if they share the same document id and class.
+    # Compares documents for equality. Two documents are considered equal if they share the same document id and class.
     def ==(other)
       other.class == self.class && other.id == self.id
     end
@@ -140,20 +139,15 @@ def save_to_database
       true
     end
 
-    class << self
+    module ClassMethods
       # Loads one or more documents from the database given their document IDs.
       # If a document does not exist, nil will be returned.
       #
       # ==== Examples
       #
-      #   >> TestDocument.load('some-document-id')
-      #   => #<TestDocument>
-      #
-      #   >> TestDocument.load('missing-document')
-      #   => nil
-      #
-      #   >> TestDocument.load('document-1', 'document-2')
-      #   => [#<TestDocument>, #<TestDocument>]
+      #   >> TestDocument.load('some-document-id')         # returns the object with id 'some-document-id'
+      #   >> TestDocument.load('missing-document')         # returns nil for missing documents
+      #   >> TestDocument.load('document-1', 'document-2') # returns an array of objects with ids 'document-1', 'document-2'
       def load(*ids)
         load_ids(ids, false)
       end
@@ -163,14 +157,9 @@ def load(*ids)
       #
       # ==== Examples
       #
-      #   >> TestDocument.load!('some-document-id')
-      #   => #<TestDocument>
-      #
-      #   >> TestDocument.load!('missing-document')
-      #   Recliner::DocumentNotFound
-      #
-      #   >> TestDocument.load!('document-1', 'document-2')
-      #   => [#<TestDocument>, #<TestDocument>]
+      #   >> TestDocument.load!('some-document-id')         # returns the object with id 'some-document-id'
+      #   >> TestDocument.load!('missing-document')         # raises Recliner::DocumentNotFound exception for missing documents
+      #   >> TestDocument.load!('document-1', 'document-2') # returns an array of objects with ids 'document-1', 'document-2'
       def load!(*ids)
         load_ids(ids, true)
       end
@@ -196,32 +185,33 @@ def create(attributes={})
         end
       end
 
-      #
+      # Creates an object just like create but calls save! instead of save
+      # so an exception is raised if the document is invalid.
       def create!(attributes={})
         returning new(attributes) do |doc|
           yield doc if block_given?
           doc.save!
         end
       end
 
-  #     #
-  #     def destroy(id)
-  #       if id.is_a?(Array)
-  #         id.map { |i| destroy(i) }
-  #       else
-  #         load(id).destroy
-  #       end
-  #     end
-  #     
-  #     #
-  #     def delete(id)
-  #       if id.is_a?(Array)
-  #         id.map { |i| delete(i) }
-  #       else
-  #         # We have to instantiate the document to know its revision
-  #         load(id).delete
-  #       end
-  #     end
+      # #
+      # def destroy(id)
+      #   if id.is_a?(Array)
+      #     id.map { |i| destroy(i) }
+      #   else
+      #     load(id).destroy
+      #   end
+      # end
+      # 
+      # #
+      # def delete(id)
+      #   if id.is_a?(Array)
+      #     id.map { |i| delete(i) }
+      #   else
+      #     # We have to instantiate the document to know its revision
+      #     load(id).delete
+      #   end
+      # end
 
       # Set a new database URI to use for this class and subclasses.
       def use_database!(uri)
@@ -239,7 +229,7 @@ def default_database
         @default_database ||= Database.new(read_inheritable_attribute(:database_uri))
       end
 
-      #
+      # Sets a database for a block, that all objects of this type created inside the block should use.
       def with_database(db)
         Thread.current["#{name}_database"] = db
 
@@ -338,6 +328,8 @@ def load_multiple(ids, raise_exceptions=false)
   end
 
   Document.class_eval do
+    extend Document::ClassMethods
+
     use_database! 'http://localhost:5984/recliner-default'
 
     include Properties

lib/recliner/properties/map.rb

@@ -1,6 +1,6 @@
 module Recliner
   module Properties
-    module Map
+    module Map#:nodoc:
       extend ActiveSupport::Concern
 
       included do
@@ -22,7 +22,7 @@ def Map(mapping)
         end
       end
 
-      module PropertyWithMapDefault
+      module PropertyWithMapDefault#:nodoc:
         extend ActiveSupport::Concern
 
         included do

lib/recliner/properties/set.rb

@@ -1,6 +1,6 @@
 module Recliner
   module Properties
-    module Set
+    module Set#:nodoc:
       extend ActiveSupport::Concern
 
       included do
@@ -18,7 +18,7 @@ def Set(type)
         end
       end
 
-      module PropertyWithSetDefault
+      module PropertyWithSetDefault#:nodoc:
         extend ActiveSupport::Concern
 
         included do

lib/recliner/timestamps.rb

@@ -1,7 +1,7 @@
 module Recliner
   # Recliner automatically timestamps create and update operations if the document has properties
   # named created_at/created_on or updated_at/updated_on.
-  module Timestamps
+  module Timestamps#:nodoc:
     extend ActiveSupport::Concern
 
     included do