revamps the docs of strong params require [ci skip]

References #19565.

1 files changed, 40 insertions, 9 deletions

diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index da507ca294..32e569e005 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -240,25 +240,56 @@ module ActionController
       self
     end
 
-    # Ensures that a parameter is present. If it's present, returns
-    # the parameter at the given +key+, otherwise raises an
-    # <tt>ActionController::ParameterMissing</tt> error.
+    # This method accepts both a single key and an array of keys.
+    #
+    # When passed a single key, if it exists and its associated value is
+    # either present or the singleton +false+, returns said value:
     #
     #   ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person)
     #   # => {"name"=>"Francesco"}
     #
+    # Otherwise raises <tt>ActionController::ParameterMissing</tt>:
+    #
+    #   ActionController::Parameters.new.require(:person)
+    #   # ActionController::ParameterMissing: param is missing or the value is empty: person
+    #
     #   ActionController::Parameters.new(person: nil).require(:person)
-    #   # => ActionController::ParameterMissing: param is missing or the value is empty: person
+    #   # ActionController::ParameterMissing: param is missing or the value is empty: person
+    #
+    #   ActionController::Parameters.new(person: "\t").require(:person)
+    #   # ActionController::ParameterMissing: param is missing or the value is empty: person
     #
     #   ActionController::Parameters.new(person: {}).require(:person)
-    #   # => ActionController::ParameterMissing: param is missing or the value is empty: person
+    #   # ActionController::ParameterMissing: param is missing or the value is empty: person
+    #
+    # When given an array of keys, the method tries to require each one of them
+    # in order. It if succeeds an array with the respective return values is
+    # returned:
+    #
+    #   params = ActionController::Parameters.new(user: { ... }, profile: { ... })
+    #   user_params, profile_params = params.require(:user, :profile)
     #
-    #   ActionController::Parameters.new(first_name: 'Gaurish', title: nil).require([:first_name, :title])
-    #   # => ActionController::ParameterMissing: param is missing or the value is empty: title
+    # Otherwise, the method reraises the first exception found:
     #
-    #   params = ActionController::Parameters.new(first_name: 'Gaurish', title: 'Mjallo')
-    #   first_name, title = params.require([:first_name, :title])
+    #   params = ActionController::Parameters.new(user: {}, profile: {})
+    #   user_params, profile_params = params.require(:user, :profile)
+    #   # ActionController::ParameterMissing: param is missing or the value is empty: user
+    #
+    # Technically this method can be used to fetch terminal values:
+    #
+    #   # CAREFUL
+    #   params = ActionController::Parameters.new(person: { name: 'Finn' })
+    #   name = params.require(:person).require(:name) # CAREFUL
+    #
+    # but take into account that at some point those ones have to be permitted:
+    #
+    #   def user_params
+    #     params.require(:person).permit(:name).tap do |user_params|
+    #       user_params.require(:name) # SAFER
+    #     end
+    #   end
     #
+    # for example.
     def require(key)
       return key.map { |k| require(k) } if key.is_a?(Array)
       value = self[key]