Improve docs for v3 users

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

Change-Id: I8f725ca8071e592fdf932bf83f72eaebf588bb6b

1 files changed, 122 insertions, 16 deletions

diff --git a/keystoneclient/v3/users.py b/keystoneclient/v3/users.py
index 89c529d..21243b8 100644
--- a/keystoneclient/v3/users.py
+++ b/keystoneclient/v3/users.py
@@ -55,13 +55,33 @@ class UserManager(base.CrudManager):
                default_project=None, **kwargs):
         """Create a user.
 
+        :param str name: the name of the user.
+        :param domain: the domain of the user.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param project: the default project of the user.
+                        (deprecated, see warning below)
+        :type project: str or :class:`keystoneclient.v3.projects.Project`
+        :param str password: the password for the user.
+        :param str email: the email address of the user.
+        :param str description: a description of the user.
+        :param bool enabled: whether the user is enabled.
+        :param default_project: the default project of the user.
+        :type default_project: str or
+                               :class:`keystoneclient.v3.projects.Project`
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created user returned from server.
+        :rtype: :class:`keystoneclient.v3.users.User`
+
         .. warning::
 
-            The project argument is deprecated as of the 1.7.0 release in favor
-            of default_project and may be removed in the 2.0.0 release.
+          The project argument is deprecated as of the 1.7.0 release in favor
+          of default_project and may be removed in the 2.0.0 release.
+
+          If both default_project and project is provided, the default_project
+          will be used.
 
-        If both default_project and project is provided, the default_project
-        will be used.
         """
         default_project_id = base.getid(default_project) or base.getid(project)
         user_data = base.filter_none(name=name,
@@ -83,19 +103,30 @@ class UserManager(base.CrudManager):
              **kwargs):
         """List users.
 
-        If project, domain or group are provided, then filter
-        users with those attributes.
-
-        If ``**kwargs`` are provided, then filter users with
-        attributes matching ``**kwargs``.
+        :param project: the default project of the users to be filtered on.
+                        (deprecated, see warning below)
+        :type project: str or :class:`keystoneclient.v3.projects.Project`
+        :param domain: the domain of the users to be filtered on.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param group: the group in which the users are member of.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+        :param default_project: the default project of the users to be filtered
+                                on.
+        :type default_project: str or
+                               :class:`keystoneclient.v3.projects.Project`
+        :param kwargs: any other attribute provided will filter users on.
+
+        :returns: a list of users.
+        :rtype: list of :class:`keystoneclient.v3.users.User`.
 
         .. warning::
 
           The project argument is deprecated as of the 1.7.0 release in favor
           of default_project and may be removed in the 2.0.0 release.
 
-        If both default_project and project is provided, the default_project
-        will be used.
+          If both default_project and project is provided, the default_project
+          will be used.
+
         """
         default_project_id = base.getid(default_project) or base.getid(project)
         if group:
@@ -110,6 +141,15 @@ class UserManager(base.CrudManager):
             **kwargs)
 
     def get(self, user):
+        """Retrieve a user.
+
+        :param user: the user to be retrieved from the server.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+
+        :returns: the specified user returned from server.
+        :rtype: :class:`keystoneclient.v3.users.User`
+
+        """
         return super(UserManager, self).get(
             user_id=base.getid(user))
 
@@ -121,13 +161,34 @@ class UserManager(base.CrudManager):
                default_project=None, **kwargs):
         """Update a user.
 
+        :param user: the user to be updated on the server.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param str name: the new name of the user.
+        :param domain: the new domain of the user.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param project: the new default project of the user.
+                        (deprecated, see warning below)
+        :type project: str or :class:`keystoneclient.v3.projects.Project`
+        :param str password: the new password of the user.
+        :param str email: the new email of the user.
+        :param str description: the newdescription of the user.
+        :param bool enabled: whether the user is enabled.
+        :param default_project: the new default project of the user.
+        :type default_project: str or
+                               :class:`keystoneclient.v3.projects.Project`
+        :param kwargs: any other attribute provided will be passed to server.
+
+        :returns: the updated user returned from server.
+        :rtype: :class:`keystoneclient.v3.users.User`
+
         .. warning::
 
-            The project argument is deprecated as of the 1.7.0 release in favor
-            of default_project and may be removed in the 2.0.0 release.
+          The project argument is deprecated as of the 1.7.0 release in favor
+          of default_project and may be removed in the 2.0.0 release.
+
+          If both default_project and project is provided, the default_project
+          will be used.
 
-        If both default_project and project is provided, the default_project
-        will be used.
         """
         default_project_id = base.getid(default_project) or base.getid(project)
         user_data = base.filter_none(name=name,
@@ -146,7 +207,14 @@ class UserManager(base.CrudManager):
                             log=False)
 
     def update_password(self, old_password, new_password):
-        """Update the password for the user the token belongs to."""
+        """Update the password for the user the token belongs to.
+
+        :param str old_password: the user's old password
+        :param str new_password: the user's new password
+
+        :returns: 204 No Content.
+
+        """
         if not (old_password and new_password):
             msg = _('Specify both the current password and a new password')
             raise exceptions.ValidationError(msg)
@@ -163,6 +231,16 @@ class UserManager(base.CrudManager):
         return self._update(base_url, params, method='POST', log=False)
 
     def add_to_group(self, user, group):
+        """Add the specified user as a member of the specified group.
+
+        :param user: the user to be added to the group.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param group: the group to put the user in.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+
+        :returns: 204 No Content.
+
+        """
         self._require_user_and_group(user, group)
 
         base_url = '/groups/%s' % base.getid(group)
@@ -171,6 +249,16 @@ class UserManager(base.CrudManager):
             user_id=base.getid(user))
 
     def check_in_group(self, user, group):
+        """Check if the specified user is a member of the specified group.
+
+        :param user: the user to be verified in the group.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param group: the group to check the user in.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+
+        :returns: 204 No Content.
+
+        """
         self._require_user_and_group(user, group)
 
         base_url = '/groups/%s' % base.getid(group)
@@ -179,6 +267,16 @@ class UserManager(base.CrudManager):
             user_id=base.getid(user))
 
     def remove_from_group(self, user, group):
+        """Remove the specified user from the specified group.
+
+        :param user: the user to be removed from the group.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param group: the group to remove the user from.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+
+        :returns: 204 No Content.
+
+        """
         self._require_user_and_group(user, group)
 
         base_url = '/groups/%s' % base.getid(group)
@@ -187,5 +285,13 @@ class UserManager(base.CrudManager):
             user_id=base.getid(user))
 
     def delete(self, user):
+        """Delete a user.
+
+        :param user: the user to be deleted on the server.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+
+        :returns: 204 No Content.
+
+        """
         return super(UserManager, self).delete(
             user_id=base.getid(user))