doc(API): Improve req, resp param descriptions and related docs (#1003)

docs/api/api.rst

@@ -1,7 +1,7 @@
 .. _api:
 
-API Class
+The API Class
-=========
+=============
 
 Falcon's API class is a WSGI "application" that you can host with any
 standard-compliant WSGI server.
@@ -10,7 +10,7 @@ standard-compliant WSGI server.
 
     import falcon
 
-    api = application = falcon.API()
+    app = falcon.API()
 
 .. autoclass:: falcon.API
     :members:

docs/api/routing.rst

@@ -7,6 +7,10 @@ The *falcon.routing* module contains utilities used internally by
 :py:meth:`falcon.API` to route requests. They are exposed here for use by
 custom routing engines.
 
+Custom routers may derive from the default :py:class:`~.CompiledRouter`
+engine, or implement a completely different routing strategy (such as
+object-based routing).
+
 A custom router is any class that implements the following interface:
 
 .. code:: python

falcon/api.py

@@ -291,28 +291,47 @@ class API(object):
         which HTTP method they handle, as in `on_get`, `on_post`, `on_put`,
         etc.
 
-        If your resource does not support a particular
+        Note:
-        HTTP method, simply omit the corresponding responder and
+            If your resource does not support a particular
-        Falcon will reply with "405 Method not allowed" if that
+            HTTP method, simply omit the corresponding responder and
-        method is ever requested.
+            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::
+        :class:`~.Request` and :class:`~.Response` objects, respectively.
+        For example::
 
             def on_post(self, req, resp):
                 pass
 
-        In addition, if the route's template contains field
+        The :class:`~.Request` object represents the incoming HTTP
-        expressions, any responder that desires to receive requests
+        request. It exposes properties and methods for examining headers,
-        for that route must accept arguments named after the respective
+        query string parameters, and other metadata associated with
-        field names defined in the template. A field expression consists
+        the request. A file-like stream is also provided for reading
-        of a bracketed field name.
+        any data that was included in the body of the request.
+
+        The :class:`~.Response` object represents the application's
+        HTTP response to the above request. It provides properties
+        and methods for setting status, header and body data. The
+        :class:`~.Response` object also exposes a dict-like
+        :attr:`~.Response.context` property for passing arbitrary
+        data to hooks and middleware methods. This property could be
+        used, for example, to provide a resource representation to a
+        middleware component that would then serialize the
+        representation according to the client's preferred media type.
 
         Note:
-            Since field names correspond to argument names in responder
+            Rather than directly manipulate the :class:`~.Response`
-            methods, they must be valid Python identifiers.
+            object, a responder may raise an instance of either
+            :class:`~.HTTPError` or :class:`~.HTTPStatus`.
 
-        For example, given the following template::
+        In addition to the standard `req` and `resp` parameters, if the
+        route's template contains field expressions, any responder that
+        desires to receive requests for that route must accept arguments
+        named after the respective field names defined in the template.
+
+        A field expression consists of a bracketed field name. For
+        example, given the following template::
 
             /user/{name}
 
@@ -326,6 +345,10 @@ class API(object):
 
             /repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
 
+        Note:
+            Because field names correspond to argument names in responder
+            methods, they must be valid Python identifiers.
+
         Args:
             uri_template (str): A templatized URI. Care must be
                 taken to ensure the template does not mask any sink

falcon/request.py

@@ -185,7 +185,13 @@ class Request(object):
         content_length (int): Value of the Content-Length header converted
             to an ``int``, or ``None`` if the header is missing.
         stream: File-like input object for reading the body of the
-            request, if any. Since this object is provided by the WSGI
+            request, if any. This object provides direct access to the
+            server's data stream and is non-seekable. In order to
+            avoid unintended side effects, and to provide maximum
+            flexibility to the application, Falcon itself does not
+            buffer or spool the data in any way.
+
+            Since this object is provided by the WSGI
             server itself, rather than by Falcon, it may behave
             differently depending on how you host your app. For example,
             attempting to read more bytes than are expected (as