From 1caf6fb316b15581117d3770af4685b02192f14b Mon Sep 17 00:00:00 2001
From: Joshua Harlow <harlowja@gmail.com>
Date: Sat, 12 Oct 2013 22:45:32 -0700
Subject: [PATCH] Add more comments to flow/task

Increase the number of comments which
will help users of these 2 modules better
understand there desired usage.

Change-Id: Ief248770de3bedd7fc87bfcfbce4da77c011de7f
---
 taskflow/flow.py | 21 ++++++++++++++++-----
 taskflow/task.py | 11 +++++++++++
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/taskflow/flow.py b/taskflow/flow.py
index 049a173d..7e674581 100644
--- a/taskflow/flow.py
+++ b/taskflow/flow.py
@@ -27,12 +27,22 @@ from taskflow.utils import reflection
 class Flow(six.with_metaclass(abc.ABCMeta)):
     """The base abstract class of all flow implementations.
 
-    It provides a name and an identifier (uuid or other) to the flow so that
-    it can be uniquely identifed among many flows.
+    It provides a name and an identifier (uuid) to the flow so that it can be
+    uniquely identifed among many flows while executing or while referencing
+    the results (or other metadata) of this flow in storage.
 
-    Flows are expected to provide the following methods:
+    NOTE(harlowja): if a flow is placed in another flow as a subflow, a desired
+    way to compose flows together, then it is valid and permissible that during
+    execution the subflow & parent flow may be flattened into a new flow. Since
+    a flow is just a 'structuring' concept this is typically a behavior that
+    should not be worried about (as it is not visible to the user), but it is
+    worth mentioning here.
+
+    Flows are expected to provide the following methods/properties:
     - add
     - __len__
+    - requires
+    - provides
     """
 
     def __init__(self, name, uuid=None):
@@ -49,6 +59,7 @@ class Flow(six.with_metaclass(abc.ABCMeta)):
 
     @property
     def uuid(self):
+        """A unique identifier for this flow"""
         return self._id
 
     @abc.abstractmethod
@@ -69,8 +80,8 @@ class Flow(six.with_metaclass(abc.ABCMeta)):
 
     @abc.abstractproperty
     def requires(self):
-        """Browse flow requirements."""
+        """Browse argument requirement names this flow requires to run."""
 
     @abc.abstractproperty
     def provides(self):
-        """Browse values provided by the flow."""
+        """Browse argument names provided by the flow."""
diff --git a/taskflow/task.py b/taskflow/task.py
index 1e8512de..5925fdef 100644
--- a/taskflow/task.py
+++ b/taskflow/task.py
@@ -59,6 +59,12 @@ def _save_as_to_mapping(save_as):
 
 
 def _build_rebind_dict(args, rebind_args):
+    """Build a argument remapping/rebinding dictionary.
+
+    This dictionary allows a task to declare that it will take a needed
+    requirement bound to a given name with another name instead (mapping the
+    new name onto the required name).
+    """
     if rebind_args is None:
         return {}
     elif isinstance(rebind_args, (list, tuple)):
@@ -86,6 +92,11 @@ def _check_args_mapping(task_name, rebind, args, accepts_kwargs):
 
 
 def _build_arg_mapping(task_name, reqs, rebind_args, function, do_infer):
+    """Given a function, its requirements and a rebind mapping this helper
+    function will build the correct argument mapping for the given function as
+    well as verify that the final argument mapping does not have missing or
+    extra arguments (where applicable).
+    """
     task_args = reflection.get_required_callable_args(function)
     accepts_kwargs = reflection.accepts_kwargs(function)
     result = {}