Merge pull request #28381 from shime/docs-action-controller-base

[docs] fix ActionController docs

actionpack/lib/action_controller/base.rb

@@ -8,7 +8,7 @@ module ActionController
   # on the controller, which will automatically be made accessible to the web-server through \Rails Routes.
   #
   # By default, only the ApplicationController in a \Rails application inherits from <tt>ActionController::Base</tt>. All other
-  # controllers in turn inherit from ApplicationController. This gives you one class to configure things such as
+  # controllers inherit from ApplicationController. This gives you one class to configure things such as
   # request forgery protection and filtering of sensitive request parameters.
   #
   # A sample controller could look like this:
@@ -30,7 +30,7 @@ module ActionController
   #
   # Unlike index, the create action will not render a template. After performing its main purpose (creating a
   # new post), it initiates a redirect instead. This redirect works by returning an external
-  # "302 Moved" HTTP response that takes the user to the index action.
+  # <tt>302 Moved</tt> HTTP response that takes the user to the index action.
   #
   # These two methods represent the two basic action archetypes used in Action Controllers: Get-and-show and do-and-redirect.
   # Most actions are variations on these themes.
@@ -59,7 +59,7 @@ module ActionController
   #   <input type="text" name="post[name]" value="david">
   #   <input type="text" name="post[address]" value="hyacintvej">
   #
-  # A request stemming from a form holding these inputs will include <tt>{ "post" => { "name" => "david", "address" => "hyacintvej" } }</tt>.
+  # A request coming from a form holding these inputs will include <tt>{ "post" => { "name" => "david", "address" => "hyacintvej" } }</tt>.
   # If the address input had been named <tt>post[address][street]</tt>, the <tt>params</tt> would have included
   # <tt>{ "post" => { "address" => { "street" => "hyacintvej" } } }</tt>. There's no limit to the depth of the nesting.
   #
@@ -74,7 +74,7 @@ module ActionController
   #
   #   session[:person] = Person.authenticate(user_name, password)
   #
-  # And retrieved again through the same hash:
+  # You can retrieve it again through the same hash:
   #
   #   Hello #{session[:person]}
   #

actionpack/lib/action_controller/metal.rb

@@ -138,7 +138,7 @@ def self.binary_params_for?(action) # :nodoc:
       false
     end
 
-    # Delegates to the class' <tt>controller_name</tt>
+    # Delegates to the class' <tt>controller_name</tt>.
     def controller_name
       self.class.controller_name
     end
@@ -244,7 +244,7 @@ def self.action(name)
       end
     end
 
-    # Direct dispatch to the controller.  Instantiates the controller, then
+    # Direct dispatch to the controller. Instantiates the controller, then
     # executes the action named +name+.
     def self.dispatch(name, req, res)
       if middleware_stack.any?

actionpack/lib/action_controller/metal/etag_with_flash.rb

 module ActionController
   # When you're using the flash, it's generally used as a conditional on the view.
   # This means the content of the view depends on the flash. Which in turn means
-  # that the etag for a response should be computed with the content of the flash
+  # that the ETag for a response should be computed with the content of the flash
   # in mind. This does that by including the content of the flash as a component
-  # in the etag that's generated for a response.
+  # in the ETag that's generated for a response.
   module EtagWithFlash
     extend ActiveSupport::Concern
 

actionpack/lib/action_controller/metal/force_ssl.rb

@@ -10,9 +10,9 @@ module ActionController
   #
   # Note that if you are really concerned about your application security,
   # you might consider using +config.force_ssl+ in your config file instead.
-  # That will ensure all the data transferred via HTTPS protocol and prevent
-  # the user from getting their session hijacked when accessing the site over
-  # unsecured HTTP protocol.
+  # That will ensure all the data is transferred via HTTPS protocol and will
+  # prevent the user from getting their session hijacked when accessing the
+  # site over unsecured HTTP protocol.
   module ForceSSL
     extend ActiveSupport::Concern
     include AbstractController::Callbacks
@@ -71,7 +71,7 @@ def force_ssl(options = {})
     # Redirect the existing request to use the HTTPS protocol.
     #
     # ==== Parameters
-    # * <tt>host_or_options</tt> - Either a host name or any of the url &
+    # * <tt>host_or_options</tt> - Either a host name or any of the url and
     #   redirect options available to the <tt>force_ssl</tt> method.
     def force_ssl_redirect(host_or_options = nil)
       unless request.ssl?

actionpack/lib/action_controller/metal/http_authentication.rb

@@ -445,7 +445,7 @@ def authenticate(controller, &login_procedure)
         end
       end
 
-      # Parses the token and options out of the token authorization header.
+      # Parses the token and options out of the token Authorization header.
       # The value for the Authorization header is expected to have the prefix
       # <tt>"Token"</tt> or <tt>"Bearer"</tt>. If the header looks like this:
       #   Authorization: Token token="abc", nonce="def"

actionpack/lib/action_controller/metal/implicit_render.rb

@@ -2,11 +2,11 @@ module ActionController
   # Handles implicit rendering for a controller action that does not
   # explicitly respond with +render+, +respond_to+, +redirect+, or +head+.
   #
-  # For API controllers, the implicit response is always 204 No Content.
+  # For API controllers, the implicit response is always <tt>204 No Content</tt>.
   #
   # For all other controllers, we use these heuristics to decide whether to
   # render a template, raise an error for a missing template, or respond with
-  # 204 No Content:
+  # <tt>204 No Content</tt>:
   #
   # First, if we DO find a template, it's rendered. Template lookup accounts
   # for the action name, locales, format, variant, template handlers, and more
@@ -23,7 +23,7 @@ module ActionController
   # <tt>ActionView::UnknownFormat</tt> with an explanation.
   #
   # Finally, if we DON'T find a template AND the request isn't a browser page
-  # load, then we implicitly respond with 204 No Content.
+  # load, then we implicitly respond with <tt>204 No Content</tt>.
   module ImplicitRender
     # :stopdoc:
     include BasicImplicitRender

actionpack/lib/action_controller/metal/instrumentation.rb

@@ -3,7 +3,7 @@
 
 module ActionController
   # Adds instrumentation to several ends in ActionController::Base. It also provides
-  # some hooks related with process_action, this allows an ORM like Active Record
+  # some hooks related with process_action. This allows an ORM like Active Record
   # and/or DataMapper to plug in ActionController and show related information.
   #
   # Check ActiveRecord::Railties::ControllerRuntime for an example.

actionpack/lib/action_controller/metal/live.rb

@@ -239,8 +239,8 @@ def process(name)
 
       error = nil
       # This processes the action in a child thread. It lets us return the
