Merge pull request #427 from kgriffs/issues/334

doc(reference): Standardize docstring syntax

CONTRIBUTING.md

@@ -14,6 +14,16 @@ $ tox -e py27,py33,pep8
 
 * Docstrings are required for classes, attributes, methods, and functions.
 * Docstrings should utilize the [napolean style][docstrings] in order to make them read well, regardless of whether they are viewed through `help()` or on [Read the Docs][rtd].
+* Please try to be consistent with the way existing docstrings are formatted. In particular, note the use of single vs. double backticks as follows:
+    * Double backticks
+        * Inline code
+        * Variables
+        * Types
+        * Decorators
+    * Single backticks
+        * Methods
+        * Params
+        * Attributes
 * Format non-trivial comments using your GitHub nick and one of these prefixes:
     * TODO(riker): Damage report!
     * NOTE(riker): Well, that's certainly good to know.

doc/api/api.rst

@@ -14,7 +14,6 @@ standard-compliant WSGI server.
 
 .. autoclass:: falcon.API
     :members:
-    :undoc-members:
 
 .. autoclass:: falcon.RequestOptions
     :members:

doc/api/middleware.rst

@@ -18,33 +18,33 @@ The middleware interface is defined as follows:
 
             Args:
                 req: Request object that will eventually be
-                    routed to an on_* responder method
+                    routed to an on_* responder method.
                 resp: Response object that will be routed to
-                    the on_* responder
+                    the on_* responder.
             """
 
         def process_resource(self, req, resp, resource):
             """Process the request after routing.
 
             Args:
                 req: Request object that will be passed to the
-                    routed responder
+                    routed responder.
                 resp: Response object that will be passed to the
-                    responder
+                    responder.
                 resource: Resource object to which the request was
                     routed. May be None if no route was found for
-                    the request
+                    the request.
             """
 
-        def process_response(self, req, resp, resource)
+        def process_response(self, req, resp, resource):
             """Post-processing of the response (after routing).
 
             Args:
-                req: Request object
-                resp: Response object
+                req: Request object.
+                resp: Response object.
                 resource: Resource object to which the request was
                     routed. May be None if no route was found
-                    for the request
+                    for the request.
             """
 
 Because middleware can execute before routing has occurred, if a

doc/user/install.rst

@@ -3,21 +3,16 @@
 Installation
 ============
 
-Install from PyPI
------------------
-
-Falcon is super easy to install with pip. If you don't have pip yet,
-please run—don't walk—to the
-`pip website <http://www.pip-installer.org/en/latest/installing.html>`_
-and get that happy little tool installed before you do anything else.
-
 .. note::
 
   This documentation targets the upcoming 0.2 release of Falcon,
   currently in beta and available on PyPI. You will need to use the
   ``--pre`` flag with pip in order to install the Falcon 0.2 betas
   and release candidates.
 
+Install from PyPI
+-----------------
+
 If available, Falcon will compile itself with Cython for an extra
 speed boost. The following will make sure Cython is installed first, and
 that you always have the latest and greatest.
@@ -26,7 +21,8 @@ that you always have the latest and greatest.
 
     $ pip install --upgrade cython falcon
 
-If you are on PyPy, you won't need Cython, of course:
+Note that if you are running on PyPy, you won't need Cython, so you can just
+type:
 
 .. code:: bash
 

falcon/api.py

@@ -36,7 +36,7 @@ class API(object):
 
     Args:
         media_type (str, optional): Default media type to use as the value for
-            the Content-Type header on responses. (default 'application/json')
+            the Content-Type header on responses (default 'application/json').
         middleware(object or list, optional): One or more objects
             (instantiated classes) that implement the following middleware
             component interface::
@@ -47,43 +47,46 @@ def process_request(self, req, resp):
 
                         Args:
                             req: Request object that will eventually be
-                                routed to an on_* responder method
+                                routed to an on_* responder method.
                             resp: Response object that will be routed to
-                                the on_* responder
+                                the on_* responder.
                         \"""
 
                     def process_resource(self, req, resp, resource):
                         \"""Process the request after routing.
 
                         Args:
                             req: Request object that will be passed to the
-                                routed responder
+                                routed responder.
                             resp: Response object that will be passed to the
-                                responder
+                                responder.
                             resource: Resource object to which the request was
                                 routed. May be None if no route was found for
-                                the request
+                                the request.
                         \"""
 
                     def process_response(self, req, resp, resource)
                         \"""Post-processing of the response (after routing).
 
                         Args:
-                            req: Request object
-                            resp: Response object
+                            req: Request object.
+                            resp: Response object.
                             resource: Resource object to which the request was
                                 routed. May be None if no route was found
-                                for the request
+                                for the request.
                         \"""
+
             See also :ref:`Middleware <middleware>`.
-        request_type (Request, optional): Request-like class to use instead
+
+        request_type (Request, optional): ``Request``-like class to use instead
             of Falcon's default class. Among other things, this feature
             affords inheriting from ``falcon.request.Request`` in order
             to override the ``context_type`` class variable.
-            (default falcon.request.Request)
-        response_type (Response, optional): Response-like class to use
+            (default ``falcon.request.Request``)
+
+        response_type (Response, optional): ``Response``-like class to use
             instead of Falcon's default class. (default
-            falcon.response.Response)
+            ``falcon.response.Response``)
 
     Attributes:
         req_options (RequestOptions): A set of behavioral options related to
@@ -265,7 +268,7 @@ def on_put(self, req, resp, name):
         Args:
             uri_template (str): A templatized URI. Care must be
                 taken to ensure the template does not mask any sink
-                patterns, if any are registered (see also ``add_sink``).
+                patterns, if any are registered (see also `add_sink`).
             resource (instance): Object which represents a REST
                 resource. Falcon will pass "GET" requests to on_get,
                 "PUT" requests to on_put, etc. If any HTTP methods are not
@@ -311,7 +314,7 @@ def add_sink(self, sink, prefix=r'/'):
                 Note:
                     If the prefix overlaps a registered route template,
                     the route will take precedence and mask the sink
-                    (see also ``add_route``).
+                    (see also `add_route`).
 
         """
 
@@ -349,7 +352,7 @@ def handle(ex, req, resp, params):
                             raise falcon.HTTPError(falcon.HTTP_792)
 
                 Note:
-                    A handler can either raise an instance of HTTPError
+                    A handler can either raise an instance of ``HTTPError``
                     or modify resp manually in order to communicate
                     information about the issue to the client.
 
@@ -403,12 +406,12 @@ def my_serializer(req, exception):
             to override this behavior.
 
         Args:
-            serializer (callable): A function of the form
+            serializer (callable): A function taking the form
                 ``func(req, exception)``, where `req` is the request
                 object that was passed to the responder method, and
-                `exception` is an instance of falcon.HTTPError.
-                The function must return a tuple of the form
-                ``(media_type, representation)``, or ``(None, None)``
+                `exception` is an instance of ``falcon.HTTPError``.
+                The function must return a ``tuple`` of the form
+                (*media_type*, *representation*), or (``None``, ``None``)
                 if the client does not support any of the
                 available media types.
 
@@ -428,7 +431,7 @@ def _get_responder(self, req):
 
         Returns:
             A 3-member tuple consisting of a responder callable,
-            a dict containing parsed path fields (if any were specified in
+            a ``dict`` containing parsed path fields (if any were specified in
             the matching route's URI template), and a reference to the
             responder's resource instance.
 
@@ -583,11 +586,11 @@ def _get_body(self, resp, wsgi_file_wrapper=None):
                 when resp.stream is a file-like object (default None).
 
         Returns:
-            * If resp.body is not *None*, returns [resp.body], encoded
+            * If resp.body is not ``None``, returns [resp.body], encoded
               as UTF-8 if it is a Unicode string. Bytestrings are returned
               as-is.
-            * If resp.data is not *None*, returns [resp.data]
-            * If resp.stream is not *None*, returns resp.stream
+            * If resp.data is not ``None``, returns [resp.data]
+            * If resp.stream is not ``None``, returns resp.stream
               iterable using wsgi.file_wrapper, if possible.
             * Otherwise, returns []
 

falcon/api_helpers.py

@@ -86,12 +86,12 @@ def default_serialize_error(req, exception):
         override this one.
 
     Args:
-        req: Instance of falcon.Request
-        exception: Instance of falcon.HTTPError
+        req: Instance of ``falcon.Request``
+        exception: Instance of ``falcon.HTTPError``
 
     Returns:
-        A tuple of the form ``(media_type, representation)``, or
-        ``(None, None)`` if the client does not support any of the
+        A ``tuple`` of the form (*media_type*, *representation*), or
+        (``None``, ``None``) if the client does not support any of the
         available media types.
 
     """

falcon/errors.py

@@ -50,7 +50,7 @@ class HTTPUnauthorized(HTTPError):
         description (str): Human-friendly description of the error, along with
             a helpful suggestion or two.
         scheme (str): Authentication scheme to use as the value of the
-            WWW-Authenticate header in the response (default *None*).
+            WWW-Authenticate header in the response (default ``None``).
         kwargs (optional): Same as for ``HTTPError``.
 
     """
@@ -111,7 +111,7 @@ class HTTPMethodNotAllowed(OptionalRepresentation, HTTPError):
 
     Args:
         allowed_methods (list of str): Allowed HTTP methods for this
-            resource (e.g., ['GET', 'POST', 'HEAD']).
+            resource (e.g., ``['GET', 'POST', 'HEAD']``).
 
     """
 
@@ -243,9 +243,9 @@ class HTTPRequestEntityTooLarge(HTTPError):
         description (str): Human-friendly description of the error, along with
             a helpful suggestion or two.
         retry_after (datetime or int, optional): Value for the Retry-After
-            header. If a datetime object, will serialize as an HTTP date.
-            Otherwise, a non-negative int is expected, representing the number
-            of seconds to wait. See also: http://goo.gl/DIrWr .
+            header. If a ``datetime`` object, will serialize as an HTTP date.
+            Otherwise, a non-negative ``int`` is expected, representing the
+            number of seconds to wait. See also: http://goo.gl/DIrWr .
         kwargs (optional): Same as for ``HTTPError``.
 
     """
@@ -337,9 +337,9 @@ class HTTPServiceUnavailable(HTTPError):
         description (str): Human-friendly description of the error, along with
             a helpful suggestion or two.
         retry_after (datetime or int): Value for the Retry-After header. If a
-            datetime object, will serialize as an HTTP date. Otherwise,
-            a non-negative int is expected, representing the number of seconds
-            to wait. See also: http://goo.gl/DIrWr .
+            ``datetime`` object, will serialize as an HTTP date. Otherwise,
+            a non-negative ``int`` is expected, representing the number of
+            seconds to wait. See also: http://goo.gl/DIrWr .
         kwargs (optional): Same as for ``HTTPError``.
 
     """

falcon/hooks.py

@@ -29,7 +29,7 @@ def before(action):
             reference to the resource class instance associated with the
             request, and `params` is a dict of URI Template field names,
             if any, that will be passed into the resource responder as
-            *kwargs*.
+            kwargs.
 
             Note:
                 Hooks may inject extra params as needed. For example::
@@ -161,8 +161,8 @@ def _has_self(spec):
 
     Warning:
         If a method's spec lists "self", that doesn't necessarily mean
-        that it should be called with a "self" param; if the method
-        instance is bound, the caller must omit "self" on invocation.
+        that it should be called with a `self` param; if the method
+        instance is bound, the caller must omit `self` on invocation.
 
     """
 
@@ -174,13 +174,13 @@ def _wrap_with_after(action, responder, resource=None, is_method=False):
 
     Args:
         action: A function with a signature similar to a resource responder
-            method, taking (req, resp, resource).
+            method, taking the form ``func(req, resp, resource)``.
         responder: The responder method to wrap.
-        resource: The resource affected by `action` (default None). If None,
-            `is_method` MUST BE True, so that the resource can be
-            derived from the `self` param that is passed into the wrapper
+        resource: The resource affected by `action` (default ``None``). If
+            ``None``, `is_method` MUST BE True, so that the resource can be
+            derived from the `self` param that is passed into the wrapper.
         is_method: Whether or not `responder` is an unbound method
-            (default False)
+            (default ``False``).
 
     """
 
@@ -223,13 +223,13 @@ def _wrap_with_before(action, responder, resource=None, is_method=False):
 
     Args:
         action: A function with a similar signature to a resource responder
-            method, taking (req, resp, resource, params)
+            method, taking the form ``func(req, resp, resource, params)``.
         responder: The responder method to wrap
-        resource: The resource affected by `action` (default None). If None,
-            `is_method` MUST BE True, so that the resource can be
+        resource: The resource affected by `action` (default ``None``). If
+            ``None``, `is_method` MUST BE True, so that the resource can be
             derived from the `self` param that is passed into the wrapper
         is_method: Whether or not `responder` is an unbound method
-            (default False)
+            (default ``False``)
 
     """
 

falcon/http_error.py

@@ -54,11 +54,11 @@ class HTTPError(Exception):
         title (str): Human-friendly error title (default ``None``).
         description (str): Human-friendly description of the error, along with
             a helpful suggestion or two (default ``None``).
-        headers (dict or list): A dictionary of header names and values
-            to set, or list of (name, value) tuples. Both names and
-            values must be of type str or StringType, and only character
-            values 0x00 through 0xFF may be used on platforms that use
-            wide characters.
+        headers (dict or list): A ``dict`` of header names and values
+            to set, or a ``list`` of (*name*, *value*) tuples. Both *name* and
+            *value* must be of type ``str`` or ``StringType``, and only
+            character values 0x00 through 0xFF may be used on platforms that
+            use wide characters.
 
             Note:
                 The Content-Type header, if present, will be overridden. If
@@ -68,8 +68,8 @@ class HTTPError(Exception):
                 client
 
             Note:
-                Falcon can process a list of tuples slightly faster
-                than a dict.
+                Falcon can process a list of ``tuple`` slightly faster
+                than a ``dict``.
 
         headers (dict): Extra headers to return in the
             response to the client (default ``None``).
@@ -120,7 +120,7 @@ def to_dict(self, obj_type=dict):
 
         Args:
             obj_type: A dict-like type that will be used to store the
-                error information (default *dict*).
+                error information (default ``dict``).
 
         Returns:
             A dictionary populated with the error's title, description, etc.