Improve explanation of with_options

1 files changed, 5 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/core_ext/object/misc.rb b/activesupport/lib/active_support/core_ext/object/misc.rb
index 99b4a71645..cd0a04d32a 100644
--- a/activesupport/lib/active_support/core_ext/object/misc.rb
+++ b/activesupport/lib/active_support/core_ext/object/misc.rb
@@ -40,7 +40,11 @@ class Object
     value
   end
 
-  # An elegant way to refactor out common options
+  # An elegant way to factor duplication out of options passed to a series of
+  # method calls. Each method called in the block, with the block variable as
+  # the receiver, will have its options merged with the default +options+ hash
+  # provided. Each method called on the block variable must take an options
+  # hash as its final argument.
   # 
   #   with_options :order => 'created_at', :class_name => 'Comment' do |post|
   #     post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all