From 339cd20ee7df43d802c77eacd8b1bbe2ccb1bf12 Mon Sep 17 00:00:00 2001
From: Nisha Yadav <ynisha11@gmail.com>
Date: Mon, 4 Jul 2016 20:56:39 +0530
Subject: [PATCH] Improve docs for v3 services

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

Change-Id: Ic7aaadcd8f8d5ebdec0cd908e7cbe4f997a17b54
Partial-Bug: #1330769
---
 keystoneclient/v3/services.py | 54 +++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/keystoneclient/v3/services.py b/keystoneclient/v3/services.py
index 02f88e807..04fa537b2 100644
--- a/keystoneclient/v3/services.py
+++ b/keystoneclient/v3/services.py
@@ -43,6 +43,19 @@ class ServiceManager(base.CrudManager):
     @positional(1, enforcement=positional.WARN)
     def create(self, name, type=None,
                enabled=True, description=None, **kwargs):
+        """Create a service.
+
+        :param str name: the name of the service.
+        :param str type: the type of the service.
+        :param bool enabled: whether the service appears in the catalog.
+        :param str description: the description of the service.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created service returned from server.
+        :rtype: :class:`keystoneclient.v3.services.Service`
+
+        """
         type_arg = type or kwargs.pop('service_type', None)
         return super(ServiceManager, self).create(
             name=name,
@@ -52,11 +65,30 @@ class ServiceManager(base.CrudManager):
             **kwargs)
 
     def get(self, service):
+        """Retrieve a service.
+
+        :param service: the service to be retrieved from the server.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+
+        :returns: the specified service returned from server.
+        :rtype: :class:`keystoneclient.v3.services.Service`
+
+        """
         return super(ServiceManager, self).get(
             service_id=base.getid(service))
 
     @positional(enforcement=positional.WARN)
     def list(self, name=None, type=None, **kwargs):
+        """List services.
+
+        :param str name: the name of the services to be filtered on.
+        :param str type: the type of the services to be filtered on.
+        :param kwargs: any other attribute provided will filter services on.
+
+        :returns: a list of services.
+        :rtype: list of :class:`keystoneclient.v3.services.Service`
+
+        """
         type_arg = type or kwargs.pop('service_type', None)
         return super(ServiceManager, self).list(
             name=name,
@@ -66,6 +98,20 @@ class ServiceManager(base.CrudManager):
     @positional(enforcement=positional.WARN)
     def update(self, service, name=None, type=None, enabled=None,
                description=None, **kwargs):
+        """Update a service.
+
+        :param service: the service to be updated on the server.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+        :param str name: the new name of the service.
+        :param str type: the new type of the service.
+        :param bool enabled: whether the service appears in the catalog.
+        :param str description: the new description of the service.
+        :param kwargs: any other attribute provided will be passed to server.
+
+        :returns: the updated service returned from server.
+        :rtype: :class:`keystoneclient.v3.services.Service`
+
+        """
         type_arg = type or kwargs.pop('service_type', None)
         return super(ServiceManager, self).update(
             service_id=base.getid(service),
@@ -76,6 +122,14 @@ class ServiceManager(base.CrudManager):
             **kwargs)
 
     def delete(self, service=None, id=None):
+        """Delete a service.
+
+        :param service: the service to be deleted on the server.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+
+        :returns: Request object with 204 status and None as data.
+
+        """
         if service:
             service_id = base.getid(service)
         else: