Improve docs for v3 credentials

In preparation to add functional tests for v3 credentials, this
change proposes to detail the method docs, because the tests
need to be based on them.

Change-Id: Iaabf78b9b1c5e46e5812f6cf6b7896c45675be2e
Partial-Bug: #1330769

keystoneclient/v3/credentials.py

@@ -26,10 +26,10 @@ class Credential(base.Resource):
 
     Attributes:
         * id: a uuid that identifies the credential
-        * user_id: user ID
+        * user_id: user ID to which credential belongs
-        * type: credential type
+        * type: the type of credential
-        * blob: credential data
+        * blob: the text that represents the credential
-        * project_id: project ID (optional)
+        * 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
+        :param user: the user to which the credential belongs
-        :type user: :class:`keystoneclient.v3.users.User` or str
+        :type user: str or :class:`keystoneclient.v3.users.User`
-        :param str type: credential type, should be either ``ec2`` or ``cert``
+        :param str type: the type of the credential, valid values are:
-        :param JSON blob: Credential data
+                         ``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.
+                          and may be removed in the future release.
-        :param project: Project, optional
+        :param project: the project which limits the scope of the credential,
-        :type project: :class:`keystoneclient.v3.projects.Project` or str
+                        this attribbute is mandatory if the credential type is
-        :param kwargs: Extra attributes passed to create.
+                        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 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: Credential
+        :param credential: the credential to be retrieved from the server
-        :type credential: :class:`Credential` or str
+        :type credential: str or
+                          :class:`keystoneclient.v3.credentials.Credential`
+
+        :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
+        :param kwargs: If user_id or type is specified then credentials
-        attributes matching ``**kwargs``.
+                       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
+        :param credential: the credential to be updated on the server
-        :type credential: :class:`Credential` or str
+        :type credential: str or
-        :param user: User
+                         :class:`keystoneclient.v3.credentials.Credential`
-        :type user: :class:`keystoneclient.v3.users.User` or str
+        :param user: the new user to which the credential belongs
-        :param str type: credential type, should be either ``ec2`` or ``cert``
+        :type user: str or :class:`keystoneclient.v3.users.User`
-        :param JSON blob: Credential data
+        :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.
+                          and may be removed in the future release.
-        :param project: Project
+        :param project: the new project which limits the scope of the
-        :type project: :class:`keystoneclient.v3.projects.Project` or str
+                        credential, this attribute is mandatory if the
-        :param kwargs: Extra attributes passed to create.
+                        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
+        :param credential: the credential to be deleted
-        :type credential: :class:`Credential` or str
+        :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(