copy-edits some docs

2 files changed, 25 insertions, 22 deletions

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 555a611e68..ffc3847a31 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -103,15 +103,14 @@ module ActiveRecord
       # The +options+ hash can include the following keys:
       # [<tt>:id</tt>]
       #   Whether to automatically add a primary key column. Defaults to true.
-      #   Join tables for +has_and_belongs_to_many+ should set <tt>:id => false</tt>.
+      #   Join tables for +has_and_belongs_to_many+ should set it to false.
       # [<tt>:primary_key</tt>]
       #   The name of the primary key, if one is to be added automatically.
-      #   Defaults to +id+. You must NOT pass :id => false otherwise :primary_key option
-      #   will have no effect.
+      #   Defaults to +id+. If <tt>:id</tt> is false this option is ignored.
       #
-      #   Also note that this just sets the primary_key in the table. You still need to
-      #   add :set_primary_key => '' in the model to tell model what column is the 
-      #   primary_key. Models do NOT auto-detect the primary_key from table defintion. 
+      #   Also note that this just sets the primary key in the table. You additionally
+      #   need to configure the primary key in the model via the +set_primary_key+ macro.
+      #   Models do NOT auto-detect the primary key from their table definition. 
       #   
       # [<tt>:options</tt>]
       #   Any extra options you want appended to the table definition.
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index de0c00ac68..58824d7aeb 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -1107,47 +1107,51 @@ If for whatever reason an application loads the definition of a mailer class and
 
 NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+.
 
-h4. Descendants & Subclasses
+h4. Subclasses & Descendants
 
-h5. +descendants+
+h5. +subclasses+
 
-The +descendants+ method returns all classes, including its children, that inherits from self.
+The +subclasses+ method returns the subclasses of the receiver:
 
 <ruby>
 class C; end
-C.descendants #=> []
+C.subclasses # => []
 
 class B < C; end
-C.descendants #=> [B]
+C.subclasses # => [B]
 
 class A < B; end
-C.descendants #=> [B, A]
+C.subclasses # => [B]
 
 class D < C; end
-C.descendants #=> [B, A, D]
+C.subclasses # => [B, D]
 </ruby>
 
-h5. +subclasses+
+The order in which these classes are returned is unspecified.
 
-The +subclasses+ method returns all direct classes that inherits from self.
+WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
+
+NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.
+
+h5. +descendants+
+
+The +descendants+ method returns all classes that are <tt>&lt;</tt> than its receiver: 
 
 <ruby>
 class C; end
-C.subclasses #=> []
+C.descendants # => []
 
 class B < C; end
-C.subclasses #=> [B]
+C.descendants # => [B]
 
 class A < B; end
-C.subclasses #=> [B]
+C.descendants # => [B, A]
 
 class D < C; end
-C.subclasses #=> [B, D]
+C.descendants # => [B, A, D]
 </ruby>
 
-The order in which these class are returned is unspecified.
-
-WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
+The order in which these classes are returned is unspecified.
 
 NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.