Repository: falconry/falcon
Pull request #1099 (2017-08-08 21:53:39)

doc: Place kwarg docstrings under "Keyword Arguments" vs. using "optional"

codecov[bot]: # [Codecov](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=h1) Report
> Merging [#1099](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=desc) into [master](https://codecov.io/gh/falconry/falcon/commit/1186b118d956dc4333bb4e899eb16667cdf24b39?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/falconry/falcon/pull/1099/graphs/tree.svg?width=650&token=zOtkfNQ3h6&height=150&src=pr)](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree)

```diff
@@          Coverage Diff           @@
##           master   #1099   +/-   ##
======================================
  Coverage     100%    100%           
======================================
  Files          38      38           
  Lines        2412    2412           
  Branches      340     340           
======================================
  Hits         2412    2412
```


| [Impacted Files](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [falcon/testing/base.py](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree#diff-ZmFsY29uL3Rlc3RpbmcvYmFzZS5weQ==) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/util/uri.py](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree#diff-ZmFsY29uL3V0aWwvdXJpLnB5) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/util/misc.py](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree#diff-ZmFsY29uL3V0aWwvbWlzYy5weQ==) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/bench/queues/api.py](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=tree#diff-ZmFsY29uL2JlbmNoL3F1ZXVlcy9hcGkucHk=) | `100% <0%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=footer). Last update [1186b11...c91270c](https://codecov.io/gh/falconry/falcon/pull/1099?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/docs/api/media.rst b/docs/api/media.rst
index eaab9c6..28f60cc 100644
--- a/docs/api/media.rst
+++ b/docs/api/media.rst
@@ -46,7 +46,7 @@ media type that JSON also supports (i.e. dicts, lists, etc).
 
 .. autofunction:: falcon.media.validators.jsonschema.validate
 
-If JSON Schema does not meet your needs, a custom validator may be 
+If JSON Schema does not meet your needs, a custom validator may be
 implemented in a similar manner to the one above.
 
 Content-Type Negotiation
@@ -141,6 +141,7 @@ Handlers
 
 
 .. _media_type_constants:
+
 Media Type Constants
 --------------------
 
diff --git a/falcon/api.py b/falcon/api.py
index c359980..aef2efa 100644
--- a/falcon/api.py
+++ b/falcon/api.py
@@ -34,16 +34,16 @@ class API(object):
     Each API instance provides a callable WSGI interface and a routing
     engine.
 
-    Args:
-        media_type (str, optional): Default media type to use as the
+    Keyword Arguments:
+        media_type (str): Default media type to use as the
             value for the Content-Type header on responses (default
             'application/json'). The ``falcon`` module provides a
             number of constants for common media types, such as
             ``falcon.MEDIA_MSGPACK``, ``falcon.MEDIA_YAML``,
             ``falcon.MEDIA_XML``, etc.
-        middleware(object or list, optional): One or more objects
-            (instantiated classes) that implement the following middleware
-            component interface::
+        middleware(object or list): Either a single object or a list
+            of objects (instantiated classes) that implement the
+            following middleware component interface::
 
                 class ExampleComponent(object):
                     def process_request(self, req, resp):
@@ -94,23 +94,24 @@ class API(object):
 
             (See also: :ref:`Middleware <middleware>`)
 
-        request_type (Request, optional): ``Request``-like class to use instead
+        request_type (Request): ``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
+        response_type (Response): ``Response``-like class to use
             instead of Falcon's default class. (default
             ``falcon.response.Response``)
 
-        router (object, optional): An instance of a custom router
+        router (object): An instance of a custom router
             to use in lieu of the default engine.
             (See also: :ref:`Custom Routers <routing_custom>`)
 
         independent_middleware (bool): Set to ``True`` if response
             middleware should be executed independently of whether or
-            not request middleware raises an exception.
+            not request middleware raises an exception (default
+            ``False``).
 
     Attributes:
         req_options: A set of behavioral options related to incoming
diff --git a/falcon/util/misc.py b/falcon/util/misc.py
index f8c3bd0..076b7e0 100644
--- a/falcon/util/misc.py
+++ b/falcon/util/misc.py
@@ -123,7 +123,9 @@ def http_date_to_dt(http_date, obs_date=False):
     Args:
         http_date (str): An RFC 1123 date string, e.g.:
             "Tue, 15 Nov 1994 12:45:26 GMT".
-        obs_date (bool, optional): Support obs-date formats according to
+
+    Keyword Arguments:
+        obs_date (bool): Support obs-date formats according to
             RFC 7231, e.g.:
             "Sunday, 06-Nov-94 08:49:37 GMT" (default ``False``).
 
diff --git a/falcon/util/uri.py b/falcon/util/uri.py
index cdb2256..f2e3aa3 100644
--- a/falcon/util/uri.py
+++ b/falcon/util/uri.py
@@ -395,8 +395,10 @@ def parse_host(host, default_port=None):
     Args:
         host (str): Host string to parse, optionally containing a
             port number.
-        default_port (int, optional): Port number to return when
-            the host string does not contain one (default ``None``).
+
+    Keyword Arguments:
+        default_port (int): Port number to return when the host string
+            does not contain one (default ``None``).
 
     Returns:
         tuple: A parsed (*host*, *port*) tuple from the given


Test patch:
diff --git a/falcon/testing/base.py b/falcon/testing/base.py
index 261cc86..3967619 100644
--- a/falcon/testing/base.py
+++ b/falcon/testing/base.py
@@ -98,7 +98,9 @@ class TestBase(unittest.TestCase):  # pragma nocover
 
         Args:
             path (str): The path to request.
-            decode (str, optional): If this is set to a character encoding,
+
+        Keyword Arguments:
+            decode (str): If this is set to a character encoding,
                 such as 'utf-8', `simulate_request` will assume the
                 response is a single byte string, and will decode it as the
                 result of the request, rather than simply returning the