[docs] fix ActionController documentation

[ci skip]
2022-11-09 12:12:34 -05:00 · 2017-03-11 14:17:44 +01:00 · 2017-03-11 14:17:44 +01:00 · b383b34660
commit b383b34660
parent 2e752d18b3
21 changed files with 55 additions and 55 deletions
--- a/actionpack/lib/action_controller/base.rb
+++ b/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]}
  #
--- a/actionpack/lib/action_controller/metal.rb
+++ b/actionpack/lib/action_controller/metal.rb
@ -138,7 +138,7 @@ module ActionController
      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 @@ module ActionController
      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?
--- a/actionpack/lib/action_controller/metal/etag_with_flash.rb
+++ b/actionpack/lib/action_controller/metal/etag_with_flash.rb
@ -1,9 +1,9 @@
 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

--- a/actionpack/lib/action_controller/metal/force_ssl.rb
+++ b/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 @@ module ActionController
    # 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?
--- a/actionpack/lib/action_controller/metal/http_authentication.rb
+++ b/actionpack/lib/action_controller/metal/http_authentication.rb
@ -445,7 +445,7 @@ module ActionController
        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"
--- a/actionpack/lib/action_controller/metal/implicit_render.rb
+++ b/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
--- a/actionpack/lib/action_controller/metal/instrumentation.rb
+++ b/actionpack/lib/action_controller/metal/instrumentation.rb
@ -3,7 +3,7 @@ require "abstract_controller/logger"

 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.
--- a/actionpack/lib/action_controller/metal/live.rb
+++ b/actionpack/lib/action_controller/metal/live.rb
@ -239,8 +239,8 @@ module ActionController

      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 @@ module ActionController
      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 {
--- a/actionpack/lib/action_controller/metal/mime_responds.rb
+++ b/actionpack/lib/action_controller/metal/mime_responds.rb
@ -181,8 +181,8 @@ module ActionController #:nodoc:
    #
    #   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
--- a/actionpack/lib/action_controller/metal/parameter_encoding.rb
+++ b/actionpack/lib/action_controller/metal/parameter_encoding.rb
@ -39,7 +39,7 @@ module ActionController
      #   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
--- a/actionpack/lib/action_controller/metal/params_wrapper.rb
+++ b/actionpack/lib/action_controller/metal/params_wrapper.rb
@ -213,7 +213,7 @@ module ActionController
      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 @@ module ActionController
      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 @@ module ActionController
        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
--- a/actionpack/lib/action_controller/metal/redirecting.rb
+++ b/actionpack/lib/action_controller/metal/redirecting.rb
@ -22,7 +22,7 @@ module ActionController
    #   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 ActionController
    # 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
--- a/actionpack/lib/action_controller/metal/rendering.rb
+++ b/actionpack/lib/action_controller/metal/rendering.rb
@ -36,7 +36,7 @@ module ActionController
      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)
--- a/actionpack/lib/action_controller/metal/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
@ -262,9 +262,9 @@ module ActionController #:nodoc:

      # 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 @@ module ActionController #:nodoc:
        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 @@ module ActionController #:nodoc:
          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)
--- a/actionpack/lib/action_controller/metal/rescue.rb
+++ b/actionpack/lib/action_controller/metal/rescue.rb
@ -10,7 +10,7 @@ module ActionController #:nodoc:
    # 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
--- a/actionpack/lib/action_controller/metal/streaming.rb
+++ b/actionpack/lib/action_controller/metal/streaming.rb
@ -3,7 +3,7 @@ require "rack/chunked"
 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.
  #
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@ -262,7 +262,7 @@ module ActionController
    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 @@ module ActionController
    #
    #   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 @@ module ActionController
    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 @@ module ActionController

    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 @@ module ActionController
  # 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 @@ module ActionController
  #
  #     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
--- a/actionpack/lib/action_controller/metal/url_for.rb
+++ b/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
--- a/actionpack/lib/action_controller/railtie.rb
+++ b/actionpack/lib/action_controller/railtie.rb
@ -42,7 +42,7 @@ module ActionController
      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

--- a/actionpack/lib/action_controller/renderer.rb
+++ b/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: { ... }
  #
--- a/actionpack/lib/action_controller/test_case.rb
+++ b/actionpack/lib/action_controller/test_case.rb
@ -13,10 +13,10 @@ module ActionController
  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 @@ module ActionController

    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 @@ module ActionController
      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 @@ module ActionController
  #   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.