From eb60e20193a1e646deca025b97583d3e6ff97bf3 Mon Sep 17 00:00:00 2001
From: Hartley McGuire <skipkayhil@gmail.com>
Date: Tue, 14 Nov 2023 23:31:39 -0500
Subject: [PATCH] Add documentation for delegated methods on Metal

Some of these were specifically mentioned earlier in the Metal docs
(response_body=, content_type=, status=) but were not linked because the
methods were not documented (due to being part of a delegation).

This commit separates all of the delegated methods so that they can be
documented, adds links for the mentioned methods, and additionally
documents two methods on Response that are mentioned in the new Metal
documentation, but were not previously documented.
---
 actionpack/lib/action_controller/metal.rb     | 39 +++++++++++++++----
 .../lib/action_dispatch/http/response.rb      | 14 ++++++-
 2 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb
index 9f2bb0eccc..4c58735fa2 100644
--- a/actionpack/lib/action_controller/metal.rb
+++ b/actionpack/lib/action_controller/metal.rb
@@ -81,14 +81,14 @@ def build_middleware(klass, args, block)
   #
   #     get 'hello', to: HelloController.action(:index)
   #
-  # The `action` method returns a valid Rack application for the Rails router to
+  # The ::action method returns a valid Rack application for the Rails router to
   # dispatch to.
   #
   # ## Rendering Helpers
   #
-  # `ActionController::Metal` by default provides no utilities for rendering
-  # views, partials, or other responses aside from explicitly calling of
-  # `response_body=`, `content_type=`, and `status=`. To add the render helpers
+  # By default, `ActionController::Metal` provides no utilities for rendering
+  # views, partials, or other responses aside from some low-level setters such
+  # as #response_body=, #content_type=, and #status=. To add the render helpers
   # you're used to having in a normal controller, you can do the following:
   #
   #     class HelloController < ActionController::Metal
@@ -179,8 +179,33 @@ def controller_name
     # Delegates to ActionDispatch::Response#headers.
     delegate :headers, to: "@_response"
 
-    delegate :status=, :location=, :content_type=,
-             :status, :location, :content_type, :media_type, to: "@_response"
+    ##
+    # Delegates to ActionDispatch::Response#status=
+    delegate :status=, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#location=
+    delegate :location=, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#content_type=
+    delegate :content_type=, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#status
+    delegate :status, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#location
+    delegate :location, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#content_type
+    delegate :content_type, to: "@_response"
+
+    ##
+    # Delegates to ActionDispatch::Response#media_type
+    delegate :media_type, to: "@_response"
 
     def initialize
       @_request = nil
@@ -201,7 +226,7 @@ def params=(val)
 
     alias :response_code :status # :nodoc:
 
-    # Basic url_for that can be overridden for more robust functionality.
+    # Basic `url_for` that can be overridden for more robust functionality.
     def url_for(string)
       string
     end
diff --git a/actionpack/lib/action_dispatch/http/response.rb b/actionpack/lib/action_dispatch/http/response.rb
index e74363f6aa..77486647a1 100644
--- a/actionpack/lib/action_dispatch/http/response.rb
+++ b/actionpack/lib/action_dispatch/http/response.rb
@@ -231,6 +231,18 @@ def sending?;   synchronize { @sending };   end
     def committed?; synchronize { @committed }; end
     def sent?;      synchronize { @sent };      end
 
+    ##
+    # :method: location
+    #
+    # Location of the response.
+
+    ##
+    # :method: location=
+    #
+    # :call-seq: location=(location)
+    #
+    # Sets the location of the response
+
     # Sets the HTTP status code.
     def status=(status)
       @status = Rack::Utils.status_code(status)
@@ -241,7 +253,7 @@ def status=(status)
     #
     #     response.content_type = "text/plain"
     #
-    # If a character set has been defined for this response (see charset=) then the
+    # If a character set has been defined for this response (see #charset=) then the
     # character set information will also be included in the content type
     # information.
     def content_type=(content_type)