From 388ee0257fa166ad84ffce7abaf38086eea8cf5b Mon Sep 17 00:00:00 2001
From: Zane Bitter <zbitter@redhat.com>
Date: Tue, 10 Nov 2015 11:12:36 -0500
Subject: [PATCH] Fix garbled docstrings

The process of bringing us into compliance with the H405 pep8 rule has left
us with a lot of docstrings that either don't follow the recommendations of
PEP0257, are misleading, wrong, or nonsensical. This patch attempts to fix
them up.

Change-Id: Icfe90b5ba3102a7e13ab659038a8b2af9019e9e6
---
 heat/engine/dependencies.py        | 10 ++++----
 heat/engine/environment.py         | 15 ++++++------
 heat/engine/event.py               |  7 +++---
 heat/engine/function.py            | 12 ++++++---
 heat/engine/lifecycle_plugin.py    |  2 +-
 heat/engine/parameter_groups.py    |  6 ++---
 heat/engine/parameters.py          | 15 ++++++------
 heat/engine/properties.py          |  9 ++++---
 heat/engine/resource.py            | 39 +++++++++++++++---------------
 heat/engine/rsrc_defn.py           |  7 ++----
 heat/engine/scheduler.py           | 26 ++++++++++----------
 heat/engine/service.py             | 34 ++++++++++++++------------
 heat/engine/service_stack_watch.py |  2 +-
 heat/engine/stack.py               | 22 ++++++++---------
 heat/engine/template.py            |  2 +-
 heat/engine/timestamp.py           |  2 +-
 heat/engine/update.py              |  7 +++---
 heat/engine/watchrule.py           |  3 ++-
 18 files changed, 114 insertions(+), 106 deletions(-)

diff --git a/heat/engine/dependencies.py b/heat/engine/dependencies.py
index f90a47e051..2d00e15376 100644
--- a/heat/engine/dependencies.py
+++ b/heat/engine/dependencies.py
@@ -104,7 +104,7 @@ class Graph(collections.defaultdict):
         super(Graph, self).__init__(Node, *args)
 
     def map(self, func):
-        """A dict mapping the supplied function onto each node in the graph.
+        """Map the supplied function onto each node in the graph.
 
         Return a dictionary derived from mapping the supplied function onto
         each node in the graph.
@@ -172,7 +172,7 @@ class Dependencies(object):
     def __init__(self, edges=None):
         """Initialise, optionally with a list of edges.
 
-        Each edge has the form of (requirer, required) tuple.
+        Each edge takes the form of a (requirer, required) tuple.
         """
         edges = edges or []
         self._graph = Graph()
@@ -207,10 +207,10 @@ class Dependencies(object):
         return self._graph[target].requires()
 
     def __getitem__(self, last):
-        """Partial dependency graph consisting of the specified node.
+        """Return a partial dependency graph starting with the specified node.
 
-        Return a partial dependency graph consisting of the specified node and
-        all those that require it only.
+        Return a subset of the dependency graph consisting of the specified
+        node and all those that require it only.
         """
         if last not in self._graph:
             raise KeyError
diff --git a/heat/engine/environment.py b/heat/engine/environment.py
index 4b450bf5e0..ada4a16a17 100644
--- a/heat/engine/environment.py
+++ b/heat/engine/environment.py
@@ -223,8 +223,7 @@ class ResourceRegistry(object):
     def _register_info(self, path, info):
         """Place the new info in the correct location in the registry.
 
