Merge remote branch 'docrails/master'

5 files changed, 61 insertions, 53 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 73c0900c8b..8be36482d4 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -311,7 +311,8 @@ module ActiveRecord
     # You can set the :autosave option on a <tt>has_one</tt>, <tt>belongs_to</tt>,
     # <tt>has_many</tt>, or <tt>has_and_belongs_to_many</tt> association. Setting it
     # to +true+ will _always_ save the members, whereas setting it to +false+ will
-    # _never_ save the members.
+    # _never_ save the members. More details about :autosave option is available at
+    # autosave_association.rb . 
     #
     # === One-to-one associations
     #
@@ -956,8 +957,7 @@ module ActiveRecord
       #   If false, don't validate the associated objects when saving the parent object. true by default.
       # [:autosave]
       #   If true, always save the associated objects or destroy them if marked for destruction, 
-      #   when saving the parent object.
-      #   If false, never save or destroy the associated objects.
+      #   when saving the parent object. If false, never save or destroy the associated objects.
       #   By default, only save associated objects that are new records.
       # [:inverse_of]
       #   Specifies the name of the <tt>belongs_to</tt> association on the associated object 
diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb
index 2c7afe3c9f..131591405c 100644
--- a/activerecord/lib/active_record/autosave_association.rb
+++ b/activerecord/lib/active_record/autosave_association.rb
@@ -3,13 +3,13 @@ require 'active_support/core_ext/array/wrap'
 module ActiveRecord
   # = Active Record Autosave Association
   # 
-  # AutosaveAssociation is a module that takes care of automatically saving
-  # associacted records when parent is saved. In addition to saving, it
+  # +AutosaveAssociation+ is a module that takes care of automatically saving
+  # associacted records when their parent is saved. In addition to saving, it
   # also destroys any associated records that were marked for destruction.
-  # (See mark_for_destruction and marked_for_destruction?)
+  # (See +mark_for_destruction+ and <tt>marked_for_destruction?</tt>).
   #
   # Saving of the parent, its associations, and the destruction of marked
-  # associations, all happen inside 1 transaction. This should never leave the
+  # associations, all happen inside a transaction. This should never leave the
   # database in an inconsistent state.
   #
   # If validations for any of the associations fail, their error messages will
@@ -18,6 +18,9 @@ module ActiveRecord
   # Note that it also means that associations marked for destruction won't
   # be destroyed directly. They will however still be marked for destruction.
   #
+  # Note that <tt>:autosave => false</tt> is not same as not declaring <tt>:autosave</tt>.
+  # When the <tt>:autosave</tt> option is not present new associations are saved.
+  #
   # === One-to-one Example
   #
   #   class Post
@@ -28,7 +31,7 @@ module ActiveRecord
   # automatically _and_ atomically:
   #
   #   post = Post.find(1)
-  #   post.title # => "The current global position of migrating ducks"
+  #   post.title       # => "The current global position of migrating ducks"
   #   post.author.name # => "alloy"
   #
   #   post.title = "On the migration of ducks"
@@ -36,7 +39,7 @@ module ActiveRecord
   #
   #   post.save
   #   post.reload
-  #   post.title # => "On the migration of ducks"
+  #   post.title       # => "On the migration of ducks"
   #   post.author.name # => "Eloy Duran"
   #
   # Destroying an associated model, as part of the parent's save action, is as
@@ -46,6 +49,7 @@ module ActiveRecord
   #   post.author.marked_for_destruction? # => true
   #
   # Note that the model is _not_ yet removed from the database:
+  #
   #   id = post.author.id
   #   Author.find_by_id(id).nil? # => false
   #
@@ -53,40 +57,49 @@ module ActiveRecord
   #   post.reload.author # => nil
   #
   # Now it _is_ removed from the database:
+  #
   #   Author.find_by_id(id).nil? # => true
   #
   # === One-to-many Example
   #
-  # Consider a Post model with many Comments:
+  # When <tt>:autosave</tt> is not declared new children are saved when their parent is saved:
   #
   #   class Post
-  #     has_many :comments, :autosave => true
+  #     has_many :comments # :autosave option is no declared
   #   end
   #
-  # Saving changes to the parent and its associated model can now be performed
-  # automatically _and_ atomically:
+  #   post = Post.new(:title => 'ruby rocks')
+  #   post.comments.build(:body => 'hello world')
+  #   post.save # => saves both post and comment
   #
-  #   post = Post.find(1)
-  #   post.title # => "The current global position of migrating ducks"
-  #   post.comments.first.body # => "Wow, awesome info thanks!"
-  #   post.comments.last.body # => "Actually, your article should be named differently."
+  #   post = Post.create(:title => 'ruby rocks')
+  #   post.comments.build(:body => 'hello world')
+  #   post.save # => saves both post and comment
   #
-  #   post.title = "On the migration of ducks"
-  #   post.comments.last.body = "Actually, your article should be named differently. [UPDATED]: You are right, thanks."
+  #   post = Post.create(:title => 'ruby rocks')
+  #   post.comments.create(:body => 'hello world')
+  #   post.save # => saves both post and comment
+  #  
+  # When <tt>:autosave</tt> is true all children is saved, no matter whether they are new records:
   #
-  #   post.save
-  #   post.reload
-  #   post.title # => "On the migration of ducks"
-  #   post.comments.last.body # => "Actually, your article should be named differently. [UPDATED]: You are right, thanks."
+  #   class Post
+  #     has_many :comments, :autosave => true
+  #   end
+  #
+  #   post = Post.create(:title => 'ruby rocks')
+  #   post.comments.create(:body => 'hello world')
+  #   post.comments[0].body = 'hi everyone'
+  #   post.save # => saves both post and comment, with 'hi everyone' as title
   #
-  # Destroying one of the associated models members, as part of the parent's
-  # save action, is as simple as marking it for destruction:
+  # Destroying one of the associated models as part of the parent's save action
+  # is as simple as marking it for destruction:
   #
   #   post.comments.last.mark_for_destruction
   #   post.comments.last.marked_for_destruction? # => true
   #   post.comments.length # => 2
   #
   # Note that the model is _not_ yet removed from the database:
+  #
   #   id = post.comments.last.id
   #   Comment.find_by_id(id).nil? # => false
   #
@@ -94,37 +107,13 @@ module ActiveRecord
   #   post.reload.comments.length # => 1
   #
   # Now it _is_ removed from the database:
+  #
   #   Comment.find_by_id(id).nil? # => true
   #
   # === Validation
   #
-  # Validation is performed on the parent as usual, but also on all autosave
-  # enabled associations. If any of the associations fail validation, its
-  # error messages will be applied on the parents errors object and validation
-  # of the parent will fail.
-  #
-  # Consider a Post model with Author which validates the presence of its name
-  # attribute:
-  #
-  #   class Post
-  #     has_one :author, :autosave => true
-  #   end
-  #
-  #   class Author
-  #     validates_presence_of :name
-  #   end
-  #
-  #   post = Post.find(1)
-  #   post.author.name = ''
-  #   post.save # => false
-  #   post.errors # => #<ActiveRecord::Errors:0x174498c @errors={"author.name"=>["can't be blank"]}, @base=#<Post ...>>
-  #
-  # No validations will be performed on the associated models when validations
-  # are skipped for the parent:
-  #
-  #   post = Post.find(1)
-  #   post.author.name = ''
-  #   post.save(:validate => false) # => true
+  # Validations on children records are run or not depending on the <tt>:validate</tt>
+  # option of the association.
   module AutosaveAssociation
     extend ActiveSupport::Concern
 
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 8da4fbcba7..4b550eb446 100644
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -1147,6 +1147,16 @@ MSG
         #   class Person < ActiveRecord::Base
         #     default_scope order('last_name, first_name')
         #   end
+        #
+        # <tt>default_scope</tt> is also applied while creating/building a record. It is not
+        # applied while updating a record.
+        #
+        #   class Article < ActiveRecord::Base
+        #     default_scope where(:published => true)
+        #   end
+        #
+        #   Article.new.published    # => true  
+        #   Article.create.published # => true  
         def default_scope(options = {})
           self.default_scoping << construct_finder_arel(options, default_scoping.pop)
         end
diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb
index 0e560418dc..bffc450f8e 100644
--- a/activerecord/lib/active_record/named_scope.rb
+++ b/activerecord/lib/active_record/named_scope.rb
@@ -88,6 +88,15 @@ module ActiveRecord
       #       end
       #     end
       #   end
+      #
+      # Scopes can also be used while creating/building a record.
+      #
+      #   class Article < ActiveRecord::Base
+      #     scope :published, where(:published => true)
+      #   end
+      #
+      #   Article.published.new.published    # => true  
+      #   Article.published.create.published # => true  
       def scope(name, scope_options = {}, &block)
         name = name.to_sym
         valid_scope_name?(name)
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 7f47a812eb..8295fd68b3 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -41,7 +41,7 @@ module ActiveRecord
 
       # Returns the AggregateReflection object for the named +aggregation+ (use the symbol). 
       #
-      #   Account.reflect_on_aggregation(:balance) #=> the balance AggregateReflection
+      #   Account.reflect_on_aggregation(:balance) # => the balance AggregateReflection
       #
       def reflect_on_aggregation(aggregation)
         reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil