From 20ab6961571ab6147fb7b885bf5845ab0b810152 Mon Sep 17 00:00:00 2001
From: Nisha Yadav <ynisha11@gmail.com>
Date: Wed, 6 Jul 2016 00:52:04 +0530
Subject: [PATCH] Improve docs for v3 policies

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

Change-Id: I8fef9c2ec54e38648e1000874c6d2381b6fad576
Partial-Bug: #1330769
---
 keystoneclient/v3/policies.py | 53 ++++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/keystoneclient/v3/policies.py b/keystoneclient/v3/policies.py
index 9ab538756..6eb1aa5c3 100644
--- a/keystoneclient/v3/policies.py
+++ b/keystoneclient/v3/policies.py
@@ -54,31 +54,76 @@ class PolicyManager(base.CrudManager):
 
     @positional(1, enforcement=positional.WARN)
     def create(self, blob, type='application/json', **kwargs):
+        """Create a policy.
+
+        :param str blob: the policy document.
+        :param str type: the mime type of the policy blob.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created policy returned from server.
+        :rtype: :class:`keystoneclient.v3.policies.Policy`
+
+        """
         return super(PolicyManager, self).create(
             blob=blob,
             type=type,
             **kwargs)
 
     def get(self, policy):
+        """Retrieve a policy.
+
+        :param policy: the policy to be retrieved from the server.
+        :type policy: str or :class:`keystoneclient.v3.policies.Policy`
+
+        :returns: the specified policy returned from server.
+        :rtype: :class:`keystoneclient.v3.policies.Policy`
+
+        """
         return super(PolicyManager, self).get(
             policy_id=base.getid(policy))
 
     def list(self, **kwargs):
         """List policies.
 
-        ``**kwargs`` allows filter criteria to be passed where
-         supported by the server.
+        :param kwargs: allows filter criteria to be passed where
+                       supported by the server.
+
+        :returns: a list of policies.
+        :rtype: list of :class:`keystoneclient.v3.policies.Policy`.
+
         """
         return super(PolicyManager, self).list(**kwargs)
 
     @positional(enforcement=positional.WARN)
-    def update(self, entity, blob=None, type=None, **kwargs):
+    def update(self, policy, blob=None, type=None, **kwargs):
+        """Update a policy.
+
+        :param policy: the policy to be updated on the server.
+        :type policy: str or :class:`keystoneclient.v3.policies.Policy`
+        :param str blob: the new policy document.
+        :param str type: the new mime type of the policy blob.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the updated policy returned from server.
+        :rtype: :class:`keystoneclient.v3.policies.Policy`
+
+        """
         return super(PolicyManager, self).update(
-            policy_id=base.getid(entity),
+            policy_id=base.getid(policy),
             blob=blob,
             type=type,
             **kwargs)
 
     def delete(self, policy):
+        """"Delete a policy.
+
+        :param policy: the policy to be deleted on the server.
+        :type policy: str or :class:`keystoneclient.v3.policies.Policy`
+
+        :returns: Request object with 204 status and None as data.
+
+        """
         return super(PolicyManager, self).delete(
             policy_id=base.getid(policy))