Repository: falconry/falcon
Pull request #1097 (2017-08-08 18:08:06)

doc(api): Standardize "see also" text, fix links

codecov[bot]: # [Codecov](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=h1) Report
> Merging [#1097](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=desc) into [master](https://codecov.io/gh/falconry/falcon/commit/8eb3b5566083c4d41b365e80966b541017a72590?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/1097/graphs/tree.svg?token=zOtkfNQ3h6&src=pr&height=150&width=650)](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree)

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


| [Impacted Files](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [falcon/http\_error.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL2h0dHBfZXJyb3IucHk=) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/errors.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL2Vycm9ycy5weQ==) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/redirects.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL3JlZGlyZWN0cy5weQ==) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/response.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL3Jlc3BvbnNlLnB5) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/request.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL3JlcXVlc3QucHk=) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/util/misc.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL3V0aWwvbWlzYy5weQ==) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/testing/client.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL3Rlc3RpbmcvY2xpZW50LnB5) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/bench/queues/api.py](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=tree#diff-ZmFsY29uL2JlbmNoL3F1ZXVlcy9hcGkucHk=) | `100% <0%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/falconry/falcon/pull/1097?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/1097?src=pr&el=footer). Last update [8eb3b55...1feb058](https://codecov.io/gh/falconry/falcon/pull/1097?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/docs/api/api.rst b/docs/api/api.rst
index 0d2e4c2..529929e 100644
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -21,5 +21,6 @@ standard-compliant WSGI server.
 .. autoclass:: falcon.ResponseOptions
     :members:
 
+.. _compiled_router_options:
 .. autoclass:: falcon.routing.CompiledRouterOptions
     :noindex:
diff --git a/falcon/api.py b/falcon/api.py
index 725d5d1..c359980 100644
--- a/falcon/api.py
+++ b/falcon/api.py
@@ -92,7 +92,7 @@ class API(object):
                                 request; otherwise False.
                         \"\"\"
 
-            See also :ref:`Middleware <middleware>`.
+            (See also: :ref:`Middleware <middleware>`)
 
         request_type (Request, optional): ``Request``-like class to use instead
             of Falcon's default class. Among other things, this feature
@@ -106,7 +106,7 @@ class API(object):
 
         router (object, optional): An instance of a custom router
             to use in lieu of the default engine.
-            See also: :ref:`Custom Routers <routing_custom>`.
+            (See also: :ref:`Custom Routers <routing_custom>`)
 
         independent_middleware (bool): Set to ``True`` if response
             middleware should be executed independently of whether or
@@ -114,14 +114,15 @@ class API(object):
 
     Attributes:
         req_options: A set of behavioral options related to incoming
-            requests. See also: :py:class:`~.RequestOptions`
+            requests. (See also: :py:class:`~.RequestOptions`)
         resp_options: A set of behavioral options related to outgoing
-            responses. See also: :py:class:`~.ResponseOptions`
+            responses. (See also: :py:class:`~.ResponseOptions`)
         router_options: Configuration options for the router. If a
             custom router is in use, and it does not expose any
             configurable options, referencing this attribute will raise
-            an instance of ``AttributeError``. See also:
-            :py:class:`falcon.routing.CompiledRouterOptions`.
+            an instance of ``AttributeError``.
+
+            (See also: :ref:`CompiledRouterOptions <compiled_router_options>`)
     """
 
     # PERF(kgriffs): Reference via self since that is faster than
@@ -178,7 +179,7 @@ class API(object):
         host an API or called directly in order to simulate requests when
         testing the API.
 
-        See also PEP 3333.
+        (See also: PEP 3333)
 
         Args:
             env (dict): A WSGI environment dictionary
@@ -312,7 +313,10 @@ class API(object):
         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 :meth:`~.add_sink`).
+                patterns, if any are registered.
+
+                (See also: :meth:`~.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
@@ -371,8 +375,9 @@ class API(object):
 
                 Warning:
                     If the prefix overlaps a registered route template,
-                    the route will take precedence and mask the sink
-                    (see also `add_route`).
+                    the route will take precedence and mask the sink.
+
+                    (See also: :meth:`~.add_route`)
 
         """
 
diff --git a/falcon/errors.py b/falcon/errors.py
index 9ff38f6..94ba1fd 100644
--- a/falcon/errors.py
+++ b/falcon/errors.py
@@ -115,7 +115,9 @@ class HTTPUnauthorized(HTTPError):
             a helpful suggestion or two.
         challenges (iterable of str): One or more authentication
             challenges to use as the value of the WWW-Authenticate header in
-            the response (see also RFC 7235, Section 2.1).
+            the response.
+
+            (See also: RFC 7235, Section 2.1)
 
         headers (dict or list): A ``dict`` of header names and values
             to set, or a ``list`` of (*name*, *value*) tuples. Both *name* and
diff --git a/falcon/http_error.py b/falcon/http_error.py
index 6961fe3..5815270 100644
--- a/falcon/http_error.py
+++ b/falcon/http_error.py
@@ -52,7 +52,9 @@ class HTTPError(Exception):
             the HTTP response. In ``HTTPError`` this property always
             returns ``True``, but child classes may override it
             in order to return ``False`` when an empty HTTP body is desired.
-            See also the ``falcon.http_error.NoRepresentation`` mixin.
+
+            (See also: :class:`falcon.http_error.NoRepresentation`)
+
         title (str): Error title to send to the client.
         description (str): Description of the error to send to the client.
         headers (dict): Extra headers to add to the response.
diff --git a/falcon/redirects.py b/falcon/redirects.py
index 840fb91..106d4a0 100644
--- a/falcon/redirects.py
+++ b/falcon/redirects.py
@@ -30,7 +30,7 @@ class HTTPMovedPermanently(HTTPStatus):
         behavior is undesired, the 308 (Permanent Redirect) status code
         can be used instead.
 
-    See also: https://tools.ietf.org/html/rfc7231#section-6.4.2
+    (See also: RFC 7231, Section 6.4.2)
 
     Args:
         location (str): URI to provide as the Location header in the
@@ -56,7 +56,7 @@ class HTTPFound(HTTPStatus):
         behavior is undesired, the 307 (Temporary Redirect) status code
         can be used instead.
 
-    See also: https://tools.ietf.org/html/rfc7231#section-6.4.3
+    (See also: RFC 7231, Section 6.4.3)
 
     Args:
         location (str): URI to provide as the Location header in the
@@ -87,7 +87,7 @@ class HTTPSeeOther(HTTPStatus):
         The new URI in the Location header field is not considered
         equivalent to the effective request URI.
 
-    See also: https://tools.ietf.org/html/rfc7231#section-6.4.4
+    (See also: RFC 7231, Section 6.4.4)
 
     Args:
         location (str): URI to provide as the Location header in the
@@ -113,7 +113,7 @@ class HTTPTemporaryRedirect(HTTPStatus):
         This status code is similar to 302 (Found), except that it
         does not allow changing the request method from POST to GET.
 
-    See also: https://tools.ietf.org/html/rfc7231#section-6.4.7
+    (See also: RFC 7231, Section 6.4.7)
 
     Args:
         location (str): URI to provide as the Location header in the
@@ -136,7 +136,7 @@ class HTTPPermanentRedirect(HTTPStatus):
         that it does not allow changing the request method from POST to
         GET.
 
-    See also: https://tools.ietf.org/html/rfc7238#section-3
+    (See also: RFC 7238, Section 3)
 
     Args:
         location (str): URI to provide as the Location header in the
diff --git a/falcon/request.py b/falcon/request.py
index 4da7b19..f7ee338 100644
--- a/falcon/request.py
+++ b/falcon/request.py
@@ -255,8 +255,8 @@ class Request(object):
         client_accepts_xml (bool): ``True`` if the Accept header indicates that
             the client is willing to receive XML, otherwise ``False``.
         cookies (dict):
-            A dict of name/value cookie pairs.
-            See also: :ref:`Getting Cookies <getting-cookies>`
+            A dict of name/value cookie pairs. (See also:
+            :ref:`Getting Cookies <getting-cookies>`)
         content_type (str): Value of the Content-Type header, or ``None`` if
             the header is missing.
         content_length (int): Value of the Content-Length header converted
@@ -558,7 +558,9 @@ class Request(object):
 
                 # NOTE(kgriffs): Calling strip() is necessary here since
                 # "an HTTP list allows white spaces to occur between the
-                # identifiers" (see also RFC 7239, Section 7.1).
+                # identifiers".
+
+                # (See also: RFC 7239, Section 7.1)
                 for param in element.strip().split(';'):
                     # PERF(kgriffs): partition() is faster than split().
                     name, __, value = param.partition('=')
diff --git a/falcon/response.py b/falcon/response.py
index ae0b91b..76bf8b8 100644
--- a/falcon/response.py
+++ b/falcon/response.py
@@ -509,7 +509,7 @@ class Response(object):
                  anchor=None, hreflang=None, type_hint=None):
         """Add a link header to the response.
 
-        See also: https://tools.ietf.org/html/rfc5988
+        (See also: RFC 5988, Section 1)
 
         Note:
             Calling this method repeatedly will cause each link to be
@@ -524,8 +524,9 @@ class Response(object):
                 link. Will be converted to a URI, if necessary, per
                 RFC 3987, Section 3.1.
             rel (str): Relation type of the link, such as "next" or
-                "bookmark". See also http://goo.gl/618GHr for a list
-                of registered link relation types.
+                "bookmark".
+
+                (See also: http://www.iana.org/assignments/link-relations/link-relations.xhtml)
 
         Keyword Args:
             title (str): Human-readable label for the destination of
@@ -661,7 +662,7 @@ class Response(object):
             case, raising ``falcon.HTTPRangeNotSatisfiable`` will do the right
             thing.
 
-            See also: http://goo.gl/Iglhp
+        (See also: RFC 7233, Section 4.2)
         """,
         format_range)
 
