From 95ae38fe6b3c9768582b7a6106df760d664f2763 Mon Sep 17 00:00:00 2001
From: Phil Freeman <paf31@cantab.net>
Date: Sat, 21 Mar 2015 18:03:11 -0700
Subject: [PATCH 1/3] A start on more docs

---
 src/Control/Alt.purs     |  2 ++
 src/Control/Apply.purs   | 15 ++++++++++++---
 src/Control/Comonad.purs |  9 +++++++++
 src/Control/Extend.purs  | 13 +++++++++++++
 src/Control/Functor.purs |  4 ++++
 src/Control/Monad.purs   | 10 +++++++++-
 6 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/src/Control/Alt.purs b/src/Control/Alt.purs
index 63ab53b..c53374a 100644
--- a/src/Control/Alt.purs
+++ b/src/Control/Alt.purs
@@ -1,3 +1,5 @@
+-- | This module defines the `Alt` type class
+
 module Control.Alt where
 
 infixl 3 <|>
diff --git a/src/Control/Apply.purs b/src/Control/Apply.purs
index 4fc043d..f2c99c9 100644
--- a/src/Control/Apply.purs
+++ b/src/Control/Apply.purs
@@ -1,25 +1,34 @@
+-- | This module defines helper functions for working with `Apply` instances.
+
 module Control.Apply where
 
   infixl 4 <*
   infixl 4 *>
 
+  -- | Combine two effectful actions, keeping only the result of the first.
   (<*) :: forall a b f. (Apply f) => f a -> f b -> f a
   (<*) a b = const <$> a <*> b
 
+  -- | Combine two effectful actions, keeping only the result of the second.
   (*>) :: forall a b f. (Apply f) => f a -> f b -> f b
   (*>) a b = const id <$> a <*> b
 
+  -- | Lift a function of two arguments to a function which accepts and returns
+  -- | values wrapped with the type constructor `f`.
   lift2 :: forall a b c f. (Apply f) => (a -> b -> c) -> f a -> f b -> f c
   lift2 f a b = f <$> a <*> b
 
+  -- | Lift a function of three arguments to a function which accepts and returns
+  -- | values wrapped with the type constructor `f`.
   lift3 :: forall a b c d f. (Apply f) => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
   lift3 f a b c = f <$> a <*> b <*> c
 
+  -- | Lift a function of four arguments to a function which accepts and returns
+  -- | values wrapped with the type constructor `f`.
   lift4 :: forall a b c d e f. (Apply f) => (a -> b -> c -> d -> e) -> f a -> f b -> f c -> f d -> f e
   lift4 f a b c d = f <$> a <*> b <*> c <*> d
 
+  -- | Lift a function of five arguments to a function which accepts and returns
+  -- | values wrapped with the type constructor `f`.
   lift5 :: forall a b c d e f g. (Apply f) => (a -> b -> c -> d -> e -> g) -> f a -> f b -> f c -> f d -> f e -> f g
   lift5 f a b c d e = f <$> a <*> b <*> c <*> d <*> e
-
-  forever :: forall a b f. (Apply f) => f a -> f b
-  forever a = a *> forever a
diff --git a/src/Control/Comonad.purs b/src/Control/Comonad.purs
index 7674ddf..f96439b 100644
--- a/src/Control/Comonad.purs
+++ b/src/Control/Comonad.purs
@@ -1,6 +1,15 @@
+-- | This module defines the `Comonad` type class
+
 module Control.Comonad where
 
 import Control.Extend
 
+-- | `Comonad` extends the `Extend` class with the `extract` function
+-- | which extracts a value, discarding the comonadic context.
+-- | 
+-- | Laws:
+-- |
+-- | - Left Identity: `extract <<= xs = xs`
+-- | - Right Identity: `extract (f <<= xs) = f xs`
 class (Extend w) <= Comonad w where
   extract :: forall a. w a -> a
diff --git a/src/Control/Extend.purs b/src/Control/Extend.purs
index edc6af4..1a0f465 100644
--- a/src/Control/Extend.purs
+++ b/src/Control/Extend.purs
@@ -1,3 +1,5 @@
+-- | This module defines the `Extend` type class and associated helper functions
+
 module Control.Extend where
 
 infixl 1 =>>
@@ -5,20 +7,31 @@ infixr 1 <<=
 infixr 1 =>=
 infixr 1 =<=
 
+-- | The `Extend` class defines the extension operator `(<<=)`
+-- | which extends a local context-dependent computation to
+-- | a global computation.
+-- |
+-- | Laws:
+-- |
+-- | - Associativity: `extend f <<< extend g = extend (f <<< extend g)`
 class (Functor w) <= Extend w where
   (<<=) :: forall b a. (w a -> b) -> w a -> w b
 
 instance extendArr :: (Semigroup w) => Extend ((->) w) where
   (<<=) f g w = f \w' -> g (w <> w')
 
+-- | A version of `(<<=)` with its arguments reversed
 (=>>) :: forall b a w. (Extend w) => w a -> (w a -> b) -> w b
 (=>>) w f = f <<= w
 
+-- | Forwards co-Kleisli composition
 (=>=) :: forall b a w c. (Extend w) => (w a -> b) -> (w b -> c) -> w a -> c
 (=>=) f g w = g (f <<= w)
 
+-- | Backwards co-Kleisli composition
 (=<=) :: forall b a w c. (Extend w) => (w b -> c) -> (w a -> b) -> w a -> c
 (=<=) f g w = f (g <<= w)
 
+-- | Duplicate a comonadic context
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 duplicate w = id <<= w
diff --git a/src/Control/Functor.purs b/src/Control/Functor.purs
index 47968a4..7ac30fa 100644
--- a/src/Control/Functor.purs
+++ b/src/Control/Functor.purs
@@ -1,10 +1,14 @@
+-- | This module defines helper functions for working with `Functor` instances
+
 module Control.Functor where
 
 infixl 4 <$
 infixl 4 $>
 
+-- | Ignore the return value of a computation, using the specified return value instead
 (<$) :: forall f a b. (Functor f) => a -> f b -> f a
 (<$) x f = const x <$> f
 
+-- | A version of `(<$)` with its arguments flipped
 ($>) :: forall f a b. (Functor f) => f a -> b -> f b
 ($>) f x = const x <$> f
diff --git a/src/Control/Monad.purs b/src/Control/Monad.purs
index 35618d0..1b1d90c 100644
--- a/src/Control/Monad.purs
+++ b/src/Control/Monad.purs
@@ -1,5 +1,8 @@
+-- | This module defines helper functions for working with `Monad` instances
+
 module Control.Monad where
 
+-- | Perform a monadic action `n` times collecting all of the results
 replicateM :: forall m a. (Monad m) => Number -> m a -> m [a]
 replicateM 0 _ = return []
 replicateM n m = do
@@ -7,19 +10,24 @@ replicateM n m = do
   as <- replicateM (n - 1) m
   return (a : as)
 
+-- | Perform a fold using a monadic step function
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
 foldM _ a [] = return a
 foldM f a (b:bs) = f a b >>= \a' -> foldM f a' bs
 
+-- | Perform a monadic action when a condition is true.
 when :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 when true m = m
 when false _ = return unit
 
+-- | Perform a monadic action unless a condition is true.
 unless :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 unless false m = m
 unless true _ = return unit
 
--- | Filter where the predicate returns a monadic Boolean. For example: 
+-- | Filter where the predicate returns a monadic `Boolean`.
+-- |
+-- | For example: 
 -- |
 -- | ```purescript
 -- | powerSet :: forall a. [a] -> [[a]]

From 78c1d02525be00b349f56c478e7c6b4df3601f43 Mon Sep 17 00:00:00 2001
From: Phil Freeman <paf31@cantab.net>
Date: Sun, 22 Mar 2015 13:27:55 -0700
Subject: [PATCH 2/3] Docs

---
 README.md                    | 143 +++++++++++++++++++++++++++++++++--
 src/Control/Alternative.purs |  12 +++
 src/Control/Bind.purs        |  23 ++++++
 src/Control/Comonad.purs     |   3 +
 src/Control/Extend.purs      |   5 ++
 src/Control/Lazy.purs        |  15 ++++
 src/Control/MonadPlus.purs   |  17 +++++
 src/Control/Plus.purs        |   2 +
 8 files changed, 213 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 8258e5e..d7eadb1 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,9 @@
 
 ## Module Control.Alt
 
+
+This module defines the `Alt` type class
+
 #### `Alt`
 
 ``` purescript
@@ -25,6 +28,10 @@ For example, the `Array` (`[]`) type is an instance of `Alt`, where
 
 ## Module Control.Alternative
 
+
+This module defines the `Alternative` type class and associated
+helper functions.
+
 #### `Alternative`
 
 ``` purescript
@@ -46,6 +53,10 @@ laws:
 some :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 ```
 
+Attempt a computation multiple times, requiring at least one success.
+
+The `Lazy` constraint is used to generate the result lazily, to ensure
+termination.
 
 #### `many`
 
@@ -53,16 +64,25 @@ some :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 many :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 ```
 
+Attempt a computation multiple times, returning as many successful results
+as possible (possibly zero).
+
+The `Lazy` constraint is used to generate the result lazily, to ensure
+termination.
 
 
 ## Module Control.Apply
 
+
+This module defines helper functions for working with `Apply` instances.
+
 #### `(<*)`
 
 ``` purescript
 (<*) :: forall a b f. (Apply f) => f a -> f b -> f a
 ```
 
+Combine two effectful actions, keeping only the result of the first.
 
 #### `(*>)`
 
@@ -70,6 +90,7 @@ many :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 (*>) :: forall a b f. (Apply f) => f a -> f b -> f b
 ```
 
+Combine two effectful actions, keeping only the result of the second.
 
 #### `lift2`
 
@@ -77,6 +98,8 @@ many :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 lift2 :: forall a b c f. (Apply f) => (a -> b -> c) -> f a -> f b -> f c
 ```
 
+Lift a function of two arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
 
 #### `lift3`
 
@@ -84,6 +107,8 @@ lift2 :: forall a b c f. (Apply f) => (a -> b -> c) -> f a -> f b -> f c
 lift3 :: forall a b c d f. (Apply f) => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
 ```
 
+Lift a function of three arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
 
 #### `lift4`
 
