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

20 files changed, 31 insertions, 27 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 6f49e130d8..ad971b71c9 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -414,7 +414,7 @@ module ActionMailer
   # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with
   #   <tt>delivery_method :test</tt>. Most useful for unit and functional testing.
   #
-  # * <tt>deliver_later_queue_name</tt> - The name of the queue used with <tt>deliver_later</tt>
+  # * <tt>deliver_later_queue_name</tt> - The name of the queue used with <tt>deliver_later</tt>.
   class Base < AbstractController::Base
     include DeliveryMethods
     include Previews
diff --git a/actionmailer/lib/action_mailer/gem_version.rb b/actionmailer/lib/action_mailer/gem_version.rb
index ac79788cf0..b35d2ed965 100644
--- a/actionmailer/lib/action_mailer/gem_version.rb
+++ b/actionmailer/lib/action_mailer/gem_version.rb
@@ -1,5 +1,5 @@
 module ActionMailer
-  # Returns the version of the currently loaded Action Mailer as a <tt>Gem::Version</tt>
+  # Returns the version of the currently loaded Action Mailer as a <tt>Gem::Version</tt>.
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
diff --git a/actionmailer/lib/action_mailer/log_subscriber.rb b/actionmailer/lib/action_mailer/log_subscriber.rb
index c2f671fdac..7e9d916b66 100644
--- a/actionmailer/lib/action_mailer/log_subscriber.rb
+++ b/actionmailer/lib/action_mailer/log_subscriber.rb
@@ -29,7 +29,7 @@ module ActionMailer
       end
     end
 
-    # Use the logger configured for ActionMailer::Base
+    # Use the logger configured for ActionMailer::Base.
     def logger
       ActionMailer::Base.logger
     end
diff --git a/actionmailer/lib/action_mailer/message_delivery.rb b/actionmailer/lib/action_mailer/message_delivery.rb
index ff2cb0fd01..622d481113 100644
--- a/actionmailer/lib/action_mailer/message_delivery.rb
+++ b/actionmailer/lib/action_mailer/message_delivery.rb
@@ -60,9 +60,9 @@ module ActionMailer
     #
     # Options:
     #
-    # * <tt>:wait</tt> - Enqueue the email to be delivered with a delay
-    # * <tt>:wait_until</tt> - Enqueue the email to be delivered at (after) a specific date / time
-    # * <tt>:queue</tt> - Enqueue the email on the specified queue
+    # * <tt>:wait</tt> - Enqueue the email to be delivered with a delay.
+    # * <tt>:wait_until</tt> - Enqueue the email to be delivered at (after) a specific date / time.
+    # * <tt>:queue</tt> - Enqueue the email on the specified queue.
     def deliver_later(options={})
       enqueue_delivery :deliver_now, options
     end
diff --git a/actionmailer/lib/action_mailer/preview.rb b/actionmailer/lib/action_mailer/preview.rb
index 25ad7ee721..aab92fe8db 100644
--- a/actionmailer/lib/action_mailer/preview.rb
+++ b/actionmailer/lib/action_mailer/preview.rb
@@ -52,7 +52,7 @@ module ActionMailer
     extend ActiveSupport::DescendantsTracker
 
     class << self
-      # Returns all mailer preview classes
+      # Returns all mailer preview classes.
       def all
         load_previews if descendants.empty?
         descendants
@@ -68,27 +68,27 @@ module ActionMailer
         message
       end
 
-      # Returns all of the available email previews
+      # Returns all of the available email previews.
       def emails
         public_instance_methods(false).map(&:to_s).sort
       end
 
-      # Returns true if the email exists
+      # Returns true if the email exists.
       def email_exists?(email)
         emails.include?(email)
       end
 
-      # Returns true if the preview exists
+      # Returns true if the preview exists.
       def exists?(preview)
         all.any?{ |p| p.preview_name == preview }
       end
 
-      # Find a mailer preview by its underscored class name
+      # Find a mailer preview by its underscored class name.
       def find(preview)
         all.find{ |p| p.preview_name == preview }
       end
 
-      # Returns the underscored name of the mailer preview without the suffix
+      # Returns the underscored name of the mailer preview without the suffix.
       def preview_name
         name.sub(/Preview$/, '').underscore
       end
diff --git a/actionmailer/lib/action_mailer/test_helper.rb b/actionmailer/lib/action_mailer/test_helper.rb
index 4d03a616d2..45cfe16899 100644
--- a/actionmailer/lib/action_mailer/test_helper.rb
+++ b/actionmailer/lib/action_mailer/test_helper.rb
@@ -2,7 +2,7 @@ require 'active_job'
 
 module ActionMailer
   # Provides helper methods for testing Action Mailer, including #assert_emails
