actionpack 7.1.3.4 → 7.2.0.beta1

data/lib/abstract_controller/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "abstract_controller/error"
 require "active_support/configurable"
 require "active_support/descendants_tracker"
@@ -26,12 +28,12 @@ module AbstractController
     end
   end
 
-  # = Abstract Controller \Base
+  # # Abstract Controller Base
   #
-  # 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.
+  # 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.
   class Base
     ##
     # Returns the body of the HTTP response sent by the controller.
@@ -52,27 +54,26 @@ module AbstractController
       attr_reader :abstract
       alias_method :abstract?, :abstract
 
-      # Define a controller as abstract. See internal_methods for more
-      # details.
+      # Define a controller as abstract. See internal_methods for more details.
       def abstract!
         @abstract = true
       end
 
       def inherited(klass) # :nodoc:
-        # Define the abstract ivar on subclasses so that we don't get
-        # uninitialized ivar warnings
+        # Define the abstract ivar on subclasses so that we don't get uninitialized ivar
+        # warnings
         unless klass.instance_variable_defined?(:@abstract)
           klass.instance_variable_set(:@abstract, false)
         end
         super
       end
 
-      # A list of all internal methods for a controller. This finds the first
-      # abstract superclass of a controller, and gets a list of all public
-      # instance methods on that abstract class. Public instance methods of
-      # a controller would normally be considered action methods, so methods
-      # declared on abstract classes are being removed.
-      # (ActionController::Metal and ActionController::Base are defined as abstract)
+      # A list of all internal methods for a controller. This finds the first abstract
+      # superclass of a controller, and gets a list of all public instance methods on
+      # that abstract class. Public instance methods of a controller would normally be
+      # considered action methods, so methods declared on abstract classes are being
+      # removed. (ActionController::Metal and ActionController::Base are defined as
+      # abstract)
       def internal_methods
         controller = self
         methods = []
@@ -85,18 +86,18 @@ module AbstractController
         controller.public_instance_methods(true) - methods
       end
 
-      # 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 methods that are internal, but still exist on the class
-      # itself.
+      # 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 methods that are internal, but still
+      # exist on the class itself.
+      #
+      # #### Returns
+      # *   `Set` - A set of all methods that should be considered actions.
       #
-      # ==== Returns
-      # * <tt>Set</tt> - A set of all methods that should be considered actions.
       def action_methods
         @action_methods ||= begin
-          # All public instance methods of this class, including ancestors
-          # except for public instance methods of Base and its ancestors.
+          # All public instance methods of this class, including ancestors except for
+          # public instance methods of Base and its ancestors.
           methods = public_instance_methods(true) - internal_methods
           # Be sure to include shadowed public instance methods of this class.
           methods.concat(public_instance_methods(false))
@@ -105,23 +106,24 @@ module AbstractController
         end
       end
 
-      # action_methods are cached and there is sometimes a need to refresh
-      # them. ::clear_action_methods! allows you to do that, so next time
-      # you run action_methods, they will be recalculated.
+      # action_methods are cached and there is sometimes a need to refresh 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.
       #
-      #   class MyApp::MyPostsController < AbstractController::Base
+      #     class MyApp::MyPostsController < AbstractController::Base
+      #
+      #     end
       #
-      #   end
+      #     MyApp::MyPostsController.controller_path # => "my_app/my_posts"
       #
-      #   MyApp::MyPostsController.controller_path # => "my_app/my_posts"
+      # #### Returns
+      # *   `String`
       #
-      # ==== Returns
-      # * <tt>String</tt>
       def controller_path
         @controller_path ||= name.delete_suffix("Controller").underscore unless anonymous?
       end
@@ -142,13 +144,14 @@ module AbstractController
 
     # Calls the action going through the entire Action Dispatch stack.
     #
-    # The actual method that is called is determined by calling
-    # #method_for_action. If no method can handle the action, then an
-    # AbstractController::ActionNotFound error is raised.
+    # The actual method that is called is determined by calling #method_for_action.
+    # If no method can handle the action, then an AbstractController::ActionNotFound
+    # error is raised.
     #
-    # ==== Returns
-    # * <tt>self</tt>
-    def process(action, *args)
+    # #### Returns
+    # *   `self`
+    #
+    def process(action, ...)
       @_action_name = action.to_s
 
       unless action_name = _find_action_name(@_action_name)
@@ -157,9 +160,8 @@ module AbstractController
 
       @_response_body = nil
 
-      process_action(action_name, *args)
+      process_action(action_name, ...)
     end
