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

17 files changed, 74 insertions, 40 deletions

diff --git a/actionpack/lib/abstract_controller/base.rb b/actionpack/lib/abstract_controller/base.rb
index 51c661f735..2c8a67db09 100644
--- a/actionpack/lib/abstract_controller/base.rb
+++ b/actionpack/lib/abstract_controller/base.rb
@@ -12,7 +12,7 @@ module AbstractController
   class ActionNotFound < StandardError
   end
 
-  # <tt>AbstractController::Base</tt> is a low-level API. Nobody should be
+  # AbstractController::Base is a low-level API. Nobody should be
   # using it directly, and subclasses (like ActionController::Base) are
   # expected to provide their own +render+ method, since rendering means
   # different things depending on the context.
@@ -69,9 +69,9 @@ module AbstractController
 
       # A list of method names that should be considered actions. This
       # includes all public instance methods on a controller, less
-      # any internal methods (see #internal_methods), adding back in
+      # any internal methods (see internal_methods), adding back in
       # any methods that are internal, but still exist on the class
-      # itself. Finally, #hidden_actions are removed.
+      # itself. Finally, hidden_actions are removed.
       #
       # ==== Returns
       # * <tt>Set</tt> - A set of all methods that should be considered actions.
@@ -92,15 +92,19 @@ module AbstractController
       end
 
       # action_methods are cached and there is sometimes need to refresh
-      # them. clear_action_methods! allows you to do that, so next time
+      # them. ::clear_action_methods! allows you to do that, so next time
       # you run action_methods, they will be recalculated
       def clear_action_methods!
         @action_methods = nil
       end
 
       # Returns the full controller name, underscored, without the ending Controller.
-      # For instance, MyApp::MyPostsController would return "my_app/my_posts" for
-      # controller_path.
+      #
+      #   class MyApp
+      #     MyPostsController < AbstractController::Base
+      #     end
+      #   end
+      #   MyApp::MyPostsController.controller_path # => "my_app/my_posts"
       #
       # ==== Returns
       # * <tt>String</tt>
@@ -137,12 +141,12 @@ module AbstractController
       process_action(action_name, *args)
     end
 
-    # Delegates to the class' #controller_path
+    # Delegates to the class' ::controller_path
     def controller_path
       self.class.controller_path
     end
 
-    # Delegates to the class' #action_methods
+    # Delegates to the class' ::action_methods
     def action_methods
       self.class.action_methods
     end
diff --git a/actionpack/lib/abstract_controller/callbacks.rb b/actionpack/lib/abstract_controller/callbacks.rb
index ca5c80cd71..0d2f18279b 100644
--- a/actionpack/lib/abstract_controller/callbacks.rb
+++ b/actionpack/lib/abstract_controller/callbacks.rb
@@ -22,10 +22,11 @@ module AbstractController
     end
 
     module ClassMethods
-      # If :only or :except are used, convert the options into the
-      # :unless and :if options of ActiveSupport::Callbacks.
-      # The basic idea is that :only => :index gets converted to
-      # :if => proc {|c| c.action_name == "index" }.
+      # If +:only+ or +:except+ are used, convert the options into the
+      # +:if+ and +:unless+ options of ActiveSupport::Callbacks.
+      #
+      # The basic idea is that <tt>:only => :index</tt> gets converted to
+      # <tt>:if => proc {|c| c.action_name == "index" }</tt>.
       #
       # ==== Options
       # * <tt>only</tt>   - The callback should be run only for this action
diff --git a/actionpack/lib/abstract_controller/rendering.rb b/actionpack/lib/abstract_controller/rendering.rb
index 9d10140ed2..585d20c56c 100644
--- a/actionpack/lib/abstract_controller/rendering.rb
+++ b/actionpack/lib/abstract_controller/rendering.rb
@@ -18,7 +18,7 @@ module AbstractController
     include ActionView::ViewPaths
 
     # Normalize arguments, options and then delegates render_to_body and
-    # sticks the result in self.response_body.
+    # sticks the result in <tt>self.response_body</tt>.
     # :api: public
     def render(*args, &block)
       options = _normalize_render(*args, &block)
@@ -30,11 +30,11 @@ module AbstractController
     # Raw rendering of a template to a string.
     #
     # It is similar to render, except that it does not
