Proof-editing for routing.rst

docs/source/routing.rst

@@ -4,10 +4,10 @@ Routing
 =======
 
 When a user requests a Pecan-powered page how does Pecan know which
-controller to use? Pecan uses a method known as Object-dispatch to map a
+controller to use? Pecan uses a method known as object-dispatch to map an
 HTTP request to a controller. Object-dispatch begins by splitting the
-path into a list of components and then walking an object path starting at
+path into a list of components and then walking an object path, starting at
-the root controller. Let's look at a simple store application: 
+the root controller. Let's look at a simple bookstore application: 
 
 ::
 
@@ -41,12 +41,11 @@ the root controller. Let's look at a simple store application:
         catalog = CatalogController()
 
 A request for ``/catalog/books/bestsellers`` from the online store would
-begin by Pecan breaking the request up into ``catalog``, ``books``, and
+begin with Pecan breaking the request up into ``catalog``, ``books``, and
-``bestsellers``. Next, Pecan would then lookup ``catalog`` on the root
+``bestsellers``. Next, Pecan would lookup ``catalog`` on the root
 controller. Using the ``catalog`` object, Pecan would then lookup
-``books`` followed by ``bestsellers``. What if the URL ends in a slash?
+``books``, followed by ``bestsellers``. What if the URL ends in a slash?
-Pecan will check for an ``index`` method on the current object. In the
+Pecan will check for an ``index`` method on the current object. 
-example above, you may have noticed the ``expose`` decorator.
 
 Routing Algorithm
 -----------------
@@ -54,29 +53,23 @@ Routing Algorithm
 Sometimes, the standard object-dispatch routing isn't adequate to properly
 route a URL to a controller. Pecan provides several ways to short-circuit 
 the object-dispatch system to process URLs with more control, including the
-``_lookup``, ``_default``, and ``_route`` special methods. Defining these
+special ``_lookup``, ``_default``, and ``_route`` methods. Defining these
-methods on your controller objects provide several additional ways to 
+methods on your controller objects provides additional flexibility for 
-process all or part of a URL.
+processing all or part of a URL.
 
 
 ``_lookup``
 -----------
 
-The ``_lookup`` special method provides a way to process part of a URL, 
+The ``_lookup`` special method provides a way to process a portion of a URL, 
-and then return a new controller object to route on for the remainder.
+and then return a new controller object to route to for the remainder.
 
-A ``_lookup`` method will accept one or more arguments representing chunks
+A ``_lookup`` method will accept one or more arguments, representing chunks
-of the URL to be processed, split on `/`, and then a `*remainder` list which
+of the URL to be processed, split on `/`, and then provide a `*remainder` list
-will be processed by the returned controller via object-dispatch.
+which will be processed by the returned controller via object-dispatch.
 
-The ``_lookup`` method must return a two-tuple including the controller to
+Additionally, the ``_lookup`` method on a controller is called as a last
-process the remainder of the URL, and the remainder of the URL itself.
+resort, when no other controller matches the URL via standard object-dispatch.
-
-The ``_lookup`` method on a controller is called when no other controller 
-matches the URL via standard object-dispatch.
-
-
-Example 
 
 ::
 
@@ -91,23 +84,23 @@ Example
         def name(self):
             return self.student.name
 
-    class ClassController(object):
+    class RootController(object):
         @expose()
-        def _lookup(self, name, *remainder):
+        def _lookup(self, primary_key, *remainder):
-            student = get_student_by_name(name)
+            student = get_student_by_primary_key(primary_key)
             if student:
                 return StudentController(student), remainder
             else:
                 abort(404)
 
+An HTTP GET request to `/8/name` would return the name of the student
+where `primary_key == 8`.
+
 ``_default``
 ------------
 
 The ``_default`` controller is called when no other controller methods
-match the URL vis standard object-dispatch.
+match the URL via standard object-dispatch.
-
-
-Example 
 
 ::
 
@@ -145,53 +138,6 @@ A controller can receive arguments in a variety of ways, including ``GET`` and
 arguments simply map to arguments on the controller method, while unprocessed
 chunks of the URL can be passed as positional arguments to the controller method.
 
-Example  
-
-::
-
-    from pecan import expose
-
-    class RootController(object):
-        @expose()
-        def say(self, msg):
-            return msg
-
-
-In this example, if a ``GET`` request is sent to ``/say/hello``, the controller
-returns "hello". On the other hand, if a ``GET`` request is sent to 
-``/say?msg=World``, then the controller returns "World".
-
-Keyword arguments are also supported for defaults.
-
-kwargs    
-
-::
-
-    from pecan import expose
-    
-    class RootController(object):
-        @expose()
-        def say(self, msg="No message"):
-            return msg
-
-In this example, if the client requests ``/say?msg=hello`` the controller returns 
-"hello". However, if the client requests ``/say`` without any arguments, the 
-controller returns "No message".
-
-
-Generic Functions
------------------
-
-Pecan also provides a unique and useful way to dispatch from a controller to other
-methods based upon the ``HTTP`` method (``GET``, ``POST``, ``PUT``, etc.) using
-a system called "generic functions." A controller can be flagged as generic via a
-keyword argument on the ``@expose`` decorator. This makes it possible to utilize
-the ``@when`` decorator on the controller itself to define controllers to be called
-instead when certain ``HTTP`` methods are sent.
-
-
-Example
-
 ::
 
     from pecan import expose
@@ -223,8 +169,8 @@ are documented in :ref:`pecan_core`.
 -----------
 
 At its core, ``@expose`` is how you tell Pecan which methods in a class
-are controllers. ``@expose`` accepts eight optional parameters some of
+are publically-visible controllers. ``@expose`` accepts eight optional
-which can impact routing. 
+parameters, some of which can impact routing. 
 
 ::