Fix docs for ActionController::Metal#headers

This documentation was correct when it was written in 6e75455, however
`headers` has moved a few times since:

- added to ActionController::Http in 216309c as part of the new_base
- Http was renamed to Metal in 52798fd
- headers was changed from an independent hash to a delegation in
  51c7ac1 and 54becd1

Added docs for Metal#request, Metal#response, and Metal#headers that can
be linked to from Response. The recommendation to use Metal delegation
methods instead of methods on Response was also removed due to a number of
docs/guides demonstrating the opposite.

Author: skipkayhil

actionpack/lib/action_controller/base.rb

@@ -167,22 +167,6 @@ module ActionController
   class Base < Metal
     abstract!
 
-    # We document the request and response methods here because albeit they are
-    # implemented in ActionController::Metal, the type of the returned objects
-    # is unknown at that level.
-
-    ##
-    # :method: request
-    #
-    # Returns an ActionDispatch::Request instance that represents the
-    # current request.
-
-    ##
-    # :method: response
-    #
-    # Returns an ActionDispatch::Response that represents the current
-    # response.
-
     # Shortcut helper that returns all the modules included in
     # ActionController::Base except the ones passed as arguments:
     #

actionpack/lib/action_controller/metal.rb

@@ -142,9 +142,25 @@ def controller_name
       self.class.controller_name
     end
 
-    attr_internal :response, :request
+    ##
+    # :attr_reader: request
+    #
+    # The ActionDispatch::Request instance for the current request.
+    attr_internal :request
+
+    ##
+    # :attr_reader: response
+    #
+    # The ActionDispatch::Response instance for the current response.
+    attr_internal :response
+
     delegate :session, to: "@_request"
-    delegate :headers, :status=, :location=, :content_type=,
+
+    ##
+    # Delegates to ActionDispatch::Response#headers.
+    delegate :headers, to: "@_response"
+
+    delegate :status=, :location=, :content_type=,
              :status, :location, :content_type, :media_type, to: "@_response"
 
     def initialize

actionpack/lib/action_dispatch/http/response.rb

@@ -12,17 +12,15 @@ module ActionDispatch # :nodoc:
   # back to the web browser) or a TestResponse (i.e. one that is generated
   # from integration tests).
   #
-  # \Response is mostly a Ruby on \Rails framework implementation 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 Response#headers.
+  # The \Response object for the current request is exposed on controllers as
+  # ActionController::Metal#response. ActionController::Metal also provides a
+  # few additional methods that delegate to attributes of the \Response such as
+  # ActionController::Metal#headers.
   #
-  # Nevertheless, integration tests may want to inspect controller responses in
-  # more detail, and that's when \Response can be useful for application
-  # developers. Integration test methods such as
-  # Integration::RequestHelpers#get and Integration::RequestHelpers#post return
-  # objects of type TestResponse (which are of course also of type \Response).
+  # Integration tests will likely also want to inspect responses in
+  # more detail. Methods such as Integration::RequestHelpers#get
+  # and Integration::RequestHelpers#post return instances of
+  # TestResponse (which inherits from \Response) for this purpose.
   #
   # For example, the following demo integration test prints the body of the
   # controller response to the console:
@@ -63,7 +61,18 @@ def to_hash
     # The HTTP status code.
     attr_reader :status
 
-    # Get headers for this response.
+    # The headers for the response.
+    #
+    #   header["Content-Type"] # => "text/plain"
+    #   header["Content-Type"] = "application/json"
+    #   header["Content-Type"] # => "application/json"
+    #
+    # Also aliased as +headers+.
+    #
+    #   headers["Content-Type"] # => "text/plain"
+    #   headers["Content-Type"] = "application/json"
+    #   headers["Content-Type"] # => "application/json"
+    #
     attr_reader :header
 
     alias_method :headers,  :header