Merge "Add more comments that explain example & usage"

taskflow/examples/calculate_linear.py

@@ -32,14 +32,27 @@ from taskflow.patterns import linear_flow as lf
 from taskflow import task
 
 
-# In this example LinearFlow is used to group four tasks to
-# calculate value. Added task is used twice. In the first case
-# it uses default parameters ('x' and 'y') and in the second one
-# arguments are binding with 'z' and 'd' keys from engine storage.
-# Multiplier task uses binding too, but explicitly shows that 'z'
-# parameter is binded with 'a' key from engine storage.
+# INTRO: In this example linear_flow is used to group four tasks to calculate
+# a value. A single added task is used twice, showing how this can be done
+# and the twice added task takes in different bound values. In the first case
+# it uses default parameters ('x' and 'y') and in the second case arguments
+# are bound with ('z', 'd') keys from the engines storage mechanism.
+#
+# A multiplier task uses a binding that another task also provides, but this
+# example explicitly shows that 'z' parameter is binded with 'a' key
+# This shows that if a task depends on a key named the same as a key provided
+# from another task the name can be remapped to take the desired key from a
+# different origin.
 
 
+# This task provides some values from as a result of execution, this can be
+# useful when you want to provide values from a static set to other tasks that
+# depend on those values existing before those tasks can run.
+#
+# This method is *depreciated* in favor of a simpler mechanism that just
+# provides those values on engine running by prepopulating the storage backend
+# before your tasks are ran (which accomplishes a similar goal in a more
+# uniform manner).
 class Provider(task.Task):
 
     def __init__(self, name, *args, **kwargs):
@@ -50,16 +63,21 @@ class Provider(task.Task):
         return self._provide
 
 
+# This task adds two input variables and returns the result.
+#
+# Note that since this task does not have a revert() function (since addition
+# is a stateless operation) there are no side-effects that this function needs
+# to undo if some later operation fails.
 class Adder(task.Task):
-
-    def __init__(self, name, provides=None, rebind=None):
-        super(Adder, self).__init__(name=name, provides=provides,
-                                    rebind=rebind)
-
     def execute(self, x, y):
         return x + y
 
 
+# This task multiplies an input variable by a multipler and returns the result.
+#
+# Note that since this task does not have a revert() function (since
+# multiplication is a stateless operation) and there are no side-effects that
+# this function needs to undo if some later operation fails.
 class Multiplier(task.Task):
     def __init__(self, name, multiplier, provides=None, rebind=None):
         super(Multiplier, self).__init__(name=name, provides=provides,
@@ -70,16 +88,30 @@ class Multiplier(task.Task):
         return z * self._multiplier
 
 
+# Note here that the ordering is established so that the correct sequences
+# of operations occurs where the adding and multiplying is done according
+# to the expected and typical mathematical model. A graph_flow could also be
+# used here to automatically ensure the correct ordering.
 flow = lf.Flow('root').add(
+    # Provide the initial values for other tasks to depend on.
+    #
     # x = 2, y = 3, d = 5
     Provider("provide-adder", 2, 3, 5, provides=('x', 'y', 'd')),
     # z = x+y = 5
     Adder("add-1", provides='z'),
     # a = z+d = 10
     Adder("add-2", provides='a', rebind=['z', 'd']),
-    # r = a*3 = 30
+    # Calculate 'r = a*3 = 30'
+    #
+    # Note here that the 'z' argument of the execute() function will not be
+    # bound to the 'z' variable provided from the above 'provider' object but
+    # instead the 'z' argument will be taken from the 'a' variable provided
+    # by the second add-2 listed above.
     Multiplier("multi", 3, provides='r', rebind={'z': 'a'})
 )
 
+# The result here will be all results (from all tasks) which is stored in an
+# in-memory storage location that backs this engine since it is not configured
+# with persistance storage.
 results = taskflow.engines.run(flow)
 print(results)