Improve docs of URLSpec capturing groups

Inspired by https://groups.google.com/d/msg/python-tornado/eQ3wyusHCio/4eVVANYxAAAJ

diff --git a/docs/web.rst b/docs/web.rst
index a204e9d0ecb1d4bc61c62dcae68a88eb0ccc3236..dbbc13ce8253092d7e25879588ed185b56a36909 100644 (file)
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -25,6 +25,11 @@
    These methods can be made asynchronous with one of the following
    decorators: `.gen.coroutine`, `.return_future`, or `asynchronous`.
 
+   The arguments to these methods come from the `.URLSpec`: Any
+   capturing groups in the regular expression become arguments to the
+   HTTP verb methods (keyword arguments if the group is named,
+   positional arguments if its unnamed).
+
    To support a method not on this list, override the class variable
    ``SUPPORTED_METHODS``::
 

diff --git a/tornado/web.py b/tornado/web.py
index fd971a8ca2caccf77f4cec9ef6f9b1590ea4ab1a..4979813c06c0290ffa79e17ff75f7c41a38c6c5c 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -2967,9 +2967,11 @@ class URLSpec(object):
     def __init__(self, pattern, handler, kwargs=None, name=None):
         """Parameters:
 
-        * ``pattern``: Regular expression to be matched.  Any groups
-          in the regex will be passed in to the handler's get/post/etc
-          methods as arguments.
+        * ``pattern``: Regular expression to be matched. Any capturing
+          groups in the regex will be passed in to the handler's
+          get/post/etc methods as arguments (by keyword if named, by
+          position if unnamed. Named and unnamed capturing groups may
+          may not be mixed in the same rule).
 
         * ``handler``: `RequestHandler` subclass to be invoked.
 
@@ -2978,6 +2980,7 @@ class URLSpec(object):
 
         * ``name`` (optional): A name for this handler.  Used by
           `Application.reverse_url`.
+
         """
         if not pattern.endswith('$'):
             pattern += '$'