From 79db63ef1166afb2df2d08a6df0055d4eaaa7e48 Mon Sep 17 00:00:00 2001
From: Nisha Yadav <ynisha11@gmail.com>
Date: Mon, 20 Jun 2016 16:53:08 +0530
Subject: [PATCH] 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 | 49 +++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/keystoneclient/v3/domains.py b/keystoneclient/v3/domains.py
index 466343f8b..b7f5a5a16 100644
--- a/keystoneclient/v3/domains.py
+++ b/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))