@@ -715,17 +716,17 @@ class Response(object):
         """Value to use for the Vary header.
 
         Set this property to an iterable of header names. For a single
-        asterisk or field value, simply pass a single-element ``list`` or
-        ``tuple``.
-
-        "Tells downstream proxies how to match future request headers
-        to decide whether the cached response can be used rather than
-        requesting a fresh one from the origin server."
-
-        (Wikipedia)
+        asterisk or field value, simply pass a single-element ``list``
+        or ``tuple``.
 
-        See also: http://goo.gl/NGHdL
+        The "Vary" header field in a response describes what parts of
+        a request message, aside from the method, Host header field,
+        and request target, might influence the origin server's
+        process for selecting and representing this response.  The
+        value consists of either a single asterisk ("*") or a list of
+        header field names (case-insensitive).
 
+        (See also: RFC 7231, Section 7.1.4)
         """,
         format_header_value_list)
 
diff --git a/falcon/util/misc.py b/falcon/util/misc.py
index ae70bff..f8c3bd0 100644
--- a/falcon/util/misc.py
+++ b/falcon/util/misc.py
@@ -273,8 +273,7 @@ def _get_argspec(func):
     This implementation re-uses much of inspect.getargspec but removes the strict
     check allowing interface failures to be raised as AttributeError.
 
-    See Also:
-        https://github.com/python/cpython/blob/2.7/Lib/inspect.py
+    (See also: https://github.com/python/cpython/blob/2.7/Lib/inspect.py)
     """
     if inspect.ismethod(func):
         func = func.im_func


Test patch:
diff --git a/falcon/testing/client.py b/falcon/testing/client.py
index 9125044..fa509a6 100644
--- a/falcon/testing/client.py
+++ b/falcon/testing/client.py
@@ -603,49 +603,49 @@ class TestClient(object):
     def simulate_get(self, path='/', **kwargs):
         """Simulates a GET request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_get`.
+        (See also: :py:meth:`falcon.testing.simulate_get`)
         """
         return simulate_get(self.app, path, **kwargs)
 
     def simulate_head(self, path='/', **kwargs):
         """Simulates a HEAD request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_head`.
+        (See also: :py:meth:`falcon.testing.simulate_head`)
         """
         return simulate_head(self.app, path, **kwargs)
 
     def simulate_post(self, path='/', **kwargs):
         """Simulates a POST request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_post`.
+        (See also: :py:meth:`falcon.testing.simulate_post`)
         """
         return simulate_post(self.app, path, **kwargs)
 
     def simulate_put(self, path='/', **kwargs):
         """Simulates a PUT request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_put`.
+        (See also: :py:meth:`falcon.testing.simulate_put`)
         """
         return simulate_put(self.app, path, **kwargs)
 
     def simulate_options(self, path='/', **kwargs):
         """Simulates an OPTIONS request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_options`.
+        (See also: :py:meth:`falcon.testing.simulate_options`)
         """
         return simulate_options(self.app, path, **kwargs)
 
     def simulate_patch(self, path='/', **kwargs):
         """Simulates a PATCH request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_patch`.
+        (See also: :py:meth:`falcon.testing.simulate_patch`)
         """
         return simulate_patch(self.app, path, **kwargs)
 
     def simulate_delete(self, path='/', **kwargs):
         """Simulates a DELETE request to a WSGI application.
 
-        See also: :py:meth:`falcon.testing.simulate_delete`.
+        (See also: :py:meth:`falcon.testing.simulate_delete`)
         """
         return simulate_delete(self.app, path, **kwargs)