redid the docstring fixes

14 files changed, 331 insertions, 115 deletions

diff --git a/oauthlib/oauth1/rfc5849/endpoints/access_token.py b/oauthlib/oauth1/rfc5849/endpoints/access_token.py
index 12d13e9..bea8274 100644
--- a/oauthlib/oauth1/rfc5849/endpoints/access_token.py
+++ b/oauthlib/oauth1/rfc5849/endpoints/access_token.py
@@ -37,7 +37,8 @@ class AccessTokenEndpoint(BaseEndpoint):
         Similar to OAuth 2, indication of granted scopes will be included as a
         space separated list in ``oauth_authorized_realms``.
 
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The token as an urlencoded string.
         """
         request.realms = self.request_validator.get_realms(
@@ -120,7 +121,8 @@ class AccessTokenEndpoint(BaseEndpoint):
     def validate_access_token_request(self, request):
         """Validate an access token request.
 
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :raises: OAuth1Error if the request is invalid.
         :returns: A tuple of 2 elements.
                   1. The validation result (True or False).
diff --git a/oauthlib/oauth1/rfc5849/endpoints/authorization.py b/oauthlib/oauth1/rfc5849/endpoints/authorization.py
index 1751a45..b465946 100644
--- a/oauthlib/oauth1/rfc5849/endpoints/authorization.py
+++ b/oauthlib/oauth1/rfc5849/endpoints/authorization.py
@@ -42,7 +42,8 @@ class AuthorizationEndpoint(BaseEndpoint):
     def create_verifier(self, request, credentials):
         """Create and save a new request token.
 
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :param credentials: A dict of extra token credentials.
         :returns: The verifier as a dict.
         """
diff --git a/oauthlib/oauth1/rfc5849/endpoints/request_token.py b/oauthlib/oauth1/rfc5849/endpoints/request_token.py
index 88fd6c0..e9ca331 100644
--- a/oauthlib/oauth1/rfc5849/endpoints/request_token.py
+++ b/oauthlib/oauth1/rfc5849/endpoints/request_token.py
@@ -34,7 +34,8 @@ class RequestTokenEndpoint(BaseEndpoint):
     def create_request_token(self, request, credentials):
         """Create and save a new request token.
 
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :param credentials: A dict of extra token credentials.
         :returns: The token as an urlencoded string.
         """
@@ -111,7 +112,8 @@ class RequestTokenEndpoint(BaseEndpoint):
     def validate_request_token_request(self, request):
         """Validate a request token request.
 
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :raises: OAuth1Error if the request is invalid.
         :returns: A tuple of 2 elements.
                   1. The validation result (True or False).
diff --git a/oauthlib/oauth1/rfc5849/request_validator.py b/oauthlib/oauth1/rfc5849/request_validator.py
index bc62ea0..330bcbb 100644
--- a/oauthlib/oauth1/rfc5849/request_validator.py
+++ b/oauthlib/oauth1/rfc5849/request_validator.py
@@ -267,7 +267,8 @@ class RequestValidator(object):
         """Retrieves the client secret associated with the client key.
 
         :param client_key: The client/consumer key.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The client secret as a string.
 
         This method must allow the use of a dummy client_key value.
@@ -303,7 +304,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param token: The request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The token secret as a string.
 
         This method must allow the use of a dummy values and the running time
@@ -335,7 +337,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param token: The access token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The token secret as a string.
 
         This method must allow the use of a dummy values and the running time
@@ -366,7 +369,8 @@ class RequestValidator(object):
         """Get the default realms for a client.
 
         :param client_key: The client/consumer key.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The list of default realms associated with the client.
 
         The list of default realms will be set during client registration and
@@ -382,7 +386,8 @@ class RequestValidator(object):
         """Get realms associated with a request token.
 
         :param token: The request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The list of realms associated with the request token.
 
         This method is used by
@@ -396,7 +401,8 @@ class RequestValidator(object):
         """Get the redirect URI associated with a request token.
 
         :param token: The request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The redirect URI associated with the request token.
 
         It may be desirable to return a custom URI if the redirect is set to "oob".
@@ -413,7 +419,8 @@ class RequestValidator(object):
         """Retrieves a previously stored client provided RSA key.
 
         :param client_key: The client/consumer key.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: The rsa public key as a string.
 
         This method must allow the use of a dummy client_key value. Fetching
