Improve documentation.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9226 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

16 files changed, 89 insertions, 81 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index fce319d3c6..21a8584bb9 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -3,9 +3,8 @@ module ActiveSupport #:nodoc:
     module Array #:nodoc:
       # Makes it easier to access parts of an array.
       module Access
-        # Returns the remaining of the array from the +position+.
+        # Returns the tail of the array from +position+.
         #
-        # Examples: 
         #   %w( a b c d ).from(0)  # => %w( a b c d )
         #   %w( a b c d ).from(2)  # => %w( c d )
         #   %w( a b c d ).from(10) # => nil
@@ -13,9 +12,8 @@ module ActiveSupport #:nodoc:
           self[position..-1]
         end
         
-        # Returns the beginning of the array up to the +position+.
+        # Returns the beginning of the array up to +position+.
         #
-        # Examples: 
         #   %w( a b c d ).to(0)  # => %w( a )
         #   %w( a b c d ).to(2)  # => %w( a b c )
         #   %w( a b c d ).to(10) # => %w( a b c d )
diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index e46d7c1884..34b1551abc 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -30,10 +30,8 @@ module ActiveSupport #:nodoc:
           map(&:to_param).join '/'
         end
 
-        # Converts an array into a string suitable for use as a URL query string, using the given <tt>key</tt> as the
-        # param name.
-        #
-        # Example:
+        # Converts an array into a string suitable for use as a URL query string,
+        # using the given +key+ as the param name.
         #
         #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
         def to_query(key)
@@ -81,8 +79,6 @@ module ActiveSupport #:nodoc:
         #
         # Root children have as node name the one of the root singularized.
         #
-        # Example:
-        #
         #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
         #
         #   <?xml version="1.0" encoding="UTF-8"?>
diff --git a/activesupport/lib/active_support/core_ext/array/extract_options.rb b/activesupport/lib/active_support/core_ext/array/extract_options.rb
index 980d36400b..eb917576d7 100644
--- a/activesupport/lib/active_support/core_ext/array/extract_options.rb
+++ b/activesupport/lib/active_support/core_ext/array/extract_options.rb
@@ -2,7 +2,8 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module ExtractOptions
-        # Extract options from a set of arguments. Removes and returns the last element in the array if it's a hash, otherwise returns a blank hash.
+        # Extracts options from a set of arguments. Removes and returns the last
+        # element in the array if it's a hash, otherwise returns a blank hash.
         #
         #   def options(*args)
         #     args.extract_options!
diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb
index ed5ec72daf..767acc4e07 100644
--- a/activesupport/lib/active_support/core_ext/array/grouping.rb
+++ b/activesupport/lib/active_support/core_ext/array/grouping.rb
@@ -4,11 +4,8 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module Grouping
-        # Iterate over an array in groups of a certain size, padding any remaining 
-        # slots with specified value (<tt>nil</tt> by default) unless it is
-        # <tt>false</tt>.
-        # 
-        # Examples:
+        # Iterates over the array in groups of size +number+, padding any remaining 
+        # slots with +fill_with+ unless it is +false+.
         # 
         #   %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g}
         #   ["1", "2", "3"]
@@ -42,11 +39,9 @@ module ActiveSupport #:nodoc:
           end
         end
 
-        # Divide the array into one or more subarrays based on a delimiting +value+
+        # Divides the array into one or more subarrays based on a delimiting +value+
         # or the result of an optional block.
         #
-        # Examples:
-        #
         #   [1, 2, 3, 4, 5].split(3)                # => [[1, 2], [4, 5]]
         #   (1..10).to_a.split { |i| i % 3 == 0 }   # => [[1, 2], [4, 5], [7, 8], [10]]
         def split(value = nil, &block)
diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb
index b7ee00742a..54d17cbf30 100644
--- a/activesupport/lib/active_support/core_ext/array/random_access.rb
+++ b/activesupport/lib/active_support/core_ext/array/random_access.rb
@@ -2,7 +2,7 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module RandomAccess
-        # Return a random element from the array.
+        # Returns a random element from the array.
         def rand
           self[Kernel.rand(length)]
         end
diff --git a/activesupport/lib/active_support/core_ext/blank.rb b/activesupport/lib/active_support/core_ext/blank.rb
index f4def18ae9..dfe33162e8 100644
--- a/activesupport/lib/active_support/core_ext/blank.rb
+++ b/activesupport/lib/active_support/core_ext/blank.rb
@@ -1,10 +1,13 @@
 class Object
   # An object is blank if it's false, empty, or a whitespace string.
