Merge remote-tracking branch 'docrails/master'

Conflicts:
	actionpack/lib/action_view/helpers/form_options_helper.rb
	guides/code/getting_started/app/controllers/comments_controller.rb

README.rdoc

@@ -27,7 +27,7 @@ and render view templates in order to generate the appropriate HTTP response.
 
 In Rails, the Controller and View layers are handled together by Action Pack.
 These two layers are bundled in a single package due to their heavy interdependence.
-This is unlike the relationship between Active Record and Action Pack which are
+This is unlike the relationship between Active Record and Action Pack, which are
 independent. Each of these packages can be used independently outside of Rails. You
 can read more about Action Pack in its {README}[link:/rails/rails/blob/master/actionpack/README.rdoc].
 

actionpack/lib/abstract_controller/translation.rb

@@ -1,5 +1,13 @@
 module AbstractController
   module Translation
+    # Delegates to <tt>I18n.translate</tt>. Also aliased as <tt>t</tt>.
+    #
+    # When the given key starts with a period, it will be scoped by the current
+    # controller and action. So if you call <tt>translate(".foo")</tt> from
+    # <tt>PeopleController#index</tt>, it will convert the call to
+    # <tt>I18n.translate("people.index.foo")</tt>. This makes it less repetitive
+    # to translate many keys within the same controller / action and gives you a
+    # simple framework for scoping them consistently.
     def translate(*args)
       key = args.first
       if key.is_a?(String) && (key[0] == '.')
@@ -11,6 +19,7 @@ def translate(*args)
     end
     alias :t :translate
 
+    # Delegates to <tt>I18n.localize</tt>. Also aliased as <tt>l</tt>.
     def localize(*args)
       I18n.localize(*args)
     end

actionpack/lib/action_dispatch/http/response.rb

@@ -137,6 +137,7 @@ def committed?
       @committed
     end
 
+    # Sets the HTTP status code.
     def status=(status)
       @status = Rack::Utils.status_code(status)
     end
@@ -145,16 +146,24 @@ def content_type=(content_type)
       @content_type = content_type.to_s
     end
 
-    # The response code of the request
+    # The response code of the request.
     def response_code
       @status
     end
 
-    # Returns a String to ensure compatibility with Net::HTTPResponse
+    # Returns a string to ensure compatibility with <tt>Net::HTTPResponse</tt>.
     def code
       @status.to_s
     end
 
+    # Returns the corresponding message for the current HTTP status code:
+    #
+    #   response.status = 200
+    #   response.message # => "OK"
+    #
+    #   response.status = 404
+    #   response.message # => "Not Found"
+    #
     def message
       Rack::Utils::HTTP_STATUS_CODES[@status]
     end
@@ -172,6 +181,8 @@ def to_path
       stream.to_path
     end
 
+    # Returns the content of the response as a string. This contains the contents
+    # of any calls to <tt>render</tt>.
     def body
       strings = []
       each { |part| strings << part.to_s }
@@ -180,6 +191,7 @@ def body
 
     EMPTY = " "
 
+    # Allows you to manually set or override the response body.
     def body=(body)
       @blank = true if body == EMPTY
 

actionpack/lib/action_view/helpers/asset_tag_helper.rb

@@ -182,6 +182,8 @@ def favicon_link_tag(source='favicon.ico', options={})
       #   width="30" and height="45", and "50" becomes width="50" and height="50".
       #   <tt>:size</tt> will be ignored if the value is not in the correct format.
       #
+      # ==== Examples
+      #
       #   image_tag("icon")
       #   # => <img alt="Icon" src="/assets/icon" />
       #   image_tag("icon.png")

actionpack/lib/action_view/helpers/date_helper.rb

@@ -1040,14 +1040,38 @@ def separator(type)
     end
 
     class FormBuilder
+      # Wraps ActionView::Helpers::DateHelper#date_select for form builders:
+      #
+      #   <%= form_for @person do |f| %>
+      #     <%= f.date_select :birth_date %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def date_select(method, options = {}, html_options = {})
         @template.date_select(@object_name, method, objectify_options(options), html_options)
       end
 