@@ -437,7 +444,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param request_token: The request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: None
 
         Per `Section 2.3`__ of the spec:
@@ -462,7 +470,8 @@ class RequestValidator(object):
         """Validates that supplied client key is a registered and valid client.
 
         :param client_key: The client/consumer key.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         Note that if the dummy client is supplied it should validate in same
@@ -499,7 +508,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param token: The request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         Note that if the dummy request_token is supplied it should validate in
@@ -533,7 +543,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param token: The access token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         Note that if the dummy access token is supplied it should validate in
@@ -571,7 +582,8 @@ class RequestValidator(object):
         :param nonce: The ``oauth_nonce`` parameter.
         :param request_token: Request token string, if any.
         :param access_token: Access token string, if any.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         Per `Section 3.3`_ of the spec.
@@ -618,7 +630,8 @@ class RequestValidator(object):
         :param client_key: The client/consumer key.
         :param redirect_uri: The URI the client which to redirect back to after
                              authorization is successful.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         It is highly recommended that OAuth providers require their clients
@@ -650,7 +663,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param realms: The list of realms that client is requesting access to.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         This method is invoked when obtaining a request token and should
@@ -669,7 +683,8 @@ class RequestValidator(object):
 
         :param client_key: The client/consumer key.
         :param token: A request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :param uri: The URI the realms is protecting.
         :param realms: A list of realms that must have been granted to
                        the access token.
@@ -703,7 +718,8 @@ class RequestValidator(object):
         :param client_key: The client/consumer key.
         :param token: A request token string.
         :param verifier: The authorization verifier string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         OAuth providers issue a verification code to clients after the
@@ -732,7 +748,8 @@ class RequestValidator(object):
         """Verify that the given OAuth1 request token is valid.
 
         :param token: A request token string.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         This method is used only in AuthorizationEndpoint to check whether the
@@ -751,7 +768,8 @@ class RequestValidator(object):
 
         :param token: An access token string.
         :param realms: A list of realms the client attempts to access.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :returns: True or False
 
         This prevents the list of authorized realms sent by the client during
@@ -773,7 +791,8 @@ class RequestValidator(object):
         """Save an OAuth1 access token.
 
         :param token: A dict with token credentials.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         The token dictionary will at minimum include
 
@@ -796,7 +815,8 @@ class RequestValidator(object):
         """Save an OAuth1 request token.
 
         :param token: A dict with token credentials.
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         The token dictionary will at minimum include
 
@@ -818,7 +838,8 @@ class RequestValidator(object):
         :param token: A request token string.
         :param verifier A dictionary containing the oauth_verifier and
                         oauth_token
-        :param request: An oauthlib.common.Request object.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         We need to associate verifiers with tokens for validation during the
         access token request.
diff --git a/oauthlib/oauth2/rfc6749/grant_types/authorization_code.py b/oauthlib/oauth2/rfc6749/grant_types/authorization_code.py
index ab4c184..59366b1 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/authorization_code.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/authorization_code.py
@@ -98,7 +98,12 @@ class AuthorizationCodeGrant(GrantTypeBase):
     response_types = ['code']
 
     def create_authorization_code(self, request):
