Merge docrails.

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

5 files changed, 100 insertions, 29 deletions

diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb
index 08fd0123f6..463ee9f1e7 100644
--- a/activeresource/lib/active_resource/base.rb
+++ b/activeresource/lib/active_resource/base.rb
@@ -34,18 +34,18 @@ module ActiveResource
   # from REST web services.
   # 
   #   ryan = Person.new(:first => 'Ryan', :last => 'Daigle')
-  #   ryan.save  #=> true
-  #   ryan.id  #=> 2
-  #   Person.exists?(ryan.id)  #=> true
-  #   ryan.exists?  #=> true
+  #   ryan.save                # => true
+  #   ryan.id                  # => 2
+  #   Person.exists?(ryan.id)  # => true
+  #   ryan.exists?             # => true
   # 
   #   ryan = Person.find(1)
-  #   # => Resource holding our newly created Person object
+  #   # Resource holding our newly created Person object
   # 
   #   ryan.first = 'Rizzle'
-  #   ryan.save  #=> true
+  #   ryan.save                # => true
   # 
-  #   ryan.destroy  #=> true
+  #   ryan.destroy             # => true
   #
   # As you can see, these are very similar to Active Record's lifecycle methods for database records.
   # You can read more about each of these methods in their respective documentation.
@@ -127,7 +127,7 @@ module ActiveResource
   #   # GET http://api.people.com:3000/people/999.xml
   #   ryan = Person.find(999) # 404, raises ActiveResource::ResourceNotFound
   # 
-  # <tt>404</tt> is just one of the HTTP error response codes that ActiveResource will handle with its own exception. The
+  # <tt>404</tt> is just one of the HTTP error response codes that Active Resource will handle with its own exception. The
   # following HTTP response codes will also result in these exceptions:
   # 
   # * 200..399 - Valid response, no exception
@@ -156,8 +156,8 @@ module ActiveResource
   # then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question.
   # 
   #   ryan = Person.find(1)
-  #   ryan.first #=> ''
-  #   ryan.save  #=> false
+  #   ryan.first # => ''
+  #   ryan.save  # => false
   #
   #   # When 
   #   # PUT http://api.people.com:3000/people/1.xml
@@ -167,8 +167,8 @@ module ActiveResource
   #   # <errors type="array"><error>First cannot be empty</error></errors>
   #   #
   #
-  #   ryan.errors.invalid?(:first)  #=> true
-  #   ryan.errors.full_messages  #=> ['First cannot be empty']
+  #   ryan.errors.invalid?(:first)  # => true
+  #   ryan.errors.full_messages     # => ['First cannot be empty']
   # 
   # Learn more about Active Resource's validation features in the ActiveResource::Validations documentation.
   #
@@ -201,7 +201,7 @@ module ActiveResource
 
     class << self
       # Gets the URI of the REST resources to map for this class.  The site variable is required 
-      # ActiveResource's mapping to work.
+      # Active Resource's mapping to work.
       def site
         # Not using superclass_delegating_reader because don't want subclasses to modify superclass instance
         #
@@ -226,7 +226,7 @@ module ActiveResource
       end
 
       # Sets the URI of the REST resources to map for this class to the value in the +site+ argument.
-      # The site variable is required ActiveResource's mapping to work.
+      # The site variable is required Active Resource's mapping to work.
       def site=(site)
         @connection = nil
         if site.nil?
@@ -701,7 +701,7 @@ module ActiveResource
       attributes[self.class.primary_key] = id
     end
 
-    # Allows ActiveResource objects to be used as parameters in ActionPack URL generation.
+    # Allows Active Resource objects to be used as parameters in Action Pack URL generation.
     def to_param
       id && id.to_s
     end
@@ -820,7 +820,7 @@ module ActiveResource
     # ==== Options
     # The +options+ parameter is handed off to the +to_xml+ method on each
     # attribute, so it has the same options as the +to_xml+ methods in
-    # ActiveSupport.
+    # Active Support.
     #
     # * <tt>:indent</tt> - Set the indent level for the XML output (default is +2+).
     # * <tt>:dasherize</tt> - Boolean option to determine whether or not element names should
