Add docstring for create/update methods([a-f]*)

As we discussed on
http://lists.openstack.org/pipermail/openstack-dev/2015-July/068864.html
we need to write docstring for http POST/PUT methods.
This patch adds docstring for create/update methods of compute client
[a-f]*. In addition, this patch fixes some inconsistencies like "Creates"
is changed to "Create".

Change-Id: Ibb395364ee60c3a72daecb2b65d6525d19f28e7d

6 files changed, 67 insertions, 25 deletions

diff --git a/tempest_lib/services/compute/agents_client.py b/tempest_lib/services/compute/agents_client.py
index 8d4b2eb..a2b80c5 100644
--- a/tempest_lib/services/compute/agents_client.py
+++ b/tempest_lib/services/compute/agents_client.py
@@ -33,7 +33,11 @@ class AgentsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def create_agent(self, **kwargs):
-        """Create an agent build."""
+        """Create an agent build.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#agentbuild
+        """
         post_body = json.dumps({'agent': kwargs})
         resp, body = self.post('os-agents', post_body)
         body = json.loads(body)
@@ -47,7 +51,11 @@ class AgentsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def update_agent(self, agent_id, **kwargs):
-        """Update an agent build."""
+        """Update an agent build.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#updatebuild
+        """
         put_body = json.dumps({'para': kwargs})
         resp, body = self.put('os-agents/%s' % agent_id, put_body)
         body = json.loads(body)
diff --git a/tempest_lib/services/compute/aggregates_client.py b/tempest_lib/services/compute/aggregates_client.py
index 5edcd60..75489fe 100644
--- a/tempest_lib/services/compute/aggregates_client.py
+++ b/tempest_lib/services/compute/aggregates_client.py
@@ -37,7 +37,11 @@ class AggregatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def create_aggregate(self, **kwargs):
-        """Creates a new aggregate."""
+        """Create a new aggregate.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#createaggregate
+        """
         post_body = json.dumps({'aggregate': kwargs})
         resp, body = self.post('os-aggregates', post_body)
 
@@ -46,7 +50,11 @@ class AggregatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def update_aggregate(self, aggregate_id, **kwargs):
-        """Update a aggregate."""
+        """Update an aggregate.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#updateaggregate
+        """
         put_body = json.dumps({'aggregate': kwargs})
         resp, body = self.put('os-aggregates/%s' % aggregate_id, put_body)
 
@@ -55,7 +63,7 @@ class AggregatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def delete_aggregate(self, aggregate_id):
-        """Deletes the given aggregate."""
+        """Delete the given aggregate."""
         resp, body = self.delete("os-aggregates/%s" % aggregate_id)
         self.validate_response(schema.delete_aggregate, resp, body)
         return rest_client.ResponseBody(resp, body)
@@ -69,11 +77,15 @@ class AggregatesClient(rest_client.RestClient):
 
     @property
     def resource_type(self):
-        """Returns the primary type of resource this client works with."""
+        """Return the primary type of resource this client works with."""
         return 'aggregate'
 
     def add_host(self, aggregate_id, **kwargs):
-        """Adds a host to the given aggregate."""
+        """Add a host to the given aggregate.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#addhost
+        """
         post_body = json.dumps({'add_host': kwargs})
         resp, body = self.post('os-aggregates/%s/action' % aggregate_id,
                                post_body)
@@ -82,7 +94,15 @@ class AggregatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def remove_host(self, aggregate_id, **kwargs):
-        """Removes a host from the given aggregate."""
+        """Remove a host from the given aggregate.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#removeaggregate
+        """
+        # TODO(oomichi): We can see the API doc of the above method with
+        # the above link, but the link is wrong because the link is not for
+        # host api. That is api-site problem. After fixing api-site, we will
+        # fix the above link also.
         post_body = json.dumps({'remove_host': kwargs})
         resp, body = self.post('os-aggregates/%s/action' % aggregate_id,
                                post_body)
@@ -91,7 +111,7 @@ class AggregatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def set_metadata(self, aggregate_id, **kwargs):
-        """Replaces the aggregate's existing metadata with new metadata."""
+        """Replace the aggregate's existing metadata with new metadata."""
         post_body = json.dumps({'set_metadata': kwargs})
         resp, body = self.post('os-aggregates/%s/action' % aggregate_id,
                                post_body)
diff --git a/tempest_lib/services/compute/baremetal_nodes_client.py b/tempest_lib/services/compute/baremetal_nodes_client.py
index 4434698..b0c1849 100644
--- a/tempest_lib/services/compute/baremetal_nodes_client.py
+++ b/tempest_lib/services/compute/baremetal_nodes_client.py
@@ -34,7 +34,7 @@ class BaremetalNodesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def show_baremetal_node(self, baremetal_node_id):
-        """Returns the details of a single baremetal node."""
+        """Return the details of a single baremetal node."""
         url = 'os-baremetal-nodes/%s' % baremetal_node_id
         resp, body = self.get(url)
         body = json.loads(body)
diff --git a/tempest_lib/services/compute/certificates_client.py b/tempest_lib/services/compute/certificates_client.py
index a1e0c2b..546e53c 100644
--- a/tempest_lib/services/compute/certificates_client.py
+++ b/tempest_lib/services/compute/certificates_client.py
@@ -29,7 +29,7 @@ class CertificatesClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def create_certificate(self):
-        """create certificates."""
+        """Create a certificate."""
         url = "os-certificates"
         resp, body = self.post(url, None)
         body = json.loads(body)
