Merge pull request #531 from kgriffs/sphinx-warnings

doc: Fix misc sphinx warnings
falconry · Apr 23, 2015 · 490b16f · 490b16f
2 parents 99c492a + 7890219
commit 490b16f
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 31 deletions.
diff --git a/doc/api/cookies.rst b/doc/api/cookies.rst
@@ -1,16 +1,17 @@
-
 .. _cookies:
+
 Cookies
--------------
+-------
 
-Cookie support has been added to falcon from version 0.3.
+Cookie support is available in Falcon version 0.3 or later.
 
 .. _getting-cookies:
-Getting Cookies
-~~~~~~~~~~~~~
 
-Cookie can be read from a request via the :py:attr:`~.Request.cookies` request attribute:
+Getting Cookies
+~~~~~~~~~~~~~~~
 
+Cookies can be read from a request via the :py:attr:`~.Request.cookies`
+request attribute:
 
 .. code:: python
 
@@ -31,7 +32,8 @@ The :py:attr:`~.Request.cookies` attribute is a regular
     for better performance.
 
 .. _setting-cookies:
-Setting Cookies 
+
+Setting Cookies
 ~~~~~~~~~~~~~~~
 
 Setting cookies on a response is done via the :py:meth:`~.Response.set_cookie`.
@@ -46,8 +48,6 @@ with the same name (which is how multiple cookies are sent to the client).
 header field, which is not compatible with the format used by `Set-Cookie`
 headers to send cookies to clients.
 
-
-
 Simple example:
 
 .. code:: python
@@ -60,9 +60,6 @@ Simple example:
 
 You can of course also set the domain, path and lifetime of the cookie.
 
-
-
-
 .. code:: python
 
     class Resource(object):

diff --git a/doc/api/errors.rst b/doc/api/errors.rst
@@ -37,4 +37,4 @@ Predefined Errors
         HTTPMethodNotAllowed, HTTPNotAcceptable, HTTPConflict,
         HTTPLengthRequired, HTTPPreconditionFailed, HTTPUnsupportedMediaType,
         HTTPRangeNotSatisfiable, HTTPInternalServerError, HTTPBadGateway,
-        HTTPServiceUnavailable,
+        HTTPServiceUnavailable
diff --git a/doc/community/contribute.rst b/doc/community/contribute.rst
@@ -35,13 +35,12 @@ doesn't make pyflakes sad.
   using the *help* function within a REPL, and when browsing
   them on *Read the Docs*.
 * Format non-trivial comments using your GitHub nick and an appropriate
-  prefix. Here are some examples:
-    .. code:: python
+  prefix. Here are some examples::
 
-        # TODO(riker): Damage report!
-        # NOTE(riker): Well, that's certainly good to know.
-        # PERF(riker): Travel time to the nearest starbase?
-        # APPSEC(riker): In all trust, there is the possibility for betrayal.
+      # TODO(riker): Damage report!
+      # NOTE(riker): Well, that's certainly good to know.
+      # PERF(riker): Travel time to the nearest starbase?
+      # APPSEC(riker): In all trust, there is the possibility for betrayal.
 
 * Commit messages should be formatted using `AngularJS conventions`_
   (one-liners are OK for now but bodies and footers may be required as the

diff --git a/falcon/request.py b/falcon/request.py
@@ -846,17 +846,11 @@ def get_param_as_list(self, name,
         Returns:
             list: The value of the param if it is found. Otherwise, returns
                 ``None`` unless required is True. Empty list elements will be
-                discarded. For example a query string containing this::
+                discarded. For example, the following query strings would
+                both result in `['1', '3']`::
 
-                things=1,,3
-
-            or a query string containing this::
-
-                things=1&things=&things=3
-
-            would both result in::
-
-                ['1', '3']
+                    things=1,,3
+                    things=1&things=&things=3
 
         Raises:
             HTTPBadRequest: A required param is missing from the request.

diff --git a/falcon/response.py b/falcon/response.py
@@ -466,11 +466,11 @@ def add_link(self, target, rel, title=None, title_star=None,
 
         The tuple has the form (*start*, *end*, *length*), where *start* and
         *end* designate the byte range (inclusive), and *length* is the
-        total number of bytes, or '*' if unknown. You may pass ``int``'s for
+        total number of bytes, or '\*' if unknown. You may pass ``int``'s for
         these numbers (no need to convert to ``str`` beforehand).
 
         Note:
-            You only need to use the alternate form, 'bytes */1234', for
+            You only need to use the alternate form, 'bytes \*/1234', for
             responses that use the status '416 Range Not Satisfiable'. In this
             case, raising ``falcon.HTTPRangeNotSatisfiable`` will do the right
             thing.