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

Conflicts:
	actionpack/lib/action_controller/metal/mime_responds.rb
	actionview/lib/action_view/vendor/html-scanner/html/sanitizer.rb
	activerecord/lib/active_record/type/value.rb

14 files changed, 62 insertions, 33 deletions

diff --git a/actionpack/lib/action_controller/metal/request_forgery_protection.rb b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
index 0efa0fb259..7afbd767ce 100644
--- a/actionpack/lib/action_controller/metal/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
@@ -9,7 +9,7 @@ module ActionController #:nodoc:
   end
 
   # Controller actions are protected from Cross-Site Request Forgery (CSRF) attacks
-  # by including a token in the rendered html for your application. This token is
+  # by including a token in the rendered HTML for your application. This token is
   # stored as a random string in the session, to which an attacker does not have
   # access. When a request reaches your application, \Rails verifies the received
   # token with the token in the session. Only HTML and JavaScript requests are checked,
@@ -44,7 +44,7 @@ module ActionController #:nodoc:
   #
   # The token parameter is named <tt>authenticity_token</tt> by default. The name and
   # value of this token must be added to every layout that renders forms by including
-  # <tt>csrf_meta_tags</tt> in the html +head+.
+  # <tt>csrf_meta_tags</tt> in the HTML +head+.
   #
   # Learn more about CSRF attacks and securing your application in the
   # {Ruby on Rails Security Guide}[http://guides.rubyonrails.org/security.html].
diff --git a/actionpack/lib/action_dispatch/middleware/public_exceptions.rb b/actionpack/lib/action_dispatch/middleware/public_exceptions.rb
index 6c8944e067..040cb215b7 100644
--- a/actionpack/lib/action_dispatch/middleware/public_exceptions.rb
+++ b/actionpack/lib/action_dispatch/middleware/public_exceptions.rb
@@ -1,4 +1,14 @@
 module ActionDispatch
+  # When called, this middleware renders an error page. By default if an HTML
+  # response is expected it will render static error pages from the `/public`
+  # directory. For example when this middleware receives a 500 response it will
+  # render the template found in `/public/500.html`.
+  # If an internationalized locale is set, this middleware will attempt to render
+  # the template in `/public/500.<locale>.html`. If an internationalized template
+  # is not found it will fall back on `/public/500.html`.
+  #
+  # When a request with a content type other than HTML is made, this middleware
+  # will attempt to convert error information into the appropriate response type.
   class PublicExceptions
     attr_accessor :public_path
 
diff --git a/actionpack/lib/action_dispatch/middleware/static.rb b/actionpack/lib/action_dispatch/middleware/static.rb
index 2764584fe9..25e32cdef8 100644
--- a/actionpack/lib/action_dispatch/middleware/static.rb
+++ b/actionpack/lib/action_dispatch/middleware/static.rb
@@ -2,6 +2,16 @@ require 'rack/utils'
 require 'active_support/core_ext/uri'
 
 module ActionDispatch
+  # This middleware returns a file's contents from disk in the body response.
+  # When initialized it can accept an optional 'Cache-Control' header which
+  # will be set when a response containing a file's contents is delivered.
+  #
+  # This middleware will render the file specified in `env["PATH_INFO"]`
+  # where the base path is in the +root+ directory. For example if the +root+
+  # is set to `public/` then a request with `env["PATH_INFO"]` of
+  # `assets/application.js` will return a response with contents of a file
+  # located at `public/assets/application.js` if the file exists. If the file
+  # does not exist a 404 "File not Found" response will be returned.
   class FileHandler
     def initialize(root, cache_control)
       @root          = root.chomp('/')
@@ -45,6 +55,15 @@ module ActionDispatch
     end
   end
 
+  # This middleware will attempt to return the contents of a file's body from
+  # disk in the response.  If a file is not found on disk, the request will be
+  # delegated to the application stack. This middleware is commonly initialized
+  # to serve assets from a server's `public/` directory.
+  #
+  # This middleware verifies the path to ensure that only files
+  # living in the root directory can be rendered. A request cannot
+  # produce a directory traversal using this middleware. Only 'GET' and 'HEAD'
+  # requests will result in a file being returned.
   class Static
     def initialize(app, path, cache_control=nil)
       @app = app
diff --git a/actionview/lib/action_view/helpers/asset_tag_helper.rb b/actionview/lib/action_view/helpers/asset_tag_helper.rb
index 669050e7a7..b7fdc16a9d 100644
--- a/actionview/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionview/lib/action_view/helpers/asset_tag_helper.rb
@@ -218,7 +218,7 @@ module ActionView
         tag("img", options)
       end
 
-      # Returns a string suitable for an html image tag alt attribute.
+      # Returns a string suitable for an HTML image tag alt attribute.
       # The +src+ argument is meant to be an image file path.
       # The method removes the basename of the file path and the digest,
       # if any. It also removes hyphens and underscores from file names and
