Add example of maintaining context with `route_for`

[ci skip]

1 files changed, 6 insertions, 0 deletions

diff --git a/actionpack/lib/action_dispatch/routing/url_for.rb b/actionpack/lib/action_dispatch/routing/url_for.rb
index 922e776da9..872abacd53 100644
--- a/actionpack/lib/action_dispatch/routing/url_for.rb
+++ b/actionpack/lib/action_dispatch/routing/url_for.rb
@@ -203,6 +203,12 @@ module ActionDispatch
       #     route_for(:recordable, threadable.parent)
       #   end
       #
+      # This maintains the context of the original caller on
+      # whether to return a path or full url, e.g:
+      #
+      #   threadable_path(threadable)  # => /buckets/1
+      #   threadable_url(threadable)   # => http://example.com/buckets/1
+      #
       def route_for(name, *args)
         public_send(:"#{name}_url", *args)
       end