Doc/intro updates for simple_linear_listening

Change-Id: I084ea894b9c24c3449bd29df5ef1ee999a0fc25a

taskflow/examples/simple_linear_listening.py

@@ -32,6 +32,29 @@ import taskflow.engines
 from taskflow.patterns import linear_flow as lf
 from taskflow import task
 
+# INTRO: In this example we create two tasks (this time as functions instead
+# of task subclasses as in the simple_linear.py example), each of which ~calls~
+# a given ~phone~ number (provided as a function input) in a linear fashion
+# (one after the other).
+#
+# For a workflow which is serial this shows a extremly simple way
+# of structuring your tasks (the code that does the work) into a linear
+# sequence (the flow) and then passing the work off to an engine, with some
+# initial data to be ran in a reliable manner.
+#
+# This example shows a basic usage of the taskflow structures without involving
+# the complexity of persistence. Using the structures that taskflow provides
+# via tasks and flows makes it possible for you to easily at a later time
+# hook in a persistence layer (and then gain the functionality that offers)
+# when you decide the complexity of adding that layer in is 'worth it' for your
+# applications usage pattern (which some applications may not need).
+#
+# It **also** adds on to the simple_linear.py example by adding a set of
+# callback functions which the engine will call when a flow state transition
+# or task state transition occurs. These types of functions are useful for
+# updating task or flow progress, or for debugging, sending notifications to
+# external systems, or for other yet unknown future usage that you may create!
+
 
 def call_jim(context):
     print("Calling jim.")
@@ -51,10 +74,16 @@ def task_watch(state, details):
     print('Task %s => %s' % (details.get('task_name'), state))
 
 
+# Wrap your functions into a task type that knows how to treat your functions
+# as tasks. There was previous work done to just allow a function to be
+# directly passed, but in python 3.0 there is no easy way to capture an
+# instance method, so this wrapping approach was decided upon instead which
+# can attach to instance methods (if thats desired).
 flow = lf.Flow("Call-them")
 flow.add(task.FunctorTask(execute=call_jim))
 flow.add(task.FunctorTask(execute=call_joe))
 
+# Now load (but do not run) the flow using the provided initial data.
 engine = taskflow.engines.load(flow, store={
     'context': {
         "joe_number": 444,
@@ -62,6 +91,12 @@ engine = taskflow.engines.load(flow, store={
     }
 })
 
+# This is where we attach our callback functions to the 2 different
+# notification objects that a engine exposes. The usage of a '*' (kleene star)
+# here means that we want to be notified on all state changes, if you want to
+# restrict to a specific state change, just register that instead.
 engine.notifier.register('*', flow_watch)
 engine.task_notifier.register('*', task_watch)
+
+# And now run!
 engine.run()