actionpack 7.1.3.2 → 7.2.0.beta1

data/lib/action_controller/metal/renderers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "set"
 
 module ActionController
@@ -13,7 +15,7 @@ module ActionController
     Renderers.remove(key)
   end
 
-  # See <tt>Responder#api_behavior</tt>
+  # See `Responder#api_behavior`
   class MissingRenderer < LoadError
     def initialize(format)
       super "No renderer defined for format: #{format}"
@@ -24,7 +26,7 @@ module ActionController
     extend ActiveSupport::Concern
 
     # A Set containing renderer names that correspond to available renderer procs.
-    # Default values are <tt>:json</tt>, <tt>:js</tt>, <tt>:xml</tt>.
+    # Default values are `:json`, `:js`, `:xml`.
     RENDERERS = Set.new
 
     included do
@@ -42,35 +44,34 @@ module ActionController
       end
     end
 
-    # Adds a new renderer to call within controller actions.
-    # A renderer is invoked by passing its name as an option to
-    # AbstractController::Rendering#render. To create a renderer
-    # pass it a name and a block. The block takes two arguments, the first
-    # is the value paired with its key and the second is the remaining
-    # hash of options passed to +render+.
+    # Adds a new renderer to call within controller actions. A renderer is invoked
+    # by passing its name as an option to AbstractController::Rendering#render. To
+    # create a renderer pass it a name and a block. The block takes two arguments,
+    # the first is the value paired with its key and the second is the remaining
+    # hash of options passed to `render`.
     #
     # Create a csv renderer:
     #
-    #   ActionController::Renderers.add :csv do |obj, options|
-    #     filename = options[:filename] || 'data'
-    #     str = obj.respond_to?(:to_csv) ? obj.to_csv : obj.to_s
-    #     send_data str, type: Mime[:csv],
-    #       disposition: "attachment; filename=#{filename}.csv"
-    #   end
+    #     ActionController::Renderers.add :csv do |obj, options|
+    #       filename = options[:filename] || 'data'
+    #       str = obj.respond_to?(:to_csv) ? obj.to_csv : obj.to_s
+    #       send_data str, type: Mime[:csv],
+    #         disposition: "attachment; filename=#{filename}.csv"
+    #     end
     #
-    # Note that we used Mime[:csv] for the csv mime type as it comes with \Rails.
+    # Note that we used [Mime](:csv) for the csv mime type as it comes with Rails.
     # For a custom renderer, you'll need to register a mime type with
-    # <tt>Mime::Type.register</tt>.
+    # `Mime::Type.register`.
     #
     # To use the csv renderer in a controller action:
     #
-    #   def show
-    #     @csvable = Csvable.find(params[:id])
-    #     respond_to do |format|
-    #       format.html
-    #       format.csv { render csv: @csvable, filename: @csvable.name }
+    #     def show
+    #       @csvable = Csvable.find(params[:id])
+    #       respond_to do |format|
+    #         format.html
+    #         format.csv { render csv: @csvable, filename: @csvable.name }
+    #       end
     #     end
-    #   end
     def self.add(key, &block)
       define_method(_render_with_renderer_method_name(key), &block)
       RENDERERS << key.to_sym
@@ -80,7 +81,7 @@ module ActionController
     #
     # To remove a csv renderer:
     #
-    #   ActionController::Renderers.remove(:csv)
+    #     ActionController::Renderers.remove(:csv)
     def self.remove(key)
       RENDERERS.delete(key.to_sym)
       method_name = _render_with_renderer_method_name(key)
@@ -92,39 +93,39 @@ module ActionController
     end
 
     module ClassMethods
-      # Adds, by name, a renderer or renderers to the +_renderers+ available
-      # to call within controller actions.
+      # Adds, by name, a renderer or renderers to the `_renderers` available to call
+      # within controller actions.
       #
       # It is useful when rendering from an ActionController::Metal controller or
       # otherwise to add an available renderer proc to a specific controller.
       #
