Merge "Improve docs for v3 credentials"

1 files changed, 57 insertions, 32 deletions

diff --git a/keystoneclient/v3/credentials.py b/keystoneclient/v3/credentials.py
index d165875..a651a08 100644
--- a/keystoneclient/v3/credentials.py
+++ b/keystoneclient/v3/credentials.py
@@ -26,10 +26,10 @@ class Credential(base.Resource):
 
     Attributes:
         * id: a uuid that identifies the credential
-        * user_id: user ID
-        * type: credential type
-        * blob: credential data
-        * project_id: project ID (optional)
+        * user_id: user ID to which credential belongs
+        * type: the type of credential
+        * blob: the text that represents the credential
+        * project_id: project ID which limits the scope of the credential
 
     """
 
@@ -61,17 +61,24 @@ class CredentialManager(base.CrudManager):
     def create(self, user, type, blob=None, data=None, project=None, **kwargs):
         """Create a credential.
 
-        :param user: User
-        :type user: :class:`keystoneclient.v3.users.User` or str
-        :param str type: credential type, should be either ``ec2`` or ``cert``
-        :param JSON blob: Credential data
+        :param user: the user to which the credential belongs
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param str type: the type of the credential, valid values are:
+                         ``ec2``, ``cert`` or ``totp``
+        :param str blob: the arbitrary blob of the credential data, to be
+                         parsed according to the type
         :param JSON data: Deprecated as of the 1.7.0 release in favor of blob
-                          and may by removed in the 2.0.0 release.
-        :param project: Project, optional
-        :type project: :class:`keystoneclient.v3.projects.Project` or str
-        :param kwargs: Extra attributes passed to create.
-
-        :raises ValueError: if one of ``blob`` or ``data`` is not specified.
+                          and may be removed in the future release.
+        :param project: the project which limits the scope of the credential,
+                        this attribbute is mandatory if the credential type is
+                        ec2
+        :type project: str or :class:`keystoneclient.v3.projects.Project`
+        :param kwargs: any other attribute provided will be passed to the
+                       server
+
+        :returns: the created credential
+        :rtype: :class:`keystoneclient.v3.credentials.Credential`
+        :raises ValueError: if one of ``blob`` or ``data`` is not specified
 
         """
         return super(CredentialManager, self).create(
@@ -82,10 +89,14 @@ class CredentialManager(base.CrudManager):
             **kwargs)
 
     def get(self, credential):
-        """Get a credential.
+        """Retrieve a credential.
+
+        :param credential: the credential to be retrieved from the server
+        :type credential: str or
+                          :class:`keystoneclient.v3.credentials.Credential`
 
-        :param credential: Credential
-        :type credential: :class:`Credential` or str
+        :returns: the specified credential
+        :rtype: :class:`keystoneclient.v3.credentials.Credential`
 
         """
         return super(CredentialManager, self).get(
@@ -94,8 +105,12 @@ class CredentialManager(base.CrudManager):
     def list(self, **kwargs):
         """List credentials.
 
-        If ``**kwargs`` are provided, then filter credentials with
-        attributes matching ``**kwargs``.
+        :param kwargs: If user_id or type is specified then credentials
+                       will be filtered accordingly.
+
+        :returns: a list of credentials
+        :rtype: list of :class:`keystoneclient.v3.credentials.Credential`
+
         """
         return super(CredentialManager, self).list(**kwargs)
 
@@ -106,19 +121,25 @@ class CredentialManager(base.CrudManager):
                project=None, **kwargs):
         """Update a credential.
 
-        :param credential: Credential to update
-        :type credential: :class:`Credential` or str
-        :param user: User
-        :type user: :class:`keystoneclient.v3.users.User` or str
-        :param str type: credential type, should be either ``ec2`` or ``cert``
-        :param JSON blob: Credential data
+        :param credential: the credential to be updated on the server
+        :type credential: str or
+                         :class:`keystoneclient.v3.credentials.Credential`
+        :param user: the new user to which the credential belongs
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param str type: the new type of the credential, valid values are:
+                         ``ec2``, ``cert`` or ``totp``
+        :param str blob: the new blob of the credential data
         :param JSON data: Deprecated as of the 1.7.0 release in favor of blob
-                          and may be removed in the 2.0.0 release.
-        :param project: Project
-        :type project: :class:`keystoneclient.v3.projects.Project` or str
-        :param kwargs: Extra attributes passed to create.
+                          and may be removed in the future release.
+        :param project: the new project which limits the scope of the
+                        credential, this attribute is mandatory if the
+                        credential type is ec2
+        :type project: str or :class:`keystoneclient.v3.projects.Project`
+        :param kwargs: any other attribute provided will be passed to the
+                       server
 
-        :raises ValueError: if one of ``blob`` or ``data`` is not specified.
+        :returns: the updated credential
+        :rtype: :class:`keystoneclient.v3.credentials.Credential`
 
         """
         return super(CredentialManager, self).update(
@@ -132,8 +153,12 @@ class CredentialManager(base.CrudManager):
     def delete(self, credential):
         """Delete a credential.
 
-        :param credential: Credential
-        :type credential: :class:`Credential` or str
+        :param credential: the credential to be deleted
+        :type credential: str or
+                          :class:`keystoneclient.v3.credentials.Credential`
+
+        :returns: response object with 204 status
+        :rtype: :class:`requests.models.Response`
 
         """
         return super(CredentialManager, self).delete(