-        :param path: a list of keys ['resources', 'my_server',
-         'OS::Nova::Server']
+        :param path: a list of keys ['resources', 'my_srv', 'OS::Nova::Server']
         """
         descriptive_path = '/'.join(path)
         name = path[-1]
@@ -517,14 +516,14 @@ class ResourceRegistry(object):
 class Environment(object):
 
     def __init__(self, env=None, user_env=True):
-        """Create an Environment from a dict of varying format.
+        """Create an Environment from an input dict.
 
-        Next formats are available:
-          1) old-school flat parameters
-          2) or newer {resource_registry: bla, parameters: foo}
+        The dict may be in one of two formats:
+          1) old-school flat parameters; or
+          2) newer {resource_registry: bla, parameters: foo}
 
         :param env: the json environment
-        :param user_env: boolean, if false then we manage python resources too.
+        :param user_env: boolean, if False then we manage python resources too.
         """
         if env is None:
             env = {}
@@ -612,7 +611,7 @@ def get_child_environment(parent_env, child_params, item_to_remove=None,
     environment.
 
     1. resource_registry must be merged (child env should be loaded after the
-       parent env to take presence).
+       parent env to take precedence).
     2. child parameters must overwrite the parent's as they won't be relevant
        in the child template.
 
diff --git a/heat/engine/event.py b/heat/engine/event.py
index 7cf03175ff..ea4811a091 100644
--- a/heat/engine/event.py
+++ b/heat/engine/event.py
@@ -27,11 +27,10 @@ class Event(object):
     def __init__(self, context, stack, action, status, reason,
                  physical_resource_id, resource_properties, resource_name,
                  resource_type, uuid=None, timestamp=None, id=None):
-        """Initialisation of the event.
+        """Initialise from a context, stack, and event information.
 
-        Initialise from a context, stack, and event information. The timestamp
-        and database ID may also be initialised if the event is already in the
-        database.
+        The timestamp and database ID may also be initialised if the event is
+        already in the database.
         """
         self.context = context
         self.stack = stack
diff --git a/heat/engine/function.py b/heat/engine/function.py
index 4e8a0c40e7..162ad28aab 100644
--- a/heat/engine/function.py
+++ b/heat/engine/function.py
@@ -66,6 +66,11 @@ class Function(object):
         return dependencies(self.args, '.'.join([path, self.fn_name]))
 
     def dep_attrs(self, resource_name):
+        """Return the attributes of the specified resource that are referenced.
+
+        Return an iterator over any attributes of the specified resource that
+        this function references.
+        """
         return dep_attrs(self.args, resource_name)
 
     def __reduce__(self):
@@ -179,12 +184,13 @@ def dependencies(snippet, path=''):
 
 
 def dep_attrs(snippet, resource_name):
-    """Iterator over dependent attrs for resource_name in a template snippet.
+    """Iterator over dependent attrs of a resource in a template snippet.
 
     The snippet should be already parsed to insert Function objects where
     appropriate.
-    :returns: an iterator over dependent attributes for specified resource_name
-        in a template snippet.
+
+    :returns: an iterator over the attributes of the specified resource that
+    are referenced in the template snippet.
     """
 
     if isinstance(snippet, Function):
diff --git a/heat/engine/lifecycle_plugin.py b/heat/engine/lifecycle_plugin.py
index d27a4cdb6a..281bc9a037 100644
--- a/heat/engine/lifecycle_plugin.py
+++ b/heat/engine/lifecycle_plugin.py
@@ -33,7 +33,7 @@ class LifecyclePlugin(object):
         pass
 
     def get_ordinal(self):
-        """Order class instances for pre and post operation execution.
+        """Get the sort order for pre and post operation execution.
 
         The values returned by get_ordinal are used to create a partial order
         for pre and post operation method invocations. The default ordinal
diff --git a/heat/engine/parameter_groups.py b/heat/engine/parameter_groups.py
index 88b3a07c2d..9b1444422f 100644
--- a/heat/engine/parameter_groups.py
+++ b/heat/engine/parameter_groups.py
@@ -35,10 +35,10 @@ class ParameterGroups(object):
         self.parameter_groups = tmpl.get(PARAMETER_GROUPS)
 
     def validate(self):
-        """Validate parameters in current parameter group.
+        """Validate the parameter group.
 
