Improved doc by adding links to RFC and list of claims.

1 files changed, 25 insertions, 5 deletions

diff --git a/oauthlib/oauth2/rfc6749/request_validator.py b/oauthlib/oauth2/rfc6749/request_validator.py
index 525ba33..4b76b7a 100644
--- a/oauthlib/oauth2/rfc6749/request_validator.py
+++ b/oauthlib/oauth2/rfc6749/request_validator.py
@@ -169,11 +169,28 @@ class RequestValidator(object):
     def introspect_token(self, token, token_type_hint, request, *args, **kwargs):
         """Introspect an access or refresh token.
 
-        Called once introspect token request is validated. This method
-        should return a dictionary with any desired claims associated
-        with the *token*. The implementation can use *token_type_hint*
-        to lookup this type first, but then it must fallback to other
-        types known, to be compliant with RFC.
+        Called once the introspect request is validated. This method should
+        verify the *token* and either return a dictionary with the list of
+        claims associated, or `None` in case the token is unknown.
+
+        Below the list of registered claims you should be interested in:
+        - scope : space-separated list of scopes
+        - client_id : client identifier
+        - username : human-readable identifier for the resource owner
+        - token_type : type of the token
+        - exp : integer timestamp indicating when this token will expire
+        - iat : integer timestamp indicating when this token was issued
+        - nbf : integer timestamp indicating when it can be "not-before" used
+        - sub : subject of the token - identifier of the resource owner
+        - aud : list of string identifiers representing the intended audience
+        - iss : string representing issuer of this token
+        - jti : string identifier for the token
+
+        Note that most of them are coming directly from JWT RFC. More details
+        can be found in `Introspect Claims`_ or `_JWT Claims`_.
+
+        The implementation can use *token_type_hint* to improve lookup
+        efficency, but must fallback to other types to be compliant with RFC.
 
         The dict of claims is added to request.token after this method.
 
@@ -183,6 +200,9 @@ class RequestValidator(object):
 
         Method is used by:
             - Introspect Endpoint (all grants are compatible)
+
+        .. _`Introspect Claims`: https://tools.ietf.org/html/rfc7662#section-2.2
+        .. _`JWT Claims`: https://tools.ietf.org/html/rfc7519#section-4
         """
         raise NotImplementedError('Subclasses must implement this method.')