Merge "Docstring cleanup for return type"

12 files changed, 69 insertions, 43 deletions

diff --git a/keystoneclient/_discover.py b/keystoneclient/_discover.py
index 9ecf616..07d0ae6 100644
--- a/keystoneclient/_discover.py
+++ b/keystoneclient/_discover.py
@@ -115,7 +115,8 @@ def version_match(required, candidate):
     :param tuple required: the version that must be met.
     :param tuple candidate: the version to test against required.
 
-    :returns bool: True if candidate is suitable False otherwise.
+    :returns: True if candidate is suitable False otherwise.
+    :rtype: bool
     """
     # major versions must be the same (e.g. even though v2 is a lower
     # version than v3 we can't use it if v2 was requested)
@@ -152,8 +153,9 @@ class Discover(object):
         :param bool allow_deprecated: Allow deprecated version endpoints.
         :param bool allow_unknown: Allow endpoints with an unrecognised status.
 
-        :returns list: The endpoints returned from the server that match the
-                       criteria.
+        :returns: The endpoints returned from the server that match the
+                  criteria.
+        :rtype: list
         """
         versions = []
         for v in self._data:
@@ -184,13 +186,14 @@ class Discover(object):
 
         Return version data in a structured way.
 
-        :returns list(dict): A list of version data dictionaries sorted by
-                             version number. Each data element in the returned
-                             list is a dictionary consisting of at least:
+        :returns: A list of version data dictionaries sorted by version number.
+                  Each data element in the returned list is a dictionary
+                  consisting of at least:
 
           :version tuple: The normalized version of the endpoint.
           :url str: The url for the endpoint.
           :raw_status str: The status as provided by the server
+        :rtype: list(dict)
         """
         data = self.raw_version_data(**kwargs)
         versions = []
@@ -241,9 +244,10 @@ class Discover(object):
             same major release as there should be no compatibility issues with
             using a version newer than the one asked for.
 
-        :returns dict: the endpoint data for a URL that matches the required
-                       version (the format is described in version_data)
-                       or None if no match.
+        :returns: the endpoint data for a URL that matches the required version
+                  (the format is described in version_data) or None if no
+                  match.
+        :rtype: dict
         """
         version = normalize_version_number(version)
         version_data = self.version_data(**kwargs)
@@ -261,7 +265,8 @@ class Discover(object):
             same major release as there should be no compatibility issues with
             using a version newer than the one asked for.
 
-        :returns str: The url for the specified version or None if no match.
+        :returns: The url for the specified version or None if no match.
+        :rtype: str
         """
         data = self.data_for(version, **kwargs)
         return data['url'] if data else None
diff --git a/keystoneclient/access.py b/keystoneclient/access.py
index 6786674..8d85c68 100644
--- a/keystoneclient/access.py
+++ b/keystoneclient/access.py
@@ -85,7 +85,8 @@ class AccessInfo(dict):
     def will_expire_soon(self, stale_duration=None):
         """Determines if expiration is about to occur.
 
-        :returns: boolean : true if expiration is within the given duration
+        :returns: true if expiration is within the given duration
+        :rtype: boolean
 
         """
         stale_duration = (STALE_TOKEN_DURATION if stale_duration is None
@@ -102,7 +103,8 @@ class AccessInfo(dict):
         """Determines if processing v2 or v3 token given a successful
         auth body or a user-provided dict.
 
-        :returns: boolean : true if auth body matches implementing class
+        :returns: true if auth body matches implementing class
+        :rtype: boolean
         """
         raise NotImplementedError()
 
diff --git a/keystoneclient/adapter.py b/keystoneclient/adapter.py
index 1ba9bfc..49dd198 100644
--- a/keystoneclient/adapter.py
+++ b/keystoneclient/adapter.py
@@ -97,7 +97,8 @@ class Adapter(object):
         :raises keystoneclient.exceptions.AuthorizationFailure: if a new token
             fetch fails.
 
-        :returns string: A valid token.
+        :returns: A valid token.
+        :rtype: string
         """
         return self.session.get_token(auth or self.auth)
 
@@ -111,7 +112,8 @@ class Adapter(object):
         :raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
                                                              available.
 
-        :returns string: An endpoint if available or None.
+        :returns: An endpoint if available or None.
+        :rtype: string
         """
         self._set_endpoint_filter_kwargs(kwargs)
         return self.session.get_endpoint(auth or self.auth, **kwargs)
diff --git a/keystoneclient/auth/base.py b/keystoneclient/auth/base.py
index 68d7b48..1f4ce29 100644
--- a/keystoneclient/auth/base.py
+++ b/keystoneclient/auth/base.py
@@ -67,7 +67,8 @@ class BaseAuthPlugin(object):
         Returning None will indicate that no token was able to be retrieved.
 
         :param session: A session object so the plugin can make HTTP calls.
-        :return string: A token to use.
+        :return: A token to use.
+        :rtype: string
         """
 
     def get_endpoint(self, session, **kwargs):
@@ -86,8 +87,9 @@ class BaseAuthPlugin(object):
         :param Session session: The session object that the auth_plugin
                                 belongs to.
 
-        :returns string: The base URL that will be used to talk to the
-                         required service or None if not available.
+        :returns: The base URL that will be used to talk to the required
+                  service or None if not available.
+        :rtype: string
         """
 
     def invalidate(self):
@@ -99,9 +101,10 @@ class BaseAuthPlugin(object):
         returned to indicate that the token may have been revoked or is
         otherwise now invalid.
 
-        :returns bool: True if there was something that the plugin did to
-                       invalidate. This means that it makes sense to try again.
-                       If nothing happens returns False to indicate give up.
+        :returns: True if there was something that the plugin did to
+                  invalidate. This means that it makes sense to try again. If
+                  nothing happens returns False to indicate give up.
+        :rtype: bool
         """
         return False
 
@@ -111,8 +114,9 @@ class BaseAuthPlugin(object):
 
         This list may be used to generate CLI or config arguments.
 
-        :returns list: A list of Param objects describing available plugin
-                       parameters.
+        :returns: A list of Param objects describing available plugin
+                  parameters.
+        :rtype: list
         """
         return []
 
@@ -201,7 +205,8 @@ class BaseAuthPlugin(object):
         :param conf: An oslo.config conf object.
         :param string group: The group name that options should be read from.
 
-        :returns plugin: An authentication Plugin.
+        :returns: An authentication Plugin.
+        :rtype: plugin:
         """
         plugin_opts = cls.get_options()
 
diff --git a/keystoneclient/auth/conf.py b/keystoneclient/auth/conf.py
index 34a206d..0b68184 100644
--- a/keystoneclient/auth/conf.py
+++ b/keystoneclient/auth/conf.py
@@ -88,7 +88,8 @@ def load_from_conf_options(conf, group, **kwargs):
     :param conf: An oslo.config conf object.
     :param string group: The group name that options should be read from.
 
-    :returns plugin: An authentication Plugin or None if a name is not provided
+    :returns: An authentication Plugin or None if a name is not provided
+    :rtype: plugin
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
diff --git a/keystoneclient/auth/identity/base.py b/keystoneclient/auth/identity/base.py
index 8113056..94b0712 100644
--- a/keystoneclient/auth/identity/base.py
+++ b/keystoneclient/auth/identity/base.py
@@ -80,7 +80,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
-        :returns AccessInfo: Token access information.
+        :returns: Token access information.
+        :rtype: :py:class:`keystoneclient.access.AccessInfo`
         """
 
     def get_token(self, session, **kwargs):
@@ -91,7 +92,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
-        :return string: A valid token.
+        :return: A valid token.
+        :rtype: string
         """
         return self.get_access(session).auth_token
 
@@ -126,7 +128,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
-        :returns AccessInfo: Valid AccessInfo
+        :returns: Valid AccessInfo
+        :rtype: :py:class:`keystoneclient.access.AccessInfo`
         """
         if self._needs_reauthenticate():
             self.auth_ref = self.get_auth_ref(session)
@@ -142,9 +145,10 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         returned to indicate that the token may have been revoked or is
         otherwise now invalid.
 
-        :returns bool: True if there was something that the plugin did to
-                       invalidate. This means that it makes sense to try again.
-                       If nothing happens returns False to indicate give up.
+        :returns: True if there was something that the plugin did to
+                  invalidate. This means that it makes sense to try again. If
+                  nothing happens returns False to indicate give up.
+        :rtype: bool
         """
         if self.auth_ref:
             self.auth_ref = None
