address docstring-related review comments

Author: radix

effect/fold.py

@@ -25,13 +25,24 @@ def __str__(self):
 
 def fold_effect(f, initial, effects):
     """
-    Fold over effects.
+    Fold over the results of effects, left-to-right.
 
-    The function will be called with the accumulator (starting with
+    This is like :func:`functools.reduce`, but instead of acting on plain
+    values, it acts on the results of effects.
+
+    The function ``f`` will be called with the accumulator (starting with
     ``initial``) and a result of an effect repeatedly for each effect. The
     result of the previous call will be passed as the accumulator to the next
     call.
 
+    For example, the following code evaluates to an Effect of 6::
+
+        fold_effect(operator.add, 0, [Effect(Constant(1)),
+                                      Effect(Constant(2)),
+                                      Effect(Constant(3))])
+
+    If no elements were in the list, Effect would result in 0.
+
     :param callable f: function of ``(accumulator, element) -> accumulator``
     :param initial: The value to be passed as the accumulator to the first
         invocation of ``f``.

effect/test_fold.py

@@ -11,11 +11,15 @@
 
 
 def _disp(dispatcher):
+    """Compose base_dispatcher onto the given dispatcher."""
     return ComposedDispatcher([dispatcher, base_dispatcher])
 
 
 def test_fold_effect():
-    """Behaves like foldM."""
+    """
+    :func:`fold_effect` folds the given function over the results of the
+    effects.
+    """
     effs = [Effect('a'), Effect('b'), Effect('c')]
 
     dispatcher = SequenceDispatcher([