Write overviews for AbstractController::TestResponse and AbstractController::AbstractResponse.

2 files changed, 53 insertions, 5 deletions

diff --git a/actionpack/lib/action_controller/response.rb b/actionpack/lib/action_controller/response.rb
index 1d9f6676ba..8f2672425f 100755
--- a/actionpack/lib/action_controller/response.rb
+++ b/actionpack/lib/action_controller/response.rb
@@ -1,19 +1,61 @@
 require 'digest/md5'
 
-module ActionController
-  class AbstractResponse #:nodoc:
+module ActionController # :nodoc:
+  # Represents an HTTP response generated by a controller action. One can use an
+  # ActionController::AbstractResponse object to retrieve the current state of the
+  # response, or customize the response. An AbstractResponse object can either
+  # represent a "real" HTTP response (i.e. one that is meant to be sent back to the
+  # web browser) or a test response (i.e. one that is generated from integration
+  # tests). See CgiResponse and TestResponse, respectively.
+  #
+  # AbstractResponse is mostly a Ruby on Rails framework implement detail, and should
+  # never be used directly in controllers. Controllers should use the methods defined
+  # in ActionController::Base instead. For example, if you want to set the HTTP
+  # response's content MIME type, then use ActionControllerBase#headers instead of
+  # AbstractResponse#headers.
+  #
+  # Nevertheless, integration tests may want to inspect controller responses in more
+  # detail, and that's when AbstractResponse can be useful for application developers.
+  # Integration test methods such as ActionController::Integration::Session#get and
+  # ActionController::Integration::Session#post return objects of type TestResponse
+  # (which are of course also of type AbstractResponse).
+  #
+  # For example, the following demo integration "test" prints the body of the
+  # controller response to the console:
+  #
+  #  class DemoControllerTest < ActionController::IntegrationTest
+  #    def test_print_root_path_to_console
+  #      get('/')
+  #      puts @response.body
+  #    end
+  #  end
+  class AbstractResponse
     DEFAULT_HEADERS = { "Cache-Control" => "no-cache" }
     attr_accessor :request
-    attr_accessor :body, :headers, :session, :cookies, :assigns, :template, :redirected_to, :redirected_to_method_params, :layout
+    
+    # The body content (e.g. HTML) of the response, as a String.
+    attr_accessor :body
+    # The headers of the response, as a Hash. It maps header names to header values.
+    attr_accessor :headers
+    attr_accessor :session, :cookies, :assigns, :template, :redirected_to, :redirected_to_method_params, :layout
 
     def initialize
       @body, @headers, @session, @assigns = "", DEFAULT_HEADERS.merge("cookie" => []), [], []
     end
 
+    # Sets the HTTP response's content MIME type. For example, in the controller
+    # you could write this:
+    #
+    #  response.content_type = "text/plain"
+    #
+    # If a character set has been defined for this response (see charset=) then
+    # the character set information will also be included in the content type
+    # information.
     def content_type=(mime_type)
       self.headers["Content-Type"] = charset ? "#{mime_type}; charset=#{charset}" : mime_type
     end
     
+    # Returns the response's content MIME type, or nil if content type has been set.
     def content_type
       content_type = String(headers["Content-Type"] || headers["type"]).split(";")[0]
       content_type.blank? ? nil : content_type
@@ -73,4 +115,4 @@ module ActionController
         self.headers["Content-Length"] = body.size unless body.respond_to?(:call)
       end
   end
-end
\ No newline at end of file
+end
diff --git a/actionpack/lib/action_controller/test_process.rb b/actionpack/lib/action_controller/test_process.rb
index caf7253424..5bd997245e 100644
--- a/actionpack/lib/action_controller/test_process.rb
+++ b/actionpack/lib/action_controller/test_process.rb
@@ -273,7 +273,13 @@ module ActionController #:nodoc:
     end
   end
 
-  class TestResponse < AbstractResponse #:nodoc:
+  # Integration test methods such as ActionController::Integration::Session#get
+  # and ActionController::Integration::Session#post return objects of class
+  # TestResponse, which represent the HTTP response results of the requested
+  # controller actions.
+  #
+  # See AbstractResponse for more information on controller response objects.
+  class TestResponse < AbstractResponse
     include TestResponseBehavior
   end