-      # Both ActionController::Base and ActionController::API
-      # include ActionController::Renderers::All, making all renderers
-      # available in the controller. See Renderers::RENDERERS and Renderers.add.
+      # Both ActionController::Base and ActionController::API include
+      # ActionController::Renderers::All, making all renderers available in the
+      # controller. See Renderers::RENDERERS and Renderers.add.
       #
-      # Since ActionController::Metal controllers cannot render, the controller
-      # must include AbstractController::Rendering, ActionController::Rendering,
-      # and ActionController::Renderers, and have at least one renderer.
+      # Since ActionController::Metal controllers cannot render, the controller must
+      # include AbstractController::Rendering, ActionController::Rendering, and
+      # ActionController::Renderers, and have at least one renderer.
       #
-      # Rather than including ActionController::Renderers::All and including all renderers,
-      # you may specify which renderers to include by passing the renderer name or names to
-      # +use_renderers+. For example, a controller that includes only the <tt>:json</tt> renderer
-      # (+_render_with_renderer_json+) might look like:
+      # Rather than including ActionController::Renderers::All and including all
+      # renderers, you may specify which renderers to include by passing the renderer
+      # name or names to `use_renderers`. For example, a controller that includes only
+      # the `:json` renderer (`_render_with_renderer_json`) might look like:
       #
-      #   class MetalRenderingController < ActionController::Metal
-      #     include AbstractController::Rendering
-      #     include ActionController::Rendering
-      #     include ActionController::Renderers
+      #     class MetalRenderingController < ActionController::Metal
+      #       include AbstractController::Rendering
+      #       include ActionController::Rendering
+      #       include ActionController::Renderers
       #
-      #     use_renderers :json
+      #       use_renderers :json
       #
-      #     def show
-      #       render json: record
+      #       def show
+      #         render json: record
+      #       end
       #     end
-      #   end
       #
-      # You must specify a +use_renderer+, else the +controller.renderer+ and
-      # +controller._renderers+ will be <tt>nil</tt>, and the action will fail.
+      # You must specify a `use_renderer`, else the `controller.renderer` and
+      # `controller._renderers` will be `nil`, and the action will fail.
       def use_renderers(*args)
         renderers = _renderers + args
         self._renderers = renderers.freeze
@@ -132,11 +133,11 @@ module ActionController
       alias use_renderer use_renderers
     end
 
-    # Called by +render+ in AbstractController::Rendering
-    # which sets the return value as the +response_body+.
+    # Called by `render` in AbstractController::Rendering which sets the return
+    # value as the `response_body`.
     #
-    # If no renderer is found, +super+ returns control to
-    # <tt>ActionView::Rendering.render_to_body</tt>, if present.
+    # If no renderer is found, `super` returns control to
+    # `ActionView::Rendering.render_to_body`, if present.
     def render_to_body(options)
       _render_to_body_with_renderer(options) || super
     end

data/lib/action_controller/metal/rendering.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
   module Rendering
     extend ActiveSupport::Concern
@@ -10,8 +12,8 @@ module ActionController
       # Documentation at ActionController::Renderer#render
       delegate :render, to: :renderer
 
-      # Returns a renderer instance (inherited from ActionController::Renderer)
-      # for the controller.
+      # Returns a renderer instance (inherited from ActionController::Renderer) for
+      # the controller.
       attr_reader :renderer
 
       def setup_renderer! # :nodoc:
@@ -24,113 +26,139 @@ module ActionController
       end
     end
 
-    # Renders a template and assigns the result to +self.response_body+.
+    # Renders a template and assigns the result to `self.response_body`.
+    #
+    # If no rendering mode option is specified, the template will be derived from
+    # the first argument.
+    #
+    #     render "posts/show"
+    #     # => renders app/views/posts/show.html.erb
+    #
+    #     # In a PostsController action...
+    #     render :show
+    #     # => renders app/views/posts/show.html.erb
+    #
+    # If the first argument responds to `render_in`, the template will be rendered
+    # by calling `render_in` with the current view context.
+    #
+    #     class Greeting
+    #       def render_in(view_context)
+    #         view_context.render html: "<h1>Hello, World</h1>"
+    #       end
+    #
+    #       def format
+    #         :html
+    #       end
+    #     end
+    #
+    #     render(Greeting.new)
+    #     # => "<h1>Hello, World</h1>"
     #
