Smattering of grammatical fixes to documentation. Closes #10083 [BobSilva]

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

17 files changed, 107 insertions, 96 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 1013c75643..f6ee5e1d07 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -243,7 +243,7 @@ module ActiveRecord
     #
     # == Unsaved objects and associations
     #
-    # You can manipulate objects and associations before they are saved to the database, but there is some special behaviour you should be
+    # You can manipulate objects and associations before they are saved to the database, but there is some special behavior you should be
     # aware of, mostly involving the saving of associated objects.
     #
     # === One-to-one associations
@@ -267,7 +267,7 @@ module ActiveRecord
     # === Association callbacks
     #
     # Similiar to the normal callbacks that hook into the lifecycle of an Active Record object, you can also define callbacks that get
-    # trigged when you add an object to or remove an object from an association collection. Example:
+    # triggered when you add an object to or remove an object from an association collection. Example:
     #
     #   class Project
     #     has_and_belongs_to_many :developers, :after_add => :evaluate_velocity
@@ -584,10 +584,10 @@ module ActiveRecord
       #   This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model.
       # * <tt>collection=objects</tt> - replaces the collections content by deleting and adding objects as appropriate.
       # * <tt>collection_singular_ids</tt> - returns an array of the associated objects' ids
-      # * <tt>collection_singular_ids=ids</tt> - replace the collection by the objects identified by the primary keys in +ids+
+      # * <tt>collection_singular_ids=ids</tt> - replace the collection with the objects identified by the primary keys in +ids+
       # * <tt>collection.clear</tt> - removes every object from the collection. This destroys the associated objects if they
       #   are associated with <tt>:dependent => :destroy</tt>, deletes them directly from the database if <tt>:dependent => :delete_all</tt>,
-      #   or otherwise sets their foreign keys to NULL.
+      #   otherwise sets their foreign keys to NULL.
       # * <tt>collection.empty?</tt> - returns +true+ if there are no associated objects.
       # * <tt>collection.size</tt> - returns the number of associated objects.
       # * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
@@ -621,8 +621,6 @@ module ActiveRecord
       #   SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>.
       # * <tt>:order</tt>       - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
       #   such as <tt>last_name, first_name DESC</tt>
-      # * <tt>:group</tt>       - specify the attribute by which the associated objects are returned as a <tt>GROUP BY</tt> SQL fragment,
-      #   such as +category+
       # * <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_many+ association will use +person_id+
       #   as the default +foreign_key+.
@@ -633,13 +631,13 @@ module ActiveRecord
       # * <tt>:finder_sql</tt>  - specify a complete SQL statement to fetch the association. This is a good way to go for complex
       #   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 <tt>:finder_sql</tt> is
-      #   specified but <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
+      #   specified but not <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
       # * <tt>:extend</tt>  - specify a named module for extending the proxy. See "Association extensions".
       # * <tt>:include</tt>  - specify second-order associations that should be eager loaded when the collection is loaded.
       # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause.
       # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
       # * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows.
-      # * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you for example want to do a join, 
+      # * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you, for example, want to do a join 
       #   but not include the joined columns.
       # * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>).
       # * <tt>:through</tt>: Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt> and <tt>:foreign_key</tt> 
@@ -708,8 +706,8 @@ module ActiveRecord
       #   if the real class name is +Person+, you'll have to specify it with this option.
       # * <tt>:conditions</tt>  - specify the conditions that the associated object must meet in order to be included as a +WHERE+
       #   SQL fragment, such as <tt>rank = 5</tt>.
-      # * <tt>:order</tt>       - specify the order from which the associated object will be picked at the top. Specified as
-      #   an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+      # * <tt>:order</tt>       - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+      #   such as <tt>last_name, first_name DESC</tt>
       # * <tt>:dependent</tt>   - if set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to
       #   <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method. If set to <tt>:nullify</tt>, the associated
       #   object's foreign key is set to +NULL+. Also, association is assigned.
@@ -721,7 +719,7 @@ module ActiveRecord
             #
       # Option examples:
       #   has_one :credit_card, :dependent => :destroy  # destroys the associated credit card
-      #   has_one :credit_card, :dependent => :nullify  # updates the associated records foreign key value to null rather than destroying it
+      #   has_one :credit_card, :dependent => :nullify  # updates the associated records foreign key value to NULL rather than destroying it
       #   has_one :last_comment, :class_name => "Comment", :order => "posted_on"
       #   has_one :project_manager, :class_name => "Person", :conditions => "role = 'project_manager'"
       #   has_one :attachment, :as => :attachable
