Update stack_id clearify for heat client functions

most of our client major function require stack_id. We should
provide more specific information (at lest in function description)
to clearify that it's allowed to feed in stack name to `stack_id`
too. For example, both `heat.stacks.get($Stack_UUID)` and
`heat.stacks.get($Stack_Name)` works.

Change-Id: I4428097140e0391a77679f5c69e00966f249efd7

3 files changed, 34 insertions, 16 deletions

diff --git a/heatclient/v1/events.py b/heatclient/v1/events.py
index 651ce9f..f86549d 100644
--- a/heatclient/v1/events.py
+++ b/heatclient/v1/events.py
@@ -44,7 +44,7 @@ class EventManager(stacks.StackChildManager):
     def list(self, stack_id, resource_name=None, **kwargs):
         """Get a list of events.
 
-        :param stack_id: ID of stack the events belong to
+        :param stack_id: ID or name of stack the events belong to
         :param resource_name: Optional name of resources to filter events by
         :rtype: list of :class:`Event`
         """
@@ -74,7 +74,7 @@ class EventManager(stacks.StackChildManager):
     def get(self, stack_id, resource_name, event_id):
         """Get the details for a specific event.
 
-        :param stack_id: ID of stack containing the event
+        :param stack_id: ID or name of stack containing the event
         :param resource_name: ID of resource the event belongs to
         :param event_id: ID of event to get the details for
         """
diff --git a/heatclient/v1/resources.py b/heatclient/v1/resources.py
index b82b778..cfb3203 100644
--- a/heatclient/v1/resources.py
+++ b/heatclient/v1/resources.py
@@ -72,7 +72,7 @@ class ResourceManager(stacks.StackChildManager):
     def get(self, stack_id, resource_name, with_attr=None):
         """Get the details for a specific resource.
 
-        :param stack_id: ID of stack containing the resource
+        :param stack_id: ID or name of stack containing the resource
         :param resource_name: ID of resource to get the details for
         :param with_attr: Attributes to show
         """
@@ -91,7 +91,7 @@ class ResourceManager(stacks.StackChildManager):
     def metadata(self, stack_id, resource_name):
         """Get the metadata for a specific resource.
 
-        :param stack_id: ID of stack containing the resource
+        :param stack_id: ID or name of stack containing the resource
         :param resource_name: ID of resource to get metadata for
         """
         stack_id = self._resolve_stack_id(stack_id)
@@ -105,7 +105,7 @@ class ResourceManager(stacks.StackChildManager):
     def signal(self, stack_id, resource_name, data=None):
         """Signal a specific resource.
 
-        :param stack_id: ID of stack containing the resource
+        :param stack_id: ID or name of stack containing the resource
         :param resource_name: ID of resource to send signal to
         """
         stack_id = self._resolve_stack_id(stack_id)
@@ -120,7 +120,7 @@ class ResourceManager(stacks.StackChildManager):
                        mark_unhealthy, resource_status_reason):
         """Mark a resource as healthy or unhealthy.
 
-        :param stack_id: ID of stack containing the resource
+        :param stack_id: ID or name of stack containing the resource
         :param resource_name: ID of resource
         :param mark_unhealthy: Mark resource unhealthy if set to True
         :param resource_status_reason: Reason for resource status change.
diff --git a/heatclient/v1/stacks.py b/heatclient/v1/stacks.py
index 2484ff4..d1acfa5 100644
--- a/heatclient/v1/stacks.py
+++ b/heatclient/v1/stacks.py
@@ -173,7 +173,10 @@ class StackManager(StackChildManager):
         return body
 
     def update(self, stack_id, **kwargs):
-        """Update a stack."""
+        """Update a stack.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         headers = self.client.credentials_headers()
         if kwargs.pop('existing', None):
             self.client.patch('/stacks/%s' % stack_id, data=kwargs,
@@ -183,7 +186,10 @@ class StackManager(StackChildManager):
                             headers=headers)
 
     def preview_update(self, stack_id, **kwargs):
-        """Preview a stack update."""
+        """Preview a stack update.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         stack_identifier = self._resolve_stack_id(stack_id)
         headers = self.client.credentials_headers()
         path = '/stacks/%s/preview' % stack_identifier
@@ -197,25 +203,37 @@ class StackManager(StackChildManager):
         return body
 
     def delete(self, stack_id):
-        """Delete a stack."""
+        """Delete a stack.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         self._delete("/stacks/%s" % stack_id)
 
     def abandon(self, stack_id):
-        """Abandon a stack."""
+        """Abandon a stack.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         stack_identifier = self._resolve_stack_id(stack_id)
         resp = self.client.delete('/stacks/%s/abandon' % stack_identifier)
         body = utils.get_response_body(resp)
         return body
 
     def export(self, stack_id):
-        """Export data of a stack."""
+        """Export data of a stack.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         stack_identifier = self._resolve_stack_id(stack_id)
         resp = self.client.get('/stacks/%s/export' % stack_identifier)
         body = utils.get_response_body(resp)
         return body
 
     def snapshot(self, stack_id, name=None):
-        """Snapshot a stack."""
+        """Snapshot a stack.
+
+        :param stack_id: Stack name or ID to identifies the stack
+        """
         stack_identifier = self._resolve_stack_id(stack_id)
         data = {}
         if name:
@@ -270,7 +288,7 @@ class StackManager(StackChildManager):
     def get(self, stack_id, resolve_outputs=True):
         """Get the metadata for a specific stack.
 
-        :param stack_id: Stack ID to lookup
+        :param stack_id: Stack ID or name to lookup
         :param resolve_outputs: If True, then outputs for this
                stack will be resolved
         """
@@ -284,7 +302,7 @@ class StackManager(StackChildManager):
     def template(self, stack_id):
         """Get template content for a specific stack as a parsed JSON object.
 
-        :param stack_id: Stack ID to get the template for
+        :param stack_id: Stack ID or name to get the template for
         """
         resp = self.client.get('/stacks/%s/template' % stack_id)
         body = utils.get_response_body(resp)
@@ -293,7 +311,7 @@ class StackManager(StackChildManager):
     def environment(self, stack_id):
         """Returns the environment for an existing stack.
 
-        :param stack_id: identifies the stack
+        :param stack_id: Stack name or ID to identifies the stack
         :return:
         """
         resp = self.client.get('/stacks/%s/environment' % stack_id)
@@ -303,7 +321,7 @@ class StackManager(StackChildManager):
     def files(self, stack_id):
         """Returns the files for an existing stack.
 
-        :param stack_id: identifies the stack
+        :param stack_id: Stack name or ID to identifies the stack.
         :return:
         """
         resp = self.client.get('/stacks/%s/files' % stack_id)