update AC::Parameters#permit documentation [ci skip]

bdd105d changes the behaviour of AC::Parameters#permit.

1 files changed, 22 insertions, 0 deletions

diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index a6250f5d03..c42b3dddc9 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -171,6 +171,28 @@ module ActionController
     #   permitted[:person][:age]                # => nil
     #   permitted[:person][:pets][0][:name]     # => "Purplish"
     #   permitted[:person][:pets][0][:category] # => nil
+    #
+    # Note that if you use +permit+ in a key that points to a hash,
+    # it won't allow all the hash. You also need to specify which
+    # attributes inside the hash should be whitelisted.
+    #
+    #   params = ActionController::Parameters.new({
+    #     person: {
+    #       contact: {
+    #         email: 'none@test.com'
+    #         phone: '555-1234'
+    #       }
+    #     }
+    #   })
+    #
+    #   params.require(:person).permit(:contact)
+    #   # => {}
+    #
+    #   params.require(:person).permit(contact: :phone)
+    #   # => {"contact"=>{"phone"=>"555-1234"}}
+    #
+    #   params.require(:person).permit(contact: [ :email, :phone ])
+    #   # => {"contact"=>{"email"=>"none@test.com", "phone"=>"555-1234"}}
     def permit(*filters)
       params = self.class.new