@@ -771,12 +769,12 @@ module ActiveRecord
       #   if the real class name is +Person+, you'll have to specify it with this option.
       # * <tt>:conditions</tt>  - specify the conditions that the associated object must meet in order to be included as a +WHERE+
       #   SQL fragment, such as <tt>authorized = 1</tt>.
-      # * <tt>:order</tt>       - specify the order from which the associated object will be picked at the top. Specified as
-      #   an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+      # * <tt>:order</tt>       - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+      #   such as <tt>last_name, first_name DESC</tt>
       # * <tt>:foreign_key</tt> - specify the 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 a +Person+ class that makes a +belongs_to+ association to a
       #   +Boss+ class will use +boss_id+ as the default +foreign_key+.
-      # * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through use of +increment_counter+ 
+      # * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through the use of +increment_counter+ 
       #   and +decrement_counter+. The counter cache is incremented when an object of this class is created and decremented when it's
       #   destroyed. This requires that a column named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging +Comment+ class)
       #   is used on the associate class (such as a +Post+ class). You can also specify a custom counter cache column by providing 
@@ -924,7 +922,8 @@ module ActiveRecord
       #   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 <tt>authorized = 1</tt>.
-      # * <tt>:order</tt> - specify the order in which the associated objects are returned as a <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+      # * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+      #   such as <tt>last_name, first_name DESC</tt>
       # * <tt>:uniq</tt> - if set to +true+, duplicate associated objects will be ignored by accessors and query methods
       # * <tt>:finder_sql</tt> - overwrite the default generated SQL statement used to fetch the association with a manual statement
       # * <tt>:delete_sql</tt> - overwrite the default generated SQL statement used to remove links between the associated 
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index a7d2b01f73..3e7fa13e97 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -40,7 +40,7 @@ module ActiveRecord #:nodoc:
   class DangerousAttributeError < ActiveRecordError #:nodoc:
   end
 
-  # Raised when you've tried to access a column, which wasn't
+  # Raised when you've tried to access a column which wasn't
   # loaded by your finder.  Typically this is because :select
   # has been specified
   class MissingAttributeError < NoMethodError
@@ -72,7 +72,7 @@ module ActiveRecord #:nodoc:
   # == Creation
   #
   # Active Records accept constructor parameters either in a hash or as a block. The hash method is especially useful when
-  # you're receiving the data from somewhere else, like a HTTP request. It works like this:
+  # you're receiving the data from somewhere else, like an HTTP request. It works like this:
   #
   #   user = User.new(:name => "David", :occupation => "Code Artist")
   #   user.name # => "David"
@@ -112,7 +112,7 @@ module ActiveRecord #:nodoc:
   #   end
   #
   # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
-  # attacks if the <tt>user_name</tt> and +password+ parameters come directly from a HTTP request. The <tt>authenticate_safely</tt>  and
+  # attacks if the <tt>user_name</tt> and +password+ parameters come directly from an HTTP request. The <tt>authenticate_safely</tt>  and
   # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query, 
   # which will ensure that an attacker can't escape the query and fake the login (or worse).
   #
@@ -137,9 +137,9 @@ module ActiveRecord #:nodoc:
   #
   # == Overwriting default accessors
   #
-  # All column values are automatically available through basic accessors on the Active Record object, but some times you
-  # want to specialize this behavior. This can be done by either by overwriting the default accessors (using the same
-  # name as the attribute) calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
+  # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
+  # want to specialize this behavior. This can be done by overwriting the default accessors (using the same
+  # name as the attribute) and calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
   # Example:
   #
   #   class Song < ActiveRecord::Base
@@ -230,7 +230,7 @@ module ActiveRecord #:nodoc:
   #
   # == Single table inheritance
   #
-  # Active Record allows inheritance by storing the name of the class in a column that by default is called "type" (can be changed
+  # Active Record allows inheritance by storing the name of the class in a column that by default is named "type" (can be changed
   # by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
   #
   #   class Company < ActiveRecord::Base; end
@@ -251,7 +251,7 @@ module ActiveRecord #:nodoc:
   #
   # Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
   # All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
-  # For example, if Course is a ActiveRecord::Base, but resides in a different database you can just say Course.establish_connection
+  # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say Course.establish_connection
   # and Course *and all its subclasses* will use this connection instead.
   #
   # This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
@@ -260,12 +260,12 @@ module ActiveRecord #:nodoc:
   # == Exceptions
   #
   # * +ActiveRecordError+ -- generic error class and superclass of all other errors raised by Active Record
-  # * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include a
+  # * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include an
   #   <tt>:adapter</tt> key.
-  # * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified an non-existent adapter
+  # * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a non-existent adapter
   #   (or a bad spelling of an existing one).
   # * +AssociationTypeMismatch+ -- the object assigned to the association wasn't of the type specified in the association definition.
-  # * +SerializationTypeMismatch+ -- the object serialized wasn't of the class specified as the second parameter.
+  # * +SerializationTypeMismatch+ -- the serialized object wasn't of the class specified as the second parameter.
   # * +ConnectionNotEstablished+ -- no connection has been established. Use <tt>establish_connection</tt> before querying.
   # * +RecordNotFound+ -- no record responded to the find* method.
   #   Either the row with the given ID doesn't exist or the row didn't meet the additional restrictions.
@@ -360,7 +360,7 @@ module ActiveRecord #:nodoc:
     @@schema_format = :ruby
 
     # Determines whether to raise an exception on mass-assignment to protected
-    # attribute. Defaults to true.
+    # attributes. Defaults to true.
     cattr_accessor :whiny_protected_attributes, :instance_writer => false
     @@whiny_protected_attributes = true
 
@@ -370,10 +370,10 @@ module ActiveRecord #:nodoc:
       # * Find by id: This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]).
       #   If no record can be found for all of the listed ids, then RecordNotFound will be raised.
       # * Find first: This will return the first record matched by the options used. These options can either be specific
-      #   conditions or merely an order. If no record can matched, nil is returned.
+      #   conditions or merely an order. If no record can be matched, nil is returned.
       # * Find all: This will return all the records matched by the options used. If no records are found, an empty array is returned.
       #
-      # All approaches accept an option hash as their last parameter. The options are:
+      # All approaches accept an options hash as their last parameter. The options are:
       #
       # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
       # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name".
@@ -384,9 +384,10 @@ module ActiveRecord #:nodoc:
       #   Accepts named associations in the form of :include, which will perform an INNER JOIN on the associated table(s).
       #   The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
       #   Pass :readonly => false to override.
+      #   See adding joins for associations under Associations.
       # * <tt>:include</tt>: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
       #   to already defined associations. See eager loading under Associations.
-      # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
+      # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not
       #   include the joined columns.
       # * <tt>:from</tt>: By default, this is the table name of the class, but can be changed to an alternate table name (or even the name
       #   of a database view). 
@@ -398,7 +399,7 @@ module ActiveRecord #:nodoc:
       #   Person.find(1)       # returns the object for ID = 1
       #   Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
       #   Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
-      #   Person.find([1])     # returns an array for objects the object with ID = 1
+      #   Person.find([1])     # returns an array for the object with ID = 1
       #   Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
       #
       # Note that returned records may not be in the same order as the ids you
@@ -429,6 +430,13 @@ module ActiveRecord #:nodoc:
       #   end
       def find(*args)
         options = args.extract_options!
+        # Note:  we extract any :joins option with a non-string value from the options, and turn it into
+        #  an internal option :ar_joins.  This allows code called from here to find the ar_joins, and
+        #  it bypasses marking the result as read_only.
+        #  A normal string join marks the result as read-only because it contains attributes from joined tables
+        #  which are not in the base table and therefore prevent the result from being saved.
+        #  In the case of an ar_join, the JoinDependency created to instantiate the results eliminates these
+        #  bogus attributes.  See JoinDependency#instantiate, and JoinBase#instantiate in associations.rb.
         validate_find_options(options)
         set_readonly_option!(options)
 
@@ -521,14 +529,14 @@ module ActiveRecord #:nodoc:
         connection.update(sql, "#{name} Update")
       end
 
-      # Destroys the objects for all the records that match the +condition+ by instantiating each object and calling
+      # Destroys the objects for all the records that match the +conditions+ by instantiating each object and calling
       # the destroy method. Example:
       #   Person.destroy_all "last_login < '2004-04-04'"
       def destroy_all(conditions = nil)
         find(:all, :conditions => conditions).each { |object| object.destroy }
       end
 
-      # Deletes all the records that match the +condition+ without instantiating the objects first (and hence not
+      # Deletes all the records that match the +conditions+ without instantiating the objects first (and hence not
       # calling the destroy method). Example:
       #   Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')"
       def delete_all(conditions = nil)
@@ -576,7 +584,7 @@ module ActiveRecord #:nodoc:
       #
       # This is used for caching aggregate values, so that they don't need to be computed every time. 
       # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is 
-      # shown it would have to run a SQL query to find how many posts and comments there are.
+      # shown it would have to run an SQL query to find how many posts and comments there are.
       #
       # ==== Options
       #
@@ -687,7 +695,7 @@ module ActiveRecord #:nodoc:
       # ==== Options
       #
       # +attr_name+   The field name that should be serialized
-      # +class_name+  Optional, class name that the object should be equal to
+      # +class_name+  Optional, class name that the object type should be equal to
       #
       # ==== Example
       #   # Serialize a preferences attribute
@@ -707,7 +715,7 @@ module ActiveRecord #:nodoc:
       # Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
       # directly from ActiveRecord. So if the hierarchy looks like: Reply < Message < ActiveRecord, then Message is used
       # to guess the table name from even when called on Reply. The rules used to do the guess are handled by the Inflector class
-      # in Active Support, which knows almost all common English inflections (report a bug if your inflection isn't covered).
+      # in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb.
       #
       # Nested classes are given table names prefixed by the singular form of
       # the parent's table name. Example:
@@ -964,7 +972,7 @@ module ActiveRecord #:nodoc:
         connection.quote(value,column)
       end
 
-      # Used to sanitize objects before they're used in an SELECT SQL-statement. Delegates to <tt>connection.quote</tt>.
+      # Used to sanitize objects before they're used in an SQL SELECT statement. Delegates to <tt>connection.quote</tt>.
       def sanitize(object) #:nodoc:
         connection.quote(object)
       end
@@ -1266,7 +1274,7 @@ module ActiveRecord #:nodoc:
 
         # Enables dynamic finders like find_by_user_name(user_name) and find_by_user_name_and_password(user_name, password) that are turned into
         # find(:first, :conditions => ["user_name = ?", user_name]) and  find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])
-        # respectively. Also works for find(:all), but using find_all_by_amount(50) that are turned into find(:all, :conditions => ["amount = ?", 50]).
+        # respectively. Also works for find(:all) by using find_all_by_amount(50) that is turned into find(:all, :conditions => ["amount = ?", 50]).
         #
         # It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount
         # is actually find_all_by_amount(amount, options).
@@ -1435,7 +1443,7 @@ module ActiveRecord #:nodoc:
         #     end
         #   end
         #
-        # You can ignore any previous scopings by using <tt>with_exclusive_scope</tt> method.
+        # You can ignore any previous scopings by using the <tt>with_exclusive_scope</tt> method.
         #
         #   class Article < ActiveRecord::Base
         #     def self.find_with_exclusive_scope
@@ -1889,7 +1897,7 @@ module ActiveRecord #:nodoc:
       # Allows you to set all the attributes at once by passing in a hash with keys
       # matching the attribute names (which again matches the column names). Sensitive attributes can be protected
       # from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively
-      # specify which attributes *can* be accessed in with the +attr_accessible+ macro. Then all the
+      # specify which attributes *can* be accessed with the +attr_accessible+ macro. Then all the
       # attributes not included in that won't be allowed to be mass-assigned. 
       def attributes=(new_attributes, guard_protected_attributes = true)
         return if new_attributes.nil?
@@ -2120,7 +2128,7 @@ module ActiveRecord #:nodoc:
         default
       end
 
-      # Returns copy of the attributes hash where all the values have been safely quoted for use in
+      # Returns a copy of the attributes hash where all the values have been safely quoted for use in
       # an SQL statement.
       def attributes_with_quotes(include_primary_key = true, include_readonly_attributes = true)
         quoted = attributes.inject({}) do |quoted, (name, value)|
@@ -2159,7 +2167,7 @@ module ActiveRecord #:nodoc:
       # So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
       # written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
       # parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