diff --git a/activeresource/lib/active_resource/custom_methods.rb b/activeresource/lib/active_resource/custom_methods.rb
index 52a4a4f10b..4c8699288c 100644
--- a/activeresource/lib/active_resource/custom_methods.rb
+++ b/activeresource/lib/active_resource/custom_methods.rb
@@ -7,12 +7,12 @@ module ActiveResource
   #                           :member => { :promote => :put, :deactivate => :delete }
   #                           :collection => { :active => :get }
   #
-  #  This route set creates routes for the following http requests:
+  #  This route set creates routes for the following HTTP requests:
   #
-  #    POST    /people/new/register.xml #=> PeopleController.register
-  #    PUT     /people/1/promote.xml    #=> PeopleController.promote with :id => 1
-  #    DELETE  /people/1/deactivate.xml #=> PeopleController.deactivate with :id => 1
-  #    GET     /people/active.xml       #=> PeopleController.active
+  #    POST    /people/new/register.xml # PeopleController.register
+  #    PUT     /people/1/promote.xml    # PeopleController.promote with :id => 1
+  #    DELETE  /people/1/deactivate.xml # PeopleController.deactivate with :id => 1
+  #    GET     /people/active.xml       # PeopleController.active
   #
   # Using this module, Active Resource can use these custom REST methods just like the
   # standard methods.
@@ -48,8 +48,8 @@ module ActiveResource
           #   # => [{:id => 1, :name => 'Ryan'}]
           #
           # Note: the objects returned from this method are not automatically converted
-          # into ActiveResource instances - they are ordinary Hashes. If you are expecting
-          # ActiveResource instances, use the <tt>find</tt> class method with the
+          # into Active Resource instances - they are ordinary Hashes. If you are expecting
+          # Active Resource instances, use the <tt>find</tt> class method with the
           # <tt>:from</tt> option. For example:
           #
           #   Person.find(:all, :from => :active)
diff --git a/activeresource/lib/active_resource/formats/xml_format.rb b/activeresource/lib/active_resource/formats/xml_format.rb
index 01c28dcee6..5e97ffa776 100644
--- a/activeresource/lib/active_resource/formats/xml_format.rb
+++ b/activeresource/lib/active_resource/formats/xml_format.rb
@@ -21,7 +21,7 @@ module ActiveResource
       
       private
         # Manipulate from_xml Hash, because xml_simple is not exactly what we
-        # want for ActiveResource.
+        # want for Active Resource.
         def from_xml_data(data)
           if data.is_a?(Hash) && data.keys.size == 1
             data.values.first
diff --git a/activeresource/lib/active_resource/http_mock.rb b/activeresource/lib/active_resource/http_mock.rb
index d1c1412575..22f83ae910 100644
--- a/activeresource/lib/active_resource/http_mock.rb
+++ b/activeresource/lib/active_resource/http_mock.rb
@@ -3,8 +3,52 @@ require 'active_resource/connection'
 module ActiveResource
   class InvalidRequestError < StandardError; end #:nodoc:
 