@@ -239,7 +239,7 @@ module ActionView
         File.basename(src, '.*').sub(/-[[:xdigit:]]{32}\z/, '').tr('-_', ' ').capitalize
       end
 
-      # Returns an html video tag for the +sources+. If +sources+ is a string,
+      # Returns an HTML video tag for the +sources+. If +sources+ is a string,
       # a single video tag will be returned. If +sources+ is an array, a video
       # tag with nested source tags for each source will be returned. The
       # +sources+ can be full paths or files that exists in your public videos
diff --git a/actionview/lib/action_view/helpers/date_helper.rb b/actionview/lib/action_view/helpers/date_helper.rb
index 27c7a26098..9272bb5c10 100644
--- a/actionview/lib/action_view/helpers/date_helper.rb
+++ b/actionview/lib/action_view/helpers/date_helper.rb
@@ -330,7 +330,7 @@ module ActionView
         Tags::DatetimeSelect.new(object_name, method, self, options, html_options).render
       end
 
-      # Returns a set of html select-tags (one for year, month, day, hour, minute, and second) pre-selected with the
+      # Returns a set of HTML select-tags (one for year, month, day, hour, minute, and second) pre-selected with the
       # +datetime+. It's also possible to explicitly set the order of the tags using the <tt>:order</tt> option with
       # an array of symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in the desired order. If you do not
       # supply a Symbol, it will be appended onto the <tt>:order</tt> passed in. You can also add
@@ -379,7 +379,7 @@ module ActionView
         DateTimeSelector.new(datetime, options, html_options).select_datetime
       end
 
-      # Returns a set of html select-tags (one for year, month, and day) pre-selected with the +date+.
+      # Returns a set of HTML select-tags (one for year, month, and day) pre-selected with the +date+.
       # It's possible to explicitly set the order of the tags using the <tt>:order</tt> option with an array of
       # symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in the desired order.
       # If the array passed to the <tt>:order</tt> option does not contain all the three symbols, all tags will be hidden.
@@ -418,7 +418,7 @@ module ActionView
         DateTimeSelector.new(date, options, html_options).select_date
       end
 
-      # Returns a set of html select-tags (one for hour and minute).
+      # Returns a set of HTML select-tags (one for hour and minute).
       # You can set <tt>:time_separator</tt> key to format the output, and
       # the <tt>:include_seconds</tt> option to include an input for seconds.
       #
@@ -635,7 +635,7 @@ module ActionView
         DateTimeSelector.new(date, options, html_options).select_year
       end
 
-      # Returns an html time tag for the given date or time.
+      # Returns an HTML time tag for the given date or time.
       #
       #   time_tag Date.today  # =>
       #     <time datetime="2010-11-04">November 04, 2010</time>
@@ -914,7 +914,7 @@ module ActionView
           build_select(type, build_options(selected, options))
         end
 
-        # Build select option html from date value and options.
+        # Build select option HTML from date value and options.
         #  build_options(15, start: 1, end: 31)
         #  => "<option value="1">1</option>
         #      <option value="2">2</option>
@@ -954,7 +954,7 @@ module ActionView
           (select_options.join("\n") + "\n").html_safe
         end
 
-        # Builds select tag from date type and html select options.
+        # Builds select tag from date type and HTML select options.
         #  build_select(:month, "<option value="1">January</option>...")
         #  => "<select id="post_written_on_2i" name="post[written_on(2i)]">
         #        <option value="1">January</option>...
diff --git a/actionview/lib/action_view/helpers/form_helper.rb b/actionview/lib/action_view/helpers/form_helper.rb
index 0582cb3e12..09843ca70d 100644
--- a/actionview/lib/action_view/helpers/form_helper.rb
+++ b/actionview/lib/action_view/helpers/form_helper.rb
@@ -142,7 +142,7 @@ module ActionView
       # will get expanded to
       #
       #   <%= text_field :person, :first_name %>
-      # which results in an html <tt><input></tt> tag whose +name+ attribute is
+      # which results in an HTML <tt><input></tt> tag whose +name+ attribute is
       # <tt>person[first_name]</tt>. This means that when the form is submitted,
       # the value entered by the user will be available in the controller as
       # <tt>params[:person][:first_name]</tt>.
diff --git a/actionview/lib/action_view/helpers/form_options_helper.rb b/actionview/lib/action_view/helpers/form_options_helper.rb
index 8ade7c6a74..83b07a00d4 100644
--- a/actionview/lib/action_view/helpers/form_options_helper.rb
+++ b/actionview/lib/action_view/helpers/form_options_helper.rb
@@ -314,7 +314,7 @@ module ActionView
       #   # => <option>MasterCard</option>
       #   # => <option selected="selected">Discover</option>
       #
-      # You can optionally provide html attributes as the last element of the array.
+      # You can optionally provide HTML attributes as the last element of the array.
       #
       #   options_for_select([ "Denmark", ["USA", {class: 'bold'}], "Sweden" ], ["USA", "Sweden"])
       #   # => <option value="Denmark">Denmark</option>
@@ -633,7 +633,7 @@ module ActionView
       # even use the label as wrapper, as in the example above.
       #
       # The builder methods <tt>label</tt> and <tt>radio_button</tt> also accept
-      # extra html options:
+      # extra HTML options:
       #   collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
       #     b.label(class: "radio_button") { b.radio_button(class: "radio_button") }
       #   end
@@ -696,7 +696,7 @@ module ActionView
       # use the label as wrapper, as in the example above.
       #
       # The builder methods <tt>label</tt> and <tt>check_box</tt> also accept
-      # extra html options:
+      # extra HTML options:
       #   collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
       #     b.label(class: "check_box") { b.check_box(class: "check_box") }
       #   end
diff --git a/actionview/lib/action_view/helpers/output_safety_helper.rb b/actionview/lib/action_view/helpers/output_safety_helper.rb
index f03362d0f5..1c2a400245 100644
--- a/actionview/lib/action_view/helpers/output_safety_helper.rb
+++ b/actionview/lib/action_view/helpers/output_safety_helper.rb
@@ -17,10 +17,10 @@ module ActionView #:nodoc:
         stringish.to_s.html_safe
       end
 
-      # This method returns an html safe string similar to what <tt>Array#join</tt>
+      # This method returns an HTML safe string similar to what <tt>Array#join</tt>
       # would return. The array is flattened, and all items, including
-      # the supplied separator, are html escaped unless they are html
-      # safe, and the returned string is marked as html safe.
+      # the supplied separator, are HTML escaped unless they are HTML
+      # safe, and the returned string is marked as HTML safe.
       #
       #   safe_join(["<p>foo</p>".html_safe, "<p>bar</p>"], "<br />")
       #   # => "<p>foo</p>&lt;br /&gt;&lt;p&gt;bar&lt;/p&gt;"
diff --git a/actionview/lib/action_view/helpers/rendering_helper.rb b/actionview/lib/action_view/helpers/rendering_helper.rb
index 6cd6e858dd..e11670e00d 100644
--- a/actionview/lib/action_view/helpers/rendering_helper.rb
+++ b/actionview/lib/action_view/helpers/rendering_helper.rb
@@ -14,8 +14,8 @@ module ActionView
       # * <tt>:text</tt> - Renders the text passed in out.
       # * <tt>:plain</tt> - Renders the text passed in out. Setting the content
       #   type as <tt>text/plain</tt>.
-      # * <tt>:html</tt> - Renders the html safe string passed in out, otherwise
-      #   performs html escape on the string first. Setting the content type as
+      # * <tt>:html</tt> - Renders the HTML safe string passed in out, otherwise
+      #   performs HTML escape on the string first. Setting the content type as
       #   <tt>text/html</tt>.
       # * <tt>:body</tt> - Renders the text passed in, and inherits the content
       #   type of <tt>text/html</tt> from <tt>ActionDispatch::Response</tt>
diff --git a/actionview/lib/action_view/helpers/sanitize_helper.rb b/actionview/lib/action_view/helpers/sanitize_helper.rb
index 153c64d691..dfbc52e3ac 100644
--- a/actionview/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionview/lib/action_view/helpers/sanitize_helper.rb
@@ -9,7 +9,7 @@ module ActionView
     # These helper methods extend Action View making them callable within your template files.
     module SanitizeHelper
       extend ActiveSupport::Concern
-      # This +sanitize+ helper will html encode all tags and strip all attributes that
+      # This +sanitize+ helper will HTML encode all tags and strip all attributes that
       # aren't specifically allowed.
       #
       # It also strips href/src tags with invalid protocols, like javascript: especially.
diff --git a/guides/rails_guides/markdown/renderer.rb b/guides/rails_guides/markdown/renderer.rb
index 2eb7ca17a3..688f177578 100644
--- a/guides/rails_guides/markdown/renderer.rb
+++ b/guides/rails_guides/markdown/renderer.rb
@@ -50,7 +50,7 @@ HTML
             when 'erb'
               'ruby; html-script: true'
             when 'html'
-              'xml' # html is understood, but there are .xml rules in the CSS
+              'xml' # HTML is understood, but there are .xml rules in the CSS
             else
               'plain'
           end
diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md
index ef7ef5a50e..f37bb20750 100644
--- a/guides/source/action_view_overview.md
+++ b/guides/source/action_view_overview.md
@@ -495,7 +495,7 @@ image_url("edit.png") # => http://www.example.com/assets/edit.png
 
 #### image_tag
 
