Complete `jwt` documentation (#654)

* Add warning and clarify how default values are set

* Copy `jwt.decode` documentation to `jwt.decode_complete`

* Customize `jwt.decode_complete` documentation

1 files changed, 68 insertions, 13 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 2b38b4a..d23d4bd 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -43,19 +43,23 @@ API Reference
 
     :param dict options: extended decoding and validation options
 
-        * ``require=[]`` list of claims that must be present. E.g. ``require=["exp", "iat", "nbf"]``.
-            Only verifies that the claims exists. Does NOT verify that the claims are valid.
-        * ``verify_aud=True`` but will be ignored if ``verify_signature`` is ``False``.
-            Check that ``aud`` (audience) claim matches ``audience``
-        * ``verify_iat=True`` but will be ignored if ``verify_signature`` is ``False``.
-            Check that ``iat`` (issued at) claim value is an integer
-        * ``verify_exp=True`` but will be ignored if ``verify_signature`` is ``False``.
-            Check that ``exp`` (expiration) claim value is OK
-        * ``verify_iss=True`` but will be ignored if ``verify_signature`` is ``False``.
-            Check that ``iss`` (issuer) claim matches ``issuer``
-        * ``verify_nbf=True`` but will be ignored if ``verify_signature`` is ``False``.
-            Check that ``nbf`` (not before) is in the past
         * ``verify_signature=True`` verify the JWT cryptographic signature
+        * ``require=[]`` list of claims that must be present.
+          Example: ``require=["exp", "iat", "nbf"]``.
+          **Only verifies that the claims exists**. Does not verify that the claims are valid.
+        * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience``
+        * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer``
+        * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future
+        * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer
+        * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past
+
+        .. warning::
+
+            ``exp``, ``iat`` and ``nbf`` will only be verified if present.
+            Please pass respective value to ``require`` if you want to make
+            sure that they are always present (and therefore always verified
+            if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively
+            is set to ``True``).
 
     :param Iterable audience: optional, the value for ``verify_aud`` check
     :param str issuer: optional, the value for ``verify_iss`` check
@@ -63,7 +67,58 @@ API Reference
     :rtype: dict
     :returns: the JWT claims
 
-.. note:: TODO: Document PyJWS / PyJWT classes
+.. function:: decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)
+
+    Identical to ``jwt.decode`` except for return value which is a dictionary containing the token header (JOSE Header),
+    the token payload (JWT Payload), and token signature (JWT Signature) on the keys "header", "payload",
+    and "signature" respectively.
+
+    :param str jwt: the token to be decoded
+    :param str key: the key suitable for the allowed algorithm
+
+    :param list algorithms: allowed algorithms, e.g. ``["ES256"]``
+
+        .. warning::
+
+           Do **not** compute the ``algorithms`` parameter based on
+           the ``alg`` from the token itself, or on any other data
+           that an attacker may be able to influence, as that might
+           expose you to various vulnerabilities (see `RFC 8725 §2.1
+           <https://www.rfc-editor.org/rfc/rfc8725.html#section-2.1>`_). Instead,
+           either hard-code a fixed value for ``algorithms``, or
+           configure it in the same place you configure the
+           ``key``. Make sure not to mix symmetric and asymmetric
+           algorithms that interpret the ``key`` in different ways
+           (e.g. HS\* and RS\*).
+
+    :param dict options: extended decoding and validation options
+
+        * ``verify_signature=True`` verify the JWT cryptographic signature
+        * ``require=[]`` list of claims that must be present.
+          Example: ``require=["exp", "iat", "nbf"]``.
+          **Only verifies that the claims exists**. Does not verify that the claims are valid.
+        * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience``
+        * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer``
+        * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future
+        * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer
+        * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past
+
+        .. warning::
+
+            ``exp``, ``iat`` and ``nbf`` will only be verified if present.
+            Please pass respective value to ``require`` if you want to make
+            sure that they are always present (and therefore always verified
+            if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively
+            is set to ``True``).
+
+    :param Iterable audience: optional, the value for ``verify_aud`` check
+    :param str issuer: optional, the value for ``verify_iss`` check
+    :param float leeway: a time margin in seconds for the expiration check
+    :rtype: dict
+    :returns: Decoded JWT with the JOSE Header on the key ``header``, the JWS
+     Payload on the key ``payload``, and the JWS Signature on the key ``signature``.
+
+.. note:: TODO: Document PyJWS class
 
 Exceptions
 ----------