From 7109e732e5419efddd12d6137e13d21ae6c7a438 Mon Sep 17 00:00:00 2001
From: Anastasia Karpinska <akarpinska@griddynamics.com>
Date: Mon, 17 Mar 2014 12:33:33 +0200
Subject: [PATCH] Add Retry to developers documentation

Change-Id: I1e97af1f2e5d34b3e403c8c06d56f5d6157a7402
---
 doc/source/arguments_and_results.rst | 44 ++++++++++++++++++++++++++++
 doc/source/atoms.rst                 | 18 ++++++++++--
 2 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/doc/source/arguments_and_results.rst b/doc/source/arguments_and_results.rst
index dacbf2d7..6871b0d6 100644
--- a/doc/source/arguments_and_results.rst
+++ b/doc/source/arguments_and_results.rst
@@ -363,3 +363,47 @@ task failed, exception:"`` and exception message on revert. If this task
 finished successfully, it will print ``"do_something returned"`` and
 representation of result.
 
+Retry Arguments
+===============
+
+A Retry controller works with arguments in the same way as a Task. But it has an additional parameter 'history' that is
+a list of tuples. Each tuple contains a result of the previous Retry run and a table where a key is a failed task and a value
+is a :py:class:`taskflow.utils.misc.Failure`.
+
+Consider the following Retry:
+
+::
+
+  class MyRetry(retry.Retry):
+
+      default_provides = 'value'
+
+      def on_failure(self, history, *args, **kwargs):
+          print history
+          return RETRY
+
+      def execute(self, history, *args, **kwargs):
+          print history
+          return 5
+
+      def revert(self, history, *args, **kwargs):
+          print history
+
+Imagine the following Retry had returned a value '5' and then some task 'A' failed with some exception.
+In this case ``on_failure`` method will receive the following history:
+
+::
+
+    [('5', {'A': misc.Failure()})]
+
+Then the ``execute`` method will be called again and it'll receive the same history.
+
+If the ``execute`` method raises an exception, the ``revert`` method of Retry will be called and :py:class:`taskflow.utils.misc.Failure` object will be present
+in the history instead of Retry result.
+
+::
+
+    [('5', {'A': misc.Failure()}), (misc.Failure(), {})]
+
+After the Retry has been reverted, the Retry history will be cleaned.
+
diff --git a/doc/source/atoms.rst b/doc/source/atoms.rst
index 63c44177..1764ec2c 100644
--- a/doc/source/atoms.rst
+++ b/doc/source/atoms.rst
@@ -1,5 +1,5 @@
 ---------------
-Atoms and Tasks
+Atoms, Tasks and Retries
 ---------------
 
 An atom is the smallest unit in taskflow which acts as the base for other
@@ -8,9 +8,21 @@ to name desired input values (requirements) and name outputs (provided
 values), see :doc:`arguments_and_results` page for complete reference
 about it.
 
+.. automodule:: taskflow.atom
+
+Task
+=====
+
 A task (derived from an atom) is the smallest possible unit of work that can
 have a execute & rollback sequence associated with it.
 
-.. automodule:: taskflow.atom
-
 .. automodule:: taskflow.task
+
+Retry
+=====
+
+A retry (derived from an atom) is a special unit that handles flow errors,
+controlls flow execution and can retry it with another parameters if needed.
+
+.. automodule:: taskflow.retry
+