Document @authenticated's behavior around query parameters.

Closes #998.

diff --git a/tornado/web.py b/tornado/web.py
index dbd6abf57e53c5d5a25e4fd62b13bfa097b87125..2b5e51f2119bae8b597d81fb9be2a3a5c64f93ae 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -2450,6 +2450,11 @@ def authenticated(method):
 
     If the user is not logged in, they will be redirected to the configured
     `login url <RequestHandler.get_login_url>`.
+
+    If you configure a login url with a query parameter, Tornado will
+    assume you know what you're doing and use it as-is.  If not, it
+    will add a `next` parameter so the login page knows where to send
+    you once you're logged in.
     """
     @functools.wraps(method)
     def wrapper(self, *args, **kwargs):