edit pass in #define_callbacks rdoc

activesupport/lib/active_support/callbacks.rb

@@ -449,7 +449,9 @@ def __update_callbacks(name, filters = [], block = nil) #:nodoc:
       # we convert :only and :except conditions into per-key conditions.
       #
       #   before_filter :authenticate, :except => "index"
+      #
       # becomes
+      #
       #   dispatch_callback :before, :authenticate, :per_key => {:unless => proc {|c| c.action_name == "index"}}
       #
       # Per-Key conditions are evaluated only once per use of a given key.
@@ -510,65 +512,65 @@ def reset_callbacks(symbol)
         __define_runner(symbol)
       end
 
-      # Define callbacks types.
-      #
-      # ==== Example
+      # Defines callbacks types:
       #
       #   define_callbacks :validate
       #
-      # ==== Options
+      # This macro accepts the following options:
       #
       # * <tt>:terminator</tt> - Indicates when a before filter is considered
       # to be halted.
       #
       #   define_callbacks :validate, :terminator => "result == false"
       #
-      # In the example above, if any before validate callbacks returns false,
-      # other callbacks are not executed. Defaults to "false".
+      # In the example above, if any before validate callbacks returns +false+,
+      # other callbacks are not executed. Defaults to "false", meaning no value
+      # halts the chain.
       #
       # * <tt>:rescuable</tt> - By default, after filters are not executed if
-      # the given block or an before_filter raises an error. Supply :rescuable => true
-      # to change this behavior.
+      # the given block or a before filter raises an error. Set this option to
+      # true to change this behavior.
       #
       # * <tt>:scope</tt> - Indicates which methods should be executed when a class
-      # is given as callback:
+      # is given as callback. Defaults to <tt>[:kind]</tt>.
       #
       #  class Audit
       #    def before(caller)
       #      puts 'Audit: before is called'
       #    end
+      #
       #    def before_save(caller)
       #      puts 'Audit: before_save is called'
       #    end
       #  end
       #
       #  class Account
       #    include ActiveSupport::Callbacks
+      #
       #    define_callbacks :save
       #    set_callback :save, :before, Audit.new
+      #
       #    def save
       #      run_callbacks :save do
       #        puts 'save in main'
       #      end
       #    end
       #  end
       #
-      #  In the above case if you execute Account.new.save then method "before" of Audit class
-      #  will be called. Now change the class "Account" and pass "scope" to method "define_callbacks".
+      # In the above case whenever you save an account the method <tt>Audit#before</tt> will
+      # be called. On the other hand
       #
-      #  define_callbacks :save, :scope => [:kind, :name]
+      #   define_callbacks :save, :scope => [:kind, :name]
       #
-      #  Now if you invoke Account.new.save then method "before_save" of Audit will be called 
-      #  instead of method "before".
+      # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling
+      # <tt>"#{kind}_#{name}"</tt> on the given instance. In this case "kind" is "before" and
+      # "name" is "save".
       #
-      #  When you do not pass any scope then the default value of scope ":kind" is implicitly being
-      #  passed. In the above case method "before_save" is constructed by calling "#{kind}_#{name}" 
-      #  in the given class. In this case "kind" is "before" and "name" is "save".
+      # A declaration like
       #
-      #  Although ":kind" is the default scope that is passed, it is possible to not to make use of ":kind".
-      #  define_callbacks :save, :scope => [:name] . A declaration like this would call "save" method of
-      #  Audit class since ":kind" is skipped.
+      #   define_callbacks :save, :scope => [:name]
       #
+      # would call <tt>Audit#save</tt>.
       #
       def define_callbacks(*callbacks)
         config = callbacks.last.is_a?(Hash) ? callbacks.pop : {}