Docs

Author: paf31

README.md

@@ -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 []
 

src/Control/Alternative.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

src/Control/Bind.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:
 -- |

src/Control/Comonad.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

src/Control/Extend.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))

src/Control/Lazy.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

src/Control/MonadPlus.purs

@@ -1,3 +1,5 @@
+-- | This module defines the `Plus` type class.
+
 module Control.Plus where
 
 import Control.Alt