-    ruby2_keywords(:process)
 
     # Delegates to the class's ::controller_path.
     def controller_path
@@ -171,31 +173,30 @@ module AbstractController
       self.class.action_methods
     end
 
-    # Returns true if a method for the action is available and
-    # can be dispatched, false otherwise.
+    # Returns true if a method for the action is available and can be dispatched,
+    # false otherwise.
+    #
+    # Notice that `action_methods.include?("foo")` may return false and
+    # `available_action?("foo")` returns true because this method considers actions
+    # that are also available through other means, for example, implicit render
+    # ones.
     #
-    # Notice that <tt>action_methods.include?("foo")</tt> may return
-    # false and <tt>available_action?("foo")</tt> returns true because
-    # this method considers actions that are also available
-    # through other means, for example, implicit render ones.
+    # #### Parameters
+    # *   `action_name` - The name of an action to be tested
     #
-    # ==== Parameters
-    # * <tt>action_name</tt> - The name of an action to be tested
     def available_action?(action_name)
       _find_action_name(action_name)
     end
 
-    # Tests if a response body is set. Used to determine if the
-    # +process_action+ callback needs to be terminated in
-    # AbstractController::Callbacks.
+    # Tests if a response body is set. Used to determine if the `process_action`
+    # callback needs to be terminated in AbstractController::Callbacks.
     def performed?
       response_body
     end
 
-    # Returns true if the given controller is capable of rendering
-    # a path. A subclass of +AbstractController::Base+
-    # may return false. An Email controller for example does not
-    # support paths, only full URLs.
+    # Returns true if the given controller is capable of rendering a path. A
+    # subclass of `AbstractController::Base` may return false. An Email controller
+    # for example does not support paths, only full URLs.
     def self.supports_path?
       true
     end
@@ -205,80 +206,83 @@ module AbstractController
     end
 
     private
-      # Returns true if the name can be considered an action because
-      # it has a method defined in the controller.
+      # Returns true if the name can be considered an action because it has a method
+      # defined in the controller.
+      #
+      # #### Parameters
+      # *   `name` - The name of an action to be tested
       #
-      # ==== Parameters
-      # * <tt>name</tt> - The name of an action to be tested
       def action_method?(name)
         self.class.action_methods.include?(name)
       end
 
-      # Call the action. Override this in a subclass to modify the
-      # behavior around processing an action. This, and not #process,
-      # is the intended way to override action dispatching.
+      # Call the action. Override this in a subclass to modify the behavior around
+      # processing an action. This, and not #process, is the intended way to override
+      # action dispatching.
       #
-      # Notice that the first argument is the method to be dispatched
-      # which is *not* necessarily the same as the action name.
+      # Notice that the first argument is the method to be dispatched which is **not**
+      # necessarily the same as the action name.
       def process_action(...)
         send_action(...)
       end
 
-      # Actually call the method associated with the action. Override
-      # this method if you wish to change how action methods are called,
-      # not to add additional behavior around it. For example, you would
-      # override #send_action if you want to inject arguments into the
-      # method.
+      # Actually call the method associated with the action. Override this method if
+      # you wish to change how action methods are called, not to add additional
+      # behavior around it. For example, you would override #send_action if you want
+      # to inject arguments into the method.
       alias send_action send
 
-      # If the action name was not found, but a method called "action_missing"
-      # was found, #method_for_action will return "_handle_action_missing".
-      # This method calls #action_missing with the current action name.
+      # If the action name was not found, but a method called "action_missing" was
+      # found, #method_for_action will return "_handle_action_missing". This method
+      # calls #action_missing with the current action name.
       def _handle_action_missing(*args)
         action_missing(@_action_name, *args)
       end
 
-      # Takes an action name and returns the name of the method that will
-      # handle the action.
+      # Takes an action name and returns the name of the method that will handle the
+      # action.
       #
       # It checks if the action name is valid and returns false otherwise.
       #
       # See method_for_action for more information.
       #
-      # ==== Parameters
-      # * <tt>action_name</tt> - An action name to find a method name for
+      # #### Parameters
+      # *   `action_name` - An action name to find a method name for
+      #
+      #
+      # #### Returns
+      # *   `string` - The name of the method that handles the action
+      # *   false           - No valid method name could be found.
       #
-      # ==== Returns
-      # * <tt>string</tt> - The name of the method that handles the action
-      # * false           - No valid method name could be found.
-      # Raise +AbstractController::ActionNotFound+.
+      # Raise `AbstractController::ActionNotFound`.
       def _find_action_name(action_name)
         _valid_action_name?(action_name) && method_for_action(action_name)
       end
 
