reviews commit dcc9d38

1 files changed, 22 insertions, 32 deletions

diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb
index d1e03e596c..ac94d12e5e 100644
--- a/activesupport/lib/active_support/concern.rb
+++ b/activesupport/lib/active_support/concern.rb
@@ -3,48 +3,48 @@ module ActiveSupport
   #
   #   module M
   #     def self.included(base)
-  #       base.send(:extend, ClassMethods)
+  #       base.extend, ClassMethods
   #       base.send(:include, InstanceMethods)
-  #       scope :foo, :conditions => { :created_at => nil }
+  #       scope :disabled, where(:disabled => true)
   #     end
   #
   #     module ClassMethods
-  #       def cm; puts 'I am a class method'; end
+  #       ...
   #     end
   #
   #     module InstanceMethods
-  #       def im; puts 'I am an instance method'; end
+  #       ...
   #     end
   #   end
   #
   # By using <tt>ActiveSupport::Concern</tt> the above module could instead be written as:
-  #   
+  #
   #   require 'active_support/concern'
   #
   #   module M
   #     extend ActiveSupport::Concern
   #
   #     included do
-  #       scope :foo, :conditions => { :created_at => nil }
+  #       scope :disabled, where(:disabled => true)
   #     end
   #
   #     module ClassMethods
-  #       def cm; puts 'I am a class method'; end
+  #       ...
   #     end
   #
   #     module InstanceMethods
-  #       def im; puts 'I am an instance method'; end
+  #       ...
   #     end
   #   end
   #
-  # Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following:
+  # Moreover, it gracefully handles module dependencies. Given a +Foo+ module and a +Bar+
+  # module which depends on the former, we would typically write the following:
   #
   #   module Foo
   #     def self.included(base)
-  #       # Define some :enhanced_method for Host class
   #       base.class_eval do
-  #         def self.enhanced_method
-  #           # Do enhanced stuff
+  #         def self.method_injected_by_foo
+  #           ...
   #         end
   #       end
   #     end
@@ -52,7 +52,7 @@ module ActiveSupport
   #
   #   module Bar
   #     def self.included(base)
-  #       base.send(:enhanced_method)
+  #       base.method_injected_by_foo
   #     end
   #   end
   #
@@ -61,23 +61,13 @@ module ActiveSupport
   #     include Bar # Bar is the module that Host really needs
   #   end
   #
-  # But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar:
-  #
-  #   module Foo
-  #     def self.included(base)
-  #       # Define some :enhanced_method for Host class
-  #       base.class_eval do
-  #         def self.enhanced_method
-  #           # Do enhanced stuff
-  #         end
-  #       end
-  #     end
-  #   end
+  # But why should +Host+ care about +Bar+'s dependencies, namely +Foo+? We could try to hide
+  # these from +Host+ directly including +Foo+ in +Bar+:
   #
   #   module Bar
   #     include Foo 
   #     def self.included(base)
-  #       base.send(:enhanced_method)
+  #       base.method_injected_by_foo
   #     end
   #   end
   #
@@ -85,8 +75,8 @@ module ActiveSupport
   #     include Bar
   #   end
   #
-  # Unfortunately this won't work, since when Foo is included, its <tt>base</tt> is Bar module, not Host class.
-  # With <tt>ActiveSupport::Concern</tt>, module dependencies are properly resolved:
+  # Unfortunately this won't work, since when +Foo+ is included, its <tt>base</tt> is the +Bar+ module,
+  # not the +Host+ class. With <tt>ActiveSupport::Concern</tt>, module dependencies are properly resolved:
   #
   #   require 'active_support/concern'
   #
@@ -94,8 +84,8 @@ module ActiveSupport
   #     extend ActiveSupport::Concern
   #     included do
   #       class_eval do
-  #         def self.enhanced_method
-  #           # Do enhanced stuff
+  #         def self.method_injected_by_foo
+  #           ...
   #         end
   #       end
   #     end
@@ -106,12 +96,12 @@ module ActiveSupport
   #     include Foo
   #
   #     included do
-  #       self.send(:enhanced_method)
+  #       self.method_injected_by_foo
   #     end
   #   end
   #
   #   class Host
-  #     include Bar # Host only needs to care about Bar without needing to know about its dependencies
+  #     include Bar # works, Bar takes care now of its dependencies
   #   end
   #
   module Concern