Update guides from docrails

1 files changed, 19 insertions, 11 deletions

diff --git a/railties/doc/guides/source/actioncontroller_basics/request_response_objects.txt b/railties/doc/guides/source/actioncontroller_basics/request_response_objects.txt
index 493bd4cb43..250f84bd72 100644
--- a/railties/doc/guides/source/actioncontroller_basics/request_response_objects.txt
+++ b/railties/doc/guides/source/actioncontroller_basics/request_response_objects.txt
@@ -1,13 +1,13 @@
-== The request and response objects ==
+== The +request+ and +response+ Objects ==
 
-In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The `request` method contains an instance of link:http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html[AbstractRequest] and the `response` method contains the link:http://github.com/rails/rails/tree/master/actionpack/lib/action_controller/response.rb[response object] representing what is going to be sent back to the client.
+In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The `request` method contains an instance of AbstractRequest and the `response` method returns a +response+ object representing what is going to be sent back to the client.
 
-=== The request ===
+=== The +request+ Object ===
 
-The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the link:http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html[API documentation].
+The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the link:http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html[API documentation]. Among the properties that you can access on this object:
 
  * host - The hostname used for this request.
- * domain - The hostname without the first part (usually "www").
+ * domain - The hostname without the first segment (usually "www").
  * format - The content type requested by the client.
  * method - The HTTP method used for the request.
  * get?, post?, put?, delete?, head? - Returns true if the HTTP method is get/post/put/delete/head.
@@ -18,18 +18,26 @@ The request object contains a lot of useful information about the request coming
  * remote_ip - The IP address of the client.
  * url - The entire URL used for the request.
 
-==== path_parameters, query_parameters and request_parameters ====
+==== +path_parameters+, +query_parameters+ and +request_parameters+ ====
 
-TODO: Does this belong here?
+Rails collects all of the parameters sent along with the request in the `params` hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The `query_parameters` hash contains parameters that were sent as part of the query string while the `request_parameters` hash contains parameters sent as part of the post body. The `path_parameters` hash contains parameters that were recognized by the routing as being part of the path leading to this particular controller and action.
 
-Rails collects all of the parameters sent along with the request in the `params` hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The `query_parameters` hash contains parameters that were sent as part of the query string while the `request_parameters` hash contains parameters sent as part of the post body. The `path_parameters` hash contains parameters that were recognised by the routing as being part of the path leading to this particular controller and action.
+=== The +response+ Object ===
 
-=== The response ===
-
-The response objects is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.
+The response object is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.
 
  * body - This is the string of data being sent back to the client. This is most often HTML.
  * status - The HTTP status code for the response, like 200 for a successful request or 404 for file not found.
  * location - The URL the client is being redirected to, if any.
  * content_type - The content type of the response.
  * charset - The character set being used for the response. Default is "utf8".
+ * headers - Headers used for the response.
+
+==== Setting Custom Headers ====
+
+If you want to set custom headers for a response then `response.headers` is the place to do it. The headers attribute is a hash which maps header names to their values, and Rails will set some of them - like "Content-Type" - automatically. If you want to add or change a header, just assign it to `headers` with the name and value:
+
+[source, ruby]
+-------------------------------------
+response.headers["Content-Type"] = "application/pdf"
+-------------------------------------