-        Validate that a parameter belongs to only one Parameter Group
-        and that each parameter name references a valid parameter.
+        Validate that each parameter belongs to only one Parameter Group and
+        that each parameter name in the group references a valid parameter.
         """
         LOG.debug('Validating Parameter Groups.')
         LOG.debug(self.parameter_names)
diff --git a/heat/engine/parameters.py b/heat/engine/parameters.py
index 31fafd9e8a..2ea39956e9 100644
--- a/heat/engine/parameters.py
+++ b/heat/engine/parameters.py
@@ -202,7 +202,7 @@ class Parameter(object):
         return ParamClass(name, schema, value)
 
     def __init__(self, name, schema, value=None):
-        """Initialisation of the parameter.
+        """Initialise the parameter.
 
         Initialise the Parameter with a name, schema and optional user-supplied
         value.
@@ -255,10 +255,9 @@ class Parameter(object):
         return self.user_value is not None or self.has_default()
 
     def hidden(self):
-        """Return if parameter is hidden.
+        """Return whether the parameter is hidden.
 
-        Return whether the parameter should be sanitised in any output to
-        the user.
+        Hidden parameters should be sanitised in any output to the user.
         """
         return self.schema.hidden
 
@@ -458,7 +457,7 @@ class JsonParam(ParsedParameter):
 class Parameters(collections.Mapping):
     """Parameters of a stack.
 
-    The parameters of a stack, with type checking, defaults etc., specified by
+    The parameters of a stack, with type checking, defaults, etc. specified by
     the stack's template.
     """
 
@@ -528,10 +527,10 @@ class Parameters(collections.Mapping):
         return self.params[key].value()
 
     def map(self, func, filter_func=lambda p: True):
-        """Map the supplied filter function onto each Parameter.
+        """Map the supplied function onto each Parameter.
 