@@ -91,6 +116,8 @@ lift3 :: forall a b c d f. (Apply f) => (a -> b -> c -> d) -> f a -> f b -> f c
 lift4 :: forall a b c d e f. (Apply f) => (a -> b -> c -> d -> e) -> f a -> f b -> f c -> f d -> f e
 ```
 
+Lift a function of four arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
 
 #### `lift5`
 
@@ -98,16 +125,14 @@ lift4 :: forall a b c d e f. (Apply f) => (a -> b -> c -> d -> e) -> f a -> f b
 lift5 :: forall a b c d e f g. (Apply f) => (a -> b -> c -> d -> e -> g) -> f a -> f b -> f c -> f d -> f e -> f g
 ```
 
+Lift a function of five arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
 
-#### `forever`
-
-``` purescript
-forever :: forall a b f. (Apply f) => f a -> f b
-```
 
+## Module Control.Bind
 
 
-## Module Control.Bind
+This module defines helper functions for working with `Bind` instances.
 
 #### `(=<<)`
 
@@ -115,6 +140,7 @@ forever :: forall a b f. (Apply f) => f a -> f b
 (=<<) :: forall a b m. (Bind m) => (a -> m b) -> m a -> m b
 ```
 
+A version of `(>>=)` with its arguments reversed
 
 #### `(>=>)`
 
@@ -122,6 +148,15 @@ forever :: forall a b f. (Apply f) => f a -> f b
 (>=>) :: forall a b c m. (Bind m) => (a -> m b) -> (b -> m c) -> a -> m c
 ```
 
+Forwards Kleisli composition
+
+For example:
+
+```purescript
+import Data.Array (head, tail)
+
+third = tail >=> tail >=> head
+```
 
 #### `(<=<)`
 
@@ -129,6 +164,7 @@ forever :: forall a b f. (Apply f) => f a -> f b
 (<=<) :: forall a b c m. (Bind m) => (b -> m c) -> (a -> m b) -> a -> m c
 ```
 
+Backwards Kleisli composition
 
 #### `join`
 
@@ -136,6 +172,7 @@ forever :: forall a b f. (Apply f) => f a -> f b
 join :: forall a m. (Bind m) => m (m a) -> m a
 ```
 
+Collapse two applications of a monadic type constructor into one.
 
 #### `ifM`
 
@@ -143,10 +180,22 @@ join :: forall a m. (Bind m) => m (m a) -> m a
 ifM :: forall a m. (Bind m) => m Boolean -> m a -> m a -> m a
 ```
 
+Execute a monadic action if a condition holds. 
+
+For example:
+
+```purescript
+main = ifM ((< 0.5) <$> random)
+         (trace "Heads")
+         (trace "Tails")
+```
 
 
 ## Module Control.Comonad
 
+
+This module defines the `Comonad` type class
+
 #### `Comonad`
 
 ``` purescript
@@ -154,10 +203,23 @@ class (Extend w) <= Comonad w where
   extract :: forall a. w a -> a
 ```
 
+`Comonad` extends the `Extend` class with the `extract` function
+which extracts a value, discarding the comonadic context.
+
+`Comonad` is the dual of `Monad`, and `extract` is the dual of 
+`pure` or `return`.
+
+Laws:
+
+- Left Identity: `extract <<= xs = xs`
+- Right Identity: `extract (f <<= xs) = f xs`
 
 
 ## Module Control.Extend
 
+
+This module defines the `Extend` type class and associated helper functions
+
 #### `Extend`
 
 ``` purescript
@@ -165,6 +227,16 @@ class (Functor w) <= Extend w where
   (<<=) :: forall b a. (w a -> b) -> w a -> w b
 ```
 
+The `Extend` class defines the extension operator `(<<=)`
+which extends a local context-dependent computation to
+a global computation.
+
+`Extend` is the dual of `Bind`, and `(<<=)` is the dual of 
+`(>>=)`.
+
+Laws:
+
+- Associativity: `extend f <<< extend g = extend (f <<< extend g)`
 
 #### `extendArr`
 
@@ -179,6 +251,7 @@ instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
 (=>>) :: forall b a w. (Extend w) => w a -> (w a -> b) -> w b
 ```
 
+A version of `(<<=)` with its arguments reversed
 
 #### `(=>=)`
 
@@ -186,6 +259,7 @@ instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
 (=>=) :: forall b a w c. (Extend w) => (w a -> b) -> (w b -> c) -> w a -> c
 ```
 
+Forwards co-Kleisli composition
 
 #### `(=<=)`
 
@@ -193,6 +267,7 @@ instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
 (=<=) :: forall b a w c. (Extend w) => (w b -> c) -> (w a -> b) -> w a -> c
 ```
 
+Backwards co-Kleisli composition
 
 #### `duplicate`
 
@@ -200,16 +275,23 @@ instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 ```
 
+Duplicate a comonadic context
+
+`duplicate` is dual to `join`.
 
 
 ## Module Control.Functor
 
+
+This module defines helper functions for working with `Functor` instances
+
 #### `(<$)`
 
 ``` purescript
 (<$) :: forall f a b. (Functor f) => a -> f b -> f a
 ```
 
+Ignore the return value of a computation, using the specified return value instead
 
 #### `($>)`
 
@@ -217,10 +299,15 @@ duplicate :: forall a w. (Extend w) => w a -> w (w a)
 ($>) :: forall f a b. (Functor f) => f a -> b -> f b
 ```
 
+A version of `(<$)` with its arguments flipped
 
 
 ## Module Control.Lazy
 
+
+This module defines the `Lazy` type class and associated
+helper functions.
+
 #### `Lazy`
 
 ``` purescript
@@ -228,6 +315,11 @@ class Lazy l where
   defer :: (Unit -> l) -> l
 ```
 
+The `Lazy` class represents types which allow evaluation of values
+to be _deferred_.
+
+Usually, this means that a type contains a function arrow which can
+be used to delay evaluation.
 
 #### `Lazy1`
 
@@ -236,6 +328,7 @@ class Lazy1 l where
   defer1 :: forall a. (Unit -> l a) -> l a
 ```
 
+A version of `Lazy` for type constructors of one type argument
 
 #### `Lazy2`
 
@@ -244,6 +337,7 @@ class Lazy2 l where
   defer2 :: forall a b. (Unit -> l a b) -> l a b
 ```
 
+A version of `Lazy` for type constructors of two type arguments
 
 #### `fix`
 
@@ -251,6 +345,9 @@ class Lazy2 l where
 fix :: forall l a. (Lazy l) => (l -> l) -> l
 ```
 
+`fix` defines a value as the fixed point of a function.
+
+The `Lazy` instance allows us to generate the result lazily.
 
 #### `fix1`
 
@@ -258,6 +355,7 @@ fix :: forall l a. (Lazy l) => (l -> l) -> l
 fix1 :: forall l a. (Lazy1 l) => (l a -> l a) -> l a
 ```
 
+A version of `fix` for type constructors of one type argument
 
 #### `fix2`
 
@@ -265,16 +363,21 @@ fix1 :: forall l a. (Lazy1 l) => (l a -> l a) -> l a
 fix2 :: forall l a b. (Lazy2 l) => (l a b -> l a b) -> l a b
 ```
 
+A version of `fix` for type constructors of two type arguments
 
 
 ## Module Control.Monad
 
+
+This module defines helper functions for working with `Monad` instances
+
 #### `replicateM`
 
 ``` purescript
 replicateM :: forall m a. (Monad m) => Number -> m a -> m [a]
 ```
 
+Perform a monadic action `n` times collecting all of the results
 
 #### `foldM`
 
@@ -282,6 +385,7 @@ replicateM :: forall m a. (Monad m) => Number -> m a -> m [a]
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
 ```
 
+Perform a fold using a monadic step function
 
 #### `when`
 
@@ -289,6 +393,7 @@ foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
 when :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 ```
 
+Perform a monadic action when a condition is true.
 
 #### `unless`
 
@@ -296,6 +401,7 @@ when :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 unless :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 ```
 
+Perform a monadic action unless a condition is true.
 
 #### `filterM`
 
@@ -303,7 +409,9 @@ unless :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 filterM :: forall a m. (Monad m) => (a -> m Boolean) -> [a] -> m [a]
 ```
 
-Filter where the predicate returns a monadic Boolean. For example: 
+Filter where the predicate returns a monadic `Boolean`.
+
+For example: 
 
 ```purescript
 powerSet :: forall a. [a] -> [[a]]
@@ -313,6 +421,9 @@ powerSet = filterM (const [true, false])
 
 ## Module Control.MonadPlus
 
+
+This module defines the `MonadPlus` type class.
+
 #### `MonadPlus`
 
 ``` purescript
@@ -334,10 +445,28 @@ laws:
 guard :: forall m. (MonadPlus m) => Boolean -> m Unit
 ```
 
+Fail using `Plus` if a condition does not hold, or
+succeed using `Monad` if it does.
+
+For example:
+
+```purescript
+import Data.Array
+
+factors :: Number -> [Number]
+factors n = do
+  a <- 1 .. n
+  b <- 1 .. a
+  guard $ a * b == n
+  return a
+```
 
 
 ## Module Control.Plus
 
+
+This module defines the `Plus` type class.
+
 #### `Plus`
 
 ``` purescript
diff --git a/src/Control/Alternative.purs b/src/Control/Alternative.purs
index 6ee9670..048a0bb 100644
--- a/src/Control/Alternative.purs
+++ b/src/Control/Alternative.purs
@@ -1,3 +1,6 @@
+-- | This module defines the `Alternative` type class and associated
+-- | helper functions.
+
 module Control.Alternative where
 
 import Control.Alt
@@ -14,9 +17,18 @@ import Control.Plus
 -- | - Annihilation: `empty <*> f = empty`
 class (Applicative f, Plus f) <= Alternative f
 
+-- | Attempt a computation multiple times, requiring at least one success.
+-- |
+-- | The `Lazy` constraint is used to generate the result lazily, to ensure
+-- | termination.
 some :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 some v = (:) <$> v <*> defer1 (\_ -> many v)
 
+-- | Attempt a computation multiple times, returning as many successful results
+-- | as possible (possibly zero).
+-- |
+-- | The `Lazy` constraint is used to generate the result lazily, to ensure
+-- | termination.
 many :: forall f a. (Alternative f, Lazy1 f) => f a -> f [a]
 many v = some v <|> pure []
 
diff --git a/src/Control/Bind.purs b/src/Control/Bind.purs
index 4ea7180..a33be44 100644
--- a/src/Control/Bind.purs
+++ b/src/Control/Bind.purs
@@ -1,20 +1,43 @@
+-- | This module defines helper functions for working with `Bind` instances.
+
 module Control.Bind where
 
   infixr 1 =<<
   infixr 1 >=>
   infixr 1 <=<
 
+  -- | A version of `(>>=)` with its arguments reversed
   (=<<) :: forall a b m. (Bind m) => (a -> m b) -> m a -> m b
   (=<<) f m = m >>= f
 
+  -- | Forwards Kleisli composition
+  -- |
+  -- | For example:
+  -- | 
+  -- | ```purescript
+  -- | import Data.Array (head, tail)
+  -- | 
+  -- | third = tail >=> tail >=> head
+  -- | ```
   (>=>) :: forall a b c m. (Bind m) => (a -> m b) -> (b -> m c) -> a -> m c
   (>=>) f g a = f a >>= g
 
+  -- | Backwards Kleisli composition
   (<=<) :: forall a b c m. (Bind m) => (b -> m c) -> (a -> m b) -> a -> m c
   (<=<) f g a = f =<< g a
 
+  -- | Collapse two applications of a monadic type constructor into one.
   join :: forall a m. (Bind m) => m (m a) -> m a
   join m = m >>= id
 
+  -- | Execute a monadic action if a condition holds. 
+  -- | 
+  -- | For example:
+  -- |
+  -- | ```purescript
+  -- | main = ifM ((< 0.5) <$> random)
+  -- |          (trace "Heads")
+  -- |          (trace "Tails")
+  -- | ```
   ifM :: forall a m. (Bind m) => m Boolean -> m a -> m a -> m a
   ifM cond t f = cond >>= \cond' -> if cond' then t else f
diff --git a/src/Control/Comonad.purs b/src/Control/Comonad.purs
index f96439b..d210761 100644
--- a/src/Control/Comonad.purs
+++ b/src/Control/Comonad.purs
@@ -6,6 +6,9 @@ import Control.Extend
 
 -- | `Comonad` extends the `Extend` class with the `extract` function
 -- | which extracts a value, discarding the comonadic context.
+-- |
+-- | `Comonad` is the dual of `Monad`, and `extract` is the dual of 
+-- | `pure` or `return`.
 -- | 
 -- | Laws:
 -- |
diff --git a/src/Control/Extend.purs b/src/Control/Extend.purs
index 1a0f465..57188d7 100644
--- a/src/Control/Extend.purs
+++ b/src/Control/Extend.purs
@@ -11,6 +11,9 @@ infixr 1 =<=
 -- | which extends a local context-dependent computation to
 -- | a global computation.
 -- |
+-- | `Extend` is the dual of `Bind`, and `(<<=)` is the dual of 
+-- | `(>>=)`.
+-- |
 -- | Laws:
 -- |
 -- | - Associativity: `extend f <<< extend g = extend (f <<< extend g)`
@@ -33,5 +36,7 @@ instance extendArr :: (Semigroup w) => Extend ((->) w) where
 (=<=) f g w = f (g <<= w)
 
 -- | Duplicate a comonadic context
+-- |
+-- | `duplicate` is dual to `join`.
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 duplicate w = id <<= w
diff --git a/src/Control/Lazy.purs b/src/Control/Lazy.purs
index d801925..10e21d9 100644
--- a/src/Control/Lazy.purs
+++ b/src/Control/Lazy.purs
@@ -1,19 +1,34 @@
+-- | This module defines the `Lazy` type class and associated
+-- | helper functions.
+
 module Control.Lazy where
 
+-- | The `Lazy` class represents types which allow evaluation of values
+-- | to be _deferred_.
+-- |
+-- | Usually, this means that a type contains a function arrow which can
+-- | be used to delay evaluation.
 class Lazy l where
   defer :: (Unit -> l) -> l
 
+-- | A version of `Lazy` for type constructors of one type argument
 class Lazy1 l where
   defer1 :: forall a. (Unit -> l a) -> l a
 
+-- | A version of `Lazy` for type constructors of two type arguments
 class Lazy2 l where
   defer2 :: forall a b. (Unit -> l a b) -> l a b
 
+-- | `fix` defines a value as the fixed point of a function.
+-- |
+-- | The `Lazy` instance allows us to generate the result lazily.
 fix :: forall l a. (Lazy l) => (l -> l) -> l
 fix f = defer (\_ -> f (fix f))
 
+-- | A version of `fix` for type constructors of one type argument
 fix1 :: forall l a. (Lazy1 l) => (l a -> l a) -> l a
 fix1 f = defer1 (\_ -> f (fix1 f))
 
+-- | A version of `fix` for type constructors of two type arguments
 fix2 :: forall l a b. (Lazy2 l) => (l a b -> l a b) -> l a b
 fix2 f = defer2 (\_ -> f (fix2 f))
diff --git a/src/Control/MonadPlus.purs b/src/Control/MonadPlus.purs
index ea4cfa3..f91cb62 100644
--- a/src/Control/MonadPlus.purs
+++ b/src/Control/MonadPlus.purs
@@ -1,3 +1,5 @@
+-- | This module defines the `MonadPlus` type class.
+
 module Control.MonadPlus where
 
 import Control.Alternative
@@ -13,6 +15,21 @@ import Control.Plus
 -- | - Annihilation: `empty >>= f = empty`
 class (Monad m, Alternative m) <= MonadPlus m
 
+-- | Fail using `Plus` if a condition does not hold, or
+-- | succeed using `Monad` if it does.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | import Data.Array
+-- | 
+-- | factors :: Number -> [Number]
+-- | factors n = do
+-- |   a <- 1 .. n
+-- |   b <- 1 .. a
+-- |   guard $ a * b == n
+-- |   return a
+-- | ```
 guard :: forall m. (MonadPlus m) => Boolean -> m Unit
 guard true = return unit
 guard false = empty
diff --git a/src/Control/Plus.purs b/src/Control/Plus.purs
index 5fa8176..21c6645 100644
--- a/src/Control/Plus.purs
+++ b/src/Control/Plus.purs
@@ -1,3 +1,5 @@
+-- | This module defines the `Plus` type class.
+
 module Control.Plus where
 
 import Control.Alt

From f7e6cb50e45ee1097188d6711102f54288724ca5 Mon Sep 17 00:00:00 2001
From: Phil Freeman <paf31@cantab.net>
Date: Sun, 22 Mar 2015 14:24:05 -0700
Subject: [PATCH 3/3] Consistency

---
 README.md                | 43 ++++++++++++++++++++--------------------
 src/Control/Alt.purs     |  2 +-
 src/Control/Bind.purs    |  6 +++---
 src/Control/Comonad.purs |  2 +-
 src/Control/Extend.purs  | 12 +++++------
 src/Control/Functor.purs |  6 +++---
 src/Control/Lazy.purs    |  8 ++++----
 src/Control/Monad.purs   |  6 +++---
 src/Control/Plus.purs    |  1 +
 9 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index d7eadb1..87c9089 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 ## Module Control.Alt
 
 
-This module defines the `Alt` type class
+This module defines the `Alt` type class.
 
 #### `Alt`
 
@@ -140,7 +140,7 @@ This module defines helper functions for working with `Bind` instances.
 (=<<) :: forall a b m. (Bind m) => (a -> m b) -> m a -> m b
 ```
 
-A version of `(>>=)` with its arguments reversed
+A version of `(>>=)` with its arguments flipped.
 
 #### `(>=>)`
 
@@ -148,7 +148,7 @@ A version of `(>>=)` with its arguments reversed
 (>=>) :: forall a b c m. (Bind m) => (a -> m b) -> (b -> m c) -> a -> m c
 ```
 
-Forwards Kleisli composition
+Forwards Kleisli composition.
 
 For example:
 
@@ -164,7 +164,7 @@ third = tail >=> tail >=> head
 (<=<) :: forall a b c m. (Bind m) => (b -> m c) -> (a -> m b) -> a -> m c
 ```
 
-Backwards Kleisli composition
+Backwards Kleisli composition.
 
 #### `join`
 
@@ -194,7 +194,7 @@ main = ifM ((< 0.5) <$> random)
 ## Module Control.Comonad
 
 
-This module defines the `Comonad` type class
+This module defines the `Comonad` type class.
 
 #### `Comonad`
 
@@ -218,7 +218,7 @@ Laws:
 ## Module Control.Extend
 
 
-This module defines the `Extend` type class and associated helper functions
+This module defines the `Extend` type class and associated helper functions.
 
 #### `Extend`
 
@@ -251,7 +251,7 @@ instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
 (=>>) :: forall b a w. (Extend w) => w a -> (w a -> b) -> w b
 ```
 
-A version of `(<<=)` with its arguments reversed
+A version of `(<<=)` with its arguments flipped.
 
 #### `(=>=)`
 
@@ -259,7 +259,7 @@ A version of `(<<=)` with its arguments reversed
 (=>=) :: forall b a w c. (Extend w) => (w a -> b) -> (w b -> c) -> w a -> c
 ```
 
-Forwards co-Kleisli composition
+Forwards co-Kleisli composition.
 
 #### `(=<=)`
 
@@ -267,7 +267,7 @@ Forwards co-Kleisli composition
 (=<=) :: forall b a w c. (Extend w) => (w b -> c) -> (w a -> b) -> w a -> c
 ```
 
-Backwards co-Kleisli composition
+Backwards co-Kleisli composition.
 
 #### `duplicate`
 
@@ -275,15 +275,15 @@ Backwards co-Kleisli composition
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 ```
 
-Duplicate a comonadic context
+Duplicate a comonadic context.
 
-`duplicate` is dual to `join`.
+`duplicate` is dual to `Control.Bind.join`.
 
 
 ## Module Control.Functor
 
 
-This module defines helper functions for working with `Functor` instances
+This module defines helper functions for working with `Functor` instances.
 
 #### `(<$)`
 
@@ -291,7 +291,7 @@ This module defines helper functions for working with `Functor` instances
 (<$) :: forall f a b. (Functor f) => a -> f b -> f a
 ```
 
-Ignore the return value of a computation, using the specified return value instead
+Ignore the return value of a computation, using the specified return value instead.
 
 #### `($>)`
 
@@ -299,7 +299,7 @@ Ignore the return value of a computation, using the specified return value inste
 ($>) :: forall f a b. (Functor f) => f a -> b -> f b
 ```
 
-A version of `(<$)` with its arguments flipped
+A version of `(<$)` with its arguments flipped.
 
 
 ## Module Control.Lazy
@@ -328,7 +328,7 @@ class Lazy1 l where
   defer1 :: forall a. (Unit -> l a) -> l a
 ```
 
-A version of `Lazy` for type constructors of one type argument
+A version of `Lazy` for type constructors of one type argument.
 
 #### `Lazy2`
 
@@ -337,7 +337,7 @@ class Lazy2 l where
   defer2 :: forall a b. (Unit -> l a b) -> l a b
 ```
 
-A version of `Lazy` for type constructors of two type arguments
+A version of `Lazy` for type constructors of two type arguments.
 
 #### `fix`
 
@@ -355,7 +355,7 @@ The `Lazy` instance allows us to generate the result lazily.
 fix1 :: forall l a. (Lazy1 l) => (l a -> l a) -> l a
 ```
 
-A version of `fix` for type constructors of one type argument
+A version of `fix` for type constructors of one type argument.
 
 #### `fix2`
 
@@ -363,13 +363,13 @@ A version of `fix` for type constructors of one type argument
 fix2 :: forall l a b. (Lazy2 l) => (l a b -> l a b) -> l a b
 ```
 
-A version of `fix` for type constructors of two type arguments
+A version of `fix` for type constructors of two type arguments.
 
 
 ## Module Control.Monad
 
 
-This module defines helper functions for working with `Monad` instances
+This module defines helper functions for working with `Monad` instances.
 
 #### `replicateM`
 
@@ -377,7 +377,7 @@ This module defines helper functions for working with `Monad` instances
 replicateM :: forall m a. (Monad m) => Number -> m a -> m [a]
 ```
 
-Perform a monadic action `n` times collecting all of the results
+Perform a monadic action `n` times collecting all of the results.
 
 #### `foldM`
 
