Fix docs (closes #2491)

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

11 files changed, 56 insertions, 55 deletions

diff --git a/activerecord/lib/active_record/acts/list.rb b/activerecord/lib/active_record/acts/list.rb
index 425ac3856d..551c41fb6a 100644
--- a/activerecord/lib/active_record/acts/list.rb
+++ b/activerecord/lib/active_record/acts/list.rb
@@ -6,7 +6,7 @@ module ActiveRecord
         base.extend(ClassMethods)
       end
       
-      # This act provides the capabilities for sorting and reordering a number of objects in list.
+      # This act provides the capabilities for sorting and reordering a number of objects in a list.
       # The class that has this specified needs to have a "position" column defined as an integer on
       # the mapped database table.
       #
diff --git a/activerecord/lib/active_record/acts/nested_set.rb b/activerecord/lib/active_record/acts/nested_set.rb
index cc120cad4b..8b02b358a9 100644
--- a/activerecord/lib/active_record/acts/nested_set.rb
+++ b/activerecord/lib/active_record/acts/nested_set.rb
@@ -7,17 +7,17 @@ module ActiveRecord
       end  
 
       # This acts provides Nested Set functionality.  Nested Set is similiar to Tree, but with
-      # the added feature that you can select the children and all of it's descendants with
+      # the added feature that you can select the children and all of their descendents with
       # a single query.  A good use case for this is a threaded post system, where you want
       # to display every reply to a comment without multiple selects.
       #
       # A google search for "Nested Set" should point you in the direction to explain the
-      # data base theory.  I figured a bunch of this from
+      # database theory.  I figured out a bunch of this from
       # http://threebit.net/tutorials/nestedset/tutorial1.html
       #
-      # Instead of picturing a leaf node structure with child pointing back to their parent,
+      # Instead of picturing a leaf node structure with children pointing back to their parent,
       # the best way to imagine how this works is to think of the parent entity surrounding all
-      # of it's children, and it's parent surrounding it, etc.  Assuming that they are lined up
+      # of its children, and its parent surrounding it, etc.  Assuming that they are lined up
       # horizontally, we store the left and right boundries in the database.
       #
       # Imagine:
@@ -42,7 +42,7 @@ module ActiveRecord
       #    |   |___________________________|   |___________________________|   |
       #    |___________________________________________________________________| 
       #
-      # The numbers represent the left and right boundries.  The table them might
+      # The numbers represent the left and right boundries.  The table then might
       # look like this:
       #    ID | PARENT | LEFT | RIGHT | DATA
       #     1 |      0 |    1 |    14 | root
@@ -63,10 +63,10 @@ module ActiveRecord
       # There are instance methods for all of these.
       #
       # The structure is good if you need to group things together; the downside is that
-      # keeping data integrity is a pain, and both adding and removing and entry
+      # keeping data integrity is a pain, and both adding and removing an entry
       # require a full table write.        
       #
-      # This sets up a before_destroy trigger to prune the tree correctly if one of it's
+      # This sets up a before_destroy trigger to prune the tree correctly if one of its
       # elements gets deleted.
       #
       module ClassMethods                      
@@ -134,10 +134,10 @@ module ActiveRecord
         end
 
                      
-        # Added a child to this object in the tree.  If this object hasn't been initialized,
+        # Adds a child to this object in the tree.  If this object hasn't been initialized,
         # it gets set up as a root node.  Otherwise, this method will update all of the
-        # other elements in the tree and shift them to the right. Keeping everything
-        # balanaced. 
+        # other elements in the tree and shift them to the right, keeping everything
+        # balanced. 
         def add_child( child )     
           self.reload
           child.reload
@@ -179,17 +179,17 @@ module ActiveRecord
           return (self[right_col_name] - self[left_col_name] - 1)/2
         end
                                                                
-        # Returns a set of itself and all of it's nested children
+        # Returns a set of itself and all of its nested children
         def full_set
           self.class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} BETWEEN #{self[left_col_name]} and #{self[right_col_name]})" )
         end
                   
-        # Returns a set of all of it's children and nested children
+        # Returns a set of all of its children and nested children
         def all_children
           self.class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} > #{self[left_col_name]}) and (#{right_col_name} < #{self[right_col_name]})" )
         end
                                   
-        # Returns a set of only this entries immediate children
+        # Returns a set of only this entry's immediate children
         def direct_children
           self.class.find(:all, :conditions => "#{scope_condition} and #{parent_column} = #{self.id}")
         end
diff --git a/activerecord/lib/active_record/acts/tree.rb b/activerecord/lib/active_record/acts/tree.rb
index 9cf5c3f732..1c7646b74c 100644
--- a/activerecord/lib/active_record/acts/tree.rb
+++ b/activerecord/lib/active_record/acts/tree.rb
@@ -6,8 +6,8 @@ module ActiveRecord
         base.extend(ClassMethods)              
       end  
 
-      # Specify this act if you want to model a tree structure by providing a parent association and an children 
-      # association. This act assumes that requires that you have a foreign key column, which by default is called parent_id.
+      # Specify this act if you want to model a tree structure by providing a parent association and a children 
+      # association. This act requires that you have a foreign key column, which by default is called parent_id.
       # 
       #   class Category < ActiveRecord::Base
       #     acts_as_tree :order => "name"
@@ -30,13 +30,14 @@ module ActiveRecord
       #
       # In addition to the parent and children associations, the following instance methods are added to the class 
       # after specifying the act:
-      # * siblings: Return all the children of the parent excluding the current node ([ subchild2 ] when called from subchild1)
-      # * ancestors: Returns all the ancestors of the current node ([child1, root] when called from subchild2)
-      # * root: Returns the root of the current node (root when called from subchild2)
+      # * siblings          : Returns all the children of the parent, excluding the current node ([ subchild2 ] when called from subchild1)
+      # * self_and_siblings : Returns all the children of the parent, including the current node ([ subchild1, subchild2 ] when called from subchild1)
+      # * ancestors         : Returns all the ancestors of the current node ([child1, root] when called from subchild2)
+      # * root              : Returns the root of the current node (root when called from subchild2)
       module ClassMethods
         # Configuration options are:
         #
-        # * <tt>foreign_key</tt> - specifies the column name to use for track of the tree (default: parent_id)
+        # * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: parent_id)
         # * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
         # * <tt>counter_cache</tt> - keeps a count in a children_count column if set to true (default: false).
         def acts_as_tree(options = {})
diff --git a/activerecord/lib/active_record/aggregations.rb b/activerecord/lib/active_record/aggregations.rb
index 29cf5c3925..6824df9b37 100644
--- a/activerecord/lib/active_record/aggregations.rb
+++ b/activerecord/lib/active_record/aggregations.rb
@@ -7,8 +7,8 @@ module ActiveRecord
 
     # Active Record implements aggregation through a macro-like class method called +composed_of+ for representing attributes 
     # as value objects. It expresses relationships like "Account [is] composed of Money [among other things]" or "Person [is]
-    # composed of [an] address". Each call to the macro adds a description on how the value objects are created from the 
-    # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing) 
+    # composed of [an] address". Each call to the macro adds a description of how the value objects are created from the 
+    # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing object) 
     # and how it can be turned back into attributes (when the entity is saved to the database). Example:
     #
     #   class Customer < ActiveRecord::Base
@@ -88,8 +88,8 @@ module ActiveRecord
     # == Writing value objects
     #
     # Value objects are immutable and interchangeable objects that represent a given value, such as a Money object representing
-    # $5. Two Money objects both representing $5 should be equal (through methods such == and <=> from Comparable if ranking makes
-    # sense). This is unlike a entity objects where equality is determined by identity. An entity class such as Customer can
+    # $5. Two Money objects both representing $5 should be equal (through methods such as == and <=> from Comparable if ranking
+    # makes sense). This is unlike entity objects where equality is determined by identity. An entity class such as Customer can
     # easily have two different objects that both have an address on Hyancintvej. Entity identity is determined by object or
     # relational unique identifiers (such as primary keys). Normal ActiveRecord::Base classes are entity objects.
     #
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 87080bf0da..dd0b71b65f 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -22,7 +22,7 @@ module ActiveRecord
     
     # Associations are a set of macro-like class methods for tying objects together through foreign keys. They express relationships like 
     # "Project has one Project Manager" or "Project belongs to a Portfolio". Each macro adds a number of methods to the class which are 
-    # specialized according to the collection or association symbol and the options hash. It works much the same was as Ruby's own attr* 
+    # specialized according to the collection or association symbol and the options hash. It works much the same way as Ruby's own attr* 
     # methods. Example:
     #
     #   class Project < ActiveRecord::Base
@@ -80,7 +80,7 @@ module ActiveRecord
     #
     # === One-to-one associations
     #
-    # * Assigning an object to a has_one association automatically saves that object, and the object being replaced (if there is one), in
+    # * Assigning an object to a has_one association automatically saves that object and the object being replaced (if there is one), in
     #   order to update their primary keys - except if the parent object is unsaved (new_record? == true).
     # * If either of these saves fail (due to one of the objects being invalid) the assignment statement returns false and the assignment
     #   is cancelled.
@@ -164,8 +164,8 @@ module ActiveRecord
     #
     # That'll add another join along the lines of: LEFT OUTER JOIN comments ON comments.post_id = posts.id. And we'll be down to 1 query.
     # But that shouldn't fool you to think that you can pull out huge amounts of data with no performance penalty just because you've reduced
-    # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So its no
-    # catch-all for performance problems, but its a great way to cut down on the number of queries in a situation as the one described above.
+    # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So it's no
+    # catch-all for performance problems, but it's a great way to cut down on the number of queries in a situation as the one described above.
     #
     # Please note that limited eager loading with has_many and has_and_belongs_to_many associations is not compatible with describing conditions
     # on these eager tables. This will work:
@@ -240,10 +240,10 @@ module ActiveRecord
       # * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
       # * <tt>collection.build(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key but has not yet been saved. *Note:* This only works if an 
-      #   associated object already exists, not if its nil!
+      #   associated object already exists, not if it's nil!
       # * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation).
-      #   *Note:* This only works if an associated object already exists, not if its nil!
+      #   *Note:* This only works if an associated object already exists, not if it's nil!
       #
       # Example: A Firm class declares <tt>has_many :clients</tt>, which will add:
       # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>)
@@ -271,7 +271,7 @@ module ActiveRecord
       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_many association will use "person_id"
       #   as the default foreign_key.
       # * <tt>:dependent</tt>   - if set to :destroy (or true) all the associated objects are destroyed
-      #   alongside this object. Also accepts :nullify which will set the associated objects foriegn key
+      #   alongside this object. Also accepts :nullify which will set the associated object's foreign key
       #   field to NULL.
       #   May not be set if :exclusively_dependent is also set.
       # * <tt>:exclusively_dependent</tt>   - if set to true all the associated object are deleted in one SQL statement without having their
@@ -279,7 +279,7 @@ module ActiveRecord
       #   clean-up in before_destroy. The upside is that it's much faster, especially if there's a counter_cache involved.
       #   May not be set if :dependent is also set.
       # * <tt>:finder_sql</tt>  - specify a complete SQL statement to fetch the association. This is a good way to go for complex
-      #   associations that depends on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added.
+      #   associations that depend on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added.
       # * <tt>:counter_sql</tt>  - specify a complete SQL statement to fetch the size of the association. If +:finder_sql+ is
       #   specified but +:counter_sql+, +:counter_sql+ will be generated by replacing SELECT ... FROM with SELECT COUNT(*) FROM.
       #
@@ -369,7 +369,7 @@ module ActiveRecord
       #   sql fragment, such as "rank = 5".
       # * <tt>:order</tt>       - specify the order from which the associated object will be picked at the top. Specified as
       #    an "ORDER BY" sql fragment, such as "last_name, first_name DESC"
-      # * <tt>:dependent</tt>   - if set to :destroy (or true) all the associated object is destroyed when this object is. Also
+      # * <tt>:dependent</tt>   - if set to :destroy (or true) all the associated objects are destroyed when this object is. Also,
       #   association is assigned.
       # * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name
       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_one association will use "person_id"
@@ -558,8 +558,8 @@ module ActiveRecord
       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_and_belongs_to_many association
       #   will use "person_id" as the default foreign_key.
       # * <tt>:association_foreign_key</tt> - specify the association foreign key used for the association. By default this is
-      #   guessed to be the name of the associated class in lower-case and "_id" suffixed. So the associated class is +Project+
-      #   that makes a has_and_belongs_to_many association will use "project_id" as the default association foreign_key.
+      #   guessed to be the name of the associated class in lower-case and "_id" suffixed. So if the associated class is +Project+,
+      #   the has_and_belongs_to_many association will use "project_id" as the default association foreign_key.
       # * <tt>:conditions</tt>  - specify the conditions that the associated object must meet in order to be included as a "WHERE"
       #   sql fragment, such as "authorized = 1".
       # * <tt>:order</tt> - specify the order in which the associated objects are returned as a "ORDER BY" sql fragment, such as "last_name, first_name DESC"
diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb
index fb428c3f31..aa3aa2d1a5 100755
--- a/activerecord/lib/active_record/callbacks.rb
+++ b/activerecord/lib/active_record/callbacks.rb
@@ -86,7 +86,7 @@ module ActiveRecord
   #
   # There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
   # inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects are the
-  # recommended approaches, inline methods using a proc is some times appropriate (such as for creating mix-ins), and inline
+  # recommended approaches, inline methods using a proc are sometimes appropriate (such as for creating mix-ins), and inline
   # eval methods are deprecated.
   #
   # The method reference callbacks work by specifying a protected or private method available in the object, like this:
@@ -153,7 +153,7 @@ module ActiveRecord
   #
   # == The after_find and after_initialize exceptions
   #
-  # Because after_find and after_initialize is called for each object instantiated found by a finder, such as Base.find(:all), we've had
+  # Because after_find and after_initialize are called for each object found and instantiated by a finder, such as Base.find(:all), we've had
   # to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_find and
   # after_initialize will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the
   # callback types will be called.
@@ -263,10 +263,10 @@ module ActiveRecord
       result
     end
 
-    # Is called _before_ Base.save on existing objects that has a record.
+    # Is called _before_ Base.save on existing objects that have a record.
     def before_update() end
 
-    # Is called _after_ Base.save on existing objects that has a record.
+    # Is called _after_ Base.save on existing objects that have a record.
     def after_update() end
 
     def update_with_callbacks #:nodoc:
@@ -291,11 +291,11 @@ module ActiveRecord
     def after_validation_on_create()  end
 
     # Is called _before_ Validations.validate (which is part of the Base.save call) on
-    # existing objects that has a record.
+    # existing objects that have a record.
     def before_validation_on_update() end
 
     # Is called _after_ Validations.validate (which is part of the Base.save call) on
-    # existing objects that has a record.
+    # existing objects that have a record.
     def after_validation_on_update()  end
 
     def valid_with_callbacks #:nodoc:
diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb
index a798c6bb02..594e320f6b 100755
--- a/activerecord/lib/active_record/fixtures.rb
+++ b/activerecord/lib/active_record/fixtures.rb
@@ -20,7 +20,7 @@ end
 # This type of fixture is in YAML format and the preferred default. YAML is a file format which describes data structures
 # in a non-verbose, humanly-readable format. It ships with Ruby 1.8.1+.
 #
-# Unlike single-file fixtures, YAML fixtures are stored in a single file per model, which is place in the directory appointed
+# Unlike single-file fixtures, YAML fixtures are stored in a single file per model, which are placed in the directory appointed
 # by <tt>Test::Unit::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just
 # put your files in <your-rails-app>/test/fixtures/). The fixture file ends with the .yml file extension (Rails example:
 # "<your-rails-app>/test/fixtures/web_sites.yml"). The format of a YAML fixture file looks like this:
@@ -56,7 +56,7 @@ end
 # = CSV fixtures
 #
 # Fixtures can also be kept in the Comma Separated Value format. Akin to YAML fixtures, CSV fixtures are stored
-# in a single file, but, instead end with the .csv file extension (Rails example: "<your-rails-app>/test/fixtures/web_sites.csv")
+# in a single file, but instead end with the .csv file extension (Rails example: "<your-rails-app>/test/fixtures/web_sites.csv")
 #
 # The format of this type of fixture file is much more compact than the others, but also a little harder to read by us
 # humans.  The first line of the CSV file is a comma-separated list of field names.  The rest of the file is then comprised
@@ -103,7 +103,7 @@ end
 # = Using Fixtures
 #
 # Since fixtures are a testing construct, we use them in our unit and functional tests.  There are two ways to use the
-# fixtures, but first lets take a look at a sample unit test found:
+# fixtures, but first let's take a look at a sample unit test found:
 #
 #   require 'web_site'
 #
@@ -139,7 +139,7 @@ end
 #
 # As seen above, the data hash created from the YAML fixtures would have @web_sites["rubyonrails"]["url"] return
 # "http://www.rubyonrails.org" and @web_sites["google"]["name"] would return "Google". The same fixtures, but loaded