-        Map the supplied filter function onto each Parameter (with an
-        optional filter function) and return the resulting dictionary.
+        Map the supplied function onto each Parameter (with an optional filter
+        function) and return the resulting dictionary.
         """
         return dict((n, func(p))
                     for n, p in six.iteritems(self.params) if filter_func(p))
diff --git a/heat/engine/properties.py b/heat/engine/properties.py
index 7d77a3519d..6ca949366d 100644
--- a/heat/engine/properties.py
+++ b/heat/engine/properties.py
@@ -350,10 +350,10 @@ class Properties(collections.Mapping):
 
     @staticmethod
     def schema_from_params(params_snippet):
-        """Convert a template snippet with parameters into a properties schema.
+        """Create properties schema from the parameters section of a template.
 
         :param params_snippet: parameter definition from a template
-        :returns: an equivalent properties schema for the specified params
+        :returns: equivalent properties schemata for the specified parameters
         """
         if params_snippet:
             return dict((n, Schema.from_parameter(p)) for n, p
@@ -561,7 +561,10 @@ class Properties(collections.Mapping):
 
     @classmethod
     def schema_to_parameters_and_properties(cls, schema, template_type='cfn'):
-        """Generates properties with params resolved for a schema.
+        """Convert a schema to template parameters and properties.
+
+        This can be used to generate a provider template that matches the
+        given properties schemata.
 
         :param schema: A resource type's properties_schema
         :returns: A tuple of params and properties dicts
diff --git a/heat/engine/resource.py b/heat/engine/resource.py
index 34ad36b2be..14827a8e8d 100644
--- a/heat/engine/resource.py
+++ b/heat/engine/resource.py
@@ -468,7 +468,7 @@ class Resource(object):
         return dict((k, after.get(k)) for k in changed_keys_set)
 
     def update_template_diff_properties(self, after_props, before_props):
-        """The changed Properties between the before and after properties.
+        """Return changed Properties between the before and after properties.
 
         If any property having immutable as True is updated, raises
         NotSupported error.
@@ -525,13 +525,12 @@ class Resource(object):
         deps += (self, None)
 
     def required_by(self):
-        """List of resources' names which require the resource as dependency.
+        """List of resources that require this one as a dependency.
 
-        Returns a list of resources' names which directly require this
-        resource as a dependency.
+        Returns a list of names of resources that depend on this resource
+        directly.
         """
-        return list(
-            [r.name for r in self.stack.dependencies.required_by(self)])
+        return [r.name for r in self.stack.dependencies.required_by(self)]
 
     def client(self, name=None):
         client_name = name or self.default_client_name
@@ -874,12 +873,12 @@ class Resource(object):
 
     def update_convergence(self, template_id, resource_data, engine_id,
                            timeout):
-        """Updates the resource.
+        """Update the resource synchronously.
 
-        Updates the resource by invoking the scheduler TaskRunner
-        and it persists the resource's current_template_id to template_id and
-        resource's requires to list of the required resource id from the
-        given resource_data and existing resource's requires.
+        Persist the resource's current_template_id to template_id and
+        resource's requires to list of the required resource ids from the given
+        resource_data and existing resource's requires, then updates the
+        resource by invoking the scheduler TaskRunner.
         """
         def update_tmpl_id_and_requires():
             self.current_template_id = template_id
@@ -905,7 +904,7 @@ class Resource(object):
 
     @scheduler.wrappertask
     def update(self, after, before=None, prev_resource=None):
-        """Update the resource.
+        """Return a task to update the resource.
 
         Subclasses should provide a handle_update() method to customise update,
         the base-class handle_update will fail by default.
@@ -1026,7 +1025,7 @@ class Resource(object):
             raise exception.Error('; '.join(invalid_checks))
 
     def suspend(self):
-        """Suspend the resource.
+        """Return a task to suspend the resource.
 
         Subclasses should provide a handle_suspend() method to implement
         suspend.
@@ -1046,7 +1045,7 @@ class Resource(object):
         return self._do_action(action)
 
     def resume(self):
-        """Resume the resource.
+        """Return a task to resume the resource.
 
         Subclasses should provide a handle_resume() method to implement resume.
         """
@@ -1222,7 +1221,7 @@ class Resource(object):
 
     @scheduler.wrappertask
     def delete(self):
-        """Delete the resource.
+        """A task to delete the resource.
 
         Subclasses should provide a handle_delete() method to customise
         deletion.
@@ -1260,7 +1259,7 @@ class Resource(object):
 
     @scheduler.wrappertask
     def destroy(self):
-        """Delete the resource and remove it from the database."""
+        """A task to delete the resource and remove it from the database."""
         yield self.delete()
 
         if self.id is None:
@@ -1672,7 +1671,7 @@ class Resource(object):
 
     @classmethod
     def resource_to_template(cls, resource_type, template_type='cfn'):
-        """Template where resource's properties mapped as parameters.
+        """Generate a provider template that mirrors the resource.
 
         :param resource_type: The resource type to be displayed in the template
         :param template_type: the template type to generate, cfn or hot.
@@ -1720,7 +1719,7 @@ class Resource(object):
         return tmpl_dict
 
     def data(self):
-        """Resource data for this resource.
+        """Return the resource data for this resource.
 
         Use methods data_set and data_delete to modify the resource data
         for this resource.
@@ -1736,13 +1735,13 @@ class Resource(object):
         return self._data or {}
 
     def data_set(self, key, value, redact=False):
-        """Save resource's key/value pair to database."""
+        """Set a key in the resource data."""
         resource_data_objects.ResourceData.set(self, key, value, redact)
         # force fetch all resource data from the database again
         self._data = None
 
     def data_delete(self, key):
-        """Remove a resource_data element associated to a resource.
+        """Remove a key from the resource data.
 
         :returns: True if the key existed to delete.
         """
diff --git a/heat/engine/rsrc_defn.py b/heat/engine/rsrc_defn.py
index e324775ce7..4b6084f872 100644
--- a/heat/engine/rsrc_defn.py
+++ b/heat/engine/rsrc_defn.py
@@ -27,10 +27,7 @@ __all__ = ['ResourceDefinition']
 
 
 class ResourceDefinitionCore(object):
-    """A definition of a resource.
-
-    Independent of any particular template format.
-    """
+    """A definition of a resource, independent of any template format."""
 
     DELETION_POLICIES = (
         DELETE, RETAIN, SNAPSHOT,
@@ -141,7 +138,7 @@ class ResourceDefinitionCore(object):
             update_policy=reparse_snippet(self._update_policy))
 
     def dep_attrs(self, resource_name):
-        """Return an iterator over dependent attributes for resource_name.
+        """Iterate over attributes of a given resource that this references.
 
         Return an iterator over dependent attributes for specified
         resource_name in resources' properties and metadata fields.
diff --git a/heat/engine/scheduler.py b/heat/engine/scheduler.py
index 38aefdb0c7..68c201a21b 100644
--- a/heat/engine/scheduler.py
+++ b/heat/engine/scheduler.py
@@ -32,9 +32,9 @@ ENABLE_SLEEP = True
 
 
 def task_description(task):
-    """Return a human-readable string description of a task suitable.
+    """Return a human-readable string description of a task.
 
-    Description is used for logging the status of the task.
+    The description is used to identify the task when logging its status.
     """
     name = task.__name__ if hasattr(task, '__name__') else None
     if isinstance(task, types.MethodType):
@@ -132,9 +132,9 @@ class TaskRunner(object):
     """Wrapper for a resumable task (co-routine)."""
 
     def __init__(self, task, *args, **kwargs):
-        """Initialise with a task function.
+        """Initialise with a task function and arguments.
 
-        Arguments to be passed to task when it is started.
+        The arguments are passed to task when it is started.
 
         The task function may be a co-routine that yields control flow between
         steps.
@@ -200,7 +200,7 @@ class TaskRunner(object):
     def step(self):
         """Run another step of the task.
 
-        :returns: True if the task is complete; False otherwise.
+        Return True if the task is complete; False otherwise.
         """
         if not self.done():
             assert self._runner is not None, "Task not started"
@@ -336,11 +336,10 @@ class DependencyTaskGroup(object):
                  aggregate_exceptions=False):
         """Initialise with the task dependencies.
 
-        Optionally initialise with a task to run on each.
-
-        If no task is supplied, it is assumed that the tasks are stored
-        directly in the dependency tree. If a task is supplied, the object
-        stored in the dependency tree is passed as an argument.
+        A task to run on each dependency may optionally be specified.  If no
+        task is supplied, it is assumed that the tasks are stored directly in
+        the dependency tree. If a task is supplied, the object stored in the
+        dependency tree is passed as an argument.
 
         If an error_wait_time is specified, tasks that are already running at
         the time of an error will continue to run for up to the specified
@@ -415,8 +414,8 @@ class DependencyTaskGroup(object):
     def _ready(self):
         """Iterate over all subtasks that are ready to start.
 
