Clarify use of params in `direct`

Since a `direct` url helper block is evaluated using `instance_exec`
then methods that are available in the instance context can be
accessed, e.g. the params object in a controller action or view.

This wasn't clear from the example so expand on that point and add
a test case for this situation.

1 files changed, 9 insertions, 0 deletions

diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index 073dabd0a8..cded23ac36 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -2057,6 +2057,15 @@ module ActionDispatch
         #     [ :products, options.merge(params.permit(:page, :size)) ]
         #   end
         #
+        # In this instance the `params` object comes from the context in which the the
+        # block is executed, e.g. generating a url inside a controller action or a view.
+        # If the block is executed where there isn't a params object such as this:
+        #
+        #   Rails.application.routes.url_helpers.browse_path
+        #
+        # then it will raise a `NameError`. Because of this you need to be aware of the
+        # context in which you will use your custom url helper when defining it.
+        #
         # NOTE: The `direct` method can't be used inside of a scope block such as
         # `namespace` or `scope` and will raise an error if it detects that it is.
         def direct(name, options = {}, &block)