Make changes to AC guide as suggested by Xavier Noria

3 files changed, 18 insertions, 14 deletions

diff --git a/railties/doc/guides/source/actioncontroller_basics/methods.txt b/railties/doc/guides/source/actioncontroller_basics/methods.txt
index c6ae54a540..68204c189a 100644
--- a/railties/doc/guides/source/actioncontroller_basics/methods.txt
+++ b/railties/doc/guides/source/actioncontroller_basics/methods.txt
@@ -1,6 +1,6 @@
 == Methods and Actions ==
 
-A controller is a Ruby class which inherits from ApplicationController and has methods just like any other class. Usually these methods correspond to actions in MVC, but they can just as well be helpful methods which can be called by actions. When your application receives a request, the routing will determine which controller and action to run. Then Rails creates an instance of that controller and runs the method corresponding to the action (the method with the same name as the action).
+A controller is a Ruby class which inherits from ApplicationController and has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Rails creates an instance of that controller and runs the public method with the same name as the action.
 
 [source, ruby]
 ----------------------------------------------
@@ -10,7 +10,7 @@ class ClientsController < ApplicationController
   def new
   end
 
-  # These methods are responsible for producing output
+  # Action methods are responsible for producing output
   def edit
   end
 
@@ -23,9 +23,9 @@ private
 end
 ----------------------------------------------
 
-Private methods in a controller are also used as filters, which will be covered later in this guide.
+There's no rule saying a method on a controller has to be an action; they may well be used for other purposes such as filters, which will be covered later in this guide.
 
-As an example, if the user goes to `/clients/new` in your application to add a new client, Rails will create a ClientsController instance will be created and run the `new` method. Note that the empty method from the example above could work just fine because Rails will by default render the `new.html.erb` view unless the action says otherwise. The `new` method could make available to the view a `@client` instance variable by creating a new Client:
+As an example, if a user goes to `/clients/new` in your application to add a new client, Rails will create an instance of ClientsController and run the `new` method. Note that the empty method from the example above could work just fine because Rails will by default render the `new.html.erb` view unless the action says otherwise. The `new` method could make available to the view a `@client` instance variable by creating a new Client:
 
 [source, ruby]
 ----------------------------------------------
diff --git a/railties/doc/guides/source/actioncontroller_basics/params.txt b/railties/doc/guides/source/actioncontroller_basics/params.txt
index fb380519fd..e8a2d3d058 100644
--- a/railties/doc/guides/source/actioncontroller_basics/params.txt
+++ b/railties/doc/guides/source/actioncontroller_basics/params.txt
@@ -43,6 +43,8 @@ The params hash is not limited to one-dimensional keys and values. It can contai
 GET /clients?ids[]=1&ids[]=2&ids[]=3
 -------------------------------------
 
+NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as [ and ] are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.
+
 The value of `params[:ids]` will now be `["1", "2", "3"]`. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.
 
 To send a hash you include the key name inside the brackets:
@@ -56,7 +58,9 @@ To send a hash you include the key name inside the brackets:
 </form>
 -------------------------------------
 
-The value of `params[:client]` when this form is submitted  will be `{:name => "Acme", :phone => "12345", :address => {:postcode => "12345", :city => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`.
+The value of `params[:client]` when this form is submitted  will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`.
+
+Note that the params hash is actually an instance of HashWithIndifferentAccess from Active Support which is a subclass of Hash which lets you use symbols and strings interchangeably as keys.
 
 === Routing Parameters ===
 
@@ -78,7 +82,7 @@ You can set global default parameters that will be used when generating URLs wit
 ------------------------------------
 class ApplicationController < ActionController::Base
 
-  #The options parameter is the hash passed in to url_for
+  #The options parameter is the hash passed in to +url_for+
   def default_url_options(options)
     {:locale => I18n.locale}
   end
@@ -86,4 +90,4 @@ class ApplicationController < ActionController::Base
 end
 ------------------------------------
 
-These options will be used as a starting-point when generating, so it's possible they'll be overridden by url_for. Because this method is defined in the controller, you can define it on ApplicationController so it would be used for all URL generation, or you could define it on only one controller for all URLs generated there.
+These options will be used as a starting-point when generating, so it's possible they'll be overridden by +url_for+. Because this method is defined in the controller, you can define it on ApplicationController so it would be used for all URL generation, or you could define it on only one controller for all URLs generated there.
diff --git a/railties/doc/guides/source/actioncontroller_basics/session.txt b/railties/doc/guides/source/actioncontroller_basics/session.txt
index 3b69ec82ef..ae5f876777 100644
--- a/railties/doc/guides/source/actioncontroller_basics/session.txt
+++ b/railties/doc/guides/source/actioncontroller_basics/session.txt
@@ -1,15 +1,15 @@
 == Session ==
 
-Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and can use one of a number of different storage mechanisms:
+Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and the view and can use one of a number of different storage mechanisms:
 
  * CookieStore - Stores everything on the client.
- * DRBStore - Stores the data on a DRb client.
- * MemCacheStore - Stores the data in MemCache.
+ * DRbStore - Stores the data on a DRb server.
+ * MemCacheStore - Stores the data in a memcache.
  * ActiveRecordStore - Stores the data in a database using Active Record.
 
-All session stores store either the session ID or the entire session in a cookie - Rails does not allow the session ID to be passed in any other way. Most stores also use this key to locate the session data on the server.
+All session stores use a cookie - this is required and Rails does not allow any part of the session to be passed in any other way (e.g. you can't use the query string to pass a session ID) because of security concerns (it's easier to hijack a session when the ID is part of the URL).
 
-The default and recommended store, the Cookie Store, does not store session data on the server, but in the cookie itself. The data is cryptographically signed to make it tamper-proof, but it is not encrypted, so anyone with access to it can read its contents but not edit it. It can only store about 4kB of data - much less than the others - but this is usually enough. Storing large amounts of data is discouraged no matter which session store your application uses. You should especially avoid storing complex objects (anything other than basic Ruby objects, the primary example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. The Cookie Store has the added advantage that it does not require any setting up beforehand - Rails will generate a "secret key" which will be used to sign the cookie when you create the application.
+Most stores use a cookie to store the session ID which is then used to look up the session data on the server. The default and recommended store, the CookieStore, does not store session data on the server, but in the cookie itself. The data is cryptographically signed to make it tamper-proof, but it is not encrypted, so anyone with access to it can read its contents but not edit it (Rails will not accept it if it has been edited). It can only store about 4kB of data - much less than the others - but this is usually enough. Storing large amounts of data is discouraged no matter which session store your application uses. You should especially avoid storing complex objects (anything other than basic Ruby objects, the most common example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. The CookieStore has the added advantage that it does not require any setting up beforehand - Rails will generate a "secret key" which will be used to sign the cookie when you create the application.
 
 Read more about session storage in the link:../security.html[Security Guide].
 
@@ -56,7 +56,7 @@ end
 
 In your controller you can access the session through the `session` instance method.
 
-NOTE: There are two `session` methods, the class and the instance method. The class method which is described above is used to turn the session on and off while the instance method described below is used to access session values. The class method is used outside of method definitions while the instance methods is used inside methods, in actions or filters.
+NOTE: There are two `session` methods, the class and the instance method. The class method which is described above is used to turn the session on and off while the instance method described below is used to access session values.
 
 Session values are stored using key/value pairs like a hash:
 
@@ -129,7 +129,7 @@ class LoginsController < ApplicationController
 end
 ------------------------------------------
 
-The `destroy` action redirects to the application's `root_url`, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to a display eventual errors or notices from the flash in the application's layout:
+The `destroy` action redirects to the application's `root_url`, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display eventual errors or notices from the flash in the application's layout:
 
 ------------------------------------------
 <html>