-        """Generates an authorization grant represented as a dictionary."""
+        """
+        Generates an authorization grant represented as a dictionary.
+        
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         grant = {'code': common.generate_token()}
         if hasattr(request, 'state') and request.state:
             grant['state'] = request.state
@@ -135,7 +140,8 @@ class AuthorizationCodeGrant(GrantTypeBase):
         HTTP redirection response, or by other means available to it via the
         user-agent.
 
-        :param request: oauthlib.commong.Request
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :param token_handler: A token handler instace, for example of type
                               oauthlib.oauth2.BearerToken.
         :returns: headers, body, status
@@ -220,6 +226,12 @@ class AuthorizationCodeGrant(GrantTypeBase):
         MUST deny the request and SHOULD revoke (when possible) all tokens
         previously issued based on that authorization code. The authorization
         code is bound to the client identifier and redirection URI.
+
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         """
         headers = {
             'Content-Type': 'application/json',
@@ -253,6 +265,9 @@ class AuthorizationCodeGrant(GrantTypeBase):
         missing. These must be caught by the provider and handled, how this
         is done is outside of the scope of OAuthLib but showing an error
         page describing the issue is a good idea.
+
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         """
 
         # First check for fatal errors
@@ -353,6 +368,10 @@ class AuthorizationCodeGrant(GrantTypeBase):
         return request.scopes, request_info
 
     def validate_token_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         # REQUIRED. Value MUST be set to "authorization_code".
         if request.grant_type not in ('authorization_code', 'openid'):
             raise errors.UnsupportedGrantTypeError(request=request)
diff --git a/oauthlib/oauth2/rfc6749/grant_types/base.py b/oauthlib/oauth2/rfc6749/grant_types/base.py
index e5d8ddd..4d9381c 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/base.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/base.py
@@ -116,14 +116,32 @@ class GrantTypeBase(object):
     def register_token_modifier(self, modifier):
         self._token_modifiers.append(modifier)
 
-
     def create_authorization_response(self, request, token_handler):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+        """
         raise NotImplementedError('Subclasses must implement this method.')
 
     def create_token_response(self, request, token_handler):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+        """
         raise NotImplementedError('Subclasses must implement this method.')
 
     def add_token(self, token, token_handler, request):
+        """
+        :param token:
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         # Only add a hybrid access token on auth step if asked for
         if not request.response_type in ["token", "code token", "id_token token", "code id_token token"]:
             return token
@@ -132,6 +150,10 @@ class GrantTypeBase(object):
         return token
 
     def validate_grant_type(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         client_id = getattr(request, 'client_id', None)
         if not self.request_validator.validate_grant_type(client_id,
                                                           request.grant_type, request.client, request):
@@ -140,6 +162,10 @@ class GrantTypeBase(object):
             raise errors.UnauthorizedClientError(request=request)
 
     def validate_scopes(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         if not request.scopes:
             request.scopes = utils.scope_to_list(request.scope) or utils.scope_to_list(
                 self.request_validator.get_default_scopes(request.client_id, request))
@@ -154,6 +180,13 @@ class GrantTypeBase(object):
 
         Base classes can define a default response mode for their authorization
         response by overriding the static `default_response_mode` member.
+
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token:
+        :param headers:
+        :param body:
+        :param status:
         """
         request.response_mode = request.response_mode or self.default_response_mode
 
diff --git a/oauthlib/oauth2/rfc6749/grant_types/client_credentials.py b/oauthlib/oauth2/rfc6749/grant_types/client_credentials.py
index 4c50a78..884363f 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/client_credentials.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/client_credentials.py
@@ -53,6 +53,11 @@ class ClientCredentialsGrant(GrantTypeBase):
     def create_token_response(self, request, token_handler):
         """Return token or error in JSON format.
 
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         If the access token request is valid and authorized, the
         authorization server issues an access token as described in
         `Section 5.1`_.  A refresh token SHOULD NOT be included.  If the request
@@ -85,6 +90,10 @@ class ClientCredentialsGrant(GrantTypeBase):
         return headers, json.dumps(token), 200
 
     def validate_token_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         for validator in self.custom_validators.pre_token:
             validator(request)
 
diff --git a/oauthlib/oauth2/rfc6749/grant_types/implicit.py b/oauthlib/oauth2/rfc6749/grant_types/implicit.py
index 3a5c058..600c0a5 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/implicit.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/implicit.py
@@ -121,6 +121,12 @@ class ImplicitGrant(GrantTypeBase):
 
     def create_authorization_response(self, request, token_handler):
         """Create an authorization response.
+
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         The client constructs the request URI by adding the following
         parameters to the query component of the authorization endpoint URI
         using the "application/x-www-form-urlencoded" format, per `Appendix B`_:
@@ -163,6 +169,11 @@ class ImplicitGrant(GrantTypeBase):
     def create_token_response(self, request, token_handler):
         """Return token or error embedded in the URI fragment.
 
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         If the resource owner grants the access request, the authorization
         server issues an access token and delivers it to the client by adding
         the following parameters to the fragment component of the redirection
@@ -243,11 +254,18 @@ class ImplicitGrant(GrantTypeBase):
             request, token, {}, None, 302)
 
     def validate_authorization_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         return self.validate_token_request(request)
 
     def validate_token_request(self, request):
         """Check the token request for normal and fatal errors.
 
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+
         This method is very similar to validate_authorization_request in
         the AuthorizationCodeGrant but differ in a few subtle areas.
 
diff --git a/oauthlib/oauth2/rfc6749/grant_types/refresh_token.py b/oauthlib/oauth2/rfc6749/grant_types/refresh_token.py
index c2d86f7..55ddbb2 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/refresh_token.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/refresh_token.py
@@ -33,6 +33,11 @@ class RefreshTokenGrant(GrantTypeBase):
     def create_token_response(self, request, token_handler):
         """Create a new access token from a refresh_token.
 
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         If valid and authorized, the authorization server issues an access
         token as described in `Section 5.1`_. If the request failed
         verification or is invalid, the authorization server returns an error
@@ -72,6 +77,10 @@ class RefreshTokenGrant(GrantTypeBase):
         return headers, json.dumps(token), 200
 
     def validate_token_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         # REQUIRED. Value MUST be set to "refresh_token".
         if request.grant_type != 'refresh_token':
             raise errors.UnsupportedGrantTypeError(request=request)
diff --git a/oauthlib/oauth2/rfc6749/grant_types/resource_owner_password_credentials.py b/oauthlib/oauth2/rfc6749/grant_types/resource_owner_password_credentials.py
index e5f04af..25fb1f1 100644
--- a/oauthlib/oauth2/rfc6749/grant_types/resource_owner_password_credentials.py
+++ b/oauthlib/oauth2/rfc6749/grant_types/resource_owner_password_credentials.py
@@ -73,6 +73,11 @@ class ResourceOwnerPasswordCredentialsGrant(GrantTypeBase):
     def create_token_response(self, request, token_handler):
         """Return token or error in json format.
 
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param token_handler: A token handler instace, for example of type
+                              oauthlib.oauth2.BearerToken.
+
         If the access token request is valid and authorized, the
         authorization server issues an access token and optional refresh
         token as described in `Section 5.1`_.  If the request failed client
@@ -114,6 +119,9 @@ class ResourceOwnerPasswordCredentialsGrant(GrantTypeBase):
 
     def validate_token_request(self, request):
         """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+
         The client makes a request to the token endpoint by adding the
         following parameters using the "application/x-www-form-urlencoded"
         format per Appendix B with a character encoding of UTF-8 in the HTTP
diff --git a/oauthlib/oauth2/rfc6749/parameters.py b/oauthlib/oauth2/rfc6749/parameters.py
index c5127e7..3f18733 100644
--- a/oauthlib/oauth2/rfc6749/parameters.py
+++ b/oauthlib/oauth2/rfc6749/parameters.py
@@ -37,14 +37,13 @@ def prepare_grant_uri(uri, client_id, response_type, redirect_uri=None,
     using the ``application/x-www-form-urlencoded`` format as defined by
     [`W3C.REC-html401-19991224`_]:
 
+    :param client_id: The client identifier as described in `Section 2.2`_.
     :param response_type: To indicate which OAuth 2 grant/flow is required,
                           "code" and "token".
-    :param client_id: The client identifier as described in `Section 2.2`_.
     :param redirect_uri: The client provided URI to redirect back to after
                          authorization as described in `Section 3.1.2`_.
     :param scope: The scope of the access request as described by
                   `Section 3.3`_.
-
     :param state: An opaque value used by the client to maintain
                   state between the request and callback.  The authorization
                   server includes this value when redirecting the user-agent
@@ -133,15 +132,19 @@ def prepare_token_revocation_request(url, token, token_type_hint="access_token",
     using the "application/x-www-form-urlencoded" format in the HTTP request
     entity-body:
 
-    token   REQUIRED.  The token that the client wants to get revoked.
-
-    token_type_hint  OPTIONAL.  A hint about the type of the token submitted
-    for revocation.  Clients MAY pass this parameter in order to help the
-    authorization server to optimize the token lookup.  If the server is unable
-    to locate the token using the given hint, it MUST extend its search across
-    all of its supported token types.  An authorization server MAY ignore this
-    parameter, particularly if it is able to detect the token type
-    automatically.  This specification defines two such values:
+    :param token: REQUIRED.  The token that the client wants to get revoked.
+
+    param:token_type_hint: OPTIONAL.  A hint about the type of the token
+                           submitted for revocation. Clients MAY pass this
+                           parameter in order to help the authorization server
+                           to optimize the token lookup.  If the server is
+                           unable to locate the token using the given hint, it
+                           MUST extend its search across all of its supported
+                           token types.  An authorization server MAY ignore this
+                           parameter, particularly if it is able to detect the
+                           token type automatically.
+    
+    This specification defines two values for `token_type_hint`:
 
         * access_token: An access token as defined in [RFC6749],
              `Section 1.4`_
diff --git a/oauthlib/oauth2/rfc6749/request_validator.py b/oauthlib/oauth2/rfc6749/request_validator.py
index ff3bbd6..6ce7910 100644
--- a/oauthlib/oauth2/rfc6749/request_validator.py
+++ b/oauthlib/oauth2/rfc6749/request_validator.py
@@ -26,7 +26,8 @@ class RequestValidator(object):
               client credentials or whenever Client provided client authentication, see
               `Section 6`_
 
-        :param request: oauthlib.common.Request
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -51,7 +52,8 @@ class RequestValidator(object):
         both body and query can be obtained by direct attribute access, i.e.
         request.client_id for client_id in the URL query.
 
-        :param request: oauthlib.common.Request
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -74,7 +76,9 @@ class RequestValidator(object):
         to set request.client to the client object associated with the
         given client_id.
 
-        :param request: oauthlib.common.Request
+        :param client_id: Unicode client identifier.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -93,11 +97,12 @@ class RequestValidator(object):
         the client's allowed redirect URIs, but against the URI used when the
         code was saved.
 
-        :param client_id: Unicode client identifier
+        :param client_id: Unicode client identifier.
         :param code: Unicode authorization_code.
-        :param redirect_uri: Unicode absolute URI
+        :param redirect_uri: Unicode absolute URI.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -108,8 +113,9 @@ class RequestValidator(object):
     def get_default_redirect_uri(self, client_id, request, *args, **kwargs):
         """Get the default redirect URI for the client.
 
-        :param client_id: Unicode client identifier
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param client_id: Unicode client identifier.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: The default redirect URI for the client
 
         Method is used by:
@@ -121,8 +127,9 @@ class RequestValidator(object):
     def get_default_scopes(self, client_id, request, *args, **kwargs):
         """Get the default scopes for the client.
 
-        :param client_id: Unicode client identifier
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param client_id: Unicode client identifier.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: List of default scopes
 
         Method is used by all core grant types:
@@ -136,8 +143,9 @@ class RequestValidator(object):
     def get_original_scopes(self, refresh_token, request, *args, **kwargs):
         """Get the list of scopes associated with the refresh token.
 
-        :param refresh_token: Unicode refresh token
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param refresh_token: Unicode refresh token.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: List of scopes.
 
         Method is used by:
@@ -156,9 +164,10 @@ class RequestValidator(object):
         used in situations where returning all valid scopes from the
         get_original_scopes is not practical.
 
-        :param request_scopes: A list of scopes that were requested by client
-        :param refresh_token: Unicode refresh_token
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request_scopes: A list of scopes that were requested by client.
+        :param refresh_token: Unicode refresh_token.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -196,7 +205,8 @@ class RequestValidator(object):
 
         :param token: The token string.
         :param token_type_hint: access_token or refresh_token.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         Method is used by:
             - Introspect Endpoint (all grants are compatible)
@@ -209,9 +219,10 @@ class RequestValidator(object):
     def invalidate_authorization_code(self, client_id, code, request, *args, **kwargs):
         """Invalidate an authorization code after use.
 
-        :param client_id: Unicode client identifier
+        :param client_id: Unicode client identifier.
         :param code: The authorization code grant (request.code).
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         Method is used by:
             - Authorization Code Grant
@@ -223,7 +234,8 @@ class RequestValidator(object):
 
         :param token: The token string.
         :param token_type_hint: access_token or refresh_token.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         Method is used by:
             - Revocation Endpoint
@@ -237,7 +249,8 @@ class RequestValidator(object):
         or replaced with a new one (rotated). Return True to rotate and
         and False for keeping original.
 
-        :param request: oauthlib.common.Request
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -269,9 +282,10 @@ class RequestValidator(object):
         http://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter
         This value should be saved in this method and used again in 'validate_code'.
 
-        :param client_id: Unicode client identifier
+        :param client_id: Unicode client identifier.
         :param code: A dict of the authorization code grant and, optionally, state.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         Method is used by:
             - Authorization Code Grant
@@ -292,10 +306,12 @@ class RequestValidator(object):
         blank value `""` don't forget to check it before using those values
         in a select query if a database is used.
 
-        :param client_id: Unicode client identifier
-        :param code: Unicode authorization code grant
-        :param redirect_uri: Unicode absolute URI
-        :return: A list of scope
+        :param client_id: Unicode client identifier.
+        :param code: Unicode authorization code grant.
+        :param redirect_uri: Unicode absolute URI.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :return: A list of scopes
 
         Method is used by:
             - Authorization Token Grant Dispatcher
@@ -306,6 +322,10 @@ class RequestValidator(object):
         """Persist the token with a token type specific method.
 
         Currently, only save_bearer_token is supported.
+
+        :param token: A (Bearer) token dict.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         """
         return self.save_bearer_token(token, request, *args, **kwargs)
 
@@ -346,8 +366,9 @@ class RequestValidator(object):
         the claims dict, which should be saved for later use when generating the
         id_token and/or UserInfo response content.
 
-        :param token: A Bearer token dict
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param token: A Bearer token dict.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: The default redirect URI for the client
 
         Method is used by all core grant types issuing Bearer tokens:
@@ -363,9 +384,10 @@ class RequestValidator(object):
 
         If using OpenID Connect this SHOULD call `oauthlib.oauth2.RequestValidator.get_id_token`
 
-        :param token: A Bearer token dict
-        :param token_handler: the token handler (BearerToken class)
-        :param request: the HTTP Request (oauthlib.common.Request)
+        :param token: A Bearer token dict.
+        :param token_handler: The token handler (BearerToken class).
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :return: The JWT Bearer token or OpenID Connect ID token (a JWS signed JWT)
 
         Method is used by JWT Bearer and OpenID Connect tokens:
@@ -398,9 +420,10 @@ class RequestValidator(object):
         .. _`3.2.2.10`: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitIDToken
         .. _`3.3.2.11`: http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken
 
-        :param token: A Bearer token dict
-        :param token_handler: the token handler (BearerToken class)
-        :param request: the HTTP Request (oauthlib.common.Request)
+        :param token: A Bearer token dict.
+        :param token_handler: The token handler (BearerToken class)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :return: The ID Token (a JWS signed JWT)
         """
         # the request.scope should be used by the get_id_token() method to determine which claims to include in the resulting id_token
@@ -419,9 +442,10 @@ class RequestValidator(object):
             - http://openid.net/specs/openid-connect-core-1_0.html#HybridIDTValidation
             - http://openid.net/specs/openid-connect-core-1_0.html#HybridIDTValidation2
 
-        :param token: Unicode Bearer token
-        :param scopes: List of scopes (defined by you)
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param token: Unicode Bearer token.
+        :param scopes: List of scopes (defined by you).
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is indirectly used by all core OpenID connect JWT token issuing grant types:
@@ -440,9 +464,10 @@ class RequestValidator(object):
             - http://openid.net/specs/openid-connect-core-1_0.html#HybridIDTValidation
             - http://openid.net/specs/openid-connect-core-1_0.html#HybridIDTValidation2
 
-        :param token: Unicode Bearer token
-        :param scopes: List of scopes (defined by you)
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param token: Unicode Bearer token.
+        :param scopes: List of scopes (defined by you).
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is indirectly used by all core OpenID connect JWT token issuing grant types:
@@ -457,7 +482,8 @@ class RequestValidator(object):
 
         :param token: A string of random characters.
         :param scopes: A list of scopes associated with the protected resource.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
 
         A key to OAuth 2 security and restricting impact of leaked tokens is
         the short expiration time of tokens, *always ensure the token has not
@@ -491,7 +517,8 @@ class RequestValidator(object):
 
         :param token: Unicode Bearer token
         :param scopes: List of scopes (defined by you)
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is indirectly used by all core Bearer token issuing grant types:
@@ -509,7 +536,9 @@ class RequestValidator(object):
         to set request.client to the client object associated with the
         given client_id.
 
-        :param request: oauthlib.common.Request
+        :param client_id: Unicode client identifier.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -535,10 +564,11 @@ class RequestValidator(object):
 
         The request.claims property, if it was given, should assigned a dict.
 
-        :param client_id: Unicode client identifier
-        :param code: Unicode authorization code
+        :param client_id: Unicode client identifier.
+        :param code: Unicode authorization code.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -549,10 +579,11 @@ class RequestValidator(object):
     def validate_grant_type(self, client_id, grant_type, client, request, *args, **kwargs):
         """Ensure client is authorized to use the grant_type requested.
 
-        :param client_id: Unicode client identifier
+        :param client_id: Unicode client identifier.
         :param grant_type: Unicode grant type, i.e. authorization_code, password.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -569,9 +600,10 @@ class RequestValidator(object):
         All clients should register the absolute URIs of all URIs they intend
         to redirect to. The registration is outside of the scope of oauthlib.
 
-        :param client_id: Unicode client identifier
-        :param redirect_uri: Unicode absolute URI
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param client_id: Unicode client identifier.
+        :param redirect_uri: Unicode absolute URI.
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -586,9 +618,10 @@ class RequestValidator(object):
         OBS! The request.user attribute should be set to the resource owner
         associated with this refresh token.
 
-        :param refresh_token: Unicode refresh token
+        :param refresh_token: Unicode refresh token.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -601,10 +634,11 @@ class RequestValidator(object):
     def validate_response_type(self, client_id, response_type, client, request, *args, **kwargs):
         """Ensure client is authorized to use the response_type requested.
 
-        :param client_id: Unicode client identifier
+        :param client_id: Unicode client identifier.
         :param response_type: Unicode response type, i.e. code, token.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -616,10 +650,11 @@ class RequestValidator(object):
     def validate_scopes(self, client_id, scopes, client, request, *args, **kwargs):
         """Ensure the client is authorized access to requested scopes.
 
-        :param client_id: Unicode client identifier
-        :param scopes: List of scopes (defined by you)
+        :param client_id: Unicode client identifier.
+        :param scopes: List of scopes (defined by you).
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by all core grant types:
@@ -636,7 +671,8 @@ class RequestValidator(object):
         Silent OpenID authorization allows access tokens and id tokens to be
         granted to clients without any user prompt or interaction.
 
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -656,7 +692,8 @@ class RequestValidator(object):
         not selected which one to link to the token then this method should
         raise an oauthlib.oauth2.AccountSelectionRequired error.
 
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -674,10 +711,11 @@ class RequestValidator(object):
         not set you will be unable to associate a token with a user in the
         persistance method used (commonly, save_bearer_token).
 
-        :param username: Unicode username
-        :param password: Unicode password
+        :param username: Unicode username.
+        :param password: Unicode password.
         :param client: Client object set by you, see authenticate_client.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -694,7 +732,8 @@ class RequestValidator(object):
         :param id_token_hint: User identifier string.
         :param scopes: List of OAuth 2 scopes and OpenID claims (strings).
         :param claims: OpenID Connect claims dict.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
diff --git a/oauthlib/oauth2/rfc6749/tokens.py b/oauthlib/oauth2/rfc6749/tokens.py
index 1d2b5eb..765251e 100644
--- a/oauthlib/oauth2/rfc6749/tokens.py
+++ b/oauthlib/oauth2/rfc6749/tokens.py
@@ -96,10 +96,14 @@ def prepare_mac_header(token, uri, key, http_method,
     .. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
     .. _`extension algorithms`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01#section-7.1
 
+    :param token:
     :param uri: Request URI.
-    :param headers: Request headers as a dictionary.
-    :param http_method: HTTP Request method.
     :param key: MAC given provided by token endpoint.
+    :param http_method: HTTP Request method.
+    :param nonce:
+    :param headers: Request headers as a dictionary.
+    :param body:
+    :param ext:
     :param hash_algorithm: HMAC algorithm provided by token endpoint.
     :param issue_time: Time when the MAC credentials were issued (datetime).
     :param draft: MAC authentication specification version.
@@ -181,6 +185,9 @@ def prepare_bearer_uri(token, uri):
     http://www.example.com/path?access_token=h480djs93hd8
 
     .. _`Bearer Token`: https://tools.ietf.org/html/rfc6750
+
+    :param token:
+    :param uri:
     """
     return add_params_to_uri(uri, [(('access_token', token))])
 
@@ -192,6 +199,9 @@ def prepare_bearer_headers(token, headers=None):
     Authorization: Bearer h480djs93hd8
 
     .. _`Bearer Token`: https://tools.ietf.org/html/rfc6750
+
+    :param token:
+    :param headers:
     """
     headers = headers or {}
     headers['Authorization'] = 'Bearer %s' % token
@@ -204,15 +214,26 @@ def prepare_bearer_body(token, body=''):
     access_token=h480djs93hd8
 
     .. _`Bearer Token`: https://tools.ietf.org/html/rfc6750
+
+    :param token:
+    :param body:
     """
     return add_params_to_qs(body, [(('access_token', token))])
 
 
 def random_token_generator(request, refresh_token=False):
+    """
+    :param request: OAuthlib request.
+    :type request: oauthlib.common.Request
+    :param refresh_token:
+    """
     return common.generate_token()
 
 
 def signed_token_generator(private_pem, **kwargs):
+    """
+    :param private_pem:
+    """
     def signed_token_generator(request):
         request.claims = kwargs
         return common.generate_signed_token(private_pem, request)
@@ -223,7 +244,8 @@ def signed_token_generator(private_pem, **kwargs):
 def get_token_from_header(request):
     """
     Helper function to extract a token from the request header.
-    :param request: The request object
+    :param request: OAuthlib request.
+    :type request: oauthlib.common.Request
     :return: Return the token or None if the Authorization header is malformed.
     """
     token = None
@@ -244,9 +266,17 @@ class TokenBase(object):
         raise NotImplementedError('Subclasses must implement this method.')
 
     def validate_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         raise NotImplementedError('Subclasses must implement this method.')
 
     def estimate_type(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         raise NotImplementedError('Subclasses must implement this method.')
 
 
@@ -266,7 +296,14 @@ class BearerToken(TokenBase):
         self.expires_in = expires_in or 3600
 
     def create_token(self, request, refresh_token=False, save_token=True):
-        """Create a BearerToken, by default without refresh token."""
+        """
+        Create a BearerToken, by default without refresh token.
+        
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        :param refresh_token:
+        :param save_token:
+        """
 
         if callable(self.expires_in):
             expires_in = self.expires_in(request)
@@ -304,11 +341,19 @@ class BearerToken(TokenBase):
         return token
 
     def validate_request(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         token = get_token_from_header(request)
         return self.request_validator.validate_bearer_token(
             token, request.scopes, request)
 
     def estimate_type(self, request):
+        """
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
+        """
         if request.headers.get('Authorization', '').split(' ')[0] == 'Bearer':
             return 9
         elif request.access_token is not None:
diff --git a/oauthlib/openid/connect/core/request_validator.py b/oauthlib/openid/connect/core/request_validator.py
index f3bcbdb..1587754 100644
--- a/oauthlib/openid/connect/core/request_validator.py
+++ b/oauthlib/openid/connect/core/request_validator.py
@@ -45,7 +45,8 @@ class RequestValidator(OAuth2RequestValidator):
 
         :param token: A Bearer token dict
         :param token_handler: the token handler (BearerToken class)
-        :param request: the HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :return: The JWT Bearer token or OpenID Connect ID token (a JWS signed JWT)
 
         Method is used by JWT Bearer and OpenID Connect tokens:
@@ -80,7 +81,8 @@ class RequestValidator(OAuth2RequestValidator):
 
         :param token: A Bearer token dict
         :param token_handler: the token handler (BearerToken class)
-        :param request: the HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :return: The ID Token (a JWS signed JWT)
         """
         # the request.scope should be used by the get_id_token() method to determine which claims to include in the resulting id_token
@@ -101,7 +103,8 @@ class RequestValidator(OAuth2RequestValidator):
 
         :param token: Unicode Bearer token
         :param scopes: List of scopes (defined by you)
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is indirectly used by all core OpenID connect JWT token issuing grant types:
@@ -122,7 +125,8 @@ class RequestValidator(OAuth2RequestValidator):
 
         :param token: Unicode Bearer token
         :param scopes: List of scopes (defined by you)
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is indirectly used by all core OpenID connect JWT token issuing grant types:
@@ -138,7 +142,8 @@ class RequestValidator(OAuth2RequestValidator):
         Silent OpenID authorization allows access tokens and id tokens to be
         granted to clients without any user prompt or interaction.
 
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -158,7 +163,8 @@ class RequestValidator(OAuth2RequestValidator):
         not selected which one to link to the token then this method should
         raise an oauthlib.oauth2.AccountSelectionRequired error.
 
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by:
@@ -177,7 +183,8 @@ class RequestValidator(OAuth2RequestValidator):
         :param id_token_hint: User identifier string.
         :param scopes: List of OAuth 2 scopes and OpenID claims (strings).
         :param claims: OpenID Connect claims dict.
-        :param request: The HTTP Request (oauthlib.common.Request)
+        :param request: OAuthlib request.
+        :type request: oauthlib.common.Request
         :rtype: True or False
 
         Method is used by: