Merge pull request #845 from farhaven/flow-doc

Rework `flow' module doc

docs/contrib/flow.rst

@@ -4,10 +4,9 @@ Flow
 
 .. versionadded:: 0.10.1
 
-The ``flow`` macros allow a programmer to direct the flow of his program with
+The ``flow`` macros allow directing the flow of a program with greater ease.
-greater ease.
+
-   
+
-   
 Macros
 ======
 
@@ -27,15 +26,15 @@ Example:
 .. code-block:: hy
 
     (require hy.contrib.flow)
-                
+
-    (defn bmi-commenter [bmi]
+    (defn temp-commenter [temp]
-        (case bmi
+        (case temp
-            10 (print "The bmi was 10, wow.")
+            -10 (print "It's freezing. Turn up the thermostat!")
-            20 (print "20? Really?")
+            15 (print "Sounds about average.")
-            30 (print "Was it 30? Ok...")
+            45 (print "Holy smokes. It's hot in here!")
                (print  "I don't even know.")))
 
-    
+
 switch
 -----
 
@@ -50,11 +49,10 @@ Example:
 .. code-block:: hy
 
     (require hy.contrib.flow)
-                
+
-    (defn bmi-commenter [bmi]
+    (defn temp-commenter [temp]
-        (switch bmi
+        (switch temp
-            (<= 18.5) (print "you are underweight!")
+            (<= 10.0) (print "Better wear a jacket!")
-            (<= 25.0) (print "apparently normal")
+            (<= 25.0) (print "Brace yourselves. Summer is coming!")
-            (<= 30.0) (print "a little too heavy, but ok")
+            (<= 30.0) (print "Time to get some ice cream.")
-                      (print  "You are a whale!")))
+                      (print "Sounds like a heat wave")))
-