-      # response code and headers back up the rack stack, and still process
-      # the body in parallel with sending data to the client
+      # response code and headers back up the Rack stack, and still process
+      # the body in parallel with sending data to the client.
       new_controller_thread {
         ActiveSupport::Dependencies.interlock.running do
           t2 = Thread.current
@@ -278,9 +278,9 @@ def process(name)
       raise error if error
     end
 
-    # Spawn a new thread to serve up the controller in.  This is to get
+    # Spawn a new thread to serve up the controller in. This is to get
     # around the fact that Rack isn't based around IOs and we need to use
-    # a thread to stream data from the response bodies.  Nobody should call
+    # a thread to stream data from the response bodies. Nobody should call
     # this method except in Rails internals. Seriously!
     def new_controller_thread # :nodoc:
       Thread.new {

actionpack/lib/action_controller/metal/mime_responds.rb

@@ -181,8 +181,8 @@ module MimeResponds
     #
     #   request.variant = [:tablet, :phone]
     #
-    # which will work similarly to formats and MIME types negotiation. If there will be no
-    # +:tablet+ variant declared, +:phone+ variant will be picked:
+    # This will work similarly to formats and MIME types negotiation. If there
+    # is no +:tablet+ variant declared, +:phone+ variant will be picked:
     #
     #   respond_to do |format|
     #     format.html.none

actionpack/lib/action_controller/metal/parameter_encoding.rb

@@ -39,7 +39,7 @@ def binary_params_for?(action) # :nodoc:
       #   end
       #
       # The show action in the above controller would have all parameter values
-      # encoded as ASCII-8BIT.  This is useful in the case where an application
+      # encoded as ASCII-8BIT. This is useful in the case where an application
       # must handle data but encoding of the data is unknown, like file system data.
       def skip_parameter_encoding(action)
         @_parameter_encodings[action.to_s] = true

actionpack/lib/action_controller/metal/params_wrapper.rb

@@ -213,7 +213,7 @@ def wrap_parameters(name_or_model_or_options, options = {})
       end
 
       # Sets the default wrapper key or model which will be used to determine
-      # wrapper key and attribute names. Will be called automatically when the
+      # wrapper key and attribute names. Called automatically when the
       # module is inherited.
       def inherited(klass)
         if klass._wrapper_options.format.any?
@@ -225,7 +225,7 @@ def inherited(klass)
       end
     end
 
-    # Performs parameters wrapping upon the request. Will be called automatically
+    # Performs parameters wrapping upon the request. Called automatically
     # by the metal call stack.
     def process_action(*args)
       if _wrapper_enabled?
@@ -238,11 +238,11 @@ def process_action(*args)
         wrapped_keys = request.request_parameters.keys
         wrapped_filtered_hash = _wrap_parameters request.filtered_parameters.slice(*wrapped_keys)
 
-        # This will make the wrapped hash accessible from controller and view
+        # This will make the wrapped hash accessible from controller and view.
         request.parameters.merge! wrapped_hash
         request.request_parameters.merge! wrapped_hash
 
-        # This will display the wrapped hash in the log file
+        # This will display the wrapped hash in the log file.
         request.filtered_parameters.merge! wrapped_filtered_hash
       end
       super

actionpack/lib/action_controller/metal/redirecting.rb

@@ -22,7 +22,7 @@ module Redirecting
     #   redirect_to posts_url
     #   redirect_to proc { edit_post_url(@post) }
     #
-    # The redirection happens as a "302 Found" header unless otherwise specified using the <tt>:status</tt> option:
+    # The redirection happens as a <tt>302 Found</tt> header unless otherwise specified using the <tt>:status</tt> option:
     #
     #   redirect_to post_url(@post), status: :found
     #   redirect_to action: 'atom', status: :moved_permanently
@@ -36,7 +36,7 @@ module Redirecting
     # If you are using XHR requests other than GET or POST and redirecting after the
     # request then some browsers will follow the redirect using the original request
     # method. This may lead to undesirable behavior such as a double DELETE. To work
-    # around this  you can return a <tt>303 See Other</tt> status code which will be
+    # around this you can return a <tt>303 See Other</tt> status code which will be
     # followed using a GET request.
     #
     #   redirect_to posts_url, status: :see_other

actionpack/lib/action_controller/metal/rendering.rb

@@ -36,7 +36,7 @@ def render(*args) #:nodoc:
       super
     end
 
-    # Overwrite render_to_string because body can now be set to a rack body.
+    # Overwrite render_to_string because body can now be set to a Rack body.
     def render_to_string(*)
       result = super
       if result.respond_to?(:each)

actionpack/lib/action_controller/metal/request_forgery_protection.rb

@@ -262,9 +262,9 @@ def non_xhr_javascript_response? # :doc:
 
       # Returns true or false if a request is verified. Checks:
       #
-      # * Is it a GET or HEAD request?  Gets should be safe and idempotent
+      # * Is it a GET or HEAD request? GETs should be safe and idempotent
       # * Does the form_authenticity_token match the given token value from the params?
-      # * Does the X-CSRF-Token header match the form_authenticity_token
+      # * Does the X-CSRF-Token header match the form_authenticity_token?
       def verified_request? # :doc:
         !protect_against_forgery? || request.get? || request.head? ||
           (valid_request_origin? && any_authenticity_token_valid?)
@@ -327,7 +327,7 @@ def valid_authenticity_token?(session, encoded_masked_token) # :doc:
         if masked_token.length == AUTHENTICITY_TOKEN_LENGTH
           # This is actually an unmasked token. This is expected if
           # you have just upgraded to masked tokens, but should stop
-          # happening shortly after installing this gem
+          # happening shortly after installing this gem.
           compare_with_real_token masked_token, session
 
         elsif masked_token.length == AUTHENTICITY_TOKEN_LENGTH * 2
@@ -336,13 +336,13 @@ def valid_authenticity_token?(session, encoded_masked_token) # :doc:
           compare_with_real_token(csrf_token, session) ||
             valid_per_form_csrf_token?(csrf_token, session)
         else
-          false # Token is malformed
+          false # Token is malformed.
         end
       end
 
       def unmask_token(masked_token) # :doc:
         # Split the token into the one-time pad and the encrypted
-        # value and decrypt it
+        # value and decrypt it.
         one_time_pad = masked_token[0...AUTHENTICITY_TOKEN_LENGTH]
         encrypted_csrf_token = masked_token[AUTHENTICITY_TOKEN_LENGTH..-1]
         xor_byte_strings(one_time_pad, encrypted_csrf_token)

actionpack/lib/action_controller/metal/rescue.rb

@@ -10,7 +10,7 @@ module Rescue
     # exceptions must be shown. This method is only called when
     # consider_all_requests_local is false. By default, it returns
     # false, but someone may set it to `request.local?` so local
-    # requests in production still shows the detailed exception pages.
+    # requests in production still show the detailed exception pages.
     def show_detailed_exceptions?
       false
     end

actionpack/lib/action_controller/metal/streaming.rb

@@ -3,7 +3,7 @@
 module ActionController #:nodoc:
   # Allows views to be streamed back to the client as they are rendered.
   #
-  # The default way Rails renders views is by first rendering the template
+  # By default, Rails renders views by first rendering the template
   # and then the layout. The response is sent to the client after the whole
   # template is rendered, all queries are made, and the layout is processed.
   #

actionpack/lib/action_controller/metal/strong_parameters.rb

@@ -262,7 +262,7 @@ def to_unsafe_h
     alias_method :to_unsafe_hash, :to_unsafe_h
 
     # Convert all hashes in values into parameters, then yield each pair in
-    # the same way as <tt>Hash#each_pair</tt>
+    # the same way as <tt>Hash#each_pair</tt>.
     def each_pair(&block)
       @parameters.each_pair do |key, value|
         yield key, convert_hashes_to_parameters(key, value)
@@ -410,7 +410,7 @@ def require(key)
     #
     #   params.permit(preferences: {})
     #
-    # but be careful because this opens the door to arbitrary input. In this
+    # Be careful because this opens the door to arbitrary input. In this
     # case, +permit+ ensures values in the returned structure are permitted
     # scalars and filters out anything else.
     #
@@ -646,15 +646,15 @@ def values_at(*keys)
     end
 
     # Returns a new <tt>ActionController::Parameters</tt> with all keys from
-    # +other_hash+ merges into current hash.
+    # +other_hash+ merged into current hash.
     def merge(other_hash)
       new_instance_with_inherited_permitted_status(
         @parameters.merge(other_hash.to_h)
       )
     end
 
-    # Returns current <tt>ActionController::Parameters</tt> instance which
-    # +other_hash+ merges into current hash.
+    # Returns current <tt>ActionController::Parameters</tt> instance with
+    # +other_hash+ merged into current hash.
     def merge!(other_hash)
       @parameters.merge!(other_hash.to_h)
       self
@@ -715,7 +715,7 @@ def init_with(coder) # :nodoc:
 
     undef_method :to_param
 
-    # Returns duplicate of object including all parameters
+    # Returns duplicate of object including all parameters.
     def deep_dup
       self.class.new(@parameters.deep_dup).tap do |duplicate|
         duplicate.permitted = @permitted
@@ -935,7 +935,7 @@ def initialize_copy(source)
   # whitelisted.
   #
   # In addition, parameters can be marked as required and flow through a
-  # predefined raise/rescue flow to end up as a 400 Bad Request with no
+  # predefined raise/rescue flow to end up as a <tt>400 Bad Request</tt> with no
   # effort.
   #
   #   class PeopleController < ActionController::Base
@@ -959,7 +959,7 @@ def initialize_copy(source)
   #
   #     private
   #       # Using a private method to encapsulate the permissible parameters is
-  #       # just a good pattern since you'll be able to reuse the same permit
+  #       # a good pattern since you'll be able to reuse the same permit
   #       # list between create and update. Also, you can specialize this method
   #       # with per-user checking of permissible attributes.
   #       def person_params

actionpack/lib/action_controller/metal/url_for.rb

@@ -3,7 +3,7 @@ module ActionController
   # the <tt>_routes</tt> method. Otherwise, an exception will be raised.
   #
   # In addition to <tt>AbstractController::UrlFor</tt>, this module accesses the HTTP layer to define
-  # url options like the +host+. In order to do so, this module requires the host class
+  # URL options like the +host+. In order to do so, this module requires the host class
   # to implement +env+ which needs to be Rack-compatible and +request+
   # which is either an instance of +ActionDispatch::Request+ or an object
   # that responds to the +host+, +optional_port+, +protocol+ and

actionpack/lib/action_controller/railtie.rb

@@ -42,7 +42,7 @@ class Railtie < Rails::Railtie #:nodoc:
       options.javascripts_dir ||= paths["public/javascripts"].first
       options.stylesheets_dir ||= paths["public/stylesheets"].first
 
-      # Ensure readers methods get compiled
+      # Ensure readers methods get compiled.
       options.asset_host        ||= app.config.asset_host
       options.relative_url_root ||= app.config.relative_url_root
 

actionpack/lib/action_controller/renderer.rb

@@ -5,7 +5,7 @@ module ActionController
   # without requirement of being in controller actions.
   #
   # You get a concrete renderer class by invoking ActionController::Base#renderer.
-  # For example,
+  # For example:
   #
   #   ApplicationController.renderer
   #
@@ -18,7 +18,7 @@ module ActionController
   #   ApplicationController.render template: '...'
   #
   # #render allows you to use the same options that you can use when rendering in a controller.
-  # For example,
+  # For example:
   #
   #   FooController.render :action, locals: { ... }, assigns: { ... }
   #

actionpack/lib/action_controller/test_case.rb

@@ -13,10 +13,10 @@ class Metal
   end
 
   module Live
-    # Disable controller / rendering threads in tests.  User tests can access
+    # Disable controller / rendering threads in tests. User tests can access
     # the database on the main thread, so they could open a txn, then the
     # controller thread will open a new connection and try to access data
-    # that's only visible to the main thread's txn.  This is the problem in #23483
+    # that's only visible to the main thread's txn. This is the problem in #23483.
     remove_method :new_controller_thread
     def new_controller_thread # :nodoc:
       yield
@@ -35,7 +35,7 @@ def self.new_session
 
     attr_reader :controller_class
 
-    # Create a new test request with default `env` values
+    # Create a new test request with default `env` values.
     def self.create(controller_class)
       env = {}
       env = Rails.application.env_config.merge(env) if defined?(Rails.application) && Rails.application
@@ -131,7 +131,7 @@ def assign_parameters(routes, controller_path, action, parameters, generated_pat
       include Rack::Test::Utils
 
       def should_multipart?(params)
-        # FIXME: lifted from Rack-Test. We should push this separation upstream
+        # FIXME: lifted from Rack-Test. We should push this separation upstream.
         multipart = false
         query = lambda { |value|
           case value
@@ -300,7 +300,7 @@ def load!
   #   assert_equal "Dave", cookies[:name] # makes sure that a cookie called :name was set as "Dave"
   #   assert flash.empty? # makes sure that there's nothing in the flash
   #
-  # On top of the collections, you have the complete url that a given action redirected to available in <tt>redirect_to_url</tt>.
+  # On top of the collections, you have the complete URL that a given action redirected to available in <tt>redirect_to_url</tt>.
   #
   # For redirects within the same controller, you can even call follow_redirect and the redirect will be followed, triggering another
   # action call which can then be asserted against.