Documented active_support/concern dependency handling

activesupport/lib/active_support/concern.rb

@@ -1,4 +1,4 @@
-# A typical module looks like this
+# A typical module looks like this:
 #
 #   module M
 #     def self.included(base)
@@ -18,6 +18,8 @@
 #
 # By using <tt>ActiveSupport::Concern</tt> the above module could instead be written as:
 #   
+#   require 'active_support/concern'
+#
 #   module M
 #     extend ActiveSupport::Concern
 #
@@ -33,6 +35,84 @@
 #       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:
+#
+#   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
+#
+#   module Bar
+#     def self.included(base)
+#       base.send(:enhanced_method)
+#     end
+#   end
+#
+#   class Host
+#     include Foo # We need to include this dependency for Bar
+#     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
+#
+#   module Bar
+#     include Foo 
+#     def self.included(base)
+#       base.send(:enhanced_method)
+#     end
+#   end
+#
+#   class Host
+#     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:
+#
+#   require 'active_support/concern'
+#
+#   module Foo
+#     extend ActiveSupport::Concern
+#     included do
+#       class_eval do
+#         def self.enhanced_method
+#           # Do enhanced stuff
+#         end
+#       end
+#     end
+#   end
+#
+#   module Bar
+#     extend ActiveSupport::Concern
+#     include Foo
+#
+#     included do
+#       self.send(:enhanced_method)
+#     end
+#   end
+#
+#   class Host
+#     include Bar # Host only needs to care about Bar without needing to know about its dependencies
+#   end
+#
 module ActiveSupport
   module Concern
     def self.extended(base)