-      # s for String, and a for Array. If all the values for a given attribute is empty, the attribute will be set to nil.
+      # s for String, and a for Array. If all the values for a given attribute are empty, the attribute will be set to nil.
       def assign_multiparameter_attributes(pairs)
         execute_callstack_for_multiparameter_attributes(
           extract_callstack_for_multiparameter_attributes(pairs)
diff --git a/activerecord/lib/active_record/calculations.rb b/activerecord/lib/active_record/calculations.rb
index 7f8af9421e..df73cee2f3 100644
--- a/activerecord/lib/active_record/calculations.rb
+++ b/activerecord/lib/active_record/calculations.rb
@@ -15,14 +15,17 @@ module ActiveRecord
       # The third approach, count using options, accepts an option hash as the only parameter. The options are:
       #
       # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
-      # * <tt>:joins</tt>: An SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
-      #   The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
+      # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
+      #    or names associations in the same form used for the :include option.
+      #   If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns.
+      #   Pass :readonly => false to override.
+      #   See adding joins for associations under Associations.
       # * <tt>:include</tt>: Named associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
-      #   to already defined associations. When using named associations count returns the number DISTINCT items for the model you're counting.
+      #   to already defined associations. When using named associations, count returns the number of DISTINCT items for the model you're counting.
       #   See eager loading under Associations.
       # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations).
       # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
-      # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
+      # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not
       #   include the joined columns.
       # * <tt>:distinct</tt>: Set this to true to make this a distinct calculation, such as SELECT COUNT(DISTINCT posts.id) ...
       #
@@ -44,35 +47,35 @@ module ActiveRecord
         calculate(:count, *construct_count_options_from_args(*args))
       end
 
-      # Calculates average value on a given column.  The value is returned as a float.  See #calculate for examples with options.
+      # Calculates the average value on a given column.  The value is returned as a float.  See #calculate for examples with options.
       #
       #   Person.average('age')
       def average(column_name, options = {})
         calculate(:avg, column_name, options)
       end
 
-      # Calculates the minimum value on a given column.  The value is returned with the same data type of the column..  See #calculate for examples with options.
+      # Calculates the minimum value on a given column.  The value is returned with the same data type of the column.  See #calculate for examples with options.
       #
       #   Person.minimum('age')
       def minimum(column_name, options = {})
         calculate(:min, column_name, options)
       end
 
-      # Calculates the maximum value on a given column.  The value is returned with the same data type of the column..  See #calculate for examples with options.
+      # Calculates the maximum value on a given column.  The value is returned with the same data type of the column.  See #calculate for examples with options.
       #
       #   Person.maximum('age')
       def maximum(column_name, options = {})
         calculate(:max, column_name, options)
       end
 
-      # Calculates the sum value on a given column.  The value is returned with the same data type of the column..  See #calculate for examples with options.
+      # Calculates the sum of values on a given column.  The value is returned with the same data type of the column.  See #calculate for examples with options.
       #
       #   Person.sum('age')
       def sum(column_name, options = {})
         calculate(:sum, column_name, options)
       end
 
-      # This calculates aggregate values in the given column:  Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
+      # This calculates aggregate values in the given column.  Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
       # Options such as :conditions, :order, :group, :having, and :joins can be passed to customize the query.
       #
       # There are two basic forms of output:
@@ -237,7 +240,7 @@ module ActiveRecord
         end
 
         # Converts a given key to the value that the database adapter returns as
-        # as a usable column name.
+        # a usable column name.
         #   users.id #=> users_id
         #   sum(id) #=> sum_id
         #   count(distinct users.id) #=> count_distinct_users_id
diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb
index 631eb911fc..8d619e3fb3 100755
--- a/activerecord/lib/active_record/callbacks.rb
+++ b/activerecord/lib/active_record/callbacks.rb
@@ -161,7 +161,7 @@ module ActiveRecord
   # == <tt>before_validation*</tt> returning statements
   #
   # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+.
-  # If <tt>Base#save!</tt> is called it will raise a +RecordNotSave+ exception.
+  # If <tt>Base#save!</tt> is called it will raise a +RecordNotSaved+ exception.
   # Nothing will be appended to the errors object.
   #
   # == Cancelling callbacks
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
index 801cb23362..51b90d3c64 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
@@ -243,7 +243,7 @@ module ActiveRecord
     end
 
     # Locate the connection of the nearest super class. This can be an
-    # active or defined connections: if it is the latter, it will be
+    # active or defined connection: if it is the latter, it will be
     # opened and set as the active connection for the class it was defined
     # for (not necessarily the current class).
     def self.retrieve_connection #:nodoc:
@@ -264,15 +264,15 @@ module ActiveRecord
       conn or raise ConnectionNotEstablished
     end
 
-    # Returns true if a connection that's accessible to this class have already been opened.
+    # Returns true if a connection that's accessible to this class has already been opened.
     def self.connected?
       active_connections[active_connection_name] ? true : false
     end
 
     # Remove the connection for this class. This will close the active
     # connection and the defined connection (if they exist). The result
-    # can be used as argument for establish_connection, for easy
-    # re-establishing of the connection.
+    # can be used as an argument for establish_connection, for easily
+    # re-establishing the connection.
     def self.remove_connection(klass=self)
       spec = @@defined_connections[klass.name]
       konn = active_connections[klass.name]
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
index 066baaba45..589acd3945 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
@@ -98,7 +98,7 @@ module ActiveRecord
         add_limit_offset!(sql, options) if options
       end
 
-      # Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
+      # Appends +LIMIT+ and +OFFSET+ options to an SQL statement.
       # This method *modifies* the +sql+ parameter.
       # ===== Examples
       #  add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50})
@@ -113,7 +113,8 @@ module ActiveRecord
         end
       end
 
-      # Appends a locking clause to a SQL statement. *Modifies the +sql+ parameter*.
+      # Appends a locking clause to an SQL statement.
+      # This method *modifies* the +sql+ parameter.
       #   # SELECT * FROM suppliers FOR UPDATE
       #   add_lock! 'SELECT * FROM suppliers', :lock => true
       #   add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index 6bd56fd3c8..c6cdc776d6 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -272,7 +272,7 @@ module ActiveRecord
     end
 
     # Represents a SQL table in an abstract way.
-    # Columns are stored as ColumnDefinition in the #columns attribute.
+    # Columns are stored as a ColumnDefinition in the #columns attribute.
     class TableDefinition
       attr_accessor :columns
 
@@ -451,7 +451,7 @@ module ActiveRecord
       alias :belongs_to :references
 
       # Returns a String whose contents are the column definitions
-      # concatenated together.  This string can then be pre and appended to
+      # concatenated together.  This string can then be prepended and appended to
       # to generate the final SQL to create the table.
       def to_sql
         @columns * ', '
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 d4fcded32a..8f981438df 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -54,7 +54,7 @@ module ActiveRecord
       # [<tt>:temporary</tt>]
       #   Make a temporary table.
       # [<tt>:force</tt>]
-      #   Set to true or false to drop the table before creating it.
+      #   Set to true to drop the table before creating it.
       #   Defaults to false.
       #
       # ===== Examples
@@ -160,13 +160,13 @@ module ActiveRecord
       # Adds a new index to the table.  +column_name+ can be a single Symbol, or
       # an Array of Symbols.
       #
-      # The index will be named after the table and the first column names,
+      # The index will be named after the table and the first column name,
       # unless you pass +:name+ 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 colum +:first+. Using just the first name for this index
+      # index for the first column +:first+. 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/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
index bf8fed1111..64f314a7f6 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -18,7 +18,7 @@ module ActiveRecord
         raise ArgumentError, "No database specified. Missing argument: database."
       end
 
-      # The postgres drivers don't allow to create an unconnected PGconn object,
+      # The postgres drivers don't allow the creation of an unconnected PGconn object,
       # so just pass a nil connection object for the time being.
       ConnectionAdapters::PostgreSQLAdapter.new(nil, logger, [host, port, nil, nil, database, username, password], config)
     end
@@ -217,8 +217,8 @@ module ActiveRecord
     # * <tt>:password</tt> -- Defaults to nothing
     # * <tt>:database</tt> -- The name of the database. No default, must be provided.
     # * <tt>:schema_search_path</tt> -- An optional schema search path for the connection given as a string of comma-separated schema names.  This is backward-compatible with the :schema_order option.
-    # * <tt>:encoding</tt> -- An optional client encoding that is using in a SET client_encoding TO <encoding> call on connection.
-    # * <tt>:min_messages</tt> -- An optional client min messages that is using in a SET client_min_messages TO <min_messages> call on connection.
+    # * <tt>:encoding</tt> -- An optional client encoding that is used in a SET client_encoding TO <encoding> call on the connection.
+    # * <tt>:min_messages</tt> -- An optional client min messages that is used in a SET client_min_messages TO <min_messages> call on the connection.
     # * <tt>:allow_concurrency</tt> -- If true, use async query methods so Ruby threads don't deadlock; otherwise, use blocking query methods.
     class PostgreSQLAdapter < AbstractAdapter
       # Returns 'PostgreSQL' as adapter name for identification purposes.
@@ -398,7 +398,7 @@ module ActiveRecord
         end
       end
 
-      # Executes a SQL statement, returning a PGresult object on success
+      # Executes an SQL statement, returning a PGresult object on success
       # or raising a PGError exception otherwise.
       def execute(sql, name = nil)
         log(sql, name) do
@@ -478,7 +478,7 @@ module ActiveRecord
 
       # Returns the list of all column definitions for a table.
       def columns(table_name, name = nil)
-        # Limit, precision, and scale are all handled by superclass.
+        # Limit, precision, and scale are all handled by the superclass.
         column_definitions(table_name).collect do |name, type, default, notnull|
           PostgreSQLColumn.new(name, default, type, notnull == 'f')
         end
@@ -669,7 +669,7 @@ module ActiveRecord
         sql << order_columns * ', '
       end
       
-      # Returns a ORDER BY clause for the passed order option.
+      # Returns an ORDER BY clause for the passed order option.
       # 
       # PostgreSQL does not allow arbitrary ordering when using DISTINCT ON, so we work around this
       # by wrapping the sql as a sub-select and ordering in that query.
@@ -761,7 +761,7 @@ module ActiveRecord
         end
 
         # Executes a SELECT query and returns the results, performing any data type
-        # conversions that require to be performed here instead of in PostgreSQLColumn.
+        # conversions that are required to be performed here instead of in PostgreSQLColumn.
         def select(sql, name = nil)
           fields, rows = select_raw(sql, name)
           result = []
@@ -791,7 +791,7 @@ module ActiveRecord
                 # fields that call value_before_type_cast.
                 if res.type(cell_index) == MONEY_COLUMN_TYPE_OID
                   # Because money output is formatted according to the locale, there are two
-                  # cases to consider (note the decimal seperators):
+                  # cases to consider (note the decimal separators):
                   #  (1) $12,345,678.12        
                   #  (2) $12.345.678,12
                   case column = row[cell_index]
diff --git a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
index c171b0239e..586594e0ef 100644
--- a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
@@ -34,7 +34,7 @@ module ActiveRecord
 
           # Allow database path relative to RAILS_ROOT, but only if
           # the database path is not the special path that tells
-          # Sqlite build a database only in memory.
+          # Sqlite to build a database only in memory.
           if Object.const_defined?(:RAILS_ROOT) && ':memory:' != config[:database]
             config[:database] = File.expand_path(config[:database], RAILS_ROOT)
           end
diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb
index 41e389d4fe..84e7c84d64 100755
--- a/activerecord/lib/active_record/fixtures.rb
+++ b/activerecord/lib/active_record/fixtures.rb
@@ -12,7 +12,7 @@ end
 class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
 end
 
-# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavours:
+# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavors:
 #
 #   1.  YAML fixtures
 #   2.  CSV fixtures
@@ -21,7 +21,7 @@ end
 # = YAML fixtures
 #
 # 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+.
+# in a non-verbose, human-readable format. It ships with Ruby 1.8.1+.
 #
 # 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
@@ -82,7 +82,7 @@ end
 #
 # = Single-file fixtures
 #
-# This type of fixtures was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
+# This type of fixture was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
 # Fixtures for this format are created by placing text files in a sub-directory (with the name of the model) to 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/<your-model-name>/ -- like <your-rails-app>/test/fixtures/web_sites/ for the WebSite
@@ -106,7 +106,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 let's take a look at a sample unit test found:
+# fixtures, but first let's take a look at a sample unit test:
 #
 #   require 'web_site'
 #
@@ -124,7 +124,7 @@ end
 #     fixtures :web_sites # add more by separating the symbols with commas
 #   ...
 #
-# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here tho), we trigger
+# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here though), we trigger
 # the testing environment to automatically load the appropriate fixtures into the database before each test.
 # To ensure consistent data, the environment deletes the fixtures before running the load.
 #
@@ -212,7 +212,7 @@ end
 # When *not* to use transactional fixtures:
 #   1. You're testing whether a transaction works correctly. Nested transactions don't commit until all parent transactions commit,
 #      particularly, the fixtures transaction which is begun in setup and rolled back in teardown. Thus, you won't be able to verify
-#      the results of your transaction until Active Record supports nested transactions or savepoints (in progress.)
+#      the results of your transaction until Active Record supports nested transactions or savepoints (in progress).
 #   2. Your database does not support transactions. Every Active Record database supports transactions except MySQL MyISAM.
 #      Use InnoDB, MaxDB, or NDB instead.
 #
@@ -260,7 +260,7 @@ end
 #
 # Specifying foreign keys in fixtures can be very fragile, not to
 # mention difficult to read. Since ActiveRecord can figure out the ID of
-# and fixture from its label, you can specify FK's by label instead of ID.
+# any fixture from its label, you can specify FK's by label instead of ID.
 #
 # === belongs_to
 #
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 2405eeb873..ee50bbd44e 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -32,9 +32,9 @@ module ActiveRecord
   #     end
   #   end
   #
-  # This migration will add a boolean flag to the accounts table and remove it again, if you're backing out of the migration.
+  # This migration will add a boolean flag to the accounts table and remove it if you're backing out of the migration.
   # It shows how all migrations have two class methods +up+ and +down+ that describes the transformations required to implement
-  # or remove the migration. These methods can consist of both the migration specific methods, like add_column and remove_column,
+  # or remove the migration. These methods can consist of both the migration specific methods like add_column and remove_column,
   # but may also contain regular Ruby code for generating data needed for the transformations.
   #
   # Example of a more complex migration that also needs to initialize data:
@@ -78,9 +78,9 @@ module ActiveRecord
   # * <tt>change_column(table_name, column_name, type, options)</tt>:  Changes the column to a different type using the same
   #   parameters as add_column.
   # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+.
-  # * <tt>add_index(table_name, column_names, options)</tt>: Add a new index with the name of the column. Other options include
+  # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
   #   :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
-  # * <tt>remove_index(table_name, index_name)</tt>: Remove the index specified by +index_name+.
+  # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
   #
   # == Irreversible transformations
   #
@@ -94,9 +94,9 @@ module ActiveRecord
   # To generate a new migration, use <tt>script/generate migration MyNewMigration</tt>
   # where MyNewMigration is the name of your migration. The generator will
   # create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
-  # directory, where <tt>nnn</tt> is the next largest migration number.
+  # directory where <tt>nnn</tt> is the next largest migration number.
   # You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
-  # n MyNewMigration.
+  # MyNewMigration.
   #
   # To run migrations against the currently configured database, use
   # <tt>rake db:migrate</tt>. This will update the database by running all of the
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 3d76ffe776..e7a0f9a835 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -44,7 +44,7 @@ module ActiveRecord
         reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil
       end
 
-      # Returns an array of AssociationReflection objects for all the aggregations in the class. If you only want to reflect on a
+      # Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a
       # certain association type, pass in the symbol (:has_many, :has_one, :belongs_to) for that as the first parameter. 
       # Example:
       #
@@ -56,7 +56,7 @@ module ActiveRecord
         macro ? association_reflections.select { |reflection| reflection.macro == macro } : association_reflections
       end
 
-      # Returns the AssociationReflection object for the named +aggregation+ (use the symbol). Example:
+      # Returns the AssociationReflection object for the named +association+ (use the symbol). Example:
       #
       #   Account.reflect_on_association(:owner) # returns the owner AssociationReflection
       #   Invoice.reflect_on_association(:line_items).macro  # returns :has_many
diff --git a/activerecord/lib/active_record/serializers/xml_serializer.rb b/activerecord/lib/active_record/serializers/xml_serializer.rb
index 16448bae77..28e9b3ddc6 100644
--- a/activerecord/lib/active_record/serializers/xml_serializer.rb
+++ b/activerecord/lib/active_record/serializers/xml_serializer.rb
@@ -1,7 +1,7 @@
 module ActiveRecord #:nodoc:
   module Serialization
     # Builds an XML document to represent the model.   Some configuration is
-    # available through +options+, however more complicated cases should use 
+    # available through +options+, however more complicated cases should 
     # override ActiveRecord's to_xml.
     #
     # By default the generated XML document will include the processing 
@@ -107,7 +107,7 @@ module ActiveRecord #:nodoc:
     #     </creator>
     #   </firm>
     #
-    # You may override the to_xml method in your ActiveRecord::Base
+    # You can override the to_xml method in your ActiveRecord::Base
     # subclasses if you need to.  The general form of doing this is
     #
     #   class IHaveMyOwnXML < ActiveRecord::Base
diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb
index c4bc55cb49..ee3e426512 100644
--- a/activerecord/lib/active_record/timestamp.rb
+++ b/activerecord/lib/active_record/timestamp.rb
@@ -1,6 +1,6 @@
 module ActiveRecord
-  # Active Record automatically timestamps create and update if the table has fields
-  # created_at/created_on or updated_at/updated_on.
+  # Active Record automatically timestamps create and update operations if the table has fields
+  # named created_at/created_on or updated_at/updated_on.
   #
   # Timestamping can be turned off by setting
   #   <tt>ActiveRecord::Base.record_timestamps = false</tt>
diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb
index 0cffcef313..61f5d819fc 100644
--- a/activerecord/lib/active_record/transactions.rb
+++ b/activerecord/lib/active_record/transactions.rb
@@ -75,7 +75,7 @@ module ActiveRecord
     #
     # Both Base#save and Base#destroy come wrapped in a transaction that ensures that whatever you do in validations or callbacks
     # will happen under the protected cover of a transaction. So you can use validations to check for values that the transaction
-    # depend on or you can raise exceptions in the callbacks to rollback.
+    # depends on or you can raise exceptions in the callbacks to rollback.
     #
     # == Exception handling
     #
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 35a1f8d0d4..24b29b1ec8 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -15,7 +15,7 @@ module ActiveRecord
   end
 
   # Active Record validation is reported to and from this object, which is used by Base#save to
-  # determine whether the object in a valid state to be saved. See usage example in Validations.
+  # determine whether the object is in a valid state to be saved. See usage example in Validations.
   class Errors
     include Enumerable
 
@@ -45,7 +45,7 @@ module ActiveRecord
       :even => "must be even"
     }
 
-    # Holds a hash with all the default error messages, such that they can be replaced by your own copy or localizations.
+    # Holds a hash with all the default error messages that can be replaced by your own copy or localizations.
     cattr_accessor :default_error_messages
 
 
@@ -118,7 +118,7 @@ module ActiveRecord
 
     alias :[] :on
 
-    # Returns errors assigned to base object through add_to_base according to the normal rules of on(attribute).
+    # Returns errors assigned to the base object through add_to_base according to the normal rules of on(attribute).
     def on_base
       on(:base)
     end