Merge pull request #528 from kgriffs/url-template-docs

doc(Routing): Update documentation per new routing engine

doc/api/routing.rst

@@ -43,4 +43,4 @@ A custom routing engine may be specified when instantiating
     api = API(router=fancy)
 
 .. automodule:: falcon.routing
-    :members:
+    :members: create_http_method_map, CompiledRouter

doc/user/tutorial.rst

@@ -160,7 +160,7 @@ params, as we shall see later on.
 
 Right now, the image resource responds to GET requests with a simple
 ``200 OK`` and a JSON body. Falcon's Internet media type defaults to
-``application/json`` but you can set it to whatever you like. See 
+``application/json`` but you can set it to whatever you like. See
 serialization with `MessagePack <http://msgpack.org/>`_ for example:
 
 .. code:: python
@@ -439,9 +439,11 @@ argument.
 
 .. note::
 
-    Falcon currently supports Level 1
-    `URI templates <https://tools.ietf.org/html/rfc6570>`_, and support for
-    higher levels is planned.
+    Falcon also supports more complex parameterized path segments containing
+    multiple values. For example, a GH-like API could use the following
+    template to add a route for diffing two branches::
+
+        /repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
 
 Now, restart gunicorn and post another picture to the service:
 
@@ -461,10 +463,10 @@ headers were set correctly. Just for fun, go ahead and paste the above URI
 into your web browser. The image should display correctly.
 
 
-Query Strings
--------------
+.. Query Strings
+.. -------------
 
-*Coming soon...*
+.. *Coming soon...*
 
 Introducing Hooks
 -----------------

falcon/api.py

@@ -250,11 +250,16 @@ def __call__(self, env, start_response):
     def add_route(self, uri_template, resource):
         """Associates a templatized URI path with a resource.
 
-        A resource is an instance of a class that defines various on_*
+        A resource is an instance of a class that defines various
         "responder" methods, one for each HTTP method the resource
-        allows. For example, to support GET, simply define an `on_get`
-        responder. If a client requests an unsupported method, Falcon
-        will respond with "405 Method not allowed".
+        allows. Responder names start with `on_` and are named according to
+        which HTTP method they handle, as in `on_get`, `on_post`, `on_put`,
+        etc.
+
+        If your resource does not support a particular
+        HTTP method, simply omit the corresponding responder and
+        Falcon will reply with "405 Method not allowed" if that
+        method is ever requested.
 
         Responders must always define at least two arguments to receive
         request and response objects, respectively. For example::
@@ -277,6 +282,11 @@ def on_post(self, req, resp):
             def on_put(self, req, resp, name):
                 pass
 
+        Individual path segments may contain one or more field expressions.
+        For example::
+
+            /repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
+
         Args:
             uri_template (str): A templatized URI. Care must be
                 taken to ensure the template does not mask any sink

falcon/routing/compiled.py

@@ -21,11 +21,8 @@
 class CompiledRouter(object):
     """Fast URI router which compiles its routing logic to Python code.
 
-    This class is a Falcon router, which handles the routing from URI paths
-    to resource class instance methods. It implements the necessary router
-    methods add_route() and find(). Generally you do not need to use this
-    router class directly, as an instance is created by default when the
-    falcon.API class is initialized.
+    Generally you do not need to use this router class directly, as an
+    instance is created by default when the falcon.API class is initialized.
 
     The router treats URI paths as a tree of URI segments and searches by
     checking the URI one segment at a time. Instead of interpreting the route