-      # Takes an action name and returns the name of the method that will
-      # handle the action. In normal cases, this method returns the same
-      # name as it receives. By default, if #method_for_action receives
-      # a name that is not an action, it will look for an #action_missing
-      # method and return "_handle_action_missing" if one is found.
+      # Takes an action name and returns the name of the method that will handle the
+      # action. In normal cases, this method returns the same name as it receives. By
+      # default, if #method_for_action receives a name that is not an action, it will
+      # look for an #action_missing method and return "_handle_action_missing" if one
+      # is found.
+      #
+      # Subclasses may override this method to add additional conditions that should
+      # be considered an action. For instance, an HTTP controller with a template
+      # matching the action name is considered to exist.
+      #
+      # If you override this method to handle additional cases, you may also provide a
+      # method (like `_handle_method_missing`) to handle the case.
       #
-      # Subclasses may override this method to add additional conditions
-      # that should be considered an action. For instance, an HTTP controller
-      # with a template matching the action name is considered to exist.
+      # If none of these conditions are true, and `method_for_action` returns `nil`,
+      # an `AbstractController::ActionNotFound` exception will be raised.
       #
-      # If you override this method to handle additional cases, you may
-      # also provide a method (like +_handle_method_missing+) to handle
-      # the case.
+      # #### Parameters
+      # *   `action_name` - An action name to find a method name for
       #
-      # If none of these conditions are true, and +method_for_action+
-      # returns +nil+, an +AbstractController::ActionNotFound+ exception will be raised.
       #
-      # ==== Parameters
-      # * <tt>action_name</tt> - An action name to find a method name for
+      # #### Returns
+      # *   `string` - The name of the method that handles the action
+      # *   `nil`    - No method name could be found.
       #
-      # ==== Returns
-      # * <tt>string</tt> - The name of the method that handles the action
-      # * <tt>nil</tt>    - No method name could be found.
       def method_for_action(action_name)
         if action_method?(action_name)
           action_name

data/lib/abstract_controller/caching/fragments.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module AbstractController
   module Caching
-    # = Abstract Controller Caching \Fragments
+    # # Abstract Controller Caching Fragments
     #
-    # Fragment caching is used for caching various blocks within
-    # views without caching the entire action as a whole. This is
-    # useful when certain elements of an action change frequently or
-    # depend on complicated state while other parts rarely change or
-    # can be shared amongst multiple parties. The caching is done using
-    # the +cache+ helper available in the Action View. See
+    # Fragment caching is used for caching various blocks within views without
+    # caching the entire action as a whole. This is useful when certain elements of
+    # an action change frequently or depend on complicated state while other parts
+    # rarely change or can be shared amongst multiple parties. The caching is done
+    # using the `cache` helper available in the Action View. See
     # ActionView::Helpers::CacheHelper for more information.
     #
-    # While it's strongly recommended that you use key-based cache
-    # expiration (see links in CacheHelper for more information),
-    # it is also possible to manually expire caches. For example:
+    # While it's strongly recommended that you use key-based cache expiration (see
+    # links in CacheHelper for more information), it is also possible to manually
+    # expire caches. For example:
     #
-    #   expire_fragment('name_of_cache')
+    #     expire_fragment('name_of_cache')
     module Fragments
       extend ActiveSupport::Concern
 
@@ -35,38 +36,35 @@ module AbstractController
       end
 
       module ClassMethods
-        # Allows you to specify controller-wide key prefixes for
-        # cache fragments. Pass either a constant +value+, or a block
-        # which computes a value each time a cache key is generated.
+        # Allows you to specify controller-wide key prefixes for cache fragments. Pass
+        # either a constant `value`, or a block which computes a value each time a cache
+        # key is generated.
         #
-        # For example, you may want to prefix all fragment cache keys
-        # with a global version identifier, so you can easily
-        # invalidate all caches.
+        # For example, you may want to prefix all fragment cache keys with a global
+        # version identifier, so you can easily invalidate all caches.
         #
-        #   class ApplicationController
-        #     fragment_cache_key "v1"
-        #   end
+        #     class ApplicationController
+        #       fragment_cache_key "v1"
+        #     end
         #
-        # When it's time to invalidate all fragments, simply change
-        # the string constant. Or, progressively roll out the cache
-        # invalidation using a computed value:
+        # When it's time to invalidate all fragments, simply change the string constant.
+        # Or, progressively roll out the cache invalidation using a computed value:
         #
-        #   class ApplicationController
-        #     fragment_cache_key do
-        #       @account.id.odd? ? "v1" : "v2"
+        #     class ApplicationController
+        #       fragment_cache_key do
+        #         @account.id.odd? ? "v1" : "v2"
+        #       end
         #     end
-        #   end
         def fragment_cache_key(value = nil, &key)
           self.fragment_cache_keys += [key || -> { value }]
         end
       end
 
-      # Given a key (as described in +expire_fragment+), returns
-      # a key array suitable for use in reading, writing, or expiring a
-      # cached fragment. All keys begin with <tt>:views</tt>,
-      # followed by <tt>ENV["RAILS_CACHE_ID"]</tt> or <tt>ENV["RAILS_APP_VERSION"]</tt> if set,
-      # followed by any controller-wide key prefix values, ending
-      # with the specified +key+ value.
+      # Given a key (as described in `expire_fragment`), returns a key array suitable
+      # for use in reading, writing, or expiring a cached fragment. All keys begin
+      # with `:views`, followed by `ENV["RAILS_CACHE_ID"]` or
+      # `ENV["RAILS_APP_VERSION"]` if set, followed by any controller-wide key prefix
+      # values, ending with the specified `key` value.
       def combined_fragment_cache_key(key)
         head = self.class.fragment_cache_keys.map { |k| instance_exec(&k) }
         tail = key.is_a?(Hash) ? url_for(key).split("://").last : key
@@ -77,8 +75,8 @@ module AbstractController
         cache_key
       end
 
-      # Writes +content+ to the location signified by
-      # +key+ (see +expire_fragment+ for acceptable formats).
+      # Writes `content` to the location signified by `key` (see `expire_fragment` for
+      # acceptable formats).
       def write_fragment(key, content, options = nil)
         return content unless cache_configured?
 
@@ -90,8 +88,8 @@ module AbstractController
         content
       end
 
-      # Reads a cached fragment from the location signified by +key+
-      # (see +expire_fragment+ for acceptable formats).
+      # Reads a cached fragment from the location signified by `key` (see
+      # `expire_fragment` for acceptable formats).
       def read_fragment(key, options = nil)
         return unless cache_configured?
 
@@ -102,8 +100,8 @@ module AbstractController
         end
       end
 
-      # Check if a cached fragment from the location signified by
-      # +key+ exists (see +expire_fragment+ for acceptable formats).
+      # Check if a cached fragment from the location signified by `key` exists (see
+      # `expire_fragment` for acceptable formats).
       def fragment_exist?(key, options = nil)
         return unless cache_configured?
         key = combined_fragment_cache_key(key)
@@ -115,22 +113,21 @@ module AbstractController
 
       # Removes fragments from the cache.
       #
-      # +key+ can take one of three forms:
+      # `key` can take one of three forms:
+      #
+      # *   String - This would normally take the form of a path, like
+      #     `pages/45/notes`.
+      # *   Hash - Treated as an implicit call to `url_for`, like `{ controller:
+      #     'pages', action: 'notes', id: 45}`
+      # *   Regexp - Will remove any fragment that matches, so `%r{pages/\d*/notes}`
+      #     might remove all notes. Make sure you don't use anchors in the regex (`^`
+      #     or `$`) because the actual filename matched looks like
+      #     `./cache/filename/path.cache`. Note: Regexp expiration is only supported
+      #     on caches that can iterate over all keys (unlike memcached).
       #
-      # * String - This would normally take the form of a path, like
-      #   <tt>pages/45/notes</tt>.
-      # * Hash - Treated as an implicit call to +url_for+, like
-      #   <tt>{ controller: 'pages', action: 'notes', id: 45}</tt>
-      # * Regexp - Will remove any fragment that matches, so
-      #   <tt>%r{pages/\d*/notes}</tt> might remove all notes. Make sure you
-      #   don't use anchors in the regex (<tt>^</tt> or <tt>$</tt>) because
-      #   the actual filename matched looks like
-      #   <tt>./cache/filename/path.cache</tt>. Note: Regexp expiration is
-      #   only supported on caches that can iterate over all keys (unlike
-      #   memcached).
       #
-      # +options+ is passed through to the cache store's +delete+
-      # method (or <tt>delete_matched</tt>, for Regexp keys).
+      # `options` is passed through to the cache store's `delete` method (or
+      # `delete_matched`, for Regexp keys).
       def expire_fragment(key, options = nil)
         return unless cache_configured?
         key = combined_fragment_cache_key(key) unless key.is_a?(Regexp)

data/lib/abstract_controller/caching.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module AbstractController
   module Caching
     extend ActiveSupport::Concern