Improve documentation coverage and markup

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

11 files changed, 100 insertions, 31 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index 34b1551abc..a9882828ca 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -67,17 +67,35 @@ module ActiveSupport #:nodoc:
           end
         end
 
-        # Returns a string that represents this array in XML by sending
-        # <tt>to_xml</tt> to each element.
+        # Returns a string that represents this array in XML by sending +to_xml+
+        # to each element. Active Record collections delegate their representation
+        # in XML to this method.
         #
-        # All elements are expected to respond to <tt>to_xml</tt>, if any of
-        # them does not an exception is raised.
+        # All elements are expected to respond to +to_xml+, if any of them does
+        # not an exception is raised.
         #
         # The root node reflects the class name of the first element in plural
-        # if all elements belong to the same type and that's not <tt>Hash</tt>.
-        # Otherwise the root element is "records".
+        # if all elements belong to the same type and that's not Hash:
         #
-        # Root children have as node name the one of the root singularized.
+        #   customer.projects.to_xml
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <projects type="array">
+        #     <project>
+        #       <amount type="decimal">20000.0</amount>
+        #       <customer-id type="integer">1567</customer-id>
+        #       <deal-date type="date">2008-04-09</deal-date>
+        #       ...
+        #     </project>
+        #     <project>
+        #       <amount type="decimal">57230.0</amount>
+        #       <customer-id type="integer">1567</customer-id>
+        #       <deal-date type="date">2008-04-15</deal-date>
+        #       ...
+        #     </project>
+        #   </projects>
+        #
+        # Otherwise the root element is "records":
         #
         #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
         #
@@ -92,9 +110,26 @@ module ActiveSupport #:nodoc:
         #     </record>
         #   </records>
         #
+        # If the collection is empty the root element is "nil-classes" by default:
+        #
+        #   [].to_xml
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <nil-classes type="array"/>
+        #
+        # To ensure a meaningful root element use the <tt>:root</tt> option:
+        #
+        #   customer_with_no_projects.projects.to_xml(:root => "projects")
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <projects type="array"/>
+        #
+        # By default root children have as node name the one of the root
+        # singularized. You can change it with the <tt>:children</tt> option.
+        #
         # The +options+ hash is passed downwards:
         #
-        #   [Message.find(:first)].to_xml(:skip_types => true)
+        #   Message.all.to_xml(:skip_types => true)
         #
         #   <?xml version="1.0" encoding="UTF-8"?>
         #   <messages>
diff --git a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
index eee61d48c4..186ca69c05 100644
--- a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
+++ b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
@@ -1,6 +1,12 @@
 # Extends the class object with class and instance accessors for class attributes,
 # just like the native attr* accessors for instance attributes.
-class Class # :nodoc:
+#
+#  class Person
+#    cattr_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+class Class
   def cattr_reader(*syms)
     syms.flatten.each do |sym|
       next if sym.is_a?(Hash)
diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index bb561f675f..183471706b 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -70,7 +70,7 @@ module ActiveSupport #:nodoc:
         end
         
         # Provides precise Date calculations for years, months, and days.  The +options+ parameter takes a hash with 
-        # any of these keys: :years, :months, :weeks, :days.
+        # any of these keys: <tt>:years</tt>, <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>.
         def advance(options)
           d = self
           d = d >> options.delete(:years) * 12 if options[:years]
diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
index fa444f71b1..155c961a91 100644
--- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
@@ -42,8 +42,10 @@ module ActiveSupport #:nodoc:
           )
         end
 
-        # Uses Date to provide precise Time calculations for years, months, and days.  The +options+ parameter takes a hash with
-        # any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds.
+        # Uses Date to provide precise Time calculations for years, months, and days.
+        # The +options+ parameter takes a hash with any of these keys: <tt>:years</tt>,
+        # <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>, <tt>:hours</tt>,
+        # <tt>:minutes</tt>, <tt>:seconds</tt>.
         def advance(options)
           d = to_date.advance(options)
           datetime_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day)
diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb
index 8f111e29fc..f1469aa0e3 100644
--- a/activesupport/lib/active_support/core_ext/enumerable.rb
+++ b/activesupport/lib/active_support/core_ext/enumerable.rb
@@ -8,7 +8,7 @@ module Enumerable
   # Example:
   #
   #   latest_transcripts.group_by(&:day).each do |day, transcripts| 
-  #     p "#{day} -> #{transcripts.map(&:class) * ', '}"
+  #     p "#{day} -> #{transcripts.map(&:class).join(', ')}"
   #   end
   #   "2006-03-01 -> Transcript"
   #   "2006-02-28 -> Transcript"
@@ -26,21 +26,22 @@ module Enumerable
 
   # Calculates a sum from the elements. Examples:
   #
-  #   payments.sum { |p| p.price * p.tax_rate }
-  #   payments.sum(&:price)
+  #  payments.sum { |p| p.price * p.tax_rate }
+  #  payments.sum(&:price)
   #
-  # This is instead of
+  # The latter is a shortcut for:
   #
-  #   payments.inject { |sum, p| sum + p.price }
+  #  payments.inject { |sum, p| sum + p.price }
   #
-  # Also calculates sums without the use of a block:
+  # It can also calculate the sum without the use of a block.
   #
-  #   [5, 15, 10].sum # => 30
+  #  [5, 15, 10].sum # => 30
+  #  ["foo", "bar"].sum # => "foobar"
+  #  [[1, 2], [3, 1, 5]].sum => [1, 2, 3, 1, 5]
   #
-  # The default identity (sum of an empty list) is zero. 
-  # However, you can override this default:
+  # The default sum of an empty list is zero. You can override this default:
   #
-  #   [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0)
+  #  [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0)
   #
   def sum(identity = 0, &block)
     return identity unless size > 0
diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
index 0ec0538024..7af10846e7 100644
--- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
@@ -8,7 +8,7 @@ module ActiveSupport #:nodoc:
       #     options.reverse_merge! :size => 25, :velocity => 10
       #   end
       #
-      # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set.
+      # The default <tt>:size</tt> and <tt>:velocity</tt> is only set if the +options+ passed in doesn't already have those keys set.
       module ReverseMerge
         # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
         def reverse_merge(other_hash)
diff --git a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
index 58ff363244..51e1c9af90 100644
--- a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
+++ b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
@@ -1,6 +1,16 @@
 # Extends the module object with module and instance accessors for class attributes, 
 # just like the native attr* accessors for instance attributes.
-class Module # :nodoc:
+#
+#  module AppConfiguration
+#    mattr_accessor :google_api_key
+#    self.google_api_key = "123456789"
+#
+#    mattr_accessor :paypal_url
+#    self.paypal_url = "www.sandbox.paypal.com"
+#  end
+#
+#  AppConfiguration.google_api_key = "overriding the api key!"
+class Module
   def mattr_reader(*syms)
     syms.each do |sym|
       next if sym.is_a?(Hash)
diff --git a/activesupport/lib/active_support/core_ext/module/delegation.rb b/activesupport/lib/active_support/core_ext/module/delegation.rb
index f6647eaed3..e0b5f3e379 100644
--- a/activesupport/lib/active_support/core_ext/module/delegation.rb
+++ b/activesupport/lib/active_support/core_ext/module/delegation.rb
@@ -1,8 +1,8 @@
 class Module
   # Provides a delegate class method to easily expose contained objects' methods
   # as your own. Pass one or more methods (specified as symbols or strings)
-  # and the name of the target object as the final :to option (also a symbol
-  # or string).  At least one method and the :to option are required.
+  # and the name of the target object as the final <tt>:to</tt> option (also a symbol
+  # or string).  At least one method and the <tt>:to</tt> option are required.
   #
   # Delegation is particularly useful with Active Record associations:
   #
@@ -20,6 +20,7 @@ class Module
   #   Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>
   #
   # Multiple delegates to the same target are allowed:
+  #
   #   class Foo < ActiveRecord::Base
   #     belongs_to :greeter
   #     delegate :hello, :goodbye, :to => :greeter
@@ -28,7 +29,8 @@ class Module
   #   Foo.new.goodbye # => "goodbye"
   #
   # Methods can be delegated to instance variables, class variables, or constants
-  # by providing the variable as a symbol:
+  # by providing them as a symbols:
+  #
   #   class Foo
   #     CONSTANT_ARRAY = [0,1,2,3]
   #     @@class_array  = [4,5,6,7]
diff --git a/activesupport/lib/active_support/core_ext/range/include_range.rb b/activesupport/lib/active_support/core_ext/range/include_range.rb
index cd53cf154a..9a7d235695 100644
--- a/activesupport/lib/active_support/core_ext/range/include_range.rb
+++ b/activesupport/lib/active_support/core_ext/range/include_range.rb
@@ -7,6 +7,14 @@ module ActiveSupport #:nodoc:
           base.alias_method_chain :include?, :range
         end
 
+        # Extends the default Range#include? to support range comparisons.
+        #  (1..5).include?(1..5) # => true
+        #  (1..5).include?(2..3) # => true
+        #  (1..5).include?(2..6) # => false
+        #
+        # The native Range#include? behavior is untouched.
+        #  ("a".."f").include?("c") # => true
+        #  (5..9).include?(11) # => false
         def include_with_range?(value)
           if value.is_a?(::Range)
             operator = exclude_end? ? :< : :<=
diff --git a/activesupport/lib/active_support/core_ext/range/overlaps.rb b/activesupport/lib/active_support/core_ext/range/overlaps.rb
index 80ed1bba9d..43c69453e7 100644
--- a/activesupport/lib/active_support/core_ext/range/overlaps.rb
+++ b/activesupport/lib/active_support/core_ext/range/overlaps.rb
@@ -3,6 +3,9 @@ module ActiveSupport #:nodoc:
     module Range #:nodoc:
       # Check if Ranges overlap.
       module Overlaps
+        # Compare two ranges and see if they overlap eachother
+        #  (1..5).overlaps?(4..6) # => true
+        #  (1..5).overlaps?(7..9) # => false
         def overlaps?(other)
           include?(other.first) || other.include?(first)
         end
diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb
index ffbdf37789..2cce782676 100644
--- a/activesupport/lib/active_support/core_ext/time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/time/calculations.rb
@@ -46,12 +46,12 @@ module ActiveSupport #:nodoc:
             ::DateTime.civil(year, month, day, hour, min, sec, offset)
           end
 
-          # wraps class method time_with_datetime_fallback with utc_or_local == :utc
+          # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to <tt>:utc</tt>.
           def utc_time(*args)
             time_with_datetime_fallback(:utc, *args)
           end
 
-          # wraps class method time_with_datetime_fallback with utc_or_local == :local
+          # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to <tt>:local</tt>.
           def local_time(*args)
             time_with_datetime_fallback(:local, *args)
           end
@@ -78,8 +78,10 @@ module ActiveSupport #:nodoc:
           )
         end
 
-        # Uses Date to provide precise Time calculations for years, months, and days.  The +options+ parameter takes a hash with
-        # any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds.
+        # Uses Date to provide precise Time calculations for years, months, and days.
+        # The +options+ parameter takes a hash with any of these keys: <tt>:years</tt>,
+        # <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>, <tt>:hours</tt>,
+        # <tt>:minutes</tt>, <tt>:seconds</tt>.
         def advance(options)
           d = to_date.advance(options)
           time_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day)