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

actionmailer/README.rdoc

@@ -67,12 +67,12 @@ simply call the method and optionally call +deliver+ on the return value.
 
 Calling the method returns a Mail Message object:
 
-  message = Notifier.welcome  # => Returns a Mail::Message object
-  message.deliver             # => delivers the email
+  message = Notifier.welcome("david@loudthinking.com")  # => Returns a Mail::Message object
+  message.deliver                                       # => delivers the email
 
 Or you can just chain the methods together like:
 
-  Notifier.welcome.deliver    # Creates the email and sends it immediately
+  Notifier.welcome("david@loudthinking.com").deliver    # Creates the email and sends it immediately
 
 == Setting defaults
 
@@ -119,8 +119,7 @@ trivial case like this:
   rails runner 'Mailman.receive(STDIN.read)'
 
 However, invoking Rails in the runner for each mail to be received is very resource intensive.  A single
-instance of Rails should be run within a daemon, if it is going to be utilized to process more than just
-a limited number of email.
+instance of Rails should be run within a daemon, if it is going to process more than just a limited amount of email.
 
 == Configuration
 

actionmailer/lib/action_mailer/base.rb

@@ -334,8 +334,8 @@ module ActionMailer
   #     and starts to use it.
   #   * <tt>:openssl_verify_mode</tt> - When using TLS, you can set how OpenSSL checks the certificate. This is
   #     really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name
-  #     of an OpenSSL verify constant ('none', 'peer', 'client_once','fail_if_no_peer_cert') or directly the
-  #     constant  (OpenSSL::SSL::VERIFY_NONE, OpenSSL::SSL::VERIFY_PEER,...).
+  #     of an OpenSSL verify constant ('none', 'peer', 'client_once', 'fail_if_no_peer_cert') or directly the
+  #     constant  (OpenSSL::SSL::VERIFY_NONE, OpenSSL::SSL::VERIFY_PEER, ...).
   #
   # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
   #   * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
@@ -596,9 +596,9 @@ def attachments
     # class method:
     #
     #  class Notifier < ActionMailer::Base
-    #    self.default from: 'no-reply@test.lindsaar.net',
-    #                 bcc: 'email_logger@test.lindsaar.net',
-    #                 reply_to: 'bounces@test.lindsaar.net'
+    #    default from: 'no-reply@test.lindsaar.net',
+    #            bcc: 'email_logger@test.lindsaar.net',
+    #            reply_to: 'bounces@test.lindsaar.net'
     #  end
     #
     # If you need other headers not listed above, you can either pass them in

actionpack/lib/action_view/helpers/form_tag_helper.rb

@@ -81,7 +81,7 @@ def form_tag(url_for_options = {}, options = {}, &block)
       # ==== Options
       # * <tt>:multiple</tt> - If set to true the selection will allow multiple choices.
       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
-      # * <tt>:include_blank</tt> - If set to true, an empty option will be create
+      # * <tt>:include_blank</tt> - If set to true, an empty option will be created.
       # * <tt>:prompt</tt> - Create a prompt option with blank value and the text asking user to select something
       # * Any other key creates standard HTML attributes for the tag.
       #

activerecord/lib/active_record/autosave_association.rb

@@ -17,7 +17,8 @@ module ActiveRecord
   # 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.
+  # When the <tt>:autosave</tt> option is not present then new association records are
+  # saved but the updated association records are not saved.
   #
   # == Validation
   #

activerecord/lib/active_record/persistence.rb

@@ -99,6 +99,9 @@ def persisted?
     # <tt>before_*</tt> callbacks return +false+ the action is cancelled and
     # +save+ returns +false+. See ActiveRecord::Callbacks for further
     # details.
+    #
+    # Attributes marked as readonly are silently ignored if the record is
+    # being updated.
     def save(*)
       create_or_update
     rescue ActiveRecord::RecordInvalid
@@ -118,6 +121,9 @@ def save(*)
     # the <tt>before_*</tt> callbacks return +false+ the action is cancelled
     # and <tt>save!</tt> raises ActiveRecord::RecordNotSaved. See
     # ActiveRecord::Callbacks for further details.
