Beefed up docs a bit

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

actionpack/lib/action_controller/request_forgery_protection.rb

@@ -1,22 +1,6 @@
 module ActionController #:nodoc:
   class InvalidToken < ActionControllerError; end
 
-  # Protect a controller's actions with the #protect_from_forgery method.  Failure to validate will result in a ActionController::InvalidToken 
-  # exception.  Customize the error message through the use of rescue_templates and rescue_action_in_public.
-  #
-  #   class FooController < ApplicationController
-  #     # uses the cookie session store
-  #     protect_from_forgery :except => :index
-  #
-  #     # uses one of the other session stores that uses a session_id value.
-  #     protect_from_forgery :secret => 'my-little-pony', :except => :index
-  #   end
-  #
-  # 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.  Leave this off if you are using the cookie session store.
-  # * <tt>:digest</tt> - Message digest used for hashing.  Defaults to 'SHA1'
   module RequestForgeryProtection
     def self.included(base)
       base.class_eval do
@@ -28,6 +12,32 @@ def self.included(base)
     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
+      # 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::InvalidToken if
+      # the token doesn't match what was expected. And it will add a _token parameter to all forms that are automatically generated
+      # by Rails. You can customize the error message given through public/422.html.
+      #
+      # Example:
+      #
+      #   class FooController < ApplicationController
+      #     # uses the cookie session store (then you don't need a separate :secret)
+      #     protect_from_forgery :except => :index
+      #
+      #     # uses one of the other session stores that uses a session_id value.
+      #     protect_from_forgery :secret => 'my-little-pony', :except => :index
+      #   end
+      #
+      # 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.
+      #   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 = {})
         self.request_forgery_protection_token ||= :authenticity_token
         before_filter :verify_authenticity_token, :only => options.delete(:only), :except => options.delete(:except)
@@ -57,7 +67,7 @@ def verifiable_request_format?
         request.format.html? || request.format.js?
       end
 
-      # Sets the token value for the current session.  Pass a :secret option in #verify_token to add a custom salt to the hash.
+      # Sets the token value for the current session.  Pass a :secret option in #protect_from_forgery to add a custom salt to the hash.
       def form_authenticity_token
         @form_authenticity_token ||= if request_forgery_protection_options[:secret]
           authenticity_token_from_session_id