-Returns an html image tag for the source. The source can be a full path or a file that exists in your `app/assets/images` directory.
+Returns an HTML image tag for the source. The source can be a full path or a file that exists in your `app/assets/images` directory.
 
 ```ruby
 image_tag("icon.png") # => <img src="/assets/icon.png" alt="Icon" />
@@ -503,7 +503,7 @@ image_tag("icon.png") # => <img src="/assets/icon.png" alt="Icon" />
 
 #### javascript_include_tag
 
-Returns an html script tag for each of the sources provided. You can pass in the filename (`.js` extension is optional) of JavaScript files that exist in your `app/assets/javascripts` directory for inclusion into the current page or you can pass the full path relative to your document root.
+Returns an HTML script tag for each of the sources provided. You can pass in the filename (`.js` extension is optional) of JavaScript files that exist in your `app/assets/javascripts` directory for inclusion into the current page or you can pass the full path relative to your document root.
 
 ```ruby
 javascript_include_tag "common" # => <script src="/assets/common.js"></script>
@@ -736,7 +736,7 @@ distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true
 
 #### select_date
 
-Returns a set of html select-tags (one for year, month, and day) pre-selected with the `date` provided.
+Returns a set of HTML select-tags (one for year, month, and day) pre-selected with the `date` provided.
 
 ```ruby
 # Generates a date select that defaults to the date provided (six days after today)
@@ -748,7 +748,7 @@ select_date()
 
 #### select_datetime
 
-Returns a set of html select-tags (one for year, month, day, hour, and minute) pre-selected with the `datetime` provided.
+Returns a set of HTML select-tags (one for year, month, day, hour, and minute) pre-selected with the `datetime` provided.
 
 ```ruby
 # Generates a datetime select that defaults to the datetime provided (four days after today)
@@ -808,7 +808,7 @@ select_second(Time.now + 16.minutes)
 
 #### select_time
 
-Returns a set of html select-tags (one for hour and minute).
+Returns a set of HTML select-tags (one for hour and minute).
 
 ```ruby
 # Generates a time select that defaults to the time provided
@@ -1526,7 +1526,7 @@ The SanitizeHelper module provides a set of methods for scrubbing text of undesi
 
 #### sanitize
 
-This sanitize helper will html encode all tags and strip all attributes that aren't specifically allowed.
+This sanitize helper will HTML encode all tags and strip all attributes that aren't specifically allowed.
 
 ```ruby
 sanitize @article.body
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 887a8edf59..964bb30856 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -21,10 +21,10 @@ application from scratch. It does not assume that you have any prior experience
 with Rails. However, to get the most out of it, you need to have some
 prerequisites installed:
 
-* The [Ruby](http://www.ruby-lang.org/en/downloads) language version 1.9.3 or newer.
-* The [RubyGems](http://rubygems.org) packaging system, which is installed with Ruby
+* The [Ruby](https://www.ruby-lang.org/en/downloads) language version 1.9.3 or newer.
+* The [RubyGems](https://rubygems.org) packaging system, which is installed with Ruby
   versions 1.9 and later. To learn more about RubyGems, please read the [RubyGems Guides](http://guides.rubygems.org).
-* A working installation of the [SQLite3 Database](http://www.sqlite.org).
+* A working installation of the [SQLite3 Database](https://www.sqlite.org).
 
 Rails is a web application framework running on the Ruby programming language.
 If you have no prior experience with Ruby, you will find a very steep learning
@@ -101,7 +101,7 @@ If you don't have Ruby installed have a look at
 install Ruby on your platform.
 
 Many popular UNIX-like OSes ship with an acceptable version of SQLite3. Windows
-users and others can find installation instructions at [the SQLite3 website](http://www.sqlite.org).
+users and others can find installation instructions at [the SQLite3 website](https://www.sqlite.org).
 Verify that it is correctly installed and in your PATH:
 
 ```bash
@@ -748,7 +748,7 @@ to create an article. Try it! You should get an error that looks like this:
 (images/getting_started/forbidden_attributes_for_new_article.png)
 
 Rails has several security features that help you write secure applications,
-and you're running into one of them now. This one is called [strong parameters](http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters),
+and you're running into one of them now. This one is called [strong parameters](action_controller_overview.html#strong-parameters),
 which requires us to tell Rails exactly which parameters are allowed into our
 controller actions.
 
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 8b37b92139..60571750a1 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -263,7 +263,7 @@ TIP: This is useful when you're rendering a small snippet of HTML code.
 However, you might want to consider moving it to a template file if the markup
 is complex.
 
-NOTE: This option will escape HTML entities if the string is not html safe.
+NOTE: This option will escape HTML entities if the string is not HTML safe.
 
 #### Rendering JSON