+    #
+    # Attributes marked as readonly are silently ignored if the record is
+    # being updated.
     def save!(*)
       create_or_update || raise(RecordNotSaved)
     end
@@ -204,6 +210,8 @@ def becomes!(klass)
     # * updated_at/updated_on column is updated if that column is available.
     # * Updates all the attributes that are dirty in this object.
     #
+    # This method raises an +ActiveRecord::ActiveRecordError+  if the
+    # attribute is marked as readonly.
     def update_attribute(name, value)
       name = name.to_s
       verify_readonly_attribute(name)

activerecord/lib/active_record/validations/associated.rb

@@ -9,8 +9,8 @@ def validate_each(record, attribute, value)
     end
 
     module ClassMethods
-      # Validates whether the associated object or objects are all valid
-      # themselves. Works with any kind of association.
+      # Validates whether the associated object or objects are all valid.
+      # Works with any kind of association.
       #
       #   class Book < ActiveRecord::Base
       #     has_many :pages

activesupport/lib/active_support/core_ext/array/wrap.rb

@@ -15,12 +15,12 @@ class Array
   #
   # * If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt>
   #   moves on to try +to_a+ if the returned value is +nil+, but <tt>Array.wrap</tt> returns
-  #   such a +nil+ right away.
+  #   +nil+ right away.
   # * If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt>
   #   raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value.
-  # * It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
+  # * It does not call +to_a+ on the argument, but returns an empty array if argument is +nil+.
   #
-  # The last point is particularly worth comparing for some enumerables:
+  # The second point is easily explained with some enumerables:
   #
   #   Array(foo: :bar)      # => [[:foo, :bar]]
   #   Array.wrap(foo: :bar) # => [{:foo=>:bar}]
@@ -29,10 +29,10 @@ class Array
   #
   #   [*object]
   #
-  # which for +nil+ returns <tt>[]</tt>, and calls to <tt>Array(object)</tt> otherwise.
+  # which returns <tt>[]</tt> for +nil+, but calls to <tt>Array(object)</tt> otherwise.
   #
-  # Thus, in this case the behavior may be different for +nil+, and the differences with
-  # <tt>Kernel#Array</tt> explained above apply to the rest of <tt>object</tt>s.
+  # The differences with <tt>Kernel#Array</tt> explained above
+  # apply to the rest of <tt>object</tt>s.
   def self.wrap(object)
     if object.nil?
       []

guides/bug_report_templates/active_record_gem.rb

@@ -1,5 +1,5 @@
 # Activate the gem you are reporting the issue against.
-gem 'activerecord', '3.2.11'
+gem 'activerecord', '3.2.13'
 require 'active_record'
 require 'minitest/autorun'
 require 'logger'

guides/source/2_2_release_notes.md

@@ -200,7 +200,7 @@ Active Record association proxies now respect the scope of methods on the proxie
 * More information:
     * [Rails 2.2 Change: Private Methods on Association Proxies are Private](http://afreshcup.com/2008/10/24/rails-22-change-private-methods-on-association-proxies-are-private/)
 
-### Other ActiveRecord Changes
+### Other Active Record Changes
 
 * `rake db:migrate:redo` now accepts an optional VERSION to target that specific migration to redo
 * Set `config.active_record.timestamped_migrations = false` to have migrations with numeric prefix instead of UTC timestamp.

guides/source/2_3_release_notes.md

@@ -134,7 +134,7 @@ Rails 2.3 will introduce the notion of _default scopes_ similar to named scopes,
 
 ### Batch Processing
 
-You can now process large numbers of records from an ActiveRecord model with less pressure on memory by using `find_in_batches`:
+You can now process large numbers of records from an Active Record model with less pressure on memory by using `find_in_batches`:
 
 ```ruby
 Customer.find_in_batches(:conditions => {:active => true}) do |customer_group|
@@ -504,7 +504,7 @@ A lot of folks have adopted the notion of using try() to attempt operations on o
 
 ### Swappable Parsers for XMLmini
 
-The support for XML parsing in ActiveSupport has been made more flexible by allowing you to swap in different parsers. By default, it uses the standard REXML implementation, but you can easily specify the faster LibXML or Nokogiri implementations for your own applications, provided you have the appropriate gems installed:
+The support for XML parsing in Active Support has been made more flexible by allowing you to swap in different parsers. By default, it uses the standard REXML implementation, but you can easily specify the faster LibXML or Nokogiri implementations for your own applications, provided you have the appropriate gems installed:
 
 ```ruby
 XmlMini.backend = 'LibXML'

guides/source/3_0_release_notes.md

@@ -79,7 +79,7 @@ Creating a Rails 3.0 application
 --------------------------------
 
 ```bash
-# You should have the 'rails' rubygem installed
+# You should have the 'rails' RubyGem installed
 $ rails new myapp
 $ cd myapp
 ```
@@ -475,7 +475,7 @@ As well as the following deprecations:
 * `named_scope` in an Active Record class is deprecated and has been renamed to just `scope`.
 * In `scope` methods, you should move to using the relation methods, instead of a `:conditions => {}` finder method, for example `scope :since, lambda {|time| where("created_at > ?", time) }`.
 * `save(false)` is deprecated, in favor of `save(:validate => false)`.
-* I18n error messages for ActiveRecord should be changed from :en.activerecord.errors.template to `:en.errors.template`.
+* I18n error messages for Active Record should be changed from :en.activerecord.errors.template to `:en.errors.template`.
 * `model.errors.on` is deprecated in favor of `model.errors[]`
 * validates_presence_of => validates... :presence => true
 * `ActiveRecord::Base.colorize_logging` and `config.active_record.colorize_logging` are deprecated in favor of `Rails::LogSubscriber.colorize_logging` or `config.colorize_logging`
@@ -580,7 +580,7 @@ Action Mailer has been given a new API with TMail being replaced out with the ne
 
 * All mailers are now in `app/mailers` by default.
 * Can now send email using new API with three methods: `attachments`, `headers` and `mail`.
-* ActionMailer now has native support for inline attachments using the `attachments.inline` method.
+* Action Mailer now has native support for inline attachments using the `attachments.inline` method.
 * Action Mailer emailing methods now return `Mail::Message` objects, which can then be sent the `deliver` message to send itself.
 * All delivery methods are now abstracted out to the Mail gem.
 * The mail delivery method can accept a hash of all valid mail header fields with their value pair.

guides/source/3_1_release_notes.md

@@ -137,7 +137,7 @@ Creating a Rails 3.1 application
 --------------------------------
 
 ```bash
-# You should have the 'rails' rubygem installed
+# You should have the 'rails' RubyGem installed
 $ rails new myapp
 $ cd myapp
 ```

guides/source/3_2_release_notes.md

@@ -67,7 +67,7 @@ Creating a Rails 3.2 application
 --------------------------------
 
 ```bash
-# You should have the 'rails' rubygem installed
+# You should have the 'rails' RubyGem installed
 $ rails new myapp
 $ cd myapp
 ```
@@ -101,7 +101,7 @@ Rails 3.2 comes with a development mode that's noticeably faster. Inspired by [A
 
 ### Automatic Query Explains
 
-Rails 3.2 comes with a nice feature that explains queries generated by ARel by defining an `explain` method in `ActiveRecord::Relation`. For example, you can run something like `puts Person.active.limit(5).explain` and the query ARel produces is explained. This allows to check for the proper indexes and further optimizations.
+Rails 3.2 comes with a nice feature that explains queries generated by Arel by defining an `explain` method in `ActiveRecord::Relation`. For example, you can run something like `puts Person.active.limit(5).explain` and the query Arel produces is explained. This allows to check for the proper indexes and further optimizations.
 
 Queries that take more than half a second to run are *automatically* explained in the development mode. This threshold, of course, can be changed.
 
@@ -189,7 +189,7 @@ Action Pack
 
 * form\_for is changed to use "#{action}\_#{as}" as the css class and id if `:as` option is provided. Earlier versions used "#{as}\_#{action}".
 
-* `ActionController::ParamsWrapper` on ActiveRecord models now only wrap `attr_accessible` attributes if they were set. If not, only the attributes returned by the class method `attribute_names` will be wrapped. This fixes the wrapping of nested attributes by adding them to `attr_accessible`.
+* `ActionController::ParamsWrapper` on Active Record models now only wrap `attr_accessible` attributes if they were set. If not, only the attributes returned by the class method `attribute_names` will be wrapped. This fixes the wrapping of nested attributes by adding them to `attr_accessible`.
 
 * Log "Filter chain halted as CALLBACKNAME rendered or redirected" every time a before callback halts.
 

guides/source/4_0_release_notes.md

@@ -22,7 +22,7 @@ Creating a Rails 4.0 application
 --------------------------------
 
 ```
- You should have the 'rails' rubygem installed
+ You should have the 'rails' RubyGem installed
 $ rails new myapp
 $ cd myapp
 ```
@@ -113,7 +113,8 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ
 
 *   Add `ActiveModel::ForbiddenAttributesProtection`, a simple module to protect attributes from mass assignment when non-permitted attributes are passed.
 
-*   Added `ActiveModel::Model`, a mixin to make Ruby objects work with ActionPack out of box.
+*   Added `ActiveModel::Model`, a mixin to make Ruby objects work with
+    Action Pack out of box.
 
 ### Deprecations
 
@@ -142,7 +143,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ
 
 *   Deprecates the compatibility method Module#local_constant_names, use Module#local_constants instead (which returns symbols).
 
-*   BufferedLogger is deprecated.  Use ActiveSupport::Logger, or the logger from Ruby stdlib.
+*   BufferedLogger is deprecated.  Use ActiveSupport::Logger, or the logger from Ruby standard library.
 
 *   Deprecate `assert_present` and `assert_blank` in favor of `assert object.blank?` and `assert object.present?`
 

guides/source/action_controller_overview.md

@@ -148,7 +148,7 @@ Also, if you've turned on `config.wrap_parameters` in your initializer or callin
 And assume that you're sending the data to `CompaniesController`, it would then be wrapped in `:company` key like this:
 
 ```ruby
-{ :name => "acme", :address => "123 Carrot Street", :company => { :name => "acme", :address => "123 Carrot Street" } }
+{ name: "acme", address: "123 Carrot Street", company: { name: "acme", address: "123 Carrot Street" } }
 ```
 
 You can customize the name of the key or specific parameters you want to wrap by consulting the [API documentation](http://api.rubyonrails.org/classes/ActionController/ParamsWrapper.html)
@@ -246,7 +246,7 @@ To declare that the value in `params` must be an array of permitted
 scalar values map the key to an empty array:
 
 ```ruby
-params.permit(:id => [])
+params.permit(id: [])
 ```
 
 To whitelist an entire hash of parameters, the `permit!` method can be
@@ -266,9 +266,9 @@ mass-assigned.
 You can also use permit on nested parameters, like:
 
 ```ruby
-params.permit(:name, {:emails => []},
-              :friends => [ :name,
-                            { :family => [ :name ], :hobbies => [] }])
+params.permit(:name, { emails: [] },
+              friends: [ :name,
+                         { family: [ :name ], hobbies: [] }])
 ```
 
 This declaration whitelists the `name`, `emails` and `friends`

guides/source/action_mailer_basics.md

@@ -1,7 +1,7 @@
 Action Mailer Basics
 ====================
 
-This guide should provide you with all you need to get started in sending and
+This guide provides you with all you need to get started in sending and
 receiving emails from and to your application, and many internals of Action
 Mailer. It also covers how to test your mailers.
 

guides/source/active_record_querying.md

@@ -707,7 +707,7 @@ Post.order('id DESC').limit(20).unscope(:order, :limit) = Post.all
 You can additionally unscope specific where clauses. For example:
 
 ```ruby
-Post.where(:id => 10).limit(1).unscope(:where => :id, :limit).order('id DESC') = Post.order('id DESC')
+Post.where(:id => 10).limit(1).unscope(where: :id, :limit).order('id DESC') = Post.order('id DESC')
 ```
 
 ### `only`
@@ -1301,6 +1301,11 @@ Client.unscoped {
 Dynamic Finders
 ---------------
 
+NOTE: Dynamic finders have been deprecated in Rails 4.0 and will be
+removed in Rails 4.1. The best practice is to use Active Record scopes
+instead. You can find the deprecation gem at
+https://github.com/rails/activerecord-deprecated_finders
+
 For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called `first_name` on your `Client` model for example, you get `find_by_first_name` for free from Active Record. If you have a `locked` field on the `Client` model, you also get `find_by_locked` and methods.
 
 You can specify an exclamation point (`!`) on the end of the dynamic finders to get them to raise an `ActiveRecord::RecordNotFound` error if they do not return any records, like `Client.find_by_name!("Ryan")`

guides/source/active_record_validations.md

@@ -434,7 +434,7 @@ end
 
 Note that the default error messages are plural (e.g., "is too short (minimum
 is %{count} characters)"). For this reason, when `:minimum` is 1 you should
-provide a personalized message or use `validates_presence_of` instead. When
+provide a personalized message or use `presence: true` instead. When
 `:in` or `:within` have a lower limit of 1, you should either provide a
 personalized message or call `presence` prior to `length`.
 
@@ -768,6 +768,7 @@ class Person < ActiveRecord::Base
   validates :name, presence: true, on: :save
 end
 ```
+The last line is in review state and as of now, it is not running in any version of Rails 3.2.x as discussed in this [issue](https://github.com/rails/rails/issues/10248)
 
 Strict Validations
 ------------------

guides/source/active_support_core_extensions.md

@@ -10,7 +10,7 @@ After reading this guide, you will know:
 * What Core Extensions are.
 * How to load all extensions.
 * How to cherry-pick just the extensions you want.
-* What extensions ActiveSupport provides.
+* What extensions Active Support provides.
 
 --------------------------------------------------------------------------------
 
@@ -2216,7 +2216,9 @@ NOTE: Defined in `active_support/core_ext/array/conversions.rb`.
 
 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 `:db` as argument. That's typically used with collections of ARs. Returned strings are:
+If the array contains items that respond to `id`, however, the symbol
+`:db` may be passed as argument. That's typically used with
+collections of Active Record objects. Returned strings are:
 
 ```ruby
 [].to_formatted_s(:db)            # => "null"
@@ -2372,7 +2374,8 @@ NOTE: Defined in `active_support/core_ext/array/wrap.rb`.
 
 ### Duplicating
 
-The method `Array.deep_dup` duplicates itself and all objects inside recursively with ActiveSupport method `Object#deep_dup`. It works like `Array#map` with sending `deep_dup` method to each object inside.
+The method `Array.deep_dup` duplicates itself and all objects inside
+recursively with Active Support method `Object#deep_dup`. It works like `Array#map` with sending `deep_dup` method to each object inside.
 
 ```ruby
 array = [1, [2, 3]]
@@ -2593,7 +2596,8 @@ NOTE: Defined in `active_support/core_ext/hash/deep_merge.rb`.
 
 ### Deep duplicating
 
-The method `Hash.deep_dup` duplicates itself and all keys and values inside recursively with ActiveSupport method `Object#deep_dup`. It works like `Enumerator#each_with_object` with sending `deep_dup` method to each pair inside.
+The method `Hash.deep_dup` duplicates itself and all keys and values
+inside recursively with Active Support method `Object#deep_dup`. It works like `Enumerator#each_with_object` with sending `deep_dup` method to each pair inside.
 
 ```ruby
 hash = { a: 1, b: { c: 2, d: [3, 4] } }