Correct inconsistencies in RequestForgeryProtection docs. #11032 [mislav]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8807 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

actionpack/CHANGELOG

 *SVN*
 
+* Correct inconsistencies in RequestForgeryProtection docs.  #11032 [mislav]
+
 * Introduce a Template class to ActionView.  #11024 [lifofifo]
 
 * Introduce the :index option for form_for and fields_for to simplify multi-model forms (see http://railscasts.com/episodes/75).  #9883 [rmm5t]

actionpack/lib/action_controller/request_forgery_protection.rb

@@ -13,20 +13,33 @@ def self.included(base)
       base.extend(ClassMethods)
     end
     
-    module ClassMethods
-      # Protect a controller's actions from CSRF attacks by ensuring that all forms are coming from the current web application, not 
-      # a forged link from another site. This is done by embedding a token based on the session (which an attacker wouldn't know) in 
-      # all forms and Ajax requests generated by Rails and then verifying the authenticity of that token in the controller. Only
+    # Protecting controller actions from CSRF attacks by ensuring that all forms are coming from the current web application, not a
+    # forged link from another site, is done by embedding a token based on the session (which an attacker wouldn't know) in all
+    # forms and Ajax requests generated by Rails and then verifying the authenticity of that token in the controller.  Only
     # HTML/JavaScript requests are checked, so this will not protect your XML API (presumably you'll have a different authentication
     # scheme there anyway).  Also, GET requests are not protected as these should be indempotent anyway.
     #
-      # You turn this on with the #protect_from_forgery method, which will perform the check and raise 
-      # an ActionController::InvalidAuthenticityToken if the token doesn't match what was expected. And it will add 
-      # a _authenticity_token parameter to all forms that are automatically generated by Rails. You can customize the error message 
-      # given through public/422.html.
+    # This is turned on with the <tt>protect_from_forgery</tt> method, which will check the token and raise an
+    # ActionController::InvalidAuthenticityToken if it doesn't match what was expected. You can customize the error message in
+    # production by editing public/422.html.  A call to this method in ApplicationController is generated by default in post-Rails 2.0
+    # applications.
+    #
+    # The token parameter is named <tt>authenticity_token</tt> by default. If you are generating an HTML form manually (without the
+    # use of Rails' <tt>form_for</tt>, <tt>form_tag</tt> or other helpers), you have to include a hidden field named like that and
+    # set its value to what is returned by <tt>form_authenticity_token</tt>. Same applies to manually constructed Ajax requests. To
+    # make the token available through a global variable to scripts on a certain page, you could add something like this to a view:
+    #
+    #   <%= javascript_tag "window._token = '#{form_authenticity_token}'" %>
+    #
+    # Request forgery protection is disabled by default in test environment.  If you are upgrading from Rails 1.x, add this to
+    # config/environments/test.rb:
+    #
+    #   # Disable request forgery protection in test environment
+    #   config.action_controller.allow_forgery_protection = false
     # 
-      # Learn more about CSRF (Cross-Site Request Forgery) attacks:
+    # == Learn more about CSRF (Cross-Site Request Forgery) attacks
     #
+    # Here are some resources:
     # * http://isc.sans.org/diary.html?storyid=1750
     # * http://en.wikipedia.org/wiki/Cross-site_request_forgery
     #
@@ -38,8 +51,8 @@ module ClassMethods
     #   * http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
     # * Make sure the session cookies that Rails creates are non-persistent.  Check in Firefox and look for "Expires: at end of session"
     #
-      # If you need to construct a request yourself, but still want to take advantage of forgery protection, you can grab the 
-      # authenticity_token using the form_authenticity_token helper method and make it part of the parameters yourself.
+    module ClassMethods
+      # Turn on request forgery protection. Bear in mind that only non-GET, HTML/JavaScript requests are checked.
       #
       # Example:
       #
@@ -54,16 +67,10 @@ module ClassMethods
       #     skip_before_filter :verify_authenticity_token
       #   end
       #
-      # If you are upgrading from Rails 1.x, disable forgery protection to
-      # simplify your tests. Add this to config/environments/test.rb:
-      #
-      #   # Disable request forgery protection in test environment
-      #   config.action_controller.allow_forgery_protection = false
-      #
       # Valid Options:
       #
-      # * <tt>:only/:except</tt> - passed to the before_filter call.  Set which actions are verified.
-      # * <tt>:secret</tt> - Custom salt used to generate the form_authenticity_token.
+      # * <tt>:only/:except</tt> - passed to the <tt>before_filter</tt> call.  Set which actions are verified.
+      # * <tt>:secret</tt> - Custom salt used to generate the <tt>form_authenticity_token</tt>.
       #   Leave this off if you are using the cookie session store.
       # * <tt>:digest</tt> - Message digest used for hashing.  Defaults to 'SHA1'
       def protect_from_forgery(options = {})