actionpack 7.1.5.1 → 8.1.2

data/lib/action_controller/metal/helpers.rb

@@ -1,59 +1,64 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller \Helpers
+  # # Action Controller Helpers
   #
-  # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
-  # numbers and model objects, to name a few. These helpers are available to all templates
-  # by default.
+  # The Rails framework provides a large number of helpers for working with
+  # assets, dates, forms, numbers and model objects, to name a few. These helpers
+  # are available to all templates by default.
   #
-  # In addition to using the standard template helpers provided, creating custom helpers to
-  # extract complicated logic or reusable functionality is strongly encouraged. By default, each controller
-  # will include all helpers. These helpers are only accessible on the controller through <tt>#helpers</tt>
+  # In addition to using the standard template helpers provided, creating custom
+  # helpers to extract complicated logic or reusable functionality is strongly
+  # encouraged. By default, each controller will include all helpers. These
+  # helpers are only accessible on the controller through `#helpers`
   #
-  # In previous versions of \Rails the controller will include a helper which
-  # matches the name of the controller, e.g., <tt>MyController</tt> will automatically
-  # include <tt>MyHelper</tt>. You can revert to the old behavior with the following:
+  # In previous versions of Rails the controller will include a helper which
+  # matches the name of the controller, e.g., `MyController` will automatically
+  # include `MyHelper`. You can revert to the old behavior with the following:
   #
-  #    # config/application.rb
-  #    class Application < Rails::Application
-  #      config.action_controller.include_all_helpers = false
-  #    end
+  #     # config/application.rb
+  #     class Application < Rails::Application
+  #       config.action_controller.include_all_helpers = false
+  #     end
   #
-  # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
-  # controller which inherits from it.
+  # Additional helpers can be specified using the `helper` class method in
+  # ActionController::Base or any controller which inherits from it.
   #
-  # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
-  # a \Time object is blank:
+  # The `to_s` method from the Time class can be wrapped in a helper method to
+  # display a custom message if a Time object is blank:
   #
-  #   module FormattedTimeHelper
-  #     def format_time(time, format=:long, blank_message="&nbsp;")
-  #       time.blank? ? blank_message : time.to_fs(format)
+  #     module FormattedTimeHelper
+  #       def format_time(time, format=:long, blank_message="&nbsp;")
+  #         time.blank? ? blank_message : time.to_fs(format)
+  #       end
   #     end
-  #   end
   #
-  # FormattedTimeHelper can now be included in a controller, using the +helper+ class method:
+  # FormattedTimeHelper can now be included in a controller, using the `helper`
+  # class method:
   #
-  #   class EventsController < ActionController::Base
-  #     helper FormattedTimeHelper
-  #     def index
-  #       @events = Event.all
+  #     class EventsController < ActionController::Base
+  #       helper FormattedTimeHelper
+  #       def index
+  #         @events = Event.all
+  #       end
   #     end
-  #   end
   #
-  # Then, in any view rendered by <tt>EventsController</tt>, the <tt>format_time</tt> method can be called:
+  # Then, in any view rendered by `EventsController`, the `format_time` method can
+  # be called:
   #
-  #   <% @events.each do |event| -%>
-  #     <p>
-  #       <%= format_time(event.time, :short, "N/A") %> | <%= event.name %>
-  #     </p>
-  #   <% end -%>
+  #     <% @events.each do |event| -%>
+  #       <p>
+  #         <%= format_time(event.time, :short, "N/A") %> | <%= event.name %>
+  #       </p>
+  #     <% end -%>
   #
-  # Finally, assuming we have two event instances, one which has a time and one which does not,
-  # the output might look like this:
+  # Finally, assuming we have two event instances, one which has a time and one
+  # which does not, the output might look like this:
   #
-  #   23 Aug 11:30 | Carolina Railhawks Soccer Match
-  #   N/A | Carolina Railhawks Training Workshop
+  #     23 Aug 11:30 | Carolina Railhawks Soccer Match
+  #     N/A | Carolina Railhawks Training Workshop
   #
   module Helpers
     extend ActiveSupport::Concern
@@ -68,23 +73,24 @@ module ActionController
 
     module ClassMethods
       # Declares helper accessors for controller attributes. For example, the
-      # following adds new +name+ and <tt>name=</tt> instance methods to a
-      # controller and makes them available to the view:
-      #   attr_accessor :name
-      #   helper_attr :name
+      # following adds new `name` and `name=` instance methods to a controller and
+      # makes them available to the view:
+      #     attr_accessor :name
+      #     helper_attr :name
+      #
+      # #### Parameters
+      # *   `attrs` - Names of attributes to be converted into helpers.
       #
-      # ==== Parameters
-      # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
       def helper_attr(*attrs)
         attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
       end
 
       # Provides a proxy to access helper methods from outside the view.
       #
-      # Note that the proxy is rendered under a different view context.
-      # This may cause incorrect behavior with capture methods. Consider
-      # using {helper}[rdoc-ref:AbstractController::Helpers::ClassMethods#helper]
-      # instead when using +capture+.
+      # Note that the proxy is rendered under a different view context. This may cause
+      # incorrect behavior with capture methods. Consider using
+      # [helper](rdoc-ref:AbstractController::Helpers::ClassMethods#helper) instead
+      # when using `capture`.
       def helpers
         @helper_proxy ||= begin
           proxy = ActionView::Base.empty
@@ -93,21 +99,23 @@ module ActionController
         end
       end
 
-      # Override modules_for_helpers to accept +:all+ as argument, which loads
-      # all helpers in helpers_path.
+      # Override modules_for_helpers to accept `:all` as argument, which loads all
+      # helpers in helpers_path.
+      #
+      # #### Parameters
+      # *   `args` - A list of helpers
+      #
       #
-      # ==== Parameters
-      # * <tt>args</tt> - A list of helpers
+      # #### Returns
+      # *   `array` - A normalized list of modules for the list of helpers provided.
       #
-      # ==== Returns
-      # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
       def modules_for_helpers(args)
         args += all_application_helpers if args.delete(:all)
         super(args)
       end
 
       private
-        # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
+        # Extract helper names from files in `app/helpers/***/**_helper.rb`
         def all_application_helpers
           all_helpers_from_path(helpers_path)
         end