More docs for Alt, Plus, MonadPlus

Author: hdgarrood

README.md

@@ -17,7 +17,7 @@ kind `* -> *`, like `Array` or `List`, rather than concrete types like
 `Alt` instances are required to satisfy the following laws:
 
 - Associativity: `(x <|> y) <|> z == x <|> (y <|> z)`
-- Distribution: `f <$> (x <|> y) == (f <$> x) <|> (f <$> y)`
+- Distributivity: `f <$> (x <|> y) == (f <$> x) <|> (f <$> y)`
 
 For example, the `Array` (`[]`) type is an instance of `Alt`, where
 `(<|>)` is defined to be concatenation.
@@ -298,6 +298,13 @@ unless :: forall m. (Monad m) => Boolean -> m Unit -> m Unit
 class (Monad m, Alternative m) <= MonadPlus m where
 ```
 
+The `MonadPlus` type class has none of its own functions; it just
+specifies that the type has both `Monad` and `Alternative` instances.
+
+Types which have `MonadPlus` instances should also satisfy the following
+law:
+
+- Left distributivity: `(x <|> y) >>= f == (x >>= f) <|> (y >>= f)`
 
 #### `guard`
 
@@ -326,5 +333,4 @@ kind `* -> *`, like `Array` or `List`, rather than concrete types like
 
 - Left identity: `empty <|> x == x`
 - Right identity: `x <|> empty == x`
-- ???: `f <$> empty == empty`
-- Left distribution: `(x <|> y) >>= f == (x >>= f) <|> (y >>= f)`
+- ???: `f <$> empty == empty`

src/Control/Alt.purs

@@ -10,7 +10,7 @@ infixl 3 <|>
 -- | `Alt` instances are required to satisfy the following laws:
 -- |
 -- | - Associativity: `(x <|> y) <|> z == x <|> (y <|> z)`
--- | - Distribution: `f <$> (x <|> y) == (f <$> x) <|> (f <$> y)`
+-- | - Distributivity: `f <$> (x <|> y) == (f <$> x) <|> (f <$> y)`
 -- |
 -- | For example, the `Array` (`[]`) type is an instance of `Alt`, where
 -- | `(<|>)` is defined to be concatenation.

src/Control/MonadPlus.purs

@@ -3,6 +3,13 @@ module Control.MonadPlus where
 import Control.Alternative
 import Control.Plus
 
+-- | The `MonadPlus` type class has none of its own functions; it just
+-- | specifies that the type has both `Monad` and `Alternative` instances.
+-- |
+-- | Types which have `MonadPlus` instances should also satisfy the following
+-- | law:
+-- |
+-- | - Left distributivity: `(x <|> y) >>= f == (x >>= f) <|> (y >>= f)`
 class (Monad m, Alternative m) <= MonadPlus m
 
 guard :: forall m. (MonadPlus m) => Boolean -> m Unit

src/Control/Plus.purs

@@ -13,6 +13,5 @@ import Control.Alt
 -- | - Left identity: `empty <|> x == x`
 -- | - Right identity: `x <|> empty == x`
 -- | - ???: `f <$> empty == empty`
--- | - Left distribution: `(x <|> y) >>= f == (x >>= f) <|> (y >>= f)`
 class (Alt f) <= Plus f where
   empty :: forall a. f a