Merge branch 'master' of git@github.com:lifo/docrails

8 files changed, 114 insertions, 43 deletions

diff --git a/activeresource/CHANGELOG b/activeresource/CHANGELOG
index 9aa7d455a2..e124e40dd1 100644
--- a/activeresource/CHANGELOG
+++ b/activeresource/CHANGELOG
@@ -1,4 +1,4 @@
-*2.1.0 RC1 (May 11th, 2008)*
+*2.1.0 (May 31st, 2008)*
 
 * Fixed response logging to use length instead of the entire thing (seangeo) [#27]
 
diff --git a/activeresource/Rakefile b/activeresource/Rakefile
index 75fe52aea8..9fd0ec4921 100644
--- a/activeresource/Rakefile
+++ b/activeresource/Rakefile
@@ -64,7 +64,7 @@ spec = Gem::Specification.new do |s|
     s.files = s.files + Dir.glob( "#{dir}/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
   end
   
-  s.add_dependency('activesupport', '= 2.0.991' + PKG_BUILD)
+  s.add_dependency('activesupport', '= 2.1.0' + PKG_BUILD)
 
   s.require_path = 'lib'
   s.autorequire = 'active_resource'
diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb
index 08fd0123f6..59e0888c2b 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.
@@ -111,7 +111,7 @@ module ActiveResource
   # over HTTPS.
   # 
   # Note: Some values cannot be provided in the URL passed to site.  e.g. email addresses 
-  # as usernames.  In those situations you should use the seperate user and password option.
+  # as usernames.  In those situations you should use the separate user and password option.
   # == Errors & Validation
   #
   # Error handling and validation is handled in much the same manner as you're used to seeing in
@@ -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.
   #
@@ -200,8 +200,8 @@ module ActiveResource
     cattr_accessor :logger
 
     class << self
-      # Gets the URI of the REST resources to map for this class.  The site variable is required 
-      # ActiveResource's mapping to work.
+      # Gets the URI of the REST resources to map for this class.  The site variable is required for
+      # 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 for Active Resource's mapping to work.
       def site=(site)
         @connection = nil
         if site.nil?
@@ -288,7 +288,7 @@ module ActiveResource
       end
 
       # Returns the current format, default is ActiveResource::Formats::XmlFormat.
-      def format # :nodoc:
+      def format
         read_inheritable_attribute("format") || ActiveResource::Formats[:xml]
       end
 
@@ -298,7 +298,7 @@ module ActiveResource
         @timeout = timeout
       end
 
-      # Gets tthe number of seconds after which requests to the REST API should time out.
+      # Gets the number of seconds after which requests to the REST API should time out.
       def timeout
         if defined?(@timeout)
           @timeout
@@ -426,16 +426,16 @@ module ActiveResource
 
       alias_method :set_primary_key, :primary_key=  #:nodoc:
 
-      # Create a new resource instance and request to the remote service
+      # Creates a new resource instance and makes a request to the remote service
       # that it be saved, making it equivalent to the following simultaneous calls:
       #
       #   ryan = Person.new(:first => 'ryan')
       #   ryan.save
       #
-      # The newly created resource is returned.  If a failure has occurred an
-      # exception will be raised (see save).  If the resource is invalid and
-      # has not been saved then valid? will return <tt>false</tt>,
-      # while new? will still return <tt>true</tt>.
+      # Returns the newly created resource.  If a failure has occurred an
+      # exception will be raised (see <tt>save</tt>).  If the resource is invalid and
+      # has not been saved then <tt>valid?</tt> will return <tt>false</tt>,
+      # while <tt>new?</tt> will still return <tt>true</tt>.
       #
       # ==== Examples
       #   Person.create(:name => 'Jeremy', :email => 'myname@nospam.com', :enabled => true)
@@ -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
@@ -812,7 +812,7 @@ module ActiveResource
     #   Person.delete(guys_id)
     #   that_guy.exists? # => false
     def exists?
-      !new? && self.class.exists?(to_param, :params => prefix_options)      
+      !new? && self.class.exists?(to_param, :params => prefix_options)
     end
 
     # A method to convert the the resource to an XML string.
@@ -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..770116ceb7 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 ActiveResource::Base instances - they are ordinary Hashes. If you are expecting
+          # ActiveResource::Base 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..554fc3bcfc 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
+      # if 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).
   #
diff --git a/activeresource/lib/active_resource/version.rb b/activeresource/lib/active_resource/version.rb
index 34fb05b703..88798ea1c1 100644
--- a/activeresource/lib/active_resource/version.rb
+++ b/activeresource/lib/active_resource/version.rb
@@ -1,8 +1,8 @@
 module ActiveResource
   module VERSION #:nodoc:
     MAJOR = 2
-    MINOR = 0
-    TINY  = 991
+    MINOR = 1
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end