-    # If no rendering mode option is specified, the template will be derived
-    # from the first argument.
+    #     render(renderable: Greeting.new)
+    #     # => "<h1>Hello, World</h1>"
     #
-    #   render "posts/show"
-    #   # => renders app/views/posts/show.html.erb
+    # #### Rendering Mode
     #
-    #   # In a PostsController action...
-    #   render :show
-    #   # => renders app/views/posts/show.html.erb
+    # `:partial`
+    # :   See ActionView::PartialRenderer for details.
     #
-    # If the first argument responds to +render_in+, the template will be
-    # rendered by calling +render_in+ with the current view context.
+    #         render partial: "posts/form", locals: { post: Post.new }
+    #         # => renders app/views/posts/_form.html.erb
     #
-    # ==== \Rendering Mode
+    # `:file`
+    # :   Renders the contents of a file. This option should **not** be used with
+    #     unsanitized user input.
     #
-    # [+:partial+]
-    #   See ActionView::PartialRenderer for details.
+    #         render file: "/path/to/some/file"
+    #         # => renders /path/to/some/file
     #
-    #     render partial: "posts/form", locals: { post: Post.new }
-    #     # => renders app/views/posts/_form.html.erb
+    # `:inline`
+    # :   Renders an ERB template string.
     #
-    # [+:file+]
-    #   Renders the contents of a file. This option should <b>not</b> be used
-    #   with unsanitized user input.
+    #         @name = "World"
+    #         render inline: "<h1>Hello, <%= @name %>!</h1>"
+    #         # => renders "<h1>Hello, World!</h1>"
     #
-    #     render file: "/path/to/some/file"
-    #     # => renders /path/to/some/file
+    # `:body`
+    # :   Renders the provided text, and sets the content type as `text/plain`.
     #
-    # [+:inline+]
-    #   Renders an ERB template string.
+    #         render body: "Hello, World!"
+    #         # => renders "Hello, World!"
     #
-    #     @name = "World"
-    #     render inline: "<h1>Hello, <%= @name %>!</h1>"
-    #     # => renders "<h1>Hello, World!</h1>"
+    # `:plain`
+    # :   Renders the provided text, and sets the content type as `text/plain`.
     #
-    # [+:body+]
-    #   Renders the provided text, and sets the content type as +text/plain+.
+    #         render plain: "Hello, World!"
+    #         # => renders "Hello, World!"
     #
-    #     render body: "Hello, World!"
-    #     # => renders "Hello, World!"
+    # `:html`
+    # :   Renders the provided HTML string, and sets the content type as
+    #     `text/html`. If the string is not `html_safe?`, performs HTML escaping on
+    #     the string before rendering.
     #
-    # [+:plain+]
-    #   Renders the provided text, and sets the content type as +text/plain+.
+    #         render html: "<h1>Hello, World!</h1>".html_safe
+    #         # => renders "<h1>Hello, World!</h1>"
     #
-    #     render plain: "Hello, World!"
-    #     # => renders "Hello, World!"
+    #         render html: "<h1>Hello, World!</h1>"
+    #         # => renders "&lt;h1&gt;Hello, World!&lt;/h1&gt;"
     #
-    # [+:html+]
-    #   Renders the provided HTML string, and sets the content type as +text/html+.
-    #   If the string is not +html_safe?+, performs HTML escaping on the string
-    #   before rendering.
+    # `:json`
+    # :   Renders the provided object as JSON, and sets the content type as
+    #     `application/json`. If the object is not a string, it will be converted to
+    #     JSON by calling `to_json`.
     #
-    #     render html: "<h1>Hello, World!</h1>".html_safe
-    #     # => renders "<h1>Hello, World!</h1>"
+    #         render json: { hello: "world" }
+    #         # => renders "{\"hello\":\"world\"}"
     #