-  # For example, "", "   ", nil, [], and {} are blank.
+  # For example, "", "   ", +nil+, [], and {} are blank.
   #
   # This simplifies
+  #
   #   if !address.nil? && !address.empty?
+  #
   # to
+  #
   #   if !address.blank?
   def blank?
     respond_to?(:empty?) ? empty? : !self
diff --git a/activesupport/lib/active_support/core_ext/class/removal.rb b/activesupport/lib/active_support/core_ext/class/removal.rb
index f768313abe..10660edb2c 100644
--- a/activesupport/lib/active_support/core_ext/class/removal.rb
+++ b/activesupport/lib/active_support/core_ext/class/removal.rb
@@ -1,21 +1,38 @@
 class Class #:nodoc:
   
-  # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves.
-  # >> Integer.remove_subclasses
-  # => [Bignum, Fixnum]
-  # >> Fixnum
-  # NameError: uninitialized constant Fixnum
+  # Unassociates the class with its subclasses and removes the subclasses
+  # themselves.
+  #
+  #   Integer.remove_subclasses # => [Bignum, Fixnum]
+  #   Fixnum                    # => NameError: uninitialized constant Fixnum
   def remove_subclasses
     Object.remove_subclasses_of(self)
   end
 
-  # Returns a list of classes that inherit from this class in an array.
-  # Example: Integer.subclasses => ["Bignum", "Fixnum"]
+  # Returns an array with the names of the subclasses of +self+ as strings.
+  #
+  #   Integer.subclasses # => ["Bignum", "Fixnum"]
   def subclasses
     Object.subclasses_of(self).map { |o| o.to_s }
   end
 
-  # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them.
+  # Removes the classes in +klasses+ from their parent module.
+  #
+  # Ordinary classes belong to some module via a constant. This method computes
+  # that constant name from the class name and removes it from the module it
+  # belongs to.
+  #
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #
+  # Take into account that in general the class object could be still stored
+  # somewhere else.
+  #
+  #   i = Integer                  # => Integer
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #   i.subclasses                 # => ["Bignum", "Fixnum"]
+  #   Fixnum.superclass            # => Integer
   def remove_class(*klasses)
     klasses.flatten.each do |klass|
       # Skip this class if there is nothing bound to this name
diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index d1a30c3f73..bb561f675f 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -16,12 +16,12 @@ module ActiveSupport #:nodoc:
         end
 
         module ClassMethods
-          # Finds yesterday's date, in the format similar to: Mon, 17 Mar 2008
+          # Returns a new Date representing the date 1 day ago (i.e. yesterday's date).
           def yesterday
             ::Date.today.yesterday
           end
           
-          # Finds tommorrow's date, in the format similar to: Tue, 18 Mar 2008
+          # Returns a new Date representing the date 1 day after today (i.e. tomorrow's date).
           def tomorrow
             ::Date.today.tomorrow
           end
diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
index c86a527045..aa9caf1774 100644
--- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
@@ -45,7 +45,7 @@ module ActiveSupport #:nodoc:
           formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
         end
 
-        # Returns the utc_offset as an +HH:MM formatted string. Examples:
+        # Returns the +utc_offset+ as an +HH:MM formatted string. Examples:
         #
         #   datetime = DateTime.civil(2000, 1, 1, 0, 0, 0, Rational(-6, 24))
         #   datetime.formatted_offset         # => "-06:00"
diff --git a/activesupport/lib/active_support/core_ext/integer/even_odd.rb b/activesupport/lib/active_support/core_ext/integer/even_odd.rb
index b53bcd066c..cfc6b4c6d6 100644
--- a/activesupport/lib/active_support/core_ext/integer/even_odd.rb
+++ b/activesupport/lib/active_support/core_ext/integer/even_odd.rb
@@ -3,12 +3,10 @@ module ActiveSupport #:nodoc:
     module Integer #:nodoc:
       # For checking if a fixnum is even or odd.
       #
-      # Examples:
-      #
       #   1.even? # => false
       #   1.odd?  # => true
       #   2.even? # => true
-      #   2.odd? # => false
+      #   2.odd?  # => false
       module EvenOdd
         def multiple_of?(number)
           self % number == 0
diff --git a/activesupport/lib/active_support/core_ext/integer/inflections.rb b/activesupport/lib/active_support/core_ext/integer/inflections.rb
index 252b2c5593..804702beb2 100644
--- a/activesupport/lib/active_support/core_ext/integer/inflections.rb
+++ b/activesupport/lib/active_support/core_ext/integer/inflections.rb
@@ -7,8 +7,6 @@ module ActiveSupport #:nodoc:
         # Ordinalize turns a number into an ordinal string used to denote the
         # position in an ordered sequence such as 1st, 2nd, 3rd, 4th.
         #
