Improve docs for v3 ec2

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

Change-Id: I57bf96a60baed3a9420879f4f897e73a40ff102a
Partial-Bug: #1330769

1 files changed, 53 insertions, 12 deletions

diff --git a/keystoneclient/v3/ec2.py b/keystoneclient/v3/ec2.py
index 038406b..06fac20 100644
--- a/keystoneclient/v3/ec2.py
+++ b/keystoneclient/v3/ec2.py
@@ -14,6 +14,14 @@ from keystoneclient import base
 
 
 class EC2(base.Resource):
+    """Represents an EC2 resource.
+
+    Attributes:
+        * id: a string that identifies the EC2 resource.
+        * user_id: the ID field of a pre-existing user in the backend.
+        * project_id: the ID field of a pre-existing project in the backend.
+
+    """
 
     def __repr__(self):
         """Return string representation of EC2 resource information."""
@@ -25,9 +33,16 @@ class EC2Manager(base.ManagerWithFind):
     resource_class = EC2
 
     def create(self, user_id, project_id):
-        """Create a new access/secret pair for the user/project pair.
+        """Create a new access/secret pair.
+
+        :param user_id: the ID of the user having access/secret pair.
+        :type user_id: str or :class:`keystoneclient.v3.users.User`
+        :param project_id: the ID of the project having access/secret pair.
+        :type project_id: str or :class:`keystoneclient.v3.projects.Project`
+
+        :returns: the created access/secret pair returned from server.
+        :rtype: :class:`keystoneclient.v3.ec2.EC2`
 
-        :rtype: object of type :class:`EC2`
         """
         # NOTE(jamielennox): Yes, this uses tenant_id as a key even though we
         # are in the v3 API.
@@ -35,23 +50,49 @@ class EC2Manager(base.ManagerWithFind):
                           body={'tenant_id': project_id},
                           response_key="credential")
 
-    def list(self, user_id):
-        """Get a list of access/secret pairs for a user_id.
+    def get(self, user_id, access):
+        """Retrieve an access/secret pair for a given access key.
 
-        :rtype: list of :class:`EC2`
-        """
-        return self._list("/users/%s/credentials/OS-EC2" % user_id,
-                          response_key="credentials")
+        :param user_id: the ID of the user whose access/secret pair will be
+                        retrieved from the server.
+        :type user_id: str or :class:`keystoneclient.v3.users.User`
+        :param access: the access key whose access/secret pair will be
+                       retrieved from the server.
+        :type access: str or :class:`keystoneclient.v3.ec2.EC2`
 
-    def get(self, user_id, access):
-        """Get the access/secret pair for a given access key.
+        :returns: the specified access/secret pair returned from server.
+        :rtype: :class:`keystoneclient.v3.ec2.EC2`
 
-        :rtype: object of type :class:`EC2`
         """
         url = "/users/%s/credentials/OS-EC2/%s" % (user_id, base.getid(access))
         return self._get(url, response_key="credential")
 
+    def list(self, user_id):
+        """List access/secret pairs for a given user.
+
+        :param str user_id: the ID of the user having access/secret pairs will
+                            be listed.
+
+        :returns: a list of access/secret pairs.
+        :rtype: list of :class:`keystoneclient.v3.ec2.EC2`
+
+        """
+        return self._list("/users/%s/credentials/OS-EC2" % user_id,
+                          response_key="credentials")
+
     def delete(self, user_id, access):
-        """Delete an access/secret pair for a user."""
+        """Delete an access/secret pair.
+
+        :param user_id: the ID of the user whose access/secret pair will be
+                        deleted on the server.
+        :type user_id: str or :class:`keystoneclient.v3.users.User`
+        :param access: the access key whose access/secret pair will be deleted
+                       on the server.
+        :type access: str or :class:`keystoneclient.v3.ec2.EC2`
+
+        :returns: Response object with 204 status.
+        :rtype: :class:`requests.models.Response`
+
+        """
         return self._delete("/users/%s/credentials/OS-EC2/%s" %
                             (user_id, base.getid(access)))