Merge "Improve docs for v3 groups"

keystoneclient/v3/groups.py

@@ -56,6 +56,19 @@ class GroupManager(base.CrudManager):
 
     @positional(1, enforcement=positional.WARN)
     def create(self, name, domain=None, description=None, **kwargs):
+        """Create a group.
+
+        :param str name: the name of the group.
+        :param domain: the domain of the group.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param str description: a description of the group.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created group returned from server.
+        :rtype: :class:`keystoneclient.v3.groups.Group`
+
+        """
         return super(GroupManager, self).create(
             name=name,
             domain_id=base.getid(domain),
@@ -66,11 +79,15 @@ class GroupManager(base.CrudManager):
     def list(self, user=None, domain=None, **kwargs):
         """List groups.
 
-        If domain or user is provided, then filter groups with
-        that attribute.
+        :param user: the user of the groups to be filtered on.
+        :type user: str or :class:`keystoneclient.v3.users.User`
+        :param domain: the domain of the groups to be filtered on.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param kwargs: any other attribute provided will filter groups on.
+
+        :returns: a list of groups.
+        :rtype: list of :class:`keystoneclient.v3.groups.Group`.
 
-        If ``**kwargs`` are provided, then filter groups with
-        attributes matching ``**kwargs``.
         """
         if user:
             base_url = '/users/%s' % base.getid(user)
@@ -82,11 +99,32 @@ class GroupManager(base.CrudManager):
             **kwargs)
 
     def get(self, group):
+        """Retrieve a group.
+
+        :param group: the group to be retrieved from the server.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+
+        :returns: the specified group returned from server.
+        :rtype: :class:`keystoneclient.v3.groups.Group`
+
+        """
         return super(GroupManager, self).get(
             group_id=base.getid(group))
 
     @positional(enforcement=positional.WARN)
     def update(self, group, name=None, description=None, **kwargs):
+        """Update a group.
+
+        :param group: the group to be updated on the server.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+        :param str name: the new name of the group.
+        :param str description: the new description of the group.
+        :param kwargs: any other attribute provided will be passed to server.
+
+        :returns: the updated group returned from server.
+        :rtype: :class:`keystoneclient.v3.groups.Group`
+
+        """
         return super(GroupManager, self).update(
             group_id=base.getid(group),
             name=name,
@@ -94,5 +132,13 @@ class GroupManager(base.CrudManager):
             **kwargs)
 
     def delete(self, group):
+        """Delete a group.
+
+        :param group: the group to be deleted on the server.
+        :type group: str or :class:`keystoneclient.v3.groups.Group`
+
+        :returns: 204 No Content.
+
+        """
         return super(GroupManager, self).delete(
             group_id=base.getid(group))