@@ -385,7 +385,7 @@ Perform a monadic action `n` times collecting all of the results
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
 ```
 
-Perform a fold using a monadic step function
+Perform a fold using a monadic step function.
 
 #### `when`
 
@@ -476,6 +476,7 @@ class (Alt f) <= Plus f where
 
 The `Plus` type class extends the `Alt` type class with a value that
 should be the left and right identity for `(<|>)`.
+
 It is similar to `Monoid`, except that it applies to types of
 kind `* -> *`, like `Array` or `List`, rather than concrete types like
 `String` or `Number`.
diff --git a/src/Control/Alt.purs b/src/Control/Alt.purs
index c53374a..b1877c4 100644
--- a/src/Control/Alt.purs
+++ b/src/Control/Alt.purs
@@ -1,4 +1,4 @@
--- | This module defines the `Alt` type class
+-- | This module defines the `Alt` type class.
 
 module Control.Alt where
 
diff --git a/src/Control/Bind.purs b/src/Control/Bind.purs
index a33be44..31dcfc9 100644
--- a/src/Control/Bind.purs
+++ b/src/Control/Bind.purs
@@ -6,11 +6,11 @@ module Control.Bind where
   infixr 1 >=>
   infixr 1 <=<
 
-  -- | A version of `(>>=)` with its arguments reversed
+  -- | A version of `(>>=)` with its arguments flipped.
   (=<<) :: forall a b m. (Bind m) => (a -> m b) -> m a -> m b
   (=<<) f m = m >>= f
 
-  -- | Forwards Kleisli composition
+  -- | Forwards Kleisli composition.
   -- |
   -- | For example:
   -- | 
@@ -22,7 +22,7 @@ module Control.Bind where
   (>=>) :: forall a b c m. (Bind m) => (a -> m b) -> (b -> m c) -> a -> m c
   (>=>) f g a = f a >>= g
 
-  -- | Backwards Kleisli composition
+  -- | Backwards Kleisli composition.
   (<=<) :: forall a b c m. (Bind m) => (b -> m c) -> (a -> m b) -> a -> m c
   (<=<) f g a = f =<< g a
 
diff --git a/src/Control/Comonad.purs b/src/Control/Comonad.purs
index d210761..ffd71f0 100644
--- a/src/Control/Comonad.purs
+++ b/src/Control/Comonad.purs
@@ -1,4 +1,4 @@
--- | This module defines the `Comonad` type class
+-- | This module defines the `Comonad` type class.
 
 module Control.Comonad where
 
diff --git a/src/Control/Extend.purs b/src/Control/Extend.purs
index 57188d7..25cc250 100644
--- a/src/Control/Extend.purs
+++ b/src/Control/Extend.purs
@@ -1,4 +1,4 @@
--- | This module defines the `Extend` type class and associated helper functions
+-- | This module defines the `Extend` type class and associated helper functions.
 
 module Control.Extend where
 
@@ -23,20 +23,20 @@ class (Functor w) <= Extend w where
 instance extendArr :: (Semigroup w) => Extend ((->) w) where
   (<<=) f g w = f \w' -> g (w <> w')
 
--- | A version of `(<<=)` with its arguments reversed
+-- | A version of `(<<=)` with its arguments flipped.
 (=>>) :: forall b a w. (Extend w) => w a -> (w a -> b) -> w b
 (=>>) w f = f <<= w
 
--- | Forwards co-Kleisli composition
+-- | Forwards co-Kleisli composition.
 (=>=) :: forall b a w c. (Extend w) => (w a -> b) -> (w b -> c) -> w a -> c
 (=>=) f g w = g (f <<= w)
 
--- | Backwards co-Kleisli composition
+-- | Backwards co-Kleisli composition.
 (=<=) :: forall b a w c. (Extend w) => (w b -> c) -> (w a -> b) -> w a -> c
 (=<=) f g w = f (g <<= w)
 
--- | Duplicate a comonadic context
+-- | Duplicate a comonadic context.
 -- |
--- | `duplicate` is dual to `join`.
+-- | `duplicate` is dual to `Control.Bind.join`.
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 duplicate w = id <<= w
diff --git a/src/Control/Functor.purs b/src/Control/Functor.purs
index 7ac30fa..2d7684a 100644
--- a/src/Control/Functor.purs
+++ b/src/Control/Functor.purs
@@ -1,14 +1,14 @@
--- | This module defines helper functions for working with `Functor` instances
+-- | This module defines helper functions for working with `Functor` instances.
 
 module Control.Functor where
 
 infixl 4 <$
 infixl 4 $>
 
--- | Ignore the return value of a computation, using the specified return value instead
+-- | Ignore the return value of a computation, using the specified return value instead.
 (<$) :: forall f a b. (Functor f) => a -> f b -> f a
 (<$) x f = const x <$> f
 
--- | A version of `(<$)` with its arguments flipped
+-- | A version of `(<$)` with its arguments flipped.
 ($>) :: forall f a b. (Functor f) => f a -> b -> f b
 ($>) f x = const x <$> f
diff --git a/src/Control/Lazy.purs b/src/Control/Lazy.purs
index 10e21d9..20f4a26 100644
--- a/src/Control/Lazy.purs
+++ b/src/Control/Lazy.purs
@@ -11,11 +11,11 @@ module Control.Lazy where
 class Lazy l where
   defer :: (Unit -> l) -> l
 
--- | A version of `Lazy` for type constructors of one type argument
+-- | A version of `Lazy` for type constructors of one type argument.
 class Lazy1 l where
   defer1 :: forall a. (Unit -> l a) -> l a
 
--- | A version of `Lazy` for type constructors of two type arguments
+-- | A version of `Lazy` for type constructors of two type arguments.
 class Lazy2 l where
   defer2 :: forall a b. (Unit -> l a b) -> l a b
 
@@ -25,10 +25,10 @@ class Lazy2 l where
 fix :: forall l a. (Lazy l) => (l -> l) -> l
 fix f = defer (\_ -> f (fix f))
 
--- | A version of `fix` for type constructors of one type argument
+-- | A version of `fix` for type constructors of one type argument.
 fix1 :: forall l a. (Lazy1 l) => (l a -> l a) -> l a
 fix1 f = defer1 (\_ -> f (fix1 f))
 
--- | A version of `fix` for type constructors of two type arguments
+-- | A version of `fix` for type constructors of two type arguments.
 fix2 :: forall l a b. (Lazy2 l) => (l a b -> l a b) -> l a b
 fix2 f = defer2 (\_ -> f (fix2 f))
diff --git a/src/Control/Monad.purs b/src/Control/Monad.purs
index 1b1d90c..a9b58e8 100644
--- a/src/Control/Monad.purs
+++ b/src/Control/Monad.purs
@@ -1,8 +1,8 @@
--- | This module defines helper functions for working with `Monad` instances
+-- | This module defines helper functions for working with `Monad` instances.
 
 module Control.Monad where
 
--- | Perform a monadic action `n` times collecting all of the results
+-- | Perform a monadic action `n` times collecting all of the results.
 replicateM :: forall m a. (Monad m) => Number -> m a -> m [a]
 replicateM 0 _ = return []
 replicateM n m = do
@@ -10,7 +10,7 @@ replicateM n m = do
   as <- replicateM (n - 1) m
   return (a : as)
 
--- | Perform a fold using a monadic step function
+-- | Perform a fold using a monadic step function.
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
 foldM _ a [] = return a
 foldM f a (b:bs) = f a b >>= \a' -> foldM f a' bs
diff --git a/src/Control/Plus.purs b/src/Control/Plus.purs
index 21c6645..ac31857 100644
--- a/src/Control/Plus.purs
+++ b/src/Control/Plus.purs
@@ -6,6 +6,7 @@ import Control.Alt
 
 -- | The `Plus` type class extends the `Alt` type class with a value that
 -- | should be the left and right identity for `(<|>)`.
+-- |
 -- | It is similar to `Monoid`, except that it applies to types of
 -- | kind `* -> *`, like `Array` or `List`, rather than concrete types like
 -- | `String` or `Number`.