+  # One thing that has always been a pain with remote web services is testing.  The HttpMock
+  # class makes it easy to test your Active Resource models by creating a set of mock responses to specific
+  # requests.
+  #
+  # To test your Active Resource model, you simply call the ActiveResource::HttpMock.respond_to
+  # method with an attached block.  The block declares a set of URIs with expected input, and the output
+  # each request should return.  The passed in block has any number of entries in the following generalized
+  # format:
+  #
+  #   mock.http_method(path, request_headers = {}, body = nil, status = 200, response_headers = {})
+  #
+  # * <tt>http_method</tt> - The HTTP method to listen for.  This can be +get+, +post+, +put+, +delete+ or
+  #   +head+.
+  # * <tt>path</tt> - A string, starting with a "/", defining the URI that is expected to be
+  #   called.
+  # * <tt>request_headers</tt> - Headers that are expected along with the request.  This argument uses a
+  #   hash format, such as <tt>{ "Content-Type" => "application/xml" }</tt>.  This mock will only trigger
+  #   if your tests sends a request with identical headers.
+  # * <tt>body</tt> - The data to be returned.  This should be a string of Active Resource parseable content,
+  #   such as XML.
+  # * <tt>status</tt> - The HTTP response code, as an integer, to return with the response.
+  # * <tt>response_headers</tt> - Headers to be returned with the response.  Uses the same hash format as
+  #   <tt>request_headers</tt> listed above.
+  #
+  # In order for a mock to deliver its content, the incoming request must match by the <tt>http_method</tt>,
+  # +path+ and <tt>request_headers</tt>.  If no match is found an InvalidRequestError exception
+  # will be raised letting you know you need to create a new mock for that request.
+  #
+  # ==== Example
+  #   def setup
+  #     @matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+  #     ActiveResource::HttpMock.respond_to do |mock|
+  #       mock.post   "/people.xml",   {}, @matz, 201, "Location" => "/people/1.xml"
+  #       mock.get    "/people/1.xml", {}, @matz
+  #       mock.put    "/people/1.xml", {}, nil, 204
+  #       mock.delete "/people/1.xml", {}, nil, 200
+  #     end
+  #   end
+  #   
+  #   def test_get_matz
+  #     person = Person.find(1)
+  #     assert_equal "Matz", person.name
+  #   end
+  #
   class HttpMock
-    class Responder
+    class Responder #:nodoc:
       def initialize(responses)
         @responses = responses
       end
@@ -19,15 +63,41 @@ module ActiveResource
     end
 
     class << self
+
+      # Returns an array of all request objects that have been sent to the mock.  You can use this to check
+      # wether or not your model actually sent an HTTP request.
+      #
+      # ==== Example
+      #   def setup
+      #     @matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+      #     ActiveResource::HttpMock.respond_to do |mock|
+      #       mock.get "/people/1.xml", {}, @matz
+      #     end
+      #   end
+      #   
+      #   def test_should_request_remote_service
+      #     person = Person.find(1)  # Call the remote service
+      #     
+      #     # This request object has the same HTTP method and path as declared by the mock
+      #     expected_request = ActiveResource::Request.new(:get, "/people/1.xml")
+      #     
+      #     # Assert that the mock received, and responded to, the expected request from the model
+      #     assert ActiveResource::HttpMock.requests.include?(expected_request)
+      #   end
       def requests
         @@requests ||= []
       end
 
+      # Returns a hash of <tt>request => response</tt> pairs for all all responses this mock has delivered, where +request+
+      # is an instance of ActiveResource::Request and the response is, naturally, an instance of
+      # ActiveResource::Response.
       def responses
         @@responses ||= {}
       end
 
-      def respond_to(pairs = {})
+      # Accepts a block which declares a set of requests and responses for the HttpMock to respond to. See the main
+      # ActiveResource::HttpMock description for a more detailed explanation.
+      def respond_to(pairs = {}) #:yields: mock
         reset!
         pairs.each do |(path, response)|
           responses[path] = response
@@ -40,6 +110,7 @@ module ActiveResource
         end
       end
 
+      # Deletes all logged requests and responses.
       def reset!
         requests.clear
         responses.clear
@@ -66,7 +137,7 @@ module ActiveResource
       EOE
     end
 
-    def initialize(site)
+    def initialize(site) #:nodoc:
       @site = site
     end
   end
diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb
index 57d2ae559d..a7c624f309 100644
--- a/activeresource/lib/active_resource/validations.rb
+++ b/activeresource/lib/active_resource/validations.rb
@@ -216,8 +216,8 @@ module ActiveResource
     end
   end
   
-  # Module to allow validation of ActiveResource objects, which creates an Errors instance for every resource.
-  # Methods are implemented by overriding +Base#validate+ or its variants   Each of these methods can inspect 
+  # Module to allow validation of Active Resource objects, which creates an Errors instance for every resource.
+  # Methods are implemented by overriding Base#validate or its variants   Each of these methods can inspect 
   # the state of the object, which usually means  ensuring that a number of attributes have a certain value 
   # (such as not empty, within a given range, matching a certain regular expression and so on).
   #