-  # and #assert_no_emails
+  # and #assert_no_emails.
   module TestHelper
     include ActiveJob::TestHelper
 
diff --git a/actionpack/lib/action_controller/metal/request_forgery_protection.rb b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
index 5674eef67b..64f6f7cf51 100644
--- a/actionpack/lib/action_controller/metal/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
@@ -90,8 +90,10 @@ module ActionController #:nodoc:
       #
       #   class FooController < ApplicationController
       #     protect_from_forgery except: :index
+      #   end
       #
       # You can disable forgery protection on controller by skipping the verification before_action:
+      #
       #   skip_before_action :verify_authenticity_token
       #
       # Valid Options:
diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index 903dba3eb4..130ba61786 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -540,7 +540,7 @@ module ActionController
     end
     alias_method :delete_if, :reject!
 
-    # Return values that were assigned to the given +keys+. Note that all the
+    # Returns values that were assigned to the given +keys+. Note that all the
     # +Hash+ objects will be converted to <tt>ActionController::Parameters</tt>.
     def values_at(*keys)
       convert_value_to_parameters(@parameters.values_at(*keys))
diff --git a/actionpack/lib/action_dispatch/http/filter_parameters.rb b/actionpack/lib/action_dispatch/http/filter_parameters.rb
index 9c0f39f2e7..9dcab79c3a 100644
--- a/actionpack/lib/action_dispatch/http/filter_parameters.rb
+++ b/actionpack/lib/action_dispatch/http/filter_parameters.rb
@@ -30,12 +30,12 @@ module ActionDispatch
         @filtered_path       = nil
       end
 
-      # Return a hash of parameters with all sensitive data replaced.
+      # Returns a hash of parameters with all sensitive data replaced.
       def filtered_parameters
         @filtered_parameters ||= parameter_filter.filter(parameters)
       end
 
-      # Return a hash of request.env with all sensitive data replaced.
+      # Returns a hash of request.env with all sensitive data replaced.
       def filtered_env
         @filtered_env ||= env_filter.filter(@env)
       end
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 0c50826c63..90b8a29869 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -947,7 +947,7 @@ module ActiveRecord
 
       def migrations_paths
         @migrations_paths ||= ['db/migrate']
-        # just to not break things if someone uses: migration_path = some_string
+        # just to not break things if someone uses: migrations_path = some_string
         Array(@migrations_paths)
       end
 
diff --git a/activerecord/lib/active_record/migration/command_recorder.rb b/activerecord/lib/active_record/migration/command_recorder.rb
index 4c4afb4dbd..0fa665c7e0 100644
--- a/activerecord/lib/active_record/migration/command_recorder.rb
+++ b/activerecord/lib/active_record/migration/command_recorder.rb
@@ -9,6 +9,7 @@ module ActiveRecord
     # * add_index
     # * add_reference
     # * add_timestamps
+    # * change_column
     # * change_column_default (must supply a :from and :to option)
     # * change_column_null
     # * create_join_table
@@ -18,6 +19,7 @@ module ActiveRecord
     # * drop_table (must supply a block)
     # * enable_extension
     # * remove_column (must supply a type)
+    # * remove_columns (must specify at least one column name or more)
     # * remove_foreign_key (must supply a second table)
     # * remove_index
     # * remove_reference
diff --git a/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
index 40811dafc0..e079af594d 100644
--- a/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
@@ -135,7 +135,7 @@ module DateAndTime
     end
     alias :at_end_of_quarter :end_of_quarter
 
-    # Return a new date/time at the beginning of the year.
+    # Returns a new date/time at the beginning of the year.
     #
     #   today = Date.today # => Fri, 10 Jul 2015
     #   today.beginning_of_year # => Thu, 01 Jan 2015
diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb
index f13d09f3ad..ce2dbfb29d 100644
--- a/activesupport/lib/active_support/core_ext/time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/time/calculations.rb
@@ -16,7 +16,7 @@ class Time
       super || (self == Time && other.is_a?(ActiveSupport::TimeWithZone))
     end
 
-    # Return the number of days in the given month.
+    # Returns the number of days in the given month.
     # If no year is specified, it will use the current year.
     def days_in_month(month, year = now.year)
       if month == 2 && ::Date.gregorian_leap?(year)
diff --git a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
index 6572ff78a6..6f0ad445fc 100644
--- a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
+++ b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
@@ -111,7 +111,7 @@ module ActiveSupport
     #
     #   PLANETS = %w(mercury venus earth mars jupiter saturn uranus neptune pluto)
     #
