Merge docrails

5 files changed, 13 insertions, 15 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 3034e9d237..468a6cd9f8 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -774,13 +774,12 @@ module ActiveRecord
       # [collection.build(attributes = {}, ...)]
       #   Returns one or more new objects of the collection type that have been instantiated
       #   with +attributes+ and linked to this object through a foreign key, but have not yet
-      #   been saved. <b>Note:</b> This only works if an associated object already exists, not if
-      #   it's +nil+!
+      #   been saved.
       # [collection.create(attributes = {})]
       #   Returns a new object of the collection type that has been instantiated
       #   with +attributes+, linked to this object through a foreign key, and that has already
-      #   been saved (if it passed the validation). <b>Note:</b> This only works if an associated
-      #   object already exists, not if it's +nil+!
+      #   been saved (if it passed the validation). *Note*: This only works if the base model
+      #   already exists in the DB, not if it is a new (unsaved) record!
       #
       # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so
       # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)
@@ -1040,7 +1039,6 @@ module ActiveRecord
       # A Post class declares <tt>belongs_to :author</tt>, which will add:
       # * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)
       # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
-      # * <tt>Post#author?</tt> (similar to <tt>post.author == some_author</tt>)
       # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
       # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 82e91a80ad..4ee9887186 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -1724,10 +1724,10 @@ module ActiveRecord #:nodoc:
         #   class Article < ActiveRecord::Base
         #     def self.find_with_scope
         #       with_scope(:find => { :conditions => "blog_id = 1", :limit => 1 }, :create => { :blog_id => 1 }) do
-        #         with_scope(:find => { :limit => 10 })
+        #         with_scope(:find => { :limit => 10 }) do
         #           find(:all) # => SELECT * from articles WHERE blog_id = 1 LIMIT 10
         #         end
-        #         with_scope(:find => { :conditions => "author_id = 3" })
+        #         with_scope(:find => { :conditions => "author_id = 3" }) do
         #           find(:all) # => SELECT * from articles WHERE blog_id = 1 AND author_id = 3 LIMIT 1
         #         end
         #       end
diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb
index adc675966a..79f70f07cd 100644
--- a/activerecord/lib/active_record/fixtures.rb
+++ b/activerecord/lib/active_record/fixtures.rb
@@ -335,7 +335,6 @@ end
 #   george:
 #     id: 1
 #     name: George the Monkey
-#     pirate_id: 1
 #
 #   ### in fruits.yml
 #
@@ -370,8 +369,8 @@ end
 #   ### in monkeys.yml
 #
 #   george:
+#     id: 1
 #     name: George the Monkey
-#     pirate: reginald
 #     fruits: apple, orange, grape
 #
 #   ### in fruits.yml
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index aeeed24881..c059b2d18b 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -1,7 +1,8 @@
 require 'active_support/core_ext/object/metaclass'
 
 module ActiveRecord
-  class IrreversibleMigration < ActiveRecordError#:nodoc:
+  # Exception that can be raised to stop migrations from going backwards.
+  class IrreversibleMigration < ActiveRecordError
   end
 
   class DuplicateMigrationVersionError < ActiveRecordError#:nodoc:
diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb
index f79a12a95c..d8fae495e7 100644
--- a/activerecord/lib/active_record/nested_attributes.rb
+++ b/activerecord/lib/active_record/nested_attributes.rb
@@ -49,14 +49,14 @@ module ActiveRecord
     # create the member and avatar in one go:
     #
     #   params = { :member => { :name => 'Jack', :avatar_attributes => { :icon => 'smiling' } } }
-    #   member = Member.create(params)
+    #   member = Member.create(params[:member])
     #   member.avatar.id # => 2
     #   member.avatar.icon # => 'smiling'
     #
     # It also allows you to update the avatar through the member:
     #
-    #   params = { :member' => { :avatar_attributes => { :id => '2', :icon => 'sad' } } }
-    #   member.update_attributes params['member']
+    #   params = { :member => { :avatar_attributes => { :id => '2', :icon => 'sad' } } }
+    #   member.update_attributes params[:member]
     #   member.avatar.icon # => 'sad'
     #
     # By default you will only be able to set and update attributes on the
@@ -75,7 +75,7 @@ module ActiveRecord
     #   member.avatar_attributes = { :id => '2', :_destroy => '1' }
     #   member.avatar.marked_for_destruction? # => true
     #   member.save
-    #   member.avatar #=> nil
+    #   member.reload.avatar #=> nil
     #
     # Note that the model will _not_ be destroyed until the parent is saved.
     #
@@ -179,7 +179,7 @@ module ActiveRecord
     #   member.posts.detect { |p| p.id == 2 }.marked_for_destruction? # => true
     #   member.posts.length #=> 2
     #   member.save
-    #   member.posts.length # => 1
+    #   member.reload.posts.length # => 1
     #
     # === Saving
     #