Improve documentation.

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

30 files changed, 177 insertions, 115 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 04dd4aadd1..96c38f0e6e 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Improve documentation. [Xavier Noria, leethal, jerome]
+
 * Ensure RJS redirect_to doesn't html-escapes string argument. Closes #8546 [josh, eventualbuddha, Pratik]
 
 * Support render :partial => collection of heterogeneous elements.  #11491 [Zach Dennis]
diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb
index 3cb8b7b93d..fa5a347db9 100644
--- a/actionpack/lib/action_controller/routing.rb
+++ b/actionpack/lib/action_controller/routing.rb
@@ -47,7 +47,7 @@ module ActionController
   #   :controller maps to your controller name
   #   :action     maps to an action with your controllers
   #
-  # Other names simply map to a parameter as in the case of +:id+.
+  # Other names simply map to a parameter as in the case of <tt>:id</tt>.
   #
   # == Route priority
   #
@@ -82,7 +82,7 @@ module ActionController
   # This sets up +blog+ as the default controller if no other is specified.
   # This means visiting '/' would invoke the blog controller.
   #
-  # More formally, you can define defaults in a route with the +:defaults+ key.
+  # More formally, you can define defaults in a route with the <tt>:defaults</tt> key.
   #
   #   map.connect ':controller/:action/:id', :action => 'show', :defaults => { :page => 'Dashboard' }
   #
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index 50feac5a0f..81938ac8e3 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -716,11 +716,11 @@ module ActionView
           #   # Insert the rendered 'navigation' partial just before the DOM
           #   # element with ID 'content'.
           #   # Generates: new Insertion.Before("content", "-- Contents of 'navigation' partial --");
-          #   insert_html :before, 'content', :partial => 'navigation'
+          #   page.insert_html :before, 'content', :partial => 'navigation'
           #
           #   # Add a list item to the bottom of the <ul> with ID 'list'.
           #   # Generates: new Insertion.Bottom("list", "<li>Last item</li>");
-          #   insert_html :bottom, 'list', '<li>Last item</li>'
+          #   page.insert_html :bottom, 'list', '<li>Last item</li>'
           #
           def insert_html(position, id, *options_for_render)
             insertion = position.to_s.camelize
@@ -735,7 +735,7 @@ module ActionView
           #   # Replace the HTML of the DOM element having ID 'person-45' with the
           #   # 'person' partial for the appropriate object.
           #   # Generates:  Element.update("person-45", "-- Contents of 'person' partial --");
-          #   replace_html 'person-45', :partial => 'person', :object => @person
+          #   page.replace_html 'person-45', :partial => 'person', :object => @person
           #
           def replace_html(id, *options_for_render)
             call 'Element.update', id, render(*options_for_render)
@@ -749,7 +749,7 @@ module ActionView
           #
           #   # Replace the DOM element having ID 'person-45' with the
           #   # 'person' partial for the appropriate object.
-          #   replace 'person-45', :partial => 'person', :object => @person
+          #   page.replace 'person-45', :partial => 'person', :object => @person
           #
           # This allows the same partial that is used for the +insert_html+ to
           # be also used for the input to +replace+ without resorting to
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 680e078404..4a951f2c88 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -86,7 +86,7 @@ module ActionView
       # of +options+. See the valid options in the documentation for
       # url_for. It's also possible to pass a string instead
       # of an options hash to get a link tag that uses the value of the string as the
-      # href for the link, or use +:back+ to link to the referrer - a JavaScript back
+      # href for the link, or use <tt>:back</tt> to link to the referrer - a JavaScript back
       # link will be used in place of a referrer if none exists. If nil is passed as
       # a name, the link itself will become the name.
       #
diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG
index 2d13ca8deb..6296d9c4f9 100644
--- a/activerecord/CHANGELOG
+++ b/activerecord/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Improve documentation. [Xavier Noria, Jack Danger Canty, leethal]
+
 * Tweak ActiveRecord::Base#to_json to include a root value in the returned hash: {"post": {"title": ...}} [rick]
 
   Post.find(1).to_json # => {"title": ...}
diff --git a/activerecord/README b/activerecord/README
index 442530184c..7204b44ec4 100755
--- a/activerecord/README
+++ b/activerecord/README
@@ -102,21 +102,14 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActiveRecord/Base.html]
 
 
-* Transaction support on both a database and object level. The latter is implemented 
-  by using Transaction::Simple[http://railsmanual.com/module/Transaction::Simple]
+* Transactions
 
-    # Just database transaction
+    # Database transaction
     Account.transaction do
       david.withdrawal(100)
       mary.deposit(100)
     end
 
-    # Database and object transaction
-    Account.transaction(david, mary) do
-      david.withdrawal(100)
-      mary.deposit(100)
-    end
-
   {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
 
 
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 62c5adff52..c5cf06cf10 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -136,7 +136,7 @@ module ActiveRecord
     #   #others.create!(attributes={})    |   X   |    X     |    X
     #   #others.size                      |   X   |    X     |    X
     #   #others.length                    |   X   |    X     |    X
-    #   #others.count                     |       |    X     |    X
+    #   #others.count                     |   X   |    X     |    X
     #   #others.sum(args*,&block)         |   X   |    X     |    X
     #   #others.empty?                    |   X   |    X     |    X
     #   #others.clear                     |   X   |    X     |
@@ -150,9 +150,9 @@ module ActiveRecord
     #
     # == Cardinality and associations
     #
-    # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many
-    # and many-to-many cardinality. Each model uses an association to describe its role in
-    # the relation. In each case, the +belongs_to+ association is used in the model that has
+    # ActiveRecord associations can be used to describe one-to-one, one-to-many and many-to-many
+    # relationships between models. Each model uses an association to describe its role in
+    # the relation. The +belongs_to+ association is always used in the model that has
     # the foreign key.
     #
     # === One-to-one
diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb
index 421ddc15ee..26274fff93 100644
--- a/activerecord/lib/active_record/associations/association_proxy.rb
+++ b/activerecord/lib/active_record/associations/association_proxy.rb
@@ -1,5 +1,50 @@
 module ActiveRecord
   module Associations
+    # This is the root class of all association proxies:
+    #
+    #   AssociationProxy
+    #     BelongsToAssociation
+    #       HasOneAssociation
+    #     BelongsToPolymorphicAssociation
+    #     AssociationCollection
+    #       HasManyAssociation
+    #       HasAndBelongsToManyAssociation
+    #     HasManyThroughAssociation
+    #       HasOneThroughAssociation
+    #
+    # Association proxies in Active Record are middlemen between the object that
+    # holds the association, known as the <tt>@owner</tt>, and the actual associated
+    # object, known as the <tt>@target</tt>. The kind of association any proxy is
+    # about is available in <tt>@reflection</tt>. That's an instance of the class
+    # ActiveRecord::Reflection::AssociationReflection.
+    #
+    # For example, given
+    #
+    #   class Blog < ActiveRecord::Base
+    #     has_many :posts
+    #   end
+    #
+    #   blog = Blog.find(:first)
+    #
+    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
+    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
+    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
+    #
+    # This class has most of the basic instance methods removed, and delegates
+    # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a
+    # corner case, it even removes the +class+ method and that's why you get
+    #
+    #   blog.posts.class # => Array
+    #
+    # though the object behind <tt>blog.posts</tt> is not an Array, but an
+    # ActiveRecord::Associations::HasManyAssociation.
+    #
+    # The <tt>@target</tt> object is not loaded until needed. For example,
+    #
+    #   blog.posts.count
+    #
+    # is computed directly through SQL and does not trigger by itself the
+    # instantiation of the actual post records.
     class AssociationProxy #:nodoc:
       alias_method :proxy_respond_to?, :respond_to?
       alias_method :proxy_extend, :extend
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index fe38454226..92417a429f 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -191,6 +191,10 @@ module ActiveRecord #:nodoc:
   #
   #   Student.find(:all, :conditions => { :grade => 9..12 })
   #
+  # An array may be used in the hash to use the SQL IN operator:
+  #
+  #   Student.find(:all, :conditions => { :grade => [9,11,12] })
+  #
   # == Overwriting default accessors
   #
   # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
@@ -488,6 +492,7 @@ module ActiveRecord #:nodoc:
       # Examples for find all:
       #   Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people
       #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
+      #   Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] }
       #   Person.find(:all, :offset => 10, :limit => 10)
       #   Person.find(:all, :include => [ :account, :friends ])
       #   Person.find(:all, :group => "category")
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index c8913d0157..393d5c130e 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -161,12 +161,12 @@ module ActiveRecord
       # an Array of Symbols.
       #
       # The index will be named after the table and the first column name,
-      # unless you pass +:name+ as an option.
+      # unless you pass <tt>:name</tt> as an option.
       #
       # When creating an index on multiple columns, the first column is used as a name
       # for the index. For example, when you specify an index on two columns
-      # [+:first+, +:last+], the DBMS creates an index for both columns as well as an
-      # index for the first column +:first+. Using just the first name for this index
+      # [<tt>:first</tt>, <tt>:last</tt>], the DBMS creates an index for both columns as well as an
+      # index for the first column <tt>:first</tt>. Using just the first name for this index
       # makes sense, because you will never have to create a singular index with this
       # name.
       #
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 07ea25a885..3f11133e8c 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -76,34 +76,39 @@ module ActiveRecord
         @macro, @name, @options, @active_record = macro, name, options, active_record
       end
 
-      # Returns the name of the macro, so it would return :balance for "composed_of :balance, :class_name => 'Money'" or
-      # :clients for "has_many :clients".
+      # Returns the name of the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return
+      # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>.
       def name
         @name
       end
 
-      # Returns the type of the macro, so it would return :composed_of for
-      # "composed_of :balance, :class_name => 'Money'" or :has_many for "has_many :clients".
+      # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt>
+      # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>.
       def macro
         @macro
       end
 
-      # Returns the hash of options used for the macro, so it would return { :class_name => "Money" } for
-      # "composed_of :balance, :class_name => 'Money'" or {} for "has_many :clients".
+      # Returns the hash of options used for the macro.  For example, it would return <tt>{ :class_name => "Money" }</tt> for
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>.
+
       def options
         @options
       end
 
-      # Returns the class for the macro, so "composed_of :balance, :class_name => 'Money'" returns the Money class and
-      # "has_many :clients" returns the Client class.
+      # Returns the class for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the +Money+
+      # class and <tt>has_many :clients</tt> returns the +Client+ class.
       def klass
         @klass ||= class_name.constantize
       end
 
+      # Returns the class name for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt>
+      # and <tt>has_many :clients</tt> returns <tt>'Client'</tt>.
       def class_name
         @class_name ||= options[:class_name] || derive_class_name
       end
 
+      # Returns +true+ if +self+ and +other_aggregation+ have the same +name+ attribute, +active_record+ attribute,
+      # and +other_aggregation+ has an options hash assigned to it.
       def ==(other_aggregation)
         name == other_aggregation.name && other_aggregation.options && active_record == other_aggregation.active_record
       end
diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb
index d1962f0c1f..13cb5f3f48 100644
--- a/activerecord/lib/active_record/transactions.rb
+++ b/activerecord/lib/active_record/transactions.rb
@@ -28,7 +28,7 @@ module ActiveRecord
     #
     # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception.
     # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though,
-    # that the objects by default will _not_ have their instance data returned to their pre-transactional state.
+    # that the objects will _not_ have their instance data returned to their pre-transactional state.
     #
     # == Different ActiveRecord classes in a single transaction
     #
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 72c48d1e2a..bd1c67cd84 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -723,7 +723,7 @@ module ActiveRecord
       #
       # Configuration options:
       # * <tt>in</tt> - An enumerable object of available items
-      # * <tt>message</tt> - Specifies a customer error message (default is: "is not included in the list")
+      # * <tt>message</tt> - Specifies a custom error message (default is: "is not included in the list")
       # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
       # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
@@ -755,7 +755,7 @@ module ActiveRecord
       #
       # Configuration options:
       # * <tt>in</tt> - An enumerable object of items that the value shouldn't be part of
-      # * <tt>message</tt> - Specifies a customer error message (default is: "is reserved")
+      # * <tt>message</tt> - Specifies a custom error message (default is: "is reserved")
       # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
       # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
diff --git a/activeresource/CHANGELOG b/activeresource/CHANGELOG
index 6048a6aafc..d1772ca735 100644
--- a/activeresource/CHANGELOG
+++ b/activeresource/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Improve documentation. [Xavier Noria]
+
 * Fixed that to_param should be used and honored instead of hardcoding the id #11406 [gspiers]
 
 * Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert]
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