Add documentation to raise_on_unpermitted_parameters option

[ci skip]

1 files changed, 17 insertions, 2 deletions

diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index 81554aad3d..713516d0cb 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -58,10 +58,15 @@ module ActionController
   #   Person.first.update!(permitted)
   #   # => #<Person id: 1, name: "Francesco", age: 22, role: "user">
   #
-  # It provides a +permit_all_parameters+ option that controls the top-level
-  # behaviour of new instances. If it's +true+, all the parameters will be
+  # It provides two options that controls the top-level behavior of new instances:
+  #
+  # * +permit_all_parameters+ - If it's +true+, all the parameters will be
   # permitted by default. The default value for +permit_all_parameters+
   # option is +false+.
+  # * +raise_on_unpermitted_parameters+ - If it's +true+, it will raise an exception
+  # if parameters that are not explicitly permitted are found. The default value for
+  # +raise_on_unpermitted_parameters+ # option is +true+ in test and development
+  # environments, +false+ otherwise.
   #
   #   params = ActionController::Parameters.new
   #   params.permitted? # => false
@@ -71,6 +76,16 @@ module ActionController
   #   params = ActionController::Parameters.new
   #   params.permitted? # => true
   #
+  #   params = ActionController::Parameters.new(a: "123", b: "456")
+  #   params.permit(:c)
+  #   # => {}
+  #
+  #   ActionController::Parameters.raise_on_unpermitted_parameters = true
+  #
+  #   params = ActionController::Parameters.new(a: "123", b: "456")
+  #   params.permit(:c)
+  #   # => ActionController::ForbiddenParameters: found forbidden keys: a, b
+  #
   # <tt>ActionController::Parameters</tt> is inherited from
   # <tt>ActiveSupport::HashWithIndifferentAccess</tt>, this means
   # that you can fetch values using either <tt>:key</tt> or <tt>"key"</tt>.