-    # set the response_body and it should be guaranteed
+    # set the +response_body+ and it should be guaranteed
     # to always return a string.
     #
-    # If a component extends the semantics of response_body
-    # (as Action Controller extends it to be anything that
+    # If a component extends the semantics of +response_body+
+    # (as ActionController extends it to be anything that
     # responds to the method each), this method needs to be
     # overridden in order to still return a string.
     # :api: plugin
@@ -73,8 +73,9 @@ module AbstractController
       }
     end
 
-    # Normalize args by converting render "foo" to render :action => "foo" and
-    # render "foo/bar" to render :file => "foo/bar".
+    # Normalize args by converting <tt>render "foo"</tt> to
+    # <tt>render :action => "foo"</tt> and <tt>render "foo/bar"</tt> to
+    # <tt>render :file => "foo/bar"</tt>.
     # :api: plugin
     def _normalize_args(action=nil, options={})
       if action.is_a? Hash
diff --git a/actionview/lib/action_view/renderer/partial_renderer.rb b/actionview/lib/action_view/renderer/partial_renderer.rb
index 610396506f..6c3015180a 100644
--- a/actionview/lib/action_view/renderer/partial_renderer.rb
+++ b/actionview/lib/action_view/renderer/partial_renderer.rb
@@ -73,7 +73,7 @@ module ActionView
   #
   #   <%= render partial: "account", locals: { user: @buyer } %>
   #
-  # == Rendering a collection of partials
+  # == \Rendering a collection of partials
   #
   # The example of partial use describes a familiar pattern where a template needs to iterate over an array and
   # render a sub template for each of the elements. This pattern has been implemented as a single method that
@@ -105,7 +105,7 @@ module ActionView
   # NOTE: Due to backwards compatibility concerns, the collection can't be one of hashes. Normally you'd also
   # just keep domain objects, like Active Records, in there.
   #
-  # == Rendering shared partials
+  # == \Rendering shared partials
   #
   # Two controllers can share a set of partials and render them like this:
   #
@@ -113,7 +113,7 @@ module ActionView
   #
   # This will render the partial "advertisement/_ad.html.erb" regardless of which controller this is being called from.
   #
-  # == Rendering objects that respond to `to_partial_path`
+  # == \Rendering objects that respond to `to_partial_path`
   #
   # Instead of explicitly naming the location of a partial, you can also let PartialRenderer do the work
   # and pick the proper path by checking `to_partial_path` method.
@@ -127,7 +127,7 @@ module ActionView
   #  # <%= render partial: "posts/post", collection: @posts %>
   #  <%= render partial: @posts %>
   #
-  # == Rendering the default case
+  # == \Rendering the default case
   #
   # If you're not going to be using any of the options like collections or layouts, you can also use the short-hand
   # defaults of render to render partials. Examples:
@@ -147,7 +147,7 @@ module ActionView
   #  # <%= render partial: "posts/post", collection: @posts %>
   #  <%= render @posts %>
   #
-  # == Rendering partials with layouts
+  # == \Rendering partials with layouts
   #
   # Partials can have their own layouts applied to them. These layouts are different than the ones that are
   # specified globally for the entire action, but they work in a similar fashion. Imagine a list with two types
diff --git a/activemodel/lib/active_model/conversion.rb b/activemodel/lib/active_model/conversion.rb
index 9c9b6f4a77..9de6ea65be 100644
--- a/activemodel/lib/active_model/conversion.rb
+++ b/activemodel/lib/active_model/conversion.rb
@@ -22,7 +22,7 @@ module ActiveModel
   module Conversion
     extend ActiveSupport::Concern
 
-    # If your object is already designed to implement all of the Active Model
+    # If your object is already designed to implement all of the \Active \Model
     # you can use the default <tt>:to_model</tt> implementation, which simply
     # returns +self+.
     #
@@ -33,9 +33,9 @@ module ActiveModel
     #   person = Person.new
     #   person.to_model == person # => true
     #
-    # If your model does not act like an Active Model object, then you should
+    # If your model does not act like an \Active \Model object, then you should
     # define <tt>:to_model</tt> yourself returning a proxy object that wraps
-    # your object with Active Model compliant methods.
+    # your object with \Active \Model compliant methods.
     def to_model
       self
     end
diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 337b61c55c..094424e4fd 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -102,7 +102,7 @@ module ActiveModel
   #
   # If an attribute is modified in-place then make use of
   # +[attribute_name]_will_change!+ to mark that the attribute is changing.
-  # Otherwise Active Model can't track changes to in-place attributes. Note
+  # Otherwise \Active \Model can't track changes to in-place attributes. Note
   # that Active Record can detect in-place modifications automatically. You do
   # not need to call +[attribute_name]_will_change!+ on Active Record models.
   #
diff --git a/activemodel/lib/active_model/gem_version.rb b/activemodel/lib/active_model/gem_version.rb
index 2403242ce6..762f4fe939 100644
--- a/activemodel/lib/active_model/gem_version.rb
+++ b/activemodel/lib/active_model/gem_version.rb
@@ -1,5 +1,5 @@
 module ActiveModel
-  # Returns the version of the currently loaded Active Model as a <tt>Gem::Version</tt>
+  # Returns the version of the currently loaded \Active \Model as a <tt>Gem::Version</tt>
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb
index 4e6b02c246..1819d2403f 100644
--- a/activemodel/lib/active_model/naming.rb
+++ b/activemodel/lib/active_model/naming.rb
@@ -211,7 +211,7 @@ module ActiveModel
   #   BookModule::BookCover.model_name.i18n_key  # => :"book_module/book_cover"
   #
   # Providing the functionality that ActiveModel::Naming provides in your object
-  # is required to pass the Active Model Lint test. So either extending the
+  # is required to pass the \Active \Model Lint test. So either extending the
   # provided method below, or rolling your own is required.
   module Naming
     def self.extended(base) #:nodoc:
diff --git a/activemodel/lib/active_model/serializers/xml.rb b/activemodel/lib/active_model/serializers/xml.rb
index 3ad3bf30ad..e33c766627 100644
--- a/activemodel/lib/active_model/serializers/xml.rb
+++ b/activemodel/lib/active_model/serializers/xml.rb
@@ -6,7 +6,7 @@ require 'active_support/core_ext/time/acts_like'
 
 module ActiveModel
   module Serializers
-    # == Active Model XML Serializer
+    # == \Active \Model XML Serializer
     module Xml
       extend ActiveSupport::Concern
       include ActiveModel::Serialization
diff --git a/activemodel/lib/active_model/validations/absence.rb b/activemodel/lib/active_model/validations/absence.rb
index 9b5416fb1d..75bf655578 100644
--- a/activemodel/lib/active_model/validations/absence.rb
+++ b/activemodel/lib/active_model/validations/absence.rb
@@ -1,6 +1,6 @@
 module ActiveModel
   module Validations
-    # == Active Model Absence Validator
+    # == \Active \Model Absence Validator
     class AbsenceValidator < EachValidator #:nodoc:
       def validate_each(record, attr_name, value)
         record.errors.add(attr_name, :present, options) if value.present?
diff --git a/activemodel/lib/active_model/validator.rb b/activemodel/lib/active_model/validator.rb
index 0116de68ab..ac32750946 100644
--- a/activemodel/lib/active_model/validator.rb
+++ b/activemodel/lib/active_model/validator.rb
@@ -127,7 +127,7 @@ module ActiveModel
   # in the options hash invoking the <tt>validate_each</tt> method passing in the
   # record, attribute and value.
   #
-  # All Active Model validations are built on top of this validator.
+  # All \Active \Model validations are built on top of this validator.
   class EachValidator < Validator #:nodoc:
     attr_reader :attributes
 
diff --git a/activemodel/lib/active_model/version.rb b/activemodel/lib/active_model/version.rb
index b1f9082ea7..6da3b4117b 100644
--- a/activemodel/lib/active_model/version.rb
+++ b/activemodel/lib/active_model/version.rb
@@ -1,7 +1,7 @@
 require_relative 'gem_version'
 
 module ActiveModel
-  # Returns the version of the currently loaded ActiveModel as a <tt>Gem::Version</tt>
+  # Returns the version of the currently loaded \Active \Model as a <tt>Gem::Version</tt>
   def self.version
     gem_version
   end
diff --git a/activerecord/lib/active_record/querying.rb b/activerecord/lib/active_record/querying.rb
index e8de4db3a7..91c9a0db99 100644
--- a/activerecord/lib/active_record/querying.rb
+++ b/activerecord/lib/active_record/querying.rb
@@ -55,11 +55,12 @@ module ActiveRecord
     # The use of this method should be restricted to complicated SQL queries that can't be executed
     # using the ActiveRecord::Calculations class methods. Look into those before using this.
     #
-    # ==== Parameters
+    #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
+    #   # => 12
     #
-    # * +sql+ - An SQL statement which should return a count query from the database, see the example below.
+    # ==== Parameters
     #
-    #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
+    # * +sql+ - An SQL statement which should return a count query from the database, see the example above.
     def count_by_sql(sql)
       sql = sanitize_conditions(sql)
       connection.select_value(sql, "#{name} Count").to_i
diff --git a/activesupport/lib/active_support/core_ext/name_error.rb b/activesupport/lib/active_support/core_ext/name_error.rb
index e1ebd4f91c..b82148e4e5 100644
--- a/activesupport/lib/active_support/core_ext/name_error.rb
+++ b/activesupport/lib/active_support/core_ext/name_error.rb
@@ -1,5 +1,12 @@
 class NameError
   # Extract the name of the missing constant from the exception message.
+  #
+  #   begin
+  #     HelloWorld
+  #   rescue NameError => e
+  #     e.missing_name
+  #   end
+  #   # => "HelloWorld"
   def missing_name
     if /undefined local variable or method/ !~ message
       $1 if /((::)?([A-Z]\w*)(::[A-Z]\w*)*)$/ =~ message
@@ -7,6 +14,13 @@ class NameError
   end
 
   # Was this exception raised because the given name was missing?
+  #
+  #   begin
+  #     HelloWorld
+  #   rescue NameError => e
+  #     e.missing_name?("HelloWorld")
+  #   end
+  #   # => true
   def missing_name?(name)
     if name.is_a? Symbol
       last_name = (missing_name || '').split('::').last
diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb
index 26b8d58948..6b3fc48a3f 100644
--- a/activesupport/lib/active_support/core_ext/object/try.rb
+++ b/activesupport/lib/active_support/core_ext/object/try.rb
@@ -63,9 +63,12 @@ class Object
     try!(*a, &b) if a.empty? || respond_to?(a.first)
   end
 
-  # Same as #try, but will raise a NoMethodError exception if the receiver is not +nil+ and
-  # does not implement the tried method.
-  
+  # Same as #try, but will raise a NoMethodError exception if the receiver is
+  # not +nil+ and does not implement the tried method.
+  #
+  #   "a".try!(:upcase) # => "A"
+  #   nil.try!(:upcase) # => nil
+  #   123.try!(:upcase) # => NoMethodError: undefined method `upcase' for 123:Fixnum
   def try!(*a, &b)
     if a.empty? && block_given?
       if b.arity.zero?
@@ -94,6 +97,9 @@ class NilClass
     nil
   end
 
+  # Calling +try!+ on +nil+ always returns +nil+.
+  #
+  #   nil.try!(:name) # => nil
   def try!(*args)
     nil
   end
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index 3046a62778..31c9406d5c 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -305,7 +305,6 @@ Active Job provides a way to catch exceptions raised during the execution of the
 job:
 
 ```ruby
-
 class GuestsCleanupJob < ActiveJob::Base
   queue_as :default
 
diff --git a/railties/lib/rails.rb b/railties/lib/rails.rb
index e7172e491f..a1a105ef2b 100644
--- a/railties/lib/rails.rb
+++ b/railties/lib/rails.rb
@@ -56,10 +56,18 @@ module Rails
       application && application.config.root
     end
 
+    # Returns the current Rails environment.
+    #
+    #   Rails.env # => "development"
+    #   Rails.env.development? # => true
+    #   Rails.env.production? # => false
     def env
       @_env ||= ActiveSupport::StringInquirer.new(ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development")
     end
 
+    # Sets the Rails environment.
+    #
+    #   Rails.env = "staging" # => "staging"
     def env=(environment)
       @_env = ActiveSupport::StringInquirer.new(environment)
     end