Merge "Fix up types within API documentation"

7 files changed, 43 insertions, 18 deletions

diff --git a/keystoneclient/auth/base.py b/keystoneclient/auth/base.py
index ecbcf96..9da90b7 100644
--- a/keystoneclient/auth/base.py
+++ b/keystoneclient/auth/base.py
@@ -34,6 +34,7 @@ def get_plugin_class(name):
     :param str name: The name of the object to get.
 
     :returns: An auth plugin class.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
@@ -67,6 +68,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.
+        :type session: keystoneclient.session.Session
+
         :return: A token to use.
         :rtype: string
         """
@@ -84,8 +87,8 @@ class BaseAuthPlugin(object):
         - ``interface``: what visibility the endpoint should have.
         - ``region_name``: the region the endpoint exists in.
 
-        :param Session session: The session object that the auth_plugin
-                                belongs to.
+        :param session: The session object that the auth_plugin belongs to.
+        :type session: keystoneclient.session.Session
 
         :returns: The base URL that will be used to talk to the required
                   service or None if not available.
@@ -167,8 +170,8 @@ class BaseAuthPlugin(object):
         Given a plugin class convert it's options into argparse arguments and
         add them to a parser.
 
-        :param AuthPlugin plugin: an auth plugin class.
-        :param argparse.ArgumentParser: the parser to attach argparse options.
+        :param parser: the parser to attach argparse options.
+        :type parser: argparse.ArgumentParser
         """
 
         # NOTE(jamielennox): ideally oslo.config would be smart enough to
@@ -201,10 +204,11 @@ class BaseAuthPlugin(object):
 
         Convert the results of a parse into the specified plugin.
 
-        :param AuthPlugin plugin: an auth plugin class.
-        :param Namespace namespace: The result from CLI parsing.
+        :param namespace: The result from CLI parsing.
+        :type namespace: argparse.Namespace
 
         :returns: An auth plugin, or None if a name is not provided.
+        :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
         """
         for opt in cls.get_options():
             val = getattr(namespace, 'os_%s' % opt.dest)
@@ -218,7 +222,8 @@ class BaseAuthPlugin(object):
     def register_conf_options(cls, conf, group):
         """Register the oslo.config options that are needed for a plugin.
 
-        :param conf: An oslo.config conf object.
+        :param conf: A config object.
+        :type conf: oslo.config.cfg.ConfigOpts
         :param string group: The group name that options should be read from.
         """
         plugin_opts = cls.get_options()
@@ -230,11 +235,12 @@ class BaseAuthPlugin(object):
 
         Convert the options already registered into a real plugin.
 
-        :param conf: An oslo.config conf object.
+        :param conf: A config object.
+        :type conf: oslo.config.cfg.ConfigOpts
         :param string group: The group name that options should be read from.
 
         :returns: An authentication Plugin.
-        :rtype: plugin:
+        :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
         """
         plugin_opts = cls.get_options()
 
diff --git a/keystoneclient/auth/cli.py b/keystoneclient/auth/cli.py
index ce4f11f..40a81c1 100644
--- a/keystoneclient/auth/cli.py
+++ b/keystoneclient/auth/cli.py
@@ -30,6 +30,7 @@ def register_argparse_arguments(parser, argv, default=None):
                               if one isn't specified by the CLI. default: None.
 
     :returns: The plugin class that will be loaded or None if not provided.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
@@ -68,6 +69,7 @@ def load_from_argparse_arguments(namespace, **kwargs):
     :param Namespace namespace: The result from CLI parsing.
 
     :returns: An auth plugin, or None if a name is not provided.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
diff --git a/keystoneclient/auth/conf.py b/keystoneclient/auth/conf.py
index 0b68184..fdd2aa4 100644
--- a/keystoneclient/auth/conf.py
+++ b/keystoneclient/auth/conf.py
@@ -60,7 +60,8 @@ def register_conf_options(conf, group):
          taken. If section is not provided then the auth plugin options will be
          taken from the same group as provided in the parameters.
 