-        # Examples:
-        #
         #   1.ordinalize    # => "1st"
         #   2.ordinalize    # => "2nd"
         #   1002.ordinalize # => "1002nd"
diff --git a/activesupport/lib/active_support/core_ext/object/instance_variables.rb b/activesupport/lib/active_support/core_ext/object/instance_variables.rb
index f091acb969..ee1010b250 100644
--- a/activesupport/lib/active_support/core_ext/object/instance_variables.rb
+++ b/activesupport/lib/active_support/core_ext/object/instance_variables.rb
@@ -37,7 +37,7 @@ class Object
     instance_variables.map(&:to_s)
   end
 
-  # Copies the instance variables of +object+ into self.
+  # Copies the instance variables of +object+ into +self+.
   #
   # Instance variable names in the +exclude+ array are ignored. If +object+
   # responds to <tt>protected_instance_variables</tt> the ones returned are
diff --git a/activesupport/lib/active_support/core_ext/string/unicode.rb b/activesupport/lib/active_support/core_ext/string/unicode.rb
index 0e00b32194..0e9770af25 100644
--- a/activesupport/lib/active_support/core_ext/string/unicode.rb
+++ b/activesupport/lib/active_support/core_ext/string/unicode.rb
@@ -10,11 +10,11 @@ module ActiveSupport #:nodoc:
           # string overrides can also be called through the +chars+ proxy.
           #
           #   name = 'Claus Müller'
-          #   name.reverse #=> "rell??M sualC"
-          #   name.length #=> 13
+          #   name.reverse  #=> "rell??M sualC"
+          #   name.length   #=> 13
           #
-          #   name.chars.reverse.to_s #=> "rellüM sualC"
-          #   name.chars.length #=> 12
+          #   name.chars.reverse.to_s   #=> "rellüM sualC"
+          #   name.chars.length         #=> 12
           #   
           #
           # All the methods on the chars proxy which normally return a string will return a Chars object. This allows
diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb
index ab7b009663..edca5b8a98 100644
--- a/activesupport/lib/active_support/core_ext/time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/time/conversions.rb
@@ -20,11 +20,10 @@ module ActiveSupport #:nodoc:
           end
         end
 
-        # Convert to a formatted string. See DATE_FORMATS for builtin formats.
+        # Converts to a formatted string. See DATE_FORMATS for builtin formats.
         #
         # This method is aliased to <tt>to_s</tt>.
         #
-        # ==== Examples:
         #   time = Time.now                     # => Thu Jan 18 06:10:17 CST 2007
         #
         #   time.to_formatted_s(:time)          # => "06:10:17"
@@ -36,7 +35,7 @@ module ActiveSupport #:nodoc:
         #   time.to_formatted_s(:long_ordinal)  # => "January 18th, 2007 06:10"
         #   time.to_formatted_s(:rfc822)        # => "Thu, 18 Jan 2007 06:10:17 -0600"
         #
-        # == Adding your own time formats to to_formatted_s
+        # == Adding your own time formats to +to_formatted_s+
         # You can add your own formats to the Time::DATE_FORMATS hash.
         # Use the format name as the hash key and either a strftime string
         # or Proc instance that takes a time argument as the value.
@@ -49,7 +48,7 @@ module ActiveSupport #:nodoc:
           formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
         end
         
-        # Returns the utc_offset as an +HH:MM formatted string. Examples:
+        # Returns the UTC offset as an +HH:MM formatted string.
         #
         #   Time.local(2000).formatted_offset         # => "-06:00"
         #   Time.local(2000).formatted_offset(false)  # => "-0600"
@@ -57,20 +56,13 @@ module ActiveSupport #:nodoc:
           utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
         end
 
-        # Convert a Time object to a Date, dropping hour, minute, and second precision.
+        # Converts a Time object to a Date, dropping hour, minute, and second precision.
         #
-        # ==== Examples
-        #   my_time = Time.now
-        #   # => Mon Nov 12 22:59:51 -0500 2007
+        #   my_time = Time.now  # => Mon Nov 12 22:59:51 -0500 2007
+        #   my_time.to_date     #=> Mon, 12 Nov 2007
         #
