Improve documentation coverage and markup

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

15 files changed, 130 insertions, 47 deletions

diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb
index 463cba6cf0..b3c9c23d9f 100644
--- a/activesupport/lib/active_support/cache.rb
+++ b/activesupport/lib/active_support/cache.rb
@@ -49,7 +49,7 @@ module ActiveSupport
         self
       end
 
-      # Pass :force => true to force a cache miss.
+      # Pass <tt>:force => true</tt> to force a cache miss.
       def fetch(key, options = {})
         @logger_off = true
         if !options[:force] && value = read(key, options)
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)
diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb
index 9f724619e9..c8736549f4 100644
--- a/activesupport/lib/active_support/inflector.rb
+++ b/activesupport/lib/active_support/inflector.rb
@@ -68,8 +68,9 @@ module Inflector
       (@uncountables << words).flatten!
     end
 
-    # Clears the loaded inflections within a given scope (default is :all). Give the scope as a symbol of the inflection type,
-    # the options are: :plurals, :singulars, :uncountables
+    # Clears the loaded inflections within a given scope (default is <tt>:all</tt>).
+    # Give the scope as a symbol of the inflection type, the options are: <tt>:plurals</tt>,
+    # <tt>:singulars</tt>, <tt>:uncountables</tt>.
     #
     # Examples:
     #   clear :all
@@ -245,13 +246,23 @@ module Inflector
     underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id")
   end
 
-  # Constantize tries to find a declared constant with the name specified
-  # in the string. It raises a NameError when the name is not in CamelCase
-  # or is not initialized.
+  # Tries to find a constant with the name specified in the argument string:
   #
-  # Examples
-  #   "Module".constantize #=> Module
-  #   "Class".constantize #=> Class
+  #   "Module".constantize     # => Module
+  #   "Test::Unit".constantize # => Test::Unit
+  #
+  # The name is assumed to be the one of a top-level constant, no matter whether
+  # it starts with "::" or not. No lexical context is taken into account:
+  #
+  #   C = 'outside'
+  #   module M
+  #     C = 'inside'
+  #     C               # => 'inside'
+  #     "C".constantize # => 'outside', same as ::C
+  #   end
+  #
+  # NameError is raised when the name is not in CamelCase or the constant is
+  # unknown.
   def constantize(camel_cased_word)
     unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ camel_cased_word
       raise NameError, "#{camel_cased_word.inspect} is not a valid constant name!"
diff --git a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
index 66fe47a604..0166b69ac3 100644
--- a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
+++ b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
@@ -284,7 +284,9 @@ module ActiveSupport::Multibyte::Handlers #:nodoc:
       # passing strings to databases and validations.
       #
       # * <tt>str</tt> - The string to perform normalization on.
-      # * <tt>form</tt> - The form you want to normalize in. Should be one of the following: :c, :kc, :d or :kd.
+      # * <tt>form</tt> - The form you want to normalize in. Should be one of the following:
+      #   <tt>:c</tt>, <tt>:kc</tt>, <tt>:d</tt>, or <tt>:kd</tt>. Default is
+      #   ActiveSupport::Multibyte::DEFAULT_NORMALIZATION_FORM.
       def normalize(str, form=ActiveSupport::Multibyte::DEFAULT_NORMALIZATION_FORM)
         # See http://www.unicode.org/reports/tr15, Table 1
         codepoints = u_unpack(str)
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index f1a2498298..461d52e40e 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -101,7 +101,8 @@ module ActiveSupport
     end
     alias_method :rfc822, :rfc2822
   
-    # :db format outputs time in UTC; all others output time in local. Uses TimeWithZone's strftime, so %Z and %z work correctly
+    # <tt>:db</tt> format outputs time in UTC; all others output time in local.
+    # Uses TimeWithZone's +strftime+, so <tt>%Z</tt> and <tt>%z</tt> work correctly.
     def to_s(format = :default) 
       return utc.to_s(format) if format == :db
       if formatter = ::Time::DATE_FORMATS[format]
@@ -111,7 +112,7 @@ module ActiveSupport
       end
     end
     
-    # Replaces %Z and %z directives with #zone and #formatted_offset, respectively, before passing to 
+    # Replaces <tt>%Z</tt> and <tt>%z</tt> directives with +zone+ and +formatted_offset+, respectively, before passing to
     # Time#strftime, so that zone information is correct
     def strftime(format)
       format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false))
@@ -138,9 +139,9 @@ module ActiveSupport
       result.in_time_zone(time_zone)
     end
     
-    # If a time-like object is passed in, compare it with #utc
-    # Else if wrapped #time is a DateTime, use DateTime#ago instead of #-
-    # Otherwise, just pass on to method missing
+    # If a time-like object is passed in, compare it with +utc+.
+    # Else if wrapped +time+ is a DateTime, use DateTime#ago instead of DateTime#-.
+    # Otherwise, just pass on to +method_missing+.
     def -(other)
       if other.acts_like?(:time)
         utc - other
@@ -180,7 +181,7 @@ module ActiveSupport
     alias_method :hash, :to_i
     alias_method :tv_sec, :to_i
   
-    # A TimeWithZone acts like a Time, so just return self
+    # A TimeWithZone acts like a Time, so just return +self+.
     def to_time
       self
     end