Improve docs for v3 domains

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

Change-Id: I78e62fbd877ba32744fa3587ad2eb497bfb79fc2

keystoneclient/v3/domains.py

@@ -39,6 +39,18 @@ class DomainManager(base.CrudManager):
 
     @positional(1, enforcement=positional.WARN)
     def create(self, name, description=None, enabled=True, **kwargs):
+        """Create a domain.
+
+        :param str name: the name of the domain.
+        :param str description: a description of the domain.
+        :param bool enabled: whether the domain is enabled.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created domain returned from server.
+        :rtype: :class:`keystoneclient.v3.domains.Domain`
+
+        """
         return super(DomainManager, self).create(
             name=name,
             description=description,
@@ -46,14 +58,27 @@ class DomainManager(base.CrudManager):
             **kwargs)
 
     def get(self, domain):
+        """Retrieve a domain.
+
+        :param domain: the domain to be retrieved from the server.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+
+        :returns: the specified domain returned from server.
+        :rtype: :class:`keystoneclient.v3.domains.Domain`
+
+        """
         return super(DomainManager, self).get(
             domain_id=base.getid(domain))
 
     def list(self, **kwargs):
         """List domains.
 
-        ``**kwargs`` allows filter criteria to be passed where
+        :param kwargs: allows filter criteria to be passed where
          supported by the server.
+
+        :returns: a list of domains.
+        :rtype: list of :class:`keystoneclient.v3.domains.Domain`.
+
         """
         # Ref bug #1267530 we have to pass 0 for False to get the expected
         # results on all keystone versions
@@ -64,6 +89,20 @@ class DomainManager(base.CrudManager):
     @positional(enforcement=positional.WARN)
     def update(self, domain, name=None,
                description=None, enabled=None, **kwargs):
+        """Update a domain.
+
+        :param domain: the domain to be updated on the server.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+        :param str name: the new name of the domain.
+        :param str description: the new description of the domain.
+        :param bool enabled: whether the domain is enabled.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the updated domain returned from server.
+        :rtype: :class:`keystoneclient.v3.domains.Domain`
+
+        """
         return super(DomainManager, self).update(
             domain_id=base.getid(domain),
             name=name,
@@ -72,5 +111,13 @@ class DomainManager(base.CrudManager):
             **kwargs)
 
     def delete(self, domain):
+        """"Delete a domain.
+
+        :param domain: the domain to be deleted on the server.
+        :type domain: str or :class:`keystoneclient.v3.domains.Domain`
+
+        :returns: 204 No Content.
+
+        """
         return super(DomainManager, self).delete(
             domain_id=base.getid(domain))