Merge branch 'master' of github.com:lifo/docrails

Conflicts:
	actionmailer/lib/action_mailer/base.rb
	activesupport/lib/active_support/configurable.rb
	activesupport/lib/active_support/core_ext/module/deprecation.rb
	guides/source/action_controller_overview.md
	guides/source/active_support_core_extensions.md
	guides/source/ajax_on_rails.textile
	guides/source/association_basics.textile
	guides/source/upgrading_ruby_on_rails.md

While resolving conflicts, I have chosen to ignore changes done in
docrails at some places - these will be most likely 1.9 hash syntax
changes.

3 files changed, 28 insertions, 20 deletions

diff --git a/activerecord/README.rdoc b/activerecord/README.rdoc
index d080e0b0f5..cc8942809c 100644
--- a/activerecord/README.rdoc
+++ b/activerecord/README.rdoc
@@ -49,10 +49,10 @@ A short rundown of some of the major features:
 * Aggregations of value objects.
 
    class Account < ActiveRecord::Base
-     composed_of :balance, :class_name => "Money",
-                 :mapping => %w(balance amount)
+     composed_of :balance, class_name: 'Money',
+                 mapping: %w(balance amount)
      composed_of :address,
-                 :mapping => [%w(address_street street), %w(address_city city)]
+                 mapping: [%w(address_street street), %w(address_city city)]
    end
 
   {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
@@ -84,7 +84,7 @@ A short rundown of some of the major features:
 
    class CommentObserver < ActiveRecord::Observer
      def after_create(comment) # is called just after Comment#save
-       CommentMailer.new_comment_email("david@loudthinking.com", comment).deliver
+       CommentMailer.new_comment_email('david@loudthinking.com', comment).deliver
      end
    end
 
@@ -124,15 +124,15 @@ A short rundown of some of the major features:
 * Database abstraction through simple adapters.
 
     # connect to SQLite3
-    ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "dbfile.sqlite3")
+    ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: 'dbfile.sqlite3')
 
     # connect to MySQL with authentication
     ActiveRecord::Base.establish_connection(
-      :adapter  => "mysql2",
-      :host     => "localhost",
-      :username => "me",
-      :password => "secret",
-      :database => "activerecord"
+      adapter:  'mysql2',
+      host:     'localhost',
+      username: 'me',
+      password: 'secret',
+      database: 'activerecord'
     )
 
   {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for
@@ -144,7 +144,7 @@ A short rundown of some of the major features:
 * Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc].
 
     ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT)
-    ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
+    ActiveRecord::Base.logger = Log4r::Logger.new('Application Log')
 
 
 * Database agnostic schema management with Migrations.
@@ -159,7 +159,7 @@ A short rundown of some of the major features:
           t.integer :position
         end
 
-        SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
+        SystemSetting.create name: 'notice', label: 'Use notice?', value: 1
       end
 
       def down
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 60b7118d7e..258d602afa 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -950,6 +950,11 @@ module ActiveRecord
     # specific association types. When no option is given, the behaviour is to do nothing
     # with the associated records when destroying a record.
     #
+    # Note that <tt>:dependent</tt> is implemented using Rails' callback
+    # system, which works by processing callbacks in order. Therefore, other
+    # callbacks declared either before or after the <tt>:dependent</tt> option
+    # can affect what it does.
+    #
     # === Delete or destroy?
     #
     # +has_many+ and +has_and_belongs_to_many+ associations have the methods <tt>destroy</tt>,
@@ -1095,7 +1100,10 @@ module ActiveRecord
       #   Specify the method that returns the primary key used for the association. By default this is +id+.
       # [:dependent]
       #   Controls what happens to the associated objects when
-      #   their owner is destroyed:
+      #   their owner is destroyed. Note that these are implemented as
+      #   callbacks, and Rails executes callbacks in order. Therefore, other
+      #   similar callbacks may affect the :dependent behavior, and the
+      #   :dependent behavior may affect other callbacks.
       #
       #   * <tt>:destroy</tt> causes all the associated objects to also be destroyed
       #   * <tt>:delete_all</tt> causes all the asssociated objects to be deleted directly from the database (so callbacks will not execute)
diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb
index c32e0d6bf8..bf95ccb298 100644
--- a/activerecord/lib/active_record/timestamp.rb
+++ b/activerecord/lib/active_record/timestamp.rb
@@ -40,13 +40,13 @@ module ActiveRecord
       config_attribute :record_timestamps, instance_writer: true
     end
 
-    def initialize_dup(other)
+    def initialize_dup(other) # :nodoc:
       clear_timestamp_attributes
     end
 
   private
 
-    def create #:nodoc:
+    def create
       if self.record_timestamps
         current_time = current_time_from_proper_timezone
 
@@ -60,7 +60,7 @@ module ActiveRecord
       super
     end
 
-    def update(*args) #:nodoc:
+    def update(*args)
       if should_record_timestamps?
         current_time = current_time_from_proper_timezone
 
@@ -89,19 +89,19 @@ module ActiveRecord
       timestamp_attributes_for_create_in_model + timestamp_attributes_for_update_in_model
     end
 
-    def timestamp_attributes_for_update #:nodoc:
+    def timestamp_attributes_for_update
       [:updated_at, :updated_on]
     end
 
-    def timestamp_attributes_for_create #:nodoc:
+    def timestamp_attributes_for_create
       [:created_at, :created_on]
     end
 
-    def all_timestamp_attributes #:nodoc:
+    def all_timestamp_attributes
       timestamp_attributes_for_create + timestamp_attributes_for_update
     end
 
-    def current_time_from_proper_timezone #:nodoc:
+    def current_time_from_proper_timezone
       self.class.default_timezone == :utc ? Time.now.utc : Time.now
     end