+      # Wraps ActionView::Helpers::DateHelper#time_select for form builders:
+      #
+      #   <%= form_for @race do |f| %>
+      #     <%= f.time_select :average_lap %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def time_select(method, options = {}, html_options = {})
         @template.time_select(@object_name, method, objectify_options(options), html_options)
       end
 
+      # Wraps ActionView::Helpers::DateHelper#datetime_select for form builders:
+      #
+      #   <%= form_for @person do |f| %>
+      #     <%= f.time_select :last_request_at %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def datetime_select(method, options = {}, html_options = {})
         @template.datetime_select(@object_name, method, objectify_options(options), html_options)
       end

actionpack/lib/action_view/helpers/form_options_helper.rb

@@ -756,26 +756,74 @@ def prompt_text(prompt)
     end
 
     class FormBuilder
+      # Wraps ActionView::Helpers::FormOptionsHelper#select for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.select :person_id, Person.all.collect {|p| [ p.name, p.id ] }, { include_blank: true }) %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def select(method, choices, options = {}, html_options = {})
         @template.select(@object_name, method, choices, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_select for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_select :person_id, Author.all, :id, :name_with_initial, prompt: true %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def collection_select(method, collection, value_method, text_method, options = {}, html_options = {})
         @template.collection_select(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#grouped_collection_select for form builders:
+      #
+      #   <%= form_for @city do |f| %>
+      #     <%= f.grouped_collection_select :country_id, :country_id, @continents, :countries, :name, :id, :name %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def grouped_collection_select(method, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
         @template.grouped_collection_select(@object_name, method, collection, group_method, group_label_method, option_key_method, option_value_method, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#time_zone_select for form builders:
+      #
+      #   <%= form_for @user do |f| %>
+      #     <%= f.time_zone_select :time_zone, nil, include_blank: true %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def time_zone_select(method, priority_zones = nil, options = {}, html_options = {})
         @template.time_zone_select(@object_name, method, priority_zones, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_check_boxes for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_check_boxes :author_ids, Author.all, :id, :name_with_initial %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def collection_check_boxes(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
         @template.collection_check_boxes(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_radio_buttons for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_radio_buttons :author_id, Author.all, :id, :name_with_initial %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def collection_radio_buttons(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
         @template.collection_radio_buttons(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
       end

actionpack/lib/action_view/template.rb

@@ -80,8 +80,7 @@ class Template
     # problems with converting the user's data to
     # the <tt>default_internal</tt>.
     #
-    # To do so, simply raise the raise +WrongEncodingError+
-    # as follows:
+    # To do so, simply raise +WrongEncodingError+ as follows:
     #
     #     raise WrongEncodingError.new(
     #       problematic_string,

activerecord/lib/active_record/associations.rb

@@ -191,7 +191,7 @@ def association_instance_set(name, association)
     # * <tt>Project#portfolio, Project#portfolio=(portfolio), Project#portfolio.nil?</tt>
     # * <tt>Project#project_manager, Project#project_manager=(project_manager), Project#project_manager.nil?,</tt>
     # * <tt>Project#milestones.empty?, Project#milestones.size, Project#milestones, Project#milestones<<(milestone),</tt>
-    #   <tt>Project#milestones.delete(milestone), Project#milestones.destroy(mileston), Project#milestones.find(milestone_id),</tt>
+    #   <tt>Project#milestones.delete(milestone), Project#milestones.destroy(milestone), Project#milestones.find(milestone_id),</tt>
     #   <tt>Project#milestones.build, Project#milestones.create</tt>
     # * <tt>Project#categories.empty?, Project#categories.size, Project#categories, Project#categories<<(category1),</tt>
     #   <tt>Project#categories.delete(category1), Project#categories.destroy(category1)</tt>

activerecord/lib/active_record/base.rb

@@ -162,8 +162,8 @@ module ActiveRecord #:nodoc:
   #
   # Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects
   # by simple queries without turning to SQL. They work by appending the name of an attribute
-  # to <tt>find_by_</tt> # like <tt>Person.find_by_user_name</tt>.
-  # Instead of writing # <tt>Person.where(user_name: user_name).first</tt>, you just do
+  # to <tt>find_by_</tt> like <tt>Person.find_by_user_name</tt>.
+  # Instead of writing <tt>Person.where(user_name: user_name).first</tt>, you just do
   # <tt>Person.find_by_user_name(user_name)</tt>.
   #
   # It's possible to add an exclamation point (!) on the end of the dynamic finders to get them to raise an

activerecord/lib/active_record/fixtures.rb

@@ -363,11 +363,11 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
   #
   #   first:
   #     name: Smurf
-  #     *DEFAULTS
+  #     <<: *DEFAULTS
   #
   #   second:
   #     name: Fraggle
-  #     *DEFAULTS
+  #     <<: *DEFAULTS
   #
   # Any fixture labeled "DEFAULTS" is safely ignored.
   class FixtureSet

activesupport/lib/active_support/core_ext/date_time/calculations.rb

@@ -43,7 +43,7 @@ def seconds_until_end_of_day
 
   # Returns a new DateTime where one or more of the elements have been changed
   # according to the +options+ parameter. The time options (<tt>:hour</tt>,
-  # <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is
+  # <tt>:min</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is
   # passed, then minute and sec is set to 0. If the hour and minute is passed,
   # then sec is set to 0. The +options+ parameter takes a hash with any of these
   # keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>,

activesupport/lib/active_support/proxy_object.rb

@@ -5,7 +5,7 @@ class ProxyObject < ::BasicObject
     undef_method :==
     undef_method :equal?
 
-    # Let ActiveSupport::BasicObject at least raise exceptions.
+    # Let ActiveSupport::ProxyObject at least raise exceptions.
     def raise(*args)
       ::Object.send(:raise, *args)
     end

guides/source/4_0_release_notes.md

@@ -7,7 +7,6 @@ Highlights in Rails 4.0:
 * Strong Parameters
 * Turbolinks
 * Russian Doll Caching
-* Asynchronous Mailers
 
 These release notes cover only the major changes. To know about various bug fixes and changes, please refer to the change logs or check out the [list of commits](https://github.com/rails/rails/commits/master) in the main Rails repository on GitHub.
 
@@ -150,7 +149,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ
 Action Pack
 -----------
 
-Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railties/CHANGELOG.md) for detailed changes.
+Please refer to the [Changelog](https://github.com/rails/rails/blob/master/actionpack/CHANGELOG.md) for detailed changes.
 
 ### Notable changes
 
@@ -162,7 +161,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt
 Active Record
 -------------
 
-Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railties/CHANGELOG.md) for detailed changes.
+Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activerecord/CHANGELOG.md) for detailed changes.
 
 ### Notable changes
 

guides/source/action_controller_overview.md

@@ -58,7 +58,7 @@ Parameters
 You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from an HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the `params` hash in your controller:
 
 ```ruby
-class ClientsController < ActionController::Base
+class ClientsController < ApplicationController
   # This action uses query string parameters because it gets run
   # by an HTTP GET request, but this does not make any difference
   # to the way in which the parameters are accessed. The URL for
@@ -479,7 +479,7 @@ In addition to "before" filters, you can also run filters after an action has be
 For example, in a website where changes have an approval workflow an administrator could be able to preview them easily, just apply them within a transaction:
 
 ```ruby
-class ChangesController < ActionController::Base
+class ChangesController < ApplicationController
   around_action :wrap_in_transaction, only: :show
 
   private

guides/source/active_record_basics.md

@@ -1,6 +1,6 @@
 Active Record Basics
 ====================
-
+ 
 This guide is an introduction to Active Record.
 
 After reading this guide, you will know:

guides/source/active_record_callbacks.md

@@ -157,7 +157,6 @@ The following methods trigger callbacks:
 * `save!`
 * `save(validate: false)`
 * `toggle!`
-* `update`
 * `update_attribute`
 * `update`
 * `update!`