-    #     render html: "<h1>Hello, World!</h1>"
-    #     # => renders "&lt;h1&gt;Hello, World!&lt;/h1&gt;"
+    # `:renderable`
+    # :   Renders the provided object by calling `render_in` with the current view
+    #     context. The response format is determined by calling `format` on the
+    #     renderable if it responds to `format`, falling back to `text/html` by
+    #     default.
     #
-    # [+:json+]
-    #   Renders the provided object as JSON, and sets the content type as
-    #   +application/json+. If the object is not a string, it will be converted
-    #   to JSON by calling +to_json+.
+    #         render renderable: Greeting.new
+    #         # => renders "<h1>Hello, World</h1>"
     #
-    #     render json: { hello: "world" }
-    #     # => renders "{\"hello\":\"world\"}"
     #
     # By default, when a rendering mode is specified, no layout template is
     # rendered.
     #
-    # ==== Options
+    # #### Options
     #
-    # [+:assigns+]
-    #   Hash of instance variable assignments for the template.
+    # `:assigns`
+    # :   Hash of instance variable assignments for the template.
     #
-    #     render inline: "<h1>Hello, <%= @name %>!</h1>", assigns: { name: "World" }
-    #     # => renders "<h1>Hello, World!</h1>"
+    #         render inline: "<h1>Hello, <%= @name %>!</h1>", assigns: { name: "World" }
+    #         # => renders "<h1>Hello, World!</h1>"
     #
-    # [+:locals+]
-    #   Hash of local variable assignments for the template.
+    # `:locals`
+    # :   Hash of local variable assignments for the template.
     #
-    #     render inline: "<h1>Hello, <%= name %>!</h1>", locals: { name: "World" }
-    #     # => renders "<h1>Hello, World!</h1>"
+    #         render inline: "<h1>Hello, <%= name %>!</h1>", locals: { name: "World" }
+    #         # => renders "<h1>Hello, World!</h1>"
     #
-    # [+:layout+]
-    #   The layout template to render. Can also be +false+ or +true+ to disable
-    #   or (re)enable the default layout template.
+    # `:layout`
+    # :   The layout template to render. Can also be `false` or `true` to disable or
+    #     (re)enable the default layout template.
     #
-    #     render "posts/show", layout: "holiday"
-    #     # => renders app/views/posts/show.html.erb with the app/views/layouts/holiday.html.erb layout
+    #         render "posts/show", layout: "holiday"
+    #         # => renders app/views/posts/show.html.erb with the app/views/layouts/holiday.html.erb layout
     #
-    #     render "posts/show", layout: false
-    #     # => renders app/views/posts/show.html.erb with no layout
+    #         render "posts/show", layout: false
+    #         # => renders app/views/posts/show.html.erb with no layout
     #
-    #     render inline: "<h1>Hello, World!</h1>", layout: true
-    #     # => renders "<h1>Hello, World!</h1>" with the default layout
+    #         render inline: "<h1>Hello, World!</h1>", layout: true
+    #         # => renders "<h1>Hello, World!</h1>" with the default layout
     #
-    # [+:status+]
-    #   The HTTP status code to send with the response. Can be specified as a
-    #   number or as the status name in Symbol form. Defaults to 200.
+    # `:status`
+    # :   The HTTP status code to send with the response. Can be specified as a
+    #     number or as the status name in Symbol form. Defaults to 200.
     #
-    #     render "posts/new", status: 422
-    #     # => renders app/views/posts/new.html.erb with HTTP status code 422
+    #         render "posts/new", status: 422
+    #         # => renders app/views/posts/new.html.erb with HTTP status code 422
     #
-    #     render "posts/new", status: :unprocessable_entity
-    #     # => renders app/views/posts/new.html.erb with HTTP status code 422
+    #         render "posts/new", status: :unprocessable_entity
+    #         # => renders app/views/posts/new.html.erb with HTTP status code 422
     #
     #--
     # Check for double render errors and set the content_type after rendering.
@@ -140,7 +168,7 @@ module ActionController
     end
 
     # Similar to #render, but only returns the rendered template as a string,
-    # instead of setting +self.response_body+.
+    # instead of setting `self.response_body`.
     #--
     # Override render_to_string because body can now be set to a Rack body.
     def render_to_string(*)