@@ -178,7 +182,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
-        :return string or None: A valid endpoint URL or None if not available.
+        :return: A valid endpoint URL or None if not available.
+        :rtype: string or None
         """
         # NOTE(jamielennox): if you specifically ask for requests to be sent to
         # the auth url then we can ignore the rest of the checks. Typically if
diff --git a/keystoneclient/auth/identity/v2.py b/keystoneclient/auth/identity/v2.py
index 1668a82..23d4c43 100644
--- a/keystoneclient/auth/identity/v2.py
+++ b/keystoneclient/auth/identity/v2.py
@@ -91,7 +91,8 @@ class Auth(base.BaseIdentityPlugin):
 
         :param dict headers: The headers that will be sent with the auth
                              request if a plugin needs to add to them.
-        :return dict: A dict of authentication data for the auth type.
+        :return: A dict of authentication data for the auth type.
+        :rtype: dict
         """
 
 
diff --git a/keystoneclient/auth/identity/v3.py b/keystoneclient/auth/identity/v3.py
index e0f6b08..0749924 100644
--- a/keystoneclient/auth/identity/v3.py
+++ b/keystoneclient/auth/identity/v3.py
@@ -182,8 +182,9 @@ class AuthMethod(object):
         :param Auth auth: The auth plugin calling the method.
         :param dict headers: The headers that will be sent with the auth
                              request if a plugin needs to add to them.
-        :return tuple(string, dict): The identifier of this plugin and a dict
-                                     of authentication data for the auth type.
+        :return: The identifier of this plugin and a dict of authentication
+                 data for the auth type.
+        :rtype: tuple(string, dict)
         """
 
 
diff --git a/keystoneclient/contrib/auth/v3/saml2.py b/keystoneclient/contrib/auth/v3/saml2.py
index cecde02..5458ac1 100644
--- a/keystoneclient/contrib/auth/v3/saml2.py
+++ b/keystoneclient/contrib/auth/v3/saml2.py
@@ -427,8 +427,9 @@ class Saml2UnscopedToken(_BaseSAMLPlugin):
         :param session : a session object to send out HTTP requests.
         :type session: keystoneclient.session.Session
 
-        :return access.AccessInfoV3: an object with scoped token's id and
-                                     unscoped token json included.
+        :return: an object with scoped token's id and unscoped token json
+                 included.
+        :rtype: :py:class:`keystoneclient.access.AccessInfoV3`
 
         """
         token, token_json = self._get_unscoped_token(session)
@@ -840,7 +841,7 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
         :param session : a session object to send out HTTP requests.
         :type session: keystoneclient.session.Session
 
-        :returns (Unscoped federated token, token JSON body)
+        :returns: (Unscoped federated token, token JSON body)
 
         """
         self._prepare_adfs_request()
diff --git a/keystoneclient/contrib/revoke/model.py b/keystoneclient/contrib/revoke/model.py
index 60085ba..c3f3864 100644
--- a/keystoneclient/contrib/revoke/model.py
+++ b/keystoneclient/contrib/revoke/model.py
@@ -110,9 +110,9 @@ class RevokeTree(object):
         fields of the revocation event.  The leaf node will always be set to
         the latest 'issued_before' for events that are otherwise identical.
 
-        :param:  Event to add to the tree
+        :param: Event to add to the tree
 
-        :returns:  the event that was passed in.
+        :returns: the event that was passed in.
 
         """
         revoke_map = self.revoke_map
diff --git a/keystoneclient/discover.py b/keystoneclient/discover.py
index 032891b..695d345 100644
--- a/keystoneclient/discover.py
+++ b/keystoneclient/discover.py
@@ -164,8 +164,9 @@ class Discover(_discover.Discover):
         :param bool allow_deprecated: Allow deprecated version endpoints.
         :param bool allow_unknown: Allow endpoints with an unrecognised status.
 
-        :returns list: The endpoints returned from the server that match the
-                       criteria.
+        :returns: The endpoints returned from the server that match the
+                  criteria.
+        :rtype: list
 
         Example::
 
diff --git a/keystoneclient/session.py b/keystoneclient/session.py
index 06a7171..084613f 100644
--- a/keystoneclient/session.py
+++ b/keystoneclient/session.py
@@ -504,7 +504,8 @@ class Session(object):
         :raises keystoneclient.exceptions.AuthorizationFailure: if a new token
                                                                 fetch fails.
 
-        :returns string: A valid token.
+        :returns: A valid token.
+        :rtype: string
         """
         if not auth:
             auth = self.auth
@@ -528,7 +529,8 @@ class Session(object):
         :raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
                                                              available.
 
-        :returns string: An endpoint if available or None.
+        :returns: An endpoint if available or None.
+        :rtype: string
         """
         if not auth:
             auth = self.auth