A start on more docs

Author: paf31

src/Control/Alt.purs

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

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

src/Control/Extend.purs

@@ -1,24 +1,37 @@
+-- | 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.
+-- |
+-- | 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

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