diff --git a/tempest_lib/services/compute/fixed_ips_client.py b/tempest_lib/services/compute/fixed_ips_client.py
index 3804b8a..1b4afb7 100644
--- a/tempest_lib/services/compute/fixed_ips_client.py
+++ b/tempest_lib/services/compute/fixed_ips_client.py
@@ -29,7 +29,11 @@ class FixedIPsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def reserve_fixed_ip(self, fixed_ip, **kwargs):
-        """This reserves and unreserves fixed ips."""
+        """Reserve/Unreserve a fixed IP.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#reserveIP
+        """
         url = "os-fixed-ips/%s/action" % fixed_ip
         resp, body = self.post(url, json.dumps(kwargs))
         self.validate_response(schema.reserve_unreserve_fixed_ip, resp, body)
diff --git a/tempest_lib/services/compute/flavors_client.py b/tempest_lib/services/compute/flavors_client.py
index 98daecc..a5a05d9 100644
--- a/tempest_lib/services/compute/flavors_client.py
+++ b/tempest_lib/services/compute/flavors_client.py
@@ -48,12 +48,10 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def create_flavor(self, **kwargs):
-        """Creates a new flavor or instance type.
+        """Create a new flavor or instance type.
 
-        Most parameters except the following are passed to the API without
-        any changes.
-        :param ephemeral: The name is changed to OS-FLV-EXT-DATA:ephemeral
-        :param is_public: The name is changed to os-flavor-access:is_public
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#create-flavors
         """
         if kwargs.get('ephemeral'):
             kwargs['OS-FLV-EXT-DATA:ephemeral'] = kwargs.pop('ephemeral')
@@ -68,7 +66,7 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def delete_flavor(self, flavor_id):
-        """Deletes the given flavor."""
+        """Delete the given flavor."""
         resp, body = self.delete("flavors/{0}".format(flavor_id))
         self.validate_response(schema.delete_flavor, resp, body)
         return rest_client.ResponseBody(resp, body)
@@ -85,11 +83,19 @@ class FlavorsClient(rest_client.RestClient):
 
     @property
     def resource_type(self):
-        """Returns the primary type of resource this client works with."""
+        """Return the primary type of resource this client works with."""
         return 'flavor'
 
     def set_flavor_extra_spec(self, flavor_id, **kwargs):
-        """Sets extra Specs to the mentioned flavor."""
+        """Set extra Specs to the mentioned flavor.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#updateflavor
+        """
+        # TODO(oomichi): We can see the API doc of the above method with
+        # the above link, but the link is wrong because the link is not for
+        # flavor-extraspac api. That is api-site problem.
+        # After fixing api-site, we will fix the above link also.
         post_body = json.dumps({'extra_specs': kwargs})
         resp, body = self.post('flavors/%s/os-extra_specs' % flavor_id,
                                post_body)
@@ -99,7 +105,7 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def list_flavor_extra_specs(self, flavor_id):
-        """Gets extra Specs details of the mentioned flavor."""
+        """Get extra Specs details of the mentioned flavor."""
         resp, body = self.get('flavors/%s/os-extra_specs' % flavor_id)
         body = json.loads(body)
         self.validate_response(schema_extra_specs.set_get_flavor_extra_specs,
@@ -107,7 +113,7 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def show_flavor_extra_spec(self, flavor_id, key):
-        """Gets extra Specs key-value of the mentioned flavor and key."""
+        """Get extra Specs key-value of the mentioned flavor and key."""
         resp, body = self.get('flavors/%s/os-extra_specs/%s' % (flavor_id,
                               key))
         body = json.loads(body)
@@ -117,7 +123,11 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def update_flavor_extra_spec(self, flavor_id, key, **kwargs):
-        """Update specified extra Specs of the mentioned flavor and key."""
+        """Update specified extra Specs of the mentioned flavor and key.
+
+        Available params: see http://developer.openstack.org/
+                              api-ref-compute-v2.1.html#updateflavorspec
+        """
         resp, body = self.put('flavors/%s/os-extra_specs/%s' %
                               (flavor_id, key), json.dumps(kwargs))
         body = json.loads(body)
@@ -127,14 +137,14 @@ class FlavorsClient(rest_client.RestClient):
         return rest_client.ResponseBody(resp, body)
 
     def unset_flavor_extra_spec(self, flavor_id, key):
-        """Unsets extra Specs from the mentioned flavor."""
+        """Unset extra Specs from the mentioned flavor."""
         resp, body = self.delete('flavors/%s/os-extra_specs/%s' %
                                  (flavor_id, key))
         self.validate_response(schema.unset_flavor_extra_specs, resp, body)
         return rest_client.ResponseBody(resp, body)
 
     def list_flavor_access(self, flavor_id):
-        """Gets flavor access information given the flavor id."""
+        """Get flavor access information given the flavor id."""
         resp, body = self.get('flavors/%s/os-flavor-access' % flavor_id)
         body = json.loads(body)
         self.validate_response(schema_access.add_remove_list_flavor_access,