-    #   (In a later update, the orignal implementation of `PLANETS` has been removed.)
+    #   (In a later update, the original implementation of `PLANETS` has been removed.)
     #
     #   PLANETS_POST_2006 = %w(mercury venus earth mars jupiter saturn uranus neptune)
     #   PLANETS = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('PLANETS', 'PLANETS_POST_2006')
diff --git a/activesupport/lib/active_support/multibyte/unicode.rb b/activesupport/lib/active_support/multibyte/unicode.rb
index 5221a6dfb8..586002b03b 100644
--- a/activesupport/lib/active_support/multibyte/unicode.rb
+++ b/activesupport/lib/active_support/multibyte/unicode.rb
@@ -256,7 +256,7 @@ module ActiveSupport
       # * <tt>string</tt> - The string to perform normalization on.
       # * <tt>form</tt> - The form you want to normalize in. Should be one of
       #   the following: <tt>:c</tt>, <tt>:kc</tt>, <tt>:d</tt>, or <tt>:kd</tt>.
-      #   Default is ActiveSupport::Multibyte.default_normalization_form.
+      #   Default is ActiveSupport::Multibyte::Unicode.default_normalization_form.
       def normalize(string, form=nil)
         form ||= @default_normalization_form
         # See http://www.unicode.org/reports/tr15, Table 1
diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb
index 312cce2821..681f659100 100644
--- a/activesupport/lib/active_support/values/time_zone.rb
+++ b/activesupport/lib/active_support/values/time_zone.rb
@@ -388,7 +388,7 @@ module ActiveSupport
       time_now.utc.in_time_zone(self)
     end
 
-    # Return the current date in this time zone.
+    # Returns the current date in this time zone.
     def today
       tzinfo.now.to_date
     end
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md
index 625299c113..f89ac81fd9 100644
--- a/guides/source/contributing_to_ruby_on_rails.md
+++ b/guides/source/contributing_to_ruby_on_rails.md
@@ -318,7 +318,7 @@ $ cd activerecord
 $ bundle exec rake test:sqlite3
 ```
 
-You can now run the tests as you did for `sqlite3`. The tasks are respectively
+You can now run the tests as you did for `sqlite3`. The tasks are respectively:
 
 ```bash
 test:mysql
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index b425eb126a..8dd7f396b8 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -781,7 +781,7 @@ The `javascript_include_tag` helper returns an HTML `script` tag for each source
 
 If you are using Rails with the [Asset Pipeline](asset_pipeline.html) enabled, this helper will generate a link to `/assets/javascripts/` rather than `public/javascripts` which was used in earlier versions of Rails. This link is then served by the asset pipeline.
 
-A JavaScript file within a Rails application or Rails engine goes in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. These locations are explained in detail in the [Asset Organization section in the Asset Pipeline Guide](asset_pipeline.html#asset-organization)
+A JavaScript file within a Rails application or Rails engine goes in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. These locations are explained in detail in the [Asset Organization section in the Asset Pipeline Guide](asset_pipeline.html#asset-organization).
 
 You can specify a full path relative to the document root, or a URL, if you prefer. For example, to link to a JavaScript file that is inside a directory called `javascripts` inside of one of `app/assets`, `lib/assets` or `vendor/assets`, you would do this:
 
diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb
index 175965e565..7916e24af1 100644
--- a/railties/lib/rails/application.rb
+++ b/railties/lib/rails/application.rb
@@ -161,7 +161,7 @@ module Rails
       routes_reloader.reload!
     end
 
-    # Return the application's KeyGenerator
+    # Returns the application's KeyGenerator
     def key_generator
       # number of iterations selected based on consultation with the google security
       # team. Details at https://github.com/rails/rails/pull/6952#issuecomment-7661220
diff --git a/railties/lib/rails/generators/base.rb b/railties/lib/rails/generators/base.rb
index 6fa413f8b0..c72ec400a0 100644
--- a/railties/lib/rails/generators/base.rb
+++ b/railties/lib/rails/generators/base.rb
@@ -302,13 +302,13 @@ module Rails
           default_for_option(Rails::Generators.options, name, options, options[:default])
         end
 
-        # Return default aliases for the option name given doing a lookup in
+        # Returns default aliases for the option name given doing a lookup in
         # Rails::Generators.aliases.
         def self.default_aliases_for_option(name, options)
           default_for_option(Rails::Generators.aliases, name, options, options[:aliases])
         end
 
-        # Return default for the option name given doing a lookup in config.
+        # Returns default for the option name given doing a lookup in config.
         def self.default_for_option(config, name, options, default)
           if generator_name and c = config[generator_name.to_sym] and c.key?(name)
             c[name]