Update documentation and tests relvant to documentation

Author: 0scarB

README.md

@@ -47,6 +47,91 @@ from the caller function (in this case also `factorial`). This means that the
 resources in the caller function's scope are free to be garbage collected and that its
 frame is popped from the call stack before we push the returned function on.
 
+## Nested Calls
+
+In the previous example the whole concept of an accumulator my not fit your mental model
+that well (it doesn't for me at least).
+Luckily calls to `tail_call` support nested calls (i.e. another `tail_call` passed as an
+argument).
+Taking this functionality into consideration we can refactor the previous example.
+
+```python
+...
+
+@tail_recursive
+def mul(a, b):
+    return a * b
+
+@tail_recursive
+def factorial(n):
+    if n == 1:
+        return n
+    return mul.tail_call(n, factorial.tail_call(n - 1))
+
+...
+```
+
+This, however, comes a performance cost and can be disabled as follows.
+
+```python
+@tail_recursive(nested_call_mode="do_not_resolve_nested_calls")
+def factorial(n, accumulator=1):
+    if n == 1:
+        return accumulator
+    return factorial.tail_call(n - 1, n * accumulator)
+```
+
+or
+
+```python
+from tail_recursive import tail_recursive, NestedCallMode
+
+...
+
+@tail_recursive(nested_call_mode=NestedCallMode.DO_NOT_RESOLVE_NESTED_CALLS)
+def factorial(n, accumulator=1):
+    ...
+```
+
+Similarly, use `nested_call_mode="resolve_nested_calls"` or `nested_call_mode=NestedCallMode.RESOLVE_NESTED_CALLS`
+to explicitly enable this feature.
+
+## Current Limitations
+
+### Return Values
+
+Currently tail calls that are returned as an item in a tuple or other
+data structure are not evaluated.
+
+The following will not evaluate the tail call.
+
+```python
+from tail_recursive import tail_recursive
+
+@tail_recursive
+def func(...):
+    ...
+    return return_val1, func.tail_call(...)
+```
+
+A workaround is to use factory functions.
+
+```python
+from tail_recursive import tail_recursive
+
+@tail_recursive
+def tuple_factory(*args):
+    return tuple(args)
+
+@tail_recursive
+def func(...):
+    ...
+    return tuple_factory.tail_call(
+        return_val1,
+        func.tail_call(...)
+    )
+```
+
 ## Other Packages
 
 Check out [tco](https://github.com/baruchel/tco) for an alternative api with extra functionality.

tests.py

@@ -273,3 +273,63 @@ def fibonacci(n):
 
     n = sys.getrecursionlimit() + 1
     assert fibonacci(n) == non_recursive_fibonacci(n)
+
+
+def test_tail_call_as_part_for_datastructure_is_not_evaluated():
+
+    @tail_recursive
+    def add(a, b):
+        return a + b
+
+    @tail_recursive
+    def getitem(obj, index):
+        return obj[index]
+
+    @tail_recursive
+    def square_and_triangular_numbers(n):
+        square = n**2
+        if n == 1:
+            triangular_number = n
+        else:
+            triangular_number = add.tail_call(
+                n,
+                getitem.tail_call(
+                    square_and_triangular_numbers.tail_call(n - 1),
+                    1
+                )
+            )
+        return square, triangular_number
+
+    assert square_and_triangular_numbers(3) != (9, 6)
+
+
+def test_tail_call_as_part_for_datastructure_with_factory_succeeds():
+
+    @tail_recursive
+    def tuple_factory(*args):
+        return tuple(args)
+
+    @tail_recursive
+    def add(a, b):
+        return a + b
+
+    @tail_recursive
+    def getitem(obj, index):
+        return obj[index]
+
+    @tail_recursive
+    def square_and_triangular_numbers(n):
+        square = n**2
+        if n == 1:
+            triangular_number = n
+        else:
+            triangular_number = add.tail_call(
+                n,
+                getitem.tail_call(
+                    square_and_triangular_numbers.tail_call(n - 1),
+                    1
+                )
+            )
+        return tuple_factory.tail_call(square, triangular_number)
+
+    assert square_and_triangular_numbers(3) == (9, 6)