-# from a CSV fixture file would be accessible via @web_sites["web_site_1"]["name"] == "Ruby on Rails" and have the individual
+# from a CSV fixture file, would be accessible via @web_sites["web_site_1"]["name"] == "Ruby on Rails" and have the individual
 # fixtures available as instance variables @web_site_1 and @web_site_2.
 #
 # If you do not wish to use instantiated fixtures (usually for performance reasons) there are two options.
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index fcb5ad82de..9b93366906 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -109,7 +109,7 @@ module ActiveRecord
   #     end
   #   end
   #
-  # And some times you need to do something in SQL not abstracted directly by migrations:
+  # And sometimes you need to do something in SQL not abstracted directly by migrations:
   #
   #   class MakeJoinUnique < ActiveRecord::Migration
   #     def self.up
@@ -123,7 +123,7 @@ module ActiveRecord
   #
   # == Using the class after changing table
   #
-  # Some times you'll want to add a column in a migration and populate it immediately after. In that case, you'll need
+  # Sometimes you'll want to add a column in a migration and populate it immediately after. In that case, you'll need
   # to make a call to Base#reset_column_information in order to ensure that the class has the latest column data from 
   # after the new column was added. Example:
   #
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 9aec0ca34b..de5a01c9be 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -34,7 +34,7 @@ module ActiveRecord
     end
 
     # Reflection allows you to interrogate Active Record classes and objects about their associations and aggregations.
-    # This information can for example be used in a form builder that took an Active Record object and created input
+    # This information can, for example, be used in a form builder that took an Active Record object and created input
     # fields for all of the attributes depending on their type and displayed the associations to other objects.
     #
     # You can find the interface for the AggregateReflection and AssociationReflection classes in the abstract MacroReflection class.
diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb
index e9a612495c..2c5692c036 100644
--- a/activerecord/lib/active_record/transactions.rb
+++ b/activerecord/lib/active_record/transactions.rb
@@ -24,7 +24,7 @@ module ActiveRecord
 
     # Transactions are protective blocks where SQL statements are only permanent if they can all succeed as one atomic action. 
     # The classic example is a transfer between two accounts where you can only have a deposit if the withdrawal succeeded and
-    # vice versa. Transaction enforce the integrity of the database and guards the data against program errors or database break-downs.
+    # vice versa. Transactions enforce the integrity of the database and guard the data against program errors or database break-downs.
     # So basically you should use transaction blocks whenever you have a number of statements that must be executed together or
     # not at all. Example:
     #
@@ -62,7 +62,7 @@ module ActiveRecord
     #
     # == Object-level transactions
     #
-    # You can enable object-level transactions for Active Record objects, though. You do this by naming the each of the Active Records
+    # You can enable object-level transactions for Active Record objects, though. You do this by naming each of the Active Records
     # that you want to enable object-level transactions for, like this:
     #
     #   Account.transaction(david, mary) do
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index c3a67f9d91..1292bff432 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -29,8 +29,8 @@ module ActiveRecord
 
     
     # Adds an error to the base object instead of any particular attribute. This is used
-    # to report errors that doesn't tie to any specific attribute, but rather to the object
-    # as a whole. These error messages doesn't get prepended with any field name when iterating
+    # to report errors that don't tie to any specific attribute, but rather to the object
+    # as a whole. These error messages don't get prepended with any field name when iterating
     # with each_full, so they should be complete sentences.
     def add_to_base(msg)
       add(:base, msg)
@@ -359,7 +359,7 @@ module ActiveRecord
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:blank], :on => :save }
         configuration.update(attr_names.pop) if attr_names.last.is_a?(Hash)
 
-        # can't use validates_each here, because it cannot cope with non-existant attributes,
+        # can't use validates_each here, because it cannot cope with nonexistent attributes,
         # while errors.add_on_empty can	
         attr_names.each do |attr_name|
           send(validation_method(configuration[:on])) do |record|
@@ -460,7 +460,7 @@ module ActiveRecord
       #     validates_uniqueness_of :user_name, :scope => "account_id"
       #   end
       #
-      # When the record is created, a check is performed to make sure that no record exist in the database with the given value for the specified
+      # When the record is created, a check is performed to make sure that no record exists in the database with the given value for the specified
       # attribute (that maps to a column). When the record is updated, the same check is made but disregarding the record itself.
       #
       # Configuration options:
@@ -565,7 +565,7 @@ module ActiveRecord
         end
       end
 
-      # Validates whether the associated object or objects are all themselves valid. Works with any kind of association.
+      # Validates whether the associated object or objects are all valid themselves. Works with any kind of association.
       #
       #   class Book < ActiveRecord::Base
       #     has_many :pages