diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 73c0900c8b..cf75d2dc9b 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 has_one, belongs_to,
# has_many, or has_and_belongs_to_many 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
#
diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb
index 2c7afe3c9f..c661d68869 100644
--- a/activerecord/lib/active_record/autosave_association.rb
+++ b/activerecord/lib/active_record/autosave_association.rb
@@ -18,6 +18,10 @@ 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.
#
+ # Do note that :autosave => false is not same as not declaring :autosave
+ # option. When :autosave option is not declared then it works in
+ # theoreticall :new_only mode. Look at has_many example discused below for details.
+ #
# === One-to-one Example
#
# class Post
@@ -57,27 +61,45 @@ module ActiveRecord
#
# === One-to-many Example
#
+ # When autosave is not declared then also children will get saved when parent is saved
+ # in certain conditions.
+ #
# Consider a Post model with many Comments:
#
# class Post
+ # has_many :comments # :autosave option is no declared
+ # end
+ #
+ # post = Post.new(:title => 'ruby rocks')
+ # post.comments.build(:body => 'hello world')
+ # post.save #=> will save both post and comment
+ #
+ # post = Post.create(:title => 'ruby rocks')
+ # post.comments.build(:body => 'hello world')
+ # post.save #=> will save both post and comment
+ #
+ # post = Post.create(:title => 'ruby rocks')
+ # post.comments.create(:body => 'hello world')
+ # post.save #=> will save both post and comment
+ #
+ # post = Post.create(:title => 'ruby rocks')
+ # post.comments.build(:body => 'hello world')
+ # post.comments[0].body = 'hi everyone'
+ # post.save #=> will save both post and comment and comment will have 'hi everyone'
+ #
+ # In the above cases even without autosave option children got updated.
+ #
+ # class Post
# has_many :comments, :autosave => true
# end
#
- # Saving changes to the parent and its associated model can now be performed
- # automatically _and_ atomically:
+ # :autosave declaration is required if an attempt is made to change an existing
+ # associatin in memory.
#
- # 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.title = "On the migration of ducks"
- # post.comments.last.body = "Actually, your article should be named differently. [UPDATED]: You are right, thanks."
- #
- # 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."
+ # post = Post.create(:title => 'ruby rocks')
+ # post.comments.create(:body => 'hello world')
+ # post.comments[0].body = 'hi everyone'
+ # post.save #=> will save both post and comment and comment will have 'hi everyone'
#
# Destroying one of the associated models members, as part of the parent's
# save action, is as simple as marking it for destruction:
@@ -125,6 +147,8 @@ module ActiveRecord
# post = Post.find(1)
# post.author.name = ''
# post.save(:validate => false) # => true
+ #
+ # Note that validation will be perfomend even if autosave option is not declared.
module AutosaveAssociation
extend ActiveSupport::Concern