adding documentation to ActiveSupport::Concern ht:strictly typed for an awesome example

some minor documentation changes

3 files changed, 40 insertions, 1 deletions

diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb
index 5670ec74cb..e675937f4d 100644
--- a/activemodel/lib/active_model/serialization.rb
+++ b/activemodel/lib/active_model/serialization.rb
@@ -61,6 +61,8 @@ module ActiveModel
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #   person.to_json             # => "{\"name\":\"Bob\"}"
   #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+  #
+  # Valid options are <tt>:only</tt>, <tt>:except</tt> and <tt>:methods</tt> .  
   module Serialization
     def serializable_hash(options = nil)
       options ||= {}
diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb
index 1c7802f7de..adabdd3388 100644
--- a/activesupport/lib/active_support/callbacks.rb
+++ b/activesupport/lib/active_support/callbacks.rb
@@ -568,7 +568,9 @@ module ActiveSupport
       #
       # 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".
+      # "name" is "save". In this context treat ":kind" and ":name" as special thing where
+      # ":kind" refers to "callback type(before/after)" and ":name" refers to the method on 
+      # which callbacks are being defined.
       #
       # A declaration like
       #
diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb
index eb31f7cad4..408d327dd7 100644
--- a/activesupport/lib/active_support/concern.rb
+++ b/activesupport/lib/active_support/concern.rb
@@ -1,3 +1,38 @@
+# A typical module looks like this
+#
+#   module M
+#     def self.included(base)
+#       base.send(:extend, ClassMethods)
+#       base.send(:include, InstanceMethods)
+#       scope :foo, :conditions => {:created_at => nil}
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am instance method'; end
+#     end
+#   end
+#
+# By using <tt>ActiveSupport::Concern</tt> above module could be written as:
+#
+#   module M
+#     extend ActiveSupport::Concern
+#
+#    included do 
+#       scope :foo, :conditions => {:created_at => nil}
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am instance method'; end
+#     end
+#   end
 module ActiveSupport
   module Concern
     def self.extended(base)