-        All subtasks' dependencies have been satisfied but they have not yet
-        been started.
+        Ready subtasks are subtasks whose dependencies have all been satisfied,
+        but which have not yet been started.
         """
         for k, n in six.iteritems(self._graph):
             if not n:
@@ -427,7 +426,8 @@ class DependencyTaskGroup(object):
     def _running(self):
         """Iterate over all subtasks that are currently running.
 
-        Subtasks have been started but have not yet completed.
+        Running subtasks are subtasks have been started but have not yet
+        completed.
         """
 
         def running(k_r):
diff --git a/heat/engine/service.py b/heat/engine/service.py
index 1bbdfe3044..4ddfd77605 100644
--- a/heat/engine/service.py
+++ b/heat/engine/service.py
@@ -94,7 +94,7 @@ class ThreadGroupManager(object):
     def _service_task(self):
         """Dummy task which gets queued on the service.Service threadgroup.
 
-        Without this service.Service sees nothing running i.e has nothing to
+        Without this, service.Service sees nothing running i.e has nothing to
         wait() on, so the process exits. This could also be used to trigger
         periodic non-stack-specific housekeeping tasks.
         """
@@ -136,7 +136,7 @@ class ThreadGroupManager(object):
         return th
 
     def start_with_lock(self, cnxt, stack, engine_id, func, *args, **kwargs):
-        """Run the method in sub-thread if acquire a stack lock is successful.
+        """Run the method in sub-thread after acquiring the stack lock.
 
         Release the lock when the thread finishes.
 
@@ -156,7 +156,7 @@ class ThreadGroupManager(object):
             return th
 
     def start_with_acquired_lock(self, stack, lock, func, *args, **kwargs):
-        """Run the given method in a sub-thread.
+        """Run the given method in a sub-thread with an existing stack lock.
 
         Release the provided lock when the thread finishes.
 
@@ -189,7 +189,7 @@ class ThreadGroupManager(object):
     def add_timer(self, stack_id, func, *args, **kwargs):
         """Define a periodic task in the stack threadgroups.
 
-        Defining is to be run in a separate thread.
+        The task is run in a separate greenthread.
 
         Periodicity is cfg.CONF.periodic_interval
         """
@@ -261,7 +261,7 @@ class EngineListener(service.Service):
         server.start()
 
     def listening(self, ctxt):
-        """Confirm the engine performing the action is still alive.
+        """Respond to a watchdog request.
 
         Respond affirmatively to confirm that the engine performing the action
         is still alive.
@@ -642,7 +642,7 @@ class EngineService(service.Service):
 
     @context.request_context
     def preview_stack(self, cnxt, stack_name, template, params, files, args):
-        """Simulates a new stack using the provided template.
+        """Simulate a new stack using the provided template.
 
         Note that at this stage the template has already been fetched from the
         heat-api process if using a template-url.
@@ -673,7 +673,7 @@ class EngineService(service.Service):
     def create_stack(self, cnxt, stack_name, template, params, files, args,
                      owner_id=None, nested_depth=0, user_creds_id=None,
                      stack_user_project_id=None, parent_resource_name=None):
-        """Creates a new stack using the template provided.
+        """Create a new stack using the template provided.
 
         Note that at this stage the template has already been fetched from the
         heat-api process if using a template-url.
@@ -741,7 +741,7 @@ class EngineService(service.Service):
 
     def _prepare_stack_updates(self, cnxt, current_stack, template, params,
                                files, args):
-        """Return the current and updated stack.
+        """Return the current and updated stack for a given transition.
 
         Changes *will not* be persisted, this is a helper method for
         update_stack and preview_update_stack.
@@ -829,7 +829,7 @@ class EngineService(service.Service):
     @context.request_context
     def update_stack(self, cnxt, stack_identity, template, params,
                      files, args):
-        """Updates an existing stack based on the provided template and params.
+        """Update an existing stack based on the provided template and params.
 
         Note that at this stage the template has already been fetched from the
         heat-api process if using a template-url.
@@ -877,7 +877,7 @@ class EngineService(service.Service):
     @context.request_context
     def preview_update_stack(self, cnxt, stack_identity, template, params,
                              files, args):
-        """Shows the resources that would be updated.
+        """Show the resources that would be updated.
 
         The preview_update_stack method shows the resources that would be
         changed with an update to an existing stack based on the provided
@@ -970,7 +970,11 @@ class EngineService(service.Service):
     @context.request_context
     def validate_template(self, cnxt, template, params=None, files=None,
                           show_nested=False):
-        """Uses the stack parser to check the validity of a template.
+        """Check the validity of a template.
+
+        Checks, so far as we can, that a template is valid, and returns
+        information about the parameters suitable for producing a user
+        interface through which to specify the parameter values.
 
         :param cnxt: RPC context.
         :param template: Template of stack you want to create.
@@ -1074,7 +1078,7 @@ class EngineService(service.Service):
 
     @context.request_context
     def delete_stack(self, cnxt, stack_identity):
-        """The delete_stack method deletes a given stack.
+        """Delete a given stack.
 
         :param cnxt: RPC context.
         :param stack_identity: Name of the stack you want to delete.
@@ -1131,7 +1135,7 @@ class EngineService(service.Service):
 
     @context.request_context
     def abandon_stack(self, cnxt, stack_identity):
-        """The abandon_stack method abandons a given stack.
+        """Abandon a given stack.
 
         :param cnxt: RPC context.
         :param stack_identity: Name of the stack you want to abandon.
@@ -1602,7 +1606,7 @@ class EngineService(service.Service):
 
     @context.request_context
     def show_watch(self, cnxt, watch_name):
-        """The show_watch method returns the attributes of one watch/alarm.
+        """Return the attributes of one watch/alarm.
 
         :param cnxt: RPC context.
         :param watch_name: Name of the watch you want to see, or None to see
@@ -1623,7 +1627,7 @@ class EngineService(service.Service):
 
     @context.request_context
     def show_watch_metric(self, cnxt, metric_namespace=None, metric_name=None):
-        """The show_watch method returns the datapoints for a metric.
+        """Return the datapoints for a metric.
 
         :param cnxt: RPC context.
         :param metric_namespace: Name of the namespace you want to see, or None
diff --git a/heat/engine/service_stack_watch.py b/heat/engine/service_stack_watch.py
index 7484a27299..2729c752f9 100644
--- a/heat/engine/service_stack_watch.py
+++ b/heat/engine/service_stack_watch.py
@@ -106,7 +106,7 @@ class StackWatch(object):
                                             actions, rule.get_details())
 
     def periodic_watcher_task(self, sid):
-        """Triggers watch-rule evaluation for all rules defined for stack ID.
+        """Evaluate all watch-rules defined for stack ID.
 
         Periodic task, created for each stack, triggers watch-rule evaluation
         for all rules defined for the stack sid = stack ID.
diff --git a/heat/engine/stack.py b/heat/engine/stack.py
index 96a6dcc4a0..c25bf6ed80 100644
--- a/heat/engine/stack.py
+++ b/heat/engine/stack.py
@@ -98,7 +98,7 @@ class Stack(collections.Mapping):
                  current_traversal=None, tags=None, prev_raw_template_id=None,
                  current_deps=None, cache_data=None, resource_validate=True):
 
-        """Initialisation of stack.
+        """Initialise the Stack.
 
         Initialise from a context, name, Template object and (optionally)
         Environment object. The database ID may also be initialised, if the
@@ -330,18 +330,18 @@ class Stack(collections.Mapping):
     def _set_param_stackid(self):
         """Update self.parameters with the current ARN.
 
-        self.parameters is then provided via the Parameters class as
-        the StackId pseudo parameter.
+        The ARN is then provided via the Parameters class as the StackId pseudo
+        parameter.
         """
         if not self.parameters.set_stack_id(self.identifier()):
             LOG.warn(_LW("Unable to set parameters StackId identifier"))
 
     @staticmethod
     def get_dep_attrs(resources, outputs, resource_name):
-        """Return the set of dependent attributes for specified resource name.
+        """Return the attributes of the specified resource that are referenced.
 
-        Return the set of dependent attributes for specified resource name by
-        inspecting all resources and outputs in template.
+        Return an iterator over any attributes of the specified resource that
+        are referenced.
         """
         attr_lists = itertools.chain((res.dep_attrs(resource_name)
                                       for res in resources),
@@ -599,7 +599,7 @@ class Stack(collections.Mapping):
                 return r
 
     def register_access_allowed_handler(self, credential_id, handler):
-        """Register a specific function.
+        """Register an authorization handler function.
 
         Register a function which determines whether the credentials with a
         given ID can have access to a named resource.
@@ -820,8 +820,8 @@ class Stack(collections.Mapping):
                    aggregate_exceptions=False, pre_completion_func=None):
         """A task to perform an action on the stack.
 
-        All of the resources in forward or reverse dependency order as
-        specified by reverse.
+        All of the resources are traversed in forward or reverse dependency
+        order.
 
         :param action action that should be executed with stack resources
         :param reverse defines if action on the resources need to be executed
@@ -947,7 +947,7 @@ class Stack(collections.Mapping):
 
     @profiler.trace('Stack.adopt', hide_args=False)
     def adopt(self):
-        """Adopt the stack (create stack with all the existing resources)."""
+        """Adopt existing resources into a new stack."""
         def rollback():
             if not self.disable_rollback and self.state == (self.ADOPT,
                                                             self.FAILED):
@@ -985,7 +985,7 @@ class Stack(collections.Mapping):
 
     @profiler.trace('Stack.converge_stack', hide_args=False)
     def converge_stack(self, template, action=UPDATE, new_stack=None):
-        """Update the stack and triggers convergence for resources."""
+        """Update the stack template and trigger convergence for resources."""
         if action not in [self.CREATE, self.ADOPT]:
             # no back-up template for create action
             self.prev_raw_template_id = getattr(self.t, 'id', None)
diff --git a/heat/engine/template.py b/heat/engine/template.py
index 5ebce0bf20..2121449fa8 100644
--- a/heat/engine/template.py
+++ b/heat/engine/template.py
@@ -262,7 +262,7 @@ class Template(collections.Mapping):
     @classmethod
     def create_empty_template(cls,
                               version=('heat_template_version', '2015-04-30')):
-        """Creates an empty template.
+        """Create an empty template.
 
         Creates a new empty template with given version. If version is
         not provided, a new empty HOT template of version "2015-04-30"
diff --git a/heat/engine/timestamp.py b/heat/engine/timestamp.py
index 49376bff7c..8ba51a5147 100644
--- a/heat/engine/timestamp.py
+++ b/heat/engine/timestamp.py
@@ -18,7 +18,7 @@ class Timestamp(object):
     """A descriptor for writing a timestamp to the database."""
 
     def __init__(self, db_fetch, attribute):
-        """Initialisation of timestamp.
+        """Initialise the timestamp descriptor.
 
         Initialise with a function to fetch the database representation of an
         object (given a context and ID) and the name of the attribute to
diff --git a/heat/engine/update.py b/heat/engine/update.py
index 684bd15e8b..122d6c6380 100644
--- a/heat/engine/update.py
+++ b/heat/engine/update.py
@@ -196,10 +196,11 @@ class StackUpdate(object):
             self.existing_stack.remove_resource(res_name)
 
     def dependencies(self):
-        """Return a Dependencies object.
+        """Return the Dependencies graph for the update.
 
-        Dependencies object representing the dependencies between update
-        operations to move from an existing stack definition to a new one.
+        Returns a Dependencies object representing the dependencies between
+        update operations to move from an existing stack definition to a new
+        one.
         """
         existing_deps = self.existing_stack.dependencies
         new_deps = self.new_stack.dependencies
diff --git a/heat/engine/watchrule.py b/heat/engine/watchrule.py
index 8e088beb1e..29d1e5b205 100644
--- a/heat/engine/watchrule.py
+++ b/heat/engine/watchrule.py
@@ -77,7 +77,8 @@ class WatchRule(object):
     def load(cls, context, watch_name=None, watch=None):
         """Load the watchrule object.
 
-        Loading object either by name or via an existing DB object.
+        The object can be loaded either from the DB by name or from an existing
+        DB object.
         """
         if watch is None:
             try: