Merge pull request #19 from purescript/docs

Docs

src/Control/Alt.purs

@@ -1,3 +1,5 @@
+-- | This module defines the `Alt` type class.
+
 module Control.Alt where
 
 infixl 3 <|>

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

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

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 flipped.
   (=<<) :: 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/Comonad.purs

@@ -1,6 +1,18 @@
+-- | 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.
+-- |
+-- | `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`
 class (Extend w) <= Comonad w where
   extract :: forall a. w a -> a

src/Control/Extend.purs

@@ -1,24 +1,42 @@
+-- | This module defines the `Extend` type class and associated helper functions.
+
 module Control.Extend where
 
 infixl 1 =>>
 infixr 1 <<=
 infixr 1 =>=
 infixr 1 =<=
 
+-- | 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)`
 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 flipped.
 (=>>) :: 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` is dual to `Control.Bind.join`.
 duplicate :: forall a w. (Extend w) => w a -> w (w a)
 duplicate w = id <<= w

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

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))

src/Control/Monad.purs

@@ -1,25 +1,33 @@
+-- | 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
   a <- m
   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]]

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

src/Control/Plus.purs

@@ -1,9 +1,12 @@
+-- | This module defines the `Plus` type class.
+
 module Control.Plus where
 
 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`.