Merge pull request rails#48067 from shouichi/document-flash-delete

document AD::FlashHash#delete [skip ci]

Author: byroot

actionpack/lib/action_dispatch/middleware/flash.rb

@@ -177,6 +177,8 @@ def key?(name)
         @flashes.key? name.to_s
       end
 
+      # Immediately deletes the single flash entry. Use this method when you
+      # want remove the message within the current action. See also #discard.
       def delete(key)
         key = key.to_s
         @discard.delete key
@@ -245,6 +247,9 @@ def keep(k = nil)
       #
       #     flash.discard              # discard the entire flash at the end of the current action
       #     flash.discard(:warning)    # discard only the "warning" entry at the end of the current action
+      #
+      # Use this method when you want to display the message in the current
+      # action but not in the next one. See also #delete.
       def discard(k = nil)
         k = k.to_s if k
         @discard.merge Array(k || keys)