-        #   my_time.to_date
-        #   #=> Mon, 12 Nov 2007
-        #
-        #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")
-        #   # => Tue Jan 13 13:13:03 -0500 2009
-        #
-        #   your_time.to_date
-        #   # => Tue, 13 Jan 2009
+        #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
+        #   your_time.to_date                                 # => Tue, 13 Jan 2009
         def to_date
           ::Date.new(year, month, day)
         end
@@ -83,18 +75,11 @@ module ActiveSupport #:nodoc:
 
         # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset.
         #
-        # ==== Examples
-        #   my_time = Time.now
-        #   # => Mon Nov 12 23:04:21 -0500 2007
-        #
-        #   my_time.to_datetime
-        #   # => Mon, 12 Nov 2007 23:04:21 -0500
-        #
-        #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")
-        #   # => Tue Jan 13 13:13:03 -0500 2009
+        #   my_time = Time.now    # => Mon Nov 12 23:04:21 -0500 2007
+        #   my_time.to_datetime   # => Mon, 12 Nov 2007 23:04:21 -0500
         #
-        #   your_time.to_datetime
-        #   # => Tue, 13 Jan 2009 13:13:03 -0500
+        #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
+        #   your_time.to_datetime                             # => Tue, 13 Jan 2009 13:13:03 -0500
         def to_datetime
           ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400))
         end
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index 3096427904..d2b95698e5 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -17,10 +17,9 @@ module ActiveSupport #:nodoc:
 
           # Sets a global default time zone, separate from the system time zone in ENV['TZ']. 
           # Accepts either a Rails TimeZone object, a string that identifies a 
-          # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object
+          # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object.
           #
-          # Any Time or DateTime object can use this default time zone, via #in_time_zone.
-          # Example:
+          # Any Time or DateTime object can use this default time zone, via <tt>in_time_zone</tt>.
           #
           #   Time.zone = 'Hawaii'          # => 'Hawaii'
           #   Time.utc(2000).in_time_zone   # => Fri, 31 Dec 1999 14:00:00 HST -10:00
diff --git a/activesupport/lib/active_support/whiny_nil.rb b/activesupport/lib/active_support/whiny_nil.rb
index 983a14fd42..099619191c 100644
--- a/activesupport/lib/active_support/whiny_nil.rb
+++ b/activesupport/lib/active_support/whiny_nil.rb
@@ -1,11 +1,29 @@
-# Extensions to nil which allow for more helpful error messages for
-# people who are new to rails.
+# Extensions to +nil+ which allow for more helpful error messages for people who
+# are new to Rails.
 #
-# The aim is to ensure that when users pass nil to methods where that isn't
-# appropriate, instead of NoMethodError and the name of some method used
-# by the framework users will see a message explaining what type of object
-# was expected.
-
+# Ruby raises NoMethodError if you invoke a method on an object that does not
+# respond to it:
+#
+#   $ ruby -e nil.destroy
+#   -e:1: undefined method `destroy' for nil:NilClass (NoMethodError)
+#
+# With these extensions, if the method belongs to the public interface of the
+# classes in NilClass::WHINERS the error message suggests which could be the
+# actual intended class:
+#
+#   $ script/runner nil.destroy 
+#   ...
+#   You might have expected an instance of ActiveRecord::Base.
+#   ...
+#
+# NilClass#id exists in Ruby 1.8 (though it is deprecated). Since +id+ is a fundamental
+# method of Active Record models NilClass#id is redefined as well to raise a RuntimeError
+# and warn the user. She probably wanted a model database identifier and the 4
+# returned by the original method could result in obscure bugs.
+#
+# The flag <tt>config.whiny_nils</tt> determines whether this feature is enabled.
+# By default it is on in development and test modes, and it is off in production
+# mode.
 class NilClass
   WHINERS = [::Array]
   WHINERS << ::ActiveRecord::Base if defined? ::ActiveRecord
@@ -18,7 +36,7 @@ class NilClass
     methods.each { |method| @@method_class_map[method.to_sym] = class_name }
   end
 
-  # Raises a RuntimeError when you attempt to call id on nil or a nil object.
+  # Raises a RuntimeError when you attempt to call +id+ on +nil+.
   def id
     raise RuntimeError, "Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id", caller
   end
@@ -28,7 +46,7 @@ class NilClass
       raise_nil_warning_for @@method_class_map[method], method, caller
     end
 
-    # Raises a NoMethodError when you attempt to call a method on nil, or a nil object.
+    # Raises a NoMethodError when you attempt to call a method on +nil+.
     def raise_nil_warning_for(class_name = nil, selector = nil, with_caller = nil)
       message = "You have a nil object when you didn't expect it!"
       message << "\nYou might have expected an instance of #{class_name}." if class_name