-    :param oslo.config.Cfg conf: config object to register with.
+    :param conf: config object to register with.
+    :type conf: oslo.config.cfg.ConfigOpts
     :param string group: The ini group to register options in.
     """
     conf.register_opt(_AUTH_SECTION_OPT, group=group)
@@ -85,11 +86,12 @@ def load_from_conf_options(conf, group, **kwargs):
     The base options should have been registered with register_conf_options
     before this function is called.
 
-    :param conf: An oslo.config conf object.
+    :param conf: A conf object.
+    :type conf: oslo.config.cfg.ConfigOpts
     :param string group: The group name that options should be read from.
 
     :returns: An authentication Plugin or None if a name is not provided
-    :rtype: plugin
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :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 610039a..ad8adb0 100644
--- a/keystoneclient/auth/identity/base.py
+++ b/keystoneclient/auth/identity/base.py
@@ -74,6 +74,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         when invoked. If you are looking to just retrieve the current auth
         data then you should use get_access.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.InvalidResponse: The response
                                                            returned wasn't
                                                            appropriate.
@@ -89,6 +92,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
 
         If a valid token is not present then a new one will be fetched.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
@@ -125,6 +131,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         If a valid AccessInfo is present then it is returned otherwise a new
         one will be fetched.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
@@ -164,6 +173,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         If a valid token is not present then a new one will be fetched using
         the session and kwargs.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
         :param string service_type: The type of service to lookup the endpoint
                                     for. This plugin will return None (failure)
                                     if service_type is not provided.
@@ -253,7 +264,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         This function is expected to be used by subclasses and should not
         be needed by users.
 
-        :param Session session: A session object to discover with.
+        :param session: A session object to discover with.
+        :type session: keystoneclient.session.Session
         :param str url: The url to lookup.
         :param bool authenticated: Include a token in the discovery call.
                                    (optional) Defaults to None (use a token
diff --git a/keystoneclient/auth/identity/generic/base.py b/keystoneclient/auth/identity/generic/base.py
index 4fa3c9c..7c5a80f 100644
--- a/keystoneclient/auth/identity/generic/base.py
+++ b/keystoneclient/auth/identity/generic/base.py
@@ -81,7 +81,8 @@ class BaseGenericPlugin(base.BaseIdentityPlugin):
         params then it should return it. If not return None and then another
         call will be made with other available URLs.
 
-        :param Session session: A session object.
+        :param session: A session object.
+        :type session: keystoneclient.session.Session
         :param tuple version: A tuple of the API version at the URL.
         :param string url: The base URL for this version.
         :param string raw_status: The status that was in the discovery field.
diff --git a/keystoneclient/auth/identity/v3.py b/keystoneclient/auth/identity/v3.py
index 8f723ff..cc3a62c 100644
--- a/keystoneclient/auth/identity/v3.py
+++ b/keystoneclient/auth/identity/v3.py
@@ -176,7 +176,8 @@ class AuthMethod(object):
     def get_auth_data(self, session, auth, headers, **kwargs):
         """Return the authentication section of an auth plugin.
 
-        :param Session session: The communication session.
+        :param session: The communication session.
+        :type session: keystoneclient.session.Session
         :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.
diff --git a/keystoneclient/client.py b/keystoneclient/client.py
index 8b6a6b0..8de2963 100644
--- a/keystoneclient/client.py
+++ b/keystoneclient/client.py
@@ -28,9 +28,10 @@ def Client(version=None, unstable=False, session=None, **kwargs):
                           at least the specified minor version. For example to
                           specify the 3.1 API use (3, 1).
     :param bool unstable: Accept endpoints not marked as 'stable'. (optional)
-    :param Session session: A session object to be used for communication. If
-                            one is not provided it will be constructed from the
-                            provided kwargs. (optional)
+    :param session: A session object to be used for communication. If one is
+                    not provided it will be constructed from the provided
+                    kwargs. (optional)
+    :type session: keystoneclient.session.Session
     :param kwargs: Additional arguments are passed through to the client
                    that is being created.
     :returns: New keystone client object