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

9 files changed, 315 insertions, 34 deletions

diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index 54a65ce5f8..8cd7cf0052 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -208,13 +208,16 @@ module ActionView
       #
       # ==== Options
       # * <tt>:sanitize</tt> - If +false+, does not sanitize +text+.
-      # * <tt>:wrapper_tag</tt> - String representing the tag wrapper, defaults to <tt>"p"</tt>
+      # * <tt>:wrapper_tag</tt> - String representing the wrapper tag, defaults to <tt>"p"</tt>
       #
       # ==== Examples
       #   my_text = "Here is some basic text...\n...with a line break."
       #
       #   simple_format(my_text)
       #   # => "<p>Here is some basic text...\n<br />...with a line break.</p>"
+      # 
+      #   simple_format(my_text, {}, :wrapper_tag => "div")
+      #   # => "<div>Here is some basic text...\n<br />...with a line break.</div>"
       #
       #   more_text = "We want to put a paragraph...\n\n...right there."
       #
diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb
index 8dbcf8b225..4ec176e641 100644
--- a/activerecord/lib/active_record/associations/collection_association.rb
+++ b/activerecord/lib/active_record/associations/collection_association.rb
@@ -6,6 +6,15 @@ module ActiveRecord
     # ease the implementation of association proxies that represent
     # collections. See the class hierarchy in AssociationProxy.
     #
+    #   CollectionAssociation:
+    #     HasAndBelongsToManyAssociation => has_and_belongs_to_many
+    #     HasManyAssociation => has_many
+    #       HasManyThroughAssociation + ThroughAssociation => has_many :through
+    #
+    # CollectionAssociation class provides common methods to the collections
+    # defined by +has_and_belongs_to_many+, +has_many+ or +has_many+ with
+    # +:through association+ option.
+    #
     # You need to be careful with assumptions regarding the target: The proxy
     # does not fetch records from the database until it needs them, but new
     # ones created with +build+ are added to the target. So, the target may be
@@ -115,8 +124,9 @@ module ActiveRecord
         create_record(attributes, options, true, &block)
       end
 
-      # Add +records+ to this association. Returns +self+ so method calls may be chained.
-      # Since << flattens its argument list and inserts each record, +push+ and +concat+ behave identically.
+      # Add +records+ to this association. Returns +self+ so method calls may
+      # be chained. Since << flattens its argument list and inserts each record,
+      # +push+ and +concat+ behave identically.
       def concat(*records)
         load_target if owner.new_record?
 
@@ -142,7 +152,7 @@ module ActiveRecord
         end
       end
 
-      # Remove all records from this association
+      # Remove all records from this association.
       #
       # See delete for more info.
       def delete_all
@@ -162,7 +172,7 @@ module ActiveRecord
         end
       end
 
-      # Calculate sum using SQL, not Enumerable
+      # Calculate sum using SQL, not Enumerable.
       def sum(*args)
         if block_given?
           scoped.sum(*args) { |*block_args| yield(*block_args) }
@@ -270,13 +280,16 @@ module ActiveRecord
         load_target.size
       end
 
-      # Equivalent to <tt>collection.size.zero?</tt>. If the collection has
-      # not been already loaded and you are going to fetch the records anyway
-      # it is better to check <tt>collection.length.zero?</tt>.
+      # Returns true if the collection is empty. Equivalent to
+      # <tt>collection.size.zero?</tt>. If the collection has not been already
+      # loaded and you are going to fetch the records anyway it is better to
+      # check <tt>collection.length.zero?</tt>.
       def empty?
         size.zero?
       end
 
+      # Returns true if the collections is not empty.
+      # Equivalent to +!collection.empty?+.
       def any?
         if block_given?
           load_target.any? { |*block_args| yield(*block_args) }
@@ -285,7 +298,8 @@ module ActiveRecord
         end
       end
 
-      # Returns true if the collection has more than 1 record. Equivalent to collection.size > 1.
+      # Returns true if the collection has more than 1 record.
+      # Equivalent to +collection.size > 1+.
       def many?
         if block_given?
           load_target.many? { |*block_args| yield(*block_args) }
@@ -301,8 +315,8 @@ module ActiveRecord
         end
       end
 
-      # Replace this collection with +other_array+
-      # This will perform a diff and delete/add only records that have changed.
+      # Replace this collection with +other_array+. This will perform a diff
+      # and delete/add only records that have changed.
       def replace(other_array)
         other_array.each { |val| raise_on_type_mismatch(val) }
         original_target = load_target.dup
diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index cf4cc98f38..fa316a8c9d 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -33,9 +33,231 @@ module ActiveRecord
     #
     # is computed directly through SQL and does not trigger by itself the
     # instantiation of the actual post records.
-    class CollectionProxy < Relation # :nodoc:
+    class CollectionProxy < Relation
       delegate :target, :load_target, :loaded?, :to => :@association
 
+      ##
+      # :method: first
+      # Returns the first record, or the first +n+ records, from the collection.
+      # If the collection is empty, the first form returns nil, and the second
+      # form returns an empty array.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.first # => #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>
+      #
+      #   person.pets.first(2)
+      #   # => [
+      #   #      #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>
+      #   #    ]
+      #
+      #   another_person_without.pets          # => []
+      #   another_person_without.pets.first    # => nil
+      #   another_person_without.pets.first(3) # => []
+
+      ##
+      # :method: last
+      # Returns the last record, or the last +n+ records, from the collection.
+      # If the collection is empty, the first form returns nil, and the second
+      # form returns an empty array.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.last # => #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #
+      #   person.pets.last(2)
+      #   # => [
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #      #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   another_person_without.pets         # => []
+      #   another_person_without.pets.last    # => nil
+      #   another_person_without.pets.last(3) # => []
+
+      ##
+      # :method: concat
+      # Add one or more records to the collection by setting their foreign keys
+      # to the association's primary key. Since << flattens its argument list and
+      # inserts each record, +push+ and +concat+ behave identically. Returns +self+
+      # so method calls may be chained.
+      #
+      #   class Person < ActiveRecord::Base
+      #     pets :has_many
+      #   end
+      #
+      #   person.pets.size # => 0
+      #   person.pets.concat(Pet.new(name: 'Fancy-Fancy'))
+      #   person.pets.concat(Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo'))
+      #   person.pets.size # => 3
+      #
+      #   person.id # => 1
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.concat([Pet.new(name: 'Brain'), Pet.new(name: 'Benny')])
+      #   person.pets.size # => 5
+
+      ##
+      # :method: replace
+      # Replace this collection with +other_array+. This will perform a diff
+      # and delete/add only records that have changed.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [#<Pet id: 1, name: "Gorby", group: "cats", person_id: 1>]
+      #
+      #   other_pets = [Pet.new(name: 'Puff', group: 'celebrities']
+      #
+      #   person.pets.replace(other_pets)
+      #
+      #   person.pets
+      #   # => [#<Pet id: 2, name: "Puff", group: "celebrities", person_id: 1>]
+      #
+      # If the supplied array has an incorrect association type, it raises
+      # an <tt>ActiveRecord::AssociationTypeMismatch</tt> error:
+      #
+      #   person.pets.replace(["doo", "ggie", "gaga"])
+      #   # => ActiveRecord::AssociationTypeMismatch: Pet expected, got String
+
+      ##
+      # :method: destroy_all
+      # Destroy all the records from this association.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.size # => 3
+      #
+      #   person.pets.destroy_all
+      #
+      #   person.pets.size # => 0
+      #   person.pets      # => []
+
+      ##
+      # :method: empty?
+      # Returns true if the collection is empty.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count  # => 1
+      #   person.pets.empty? # => false
+      #
+      #   person.pets.delete_all
+      #
+      #   person.pets.count  # => 0
+      #   person.pets.empty? # => true
+
+      ##
+      # :method: any?
+      # Returns true if the collection is not empty.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count # => 0
+      #   person.pets.any?  # => false
+      #
+      #   person.pets << Pet.new(name: 'Snoop')
+      #   person.pets.count # => 0
+      #   person.pets.any?  # => true
+      #
+      # You can also pass a block to define criteria. The behaviour
+      # is the same, it returns true if the collection based on the
+      # criteria is not empty.
+      #
+      #   person.pets
+      #   # => [#<Pet name: "Snoop", group: "dogs">]
+      #
+      #   person.pets.any? do |pet|
+      #     pet.group == 'cats'
+      #   end
+      #   # => false
+      #
+      #   person.pets.any? do |pet|
+      #     pet.group == 'dogs'
+      #   end
+      #   # => true
+
+      ##
+      # :method: many?
+      # Returns true if the collection has more than one record.
+      # Equivalent to +collection.size > 1+.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count #=> 1
+      #   person.pets.many? #=> false
+      #
+      #   person.pets << Pet.new(name: 'Snoopy')
+      #   person.pets.count #=> 2
+      #   person.pets.many? #=> true
+      #
+      # You can also pass a block to define criteria. The
+      # behaviour is the same, it returns true if the collection
+      # based on the criteria has more than one record.
+      #
+      #   person.pets
+      #   # => [
+      #   #      #<Pet name: "Gorby", group: "cats">,
+      #   #      #<Pet name: "Puff", group: "cats">,
+      #   #      #<Pet name: "Snoop", group: "dogs">
+      #   #    ]
+      #
+      #   person.pets.many? do |pet|
+      #     pet.group == 'dogs'
+      #   end
+      #   # => false
+      #
+      #   person.pets.many? do |pet|
+      #     pet.group == 'cats'
+      #   end
+      #   # => true
+
+      ##
+      # :method: include?
+      # Returns true if the given object is present in the collection.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets # => [#<Pet id: 20, name: "Snoop">]
+      #
+      #   person.pets.include?(Pet.find(20)) # => true
+      #   person.pets.include?(Pet.find(21)) # => false
       delegate :select, :find, :first, :last,
                :build, :create, :create!,
                :concat, :replace, :delete_all, :destroy_all, :delete, :destroy, :uniq,
@@ -84,11 +306,57 @@ module ActiveRecord
       end
       alias_method :to_a, :to_ary
 
+      # Adds one or more +records+ to the collection by setting their foreign keys
+      # to the association‘s primary key. Returns +self+, so several appends may be
+      # chained together.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.size # => 0
+      #   person.pets << Pet.new(name: 'Fancy-Fancy')
+      #   person.pets << [Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo')]
+      #   person.pets.size # => 3
+      #
+      #   person.id # => 1
+      #   person.pets
+      #   # => [
+      #   #      #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #      #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
       def <<(*records)
         proxy_association.concat(records) && self
       end
       alias_method :push, :<<
 
+      # Removes every object from the collection. This does not destroy
+      # the objects, it sets their foreign keys to +NULL+. Returns +self+
+      # so methods can be chained.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets       # => [#<Pet id: 1, name: "Snoop", group: "dogs", person_id: 1>]
+      #   person.pets.clear # => []
+      #   person.pets.size  # => 0
+      #
+      #   Pet.find(1) # => #<Pet id: 1, name: "Snoop", group: "dogs", person_id: nil>
+      #
+      # If they are associated with +dependent: :destroy+ option, it deletes
+      # them directly from the database.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets, dependent: :destroy
+      #   end
+      #
+      #   person.pets       # => [#<Pet id: 2, name: "Gorby", group: "cats", person_id: 2>]
+      #   person.pets.clear # => []
+      #   person.pets.size  # => 0
+      #
+      #   Pet.find(2) # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=2
       def clear
         delete_all
         self
diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb
index b2ed606e5f..f2833fbf3c 100644
--- a/activerecord/lib/active_record/core.rb
+++ b/activerecord/lib/active_record/core.rb
@@ -127,7 +127,7 @@ module ActiveRecord
         object.is_a?(self)
       end
 
-      # Returns an instance of <tt>Arel::Table</tt> loaded with the curent table name.
+      # Returns an instance of <tt>Arel::Table</tt> loaded with the current table name.
       #
       #   class Post < ActiveRecord::Base
       #     scope :published_and_commented, published.and(self.arel_table[:comments_count].gt(0))
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index 779e052e3c..05ced3299b 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -370,17 +370,12 @@ module ActiveRecord
       end
     end
 
-    # Deletes the records matching +conditions+ without instantiating the records first, and hence not
-    # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that
-    # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations
-    # though, in particular <tt>:dependent</tt> rules defined on associations are not honored. Returns
-    # the number of rows affected.
-    #
-    # ==== Parameters
-    #
-    # * +conditions+ - Conditions are specified the same way as with +find+ method.
-    #
-    # ==== Example
+    # Deletes the records matching +conditions+ without instantiating the records
+    # first, and hence not calling the +destroy+ method nor invoking callbacks. This
+    # is a single SQL DELETE statement that goes straight to the database, much more
+    # efficient than +destroy_all+. Be careful with relations though, in particular
+    # <tt>:dependent</tt> rules defined on associations are not honored. Returns the
+    # number of rows affected.
     #
     #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
     #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
@@ -389,6 +384,11 @@ module ActiveRecord
     # Both calls delete the affected posts all at once with a single DELETE statement.
     # If you need to destroy dependent associations or call your <tt>before_*</tt> or
     # +after_destroy+ callbacks, use the +destroy_all+ method instead.
+    #
+    # If a limit scope is supplied, +delete_all+ raises an ActiveRecord error:
+    #
+    #   Post.limit(100).delete_all
+    #   # => ActiveRecord::ActiveRecordError: delete_all doesn't support limit scope
     def delete_all(conditions = nil)
       raise ActiveRecordError.new("delete_all doesn't support limit scope") if self.limit_value
 
diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile
index 6443255f5d..80faffa49c 100644
--- a/guides/source/active_support_core_extensions.textile
+++ b/guides/source/active_support_core_extensions.textile
@@ -84,7 +84,7 @@ The following values are considered to be blank in a Rails application:
 
 * any other object that responds to +empty?+ and it is empty.
 
-INFO: In Ruby 1.9 the predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. In Ruby 1.8 whitespace is considered to be <tt>\s</tt> together with the ideographic space U+3000.
+INFO: The predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace.
 
 WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank.
 
@@ -2093,7 +2093,7 @@ h5. +to_formatted_s+
 
 The method +to_formatted_s+ acts like +to_s+ by default.
 
-If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs, though technically any object in Ruby 1.8 responds to +id+ indeed. Returned strings are:
+If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs. Returned strings are:
 
 <ruby>
 [].to_formatted_s(:db)            # => "null"
@@ -2869,8 +2869,6 @@ d.prev_year               # => Sun, 28 Feb 1999
 d.next_year               # => Wed, 28 Feb 2001
 </ruby>
 
-Active Support defines these methods as well for Ruby 1.8.
-
 +prev_year+ is aliased to +last_year+.
 
 h6. +prev_month+, +next_month+
@@ -2892,8 +2890,6 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000
 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000
 </ruby>
 
-Active Support defines these methods as well for Ruby 1.8.
-
 +prev_month+ is aliased to +last_month+.
 
 h6. +beginning_of_week+, +end_of_week+
diff --git a/guides/source/engines.textile b/guides/source/engines.textile
index 880be57fb5..c35305a822 100644
--- a/guides/source/engines.textile
+++ b/guides/source/engines.textile
@@ -738,7 +738,7 @@ This tells sprockets to add you engine assets when +rake assets:precompile+ is r
 You can define assets for precompilation in +engine.rb+
 
 <ruby>
-initializer do |app|
+initializer "blorgh.assets.precompile" do |app|
   app.config.assets.precompile += %w(admin.css admin.js)
 end
 </ruby>
diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile
index 19bd106ff0..e25dac22da 100644
--- a/guides/source/getting_started.textile
+++ b/guides/source/getting_started.textile
@@ -678,7 +678,7 @@ end
 
 This change will ensure that all changes made through HTML forms can edit the content of the text and title fields.
 It will not be possible to define any other field value through forms. You can still define them by calling the `field=` method of course.
-Accessible attributes and the mass assignment probem is covered in details in the "Security guide":security.html#mass-assignment
+Accessible attributes and the mass assignment problem is covered in details in the "Security guide":security.html#mass-assignment
 
 h4. Adding Some Validation
 
diff --git a/guides/source/rails_on_rack.textile b/guides/source/rails_on_rack.textile
index ff862273fd..d8910cf1d0 100644
--- a/guides/source/rails_on_rack.textile
+++ b/guides/source/rails_on_rack.textile
@@ -152,9 +152,9 @@ You can swap an existing middleware in the middleware stack using +config.middle
 config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions
 </ruby>
 
-h5. Middleware Stack is an Array
+h5. Middleware Stack is an Enumerable
 
-The middleware stack behaves just like a normal +Array+. You can use any +Array+ methods to insert, reorder, or remove items from the stack. Methods described in the section above are just convenience methods.
+The middleware stack behaves just like a normal +Enumerable+. You can use any +Enumerable+ methods to manipulate or interrogate the stack. The middleware stack also implements some +Array+ methods including <tt>[]</tt>, +unshift+ and +delete+. Methods described in the section above are just convenience methods.
 
 Append following lines to your application configuration: