Permalink
Browse files

edit pass in #define_callbacks rdoc

  • Loading branch information...
1 parent e4c8bc1 commit 94de5b8cb58a5b0e1b0493932ec8b6bdf2b8f6dc @fxn fxn committed Jun 14, 2010
Showing with 22 additions and 20 deletions.
  1. +22 −20 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 : {}

2 comments on commit 94de5b8

Member

neerajdotname commented on 94de5b8 Jun 14, 2010

Xavier thanks for editing. You have certainly mastered the art of brevity. Nicely edited. Thank you.

Owner

fxn replied Jun 14, 2010

No prob! Thanks for contributing :).

Please sign in to comment.