Merge pull request #5 from purescript/docs

First stab at docs

Author: paf31

docs/Module.md

@@ -9,6 +9,8 @@ class (Biapply w) <= Biapplicative w where
   bipure :: forall a b. a -> b -> w a b
 ```
 
+`Biapplicative` captures type constructors of two arguments which support lifting of
+functions of zero or more arguments, in the sense of `Applicative`.
 
 #### `biapplicativeTuple`
 
@@ -33,6 +35,12 @@ instance biapplicativeConst :: Biapplicative Const
 (<<$>>) :: forall a b. (a -> b) -> a -> b
 ```
 
+A convenience function which can be used to apply the result of `bipure` in
+the style of `Applicative`:
+
+```purescript
+bipure f g <<$>> x <<*>> y
+```
 
 #### `Biapply`
 
@@ -41,34 +49,40 @@ class (Bifunctor w) <= Biapply w where
   (<<*>>) :: forall a b c d. w (a -> b) (c -> d) -> w a c -> w b d
 ```
 
+`Biapply` captures type constructors of two arguments which support lifting of
+functions of one or more arguments, in the sense of `Apply`.
 
 #### `(*>>)`
 
 ``` purescript
 (*>>) :: forall w a b c d. (Biapply w) => w a b -> w c d -> w c d
 ```
 
+Keep the results of the second computation
 
 #### `(<<*)`
 
 ``` purescript
 (<<*) :: forall w a b c d. (Biapply w) => w a b -> w c d -> w a b
 ```
 
+Keep the results of the first computation
 
 #### `bilift2`
 
 ``` purescript
 bilift2 :: forall w a b c d e f. (Biapply w) => (a -> b -> c) -> (d -> e -> f) -> w a d -> w b e -> w c f
 ```
 
+Lift a function of two arguments.
 
 #### `bilift3`
 
 ``` purescript
 bilift3 :: forall w a b c d e f g h. (Biapply w) => (a -> b -> c -> d) -> (e -> f -> g -> h) -> w a e -> w b f -> w c g -> w d h
 ```
 
+Lift a function of three arguments.
 
 #### `biapplyTuple`
 
@@ -96,6 +110,13 @@ class Bifoldable p where
   bifoldMap :: forall m a b. (Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
 ```
 
+`Bifoldable` represents data structures with two type arguments which can be 
+folded.
+
+A fold for such a structure requires two step functions, one for each type 
+argument. Type class instances should choose the appropriate step function based
+on the type of the element encountered at each point of the fold.
+
 
 #### `bifoldableTuple`
 
@@ -124,41 +145,49 @@ instance bifoldableConst :: Bifoldable Const
 bifold :: forall t m. (Bifoldable t, Monoid m) => t m m -> m
 ```
 
+Fold a data structure, accumulating values in a monoidal type.
 
 #### `bitraverse_`
 
 ``` purescript
 bitraverse_ :: forall t f a b c d. (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f Unit
 ```
 
+Traverse a data structure, accumulating effects using an `Applicative` functor,
+ignoring the final result.
 
 #### `bifor_`
 
 ``` purescript
 bifor_ :: forall t f a b c d. (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f Unit
 ```
 
+A version of `bitraverse_` with the data structure as the first argument.
 
 #### `bisequence_`
 
 ``` purescript
 bisequence_ :: forall t f a b. (Bifoldable t, Applicative f) => t (f a) (f b) -> f Unit
 ```
 
+Collapse a data structure, collecting effects using an `Applicative` functor,
+ignoring the final result.
 
 #### `biany`
 
 ``` purescript
 biany :: forall t a b. (Bifoldable t) => (a -> Boolean) -> (b -> Boolean) -> t a b -> Boolean
 ```
 
+Test whether a predicate holds at any position in a data structure.
 
 #### `biall`
 
 ``` purescript
 biall :: forall t a b. (Bifoldable t) => (a -> Boolean) -> (b -> Boolean) -> t a b -> Boolean
 ```
 
+Test whether a predicate holds at all positions in a data structure.
 
 
 ## Module Data.Bifunctor
@@ -170,20 +199,35 @@ class Bifunctor f where
   bimap :: forall a b c d. (a -> b) -> (c -> d) -> f a c -> f b d
 ```
 
+A `Bifunctor` is a `Functor` from the pair category `(Type, Type)` to `Type`.
+
+A type constructor with two type arguments can be made into a `Bifunctor` if
+both of its type arguments are covariant.
+
+The `bimap` function maps a pair of functions over the two type arguments
+of the bifunctor.
+
+Laws:
+
+- Identity: `bimap id id == id`
+- Composition: `bimap f1 g1 <<< bimap f2 g2 == bimap (f1 <<< f2) (g1 <<< g2)`
+
 
 #### `lmap`
 
 ``` purescript
 lmap :: forall f a b c. (Bifunctor f) => (a -> b) -> f a c -> f b c
 ```
 
+Map a function over the first type argument of a `Bifunctor`.
 
 #### `rmap`
 
 ``` purescript
 rmap :: forall f a b c. (Bifunctor f) => (b -> c) -> f a b -> f a c
 ```
 
+Map a function over the second type component of a `Bifunctor`.
 
 #### `bifunctorEither`
 
@@ -290,13 +334,16 @@ data Flip p a b
   = Flip (p b a)
 ```
 
+Flips the order of the type arguments of a `Bifunctor`, creating a
+`Functor` instance for the first type argument.
 
 #### `runFlip`
 
 ``` purescript
 runFlip :: forall p a b. Flip p a b -> p b a
 ```
 
+Remove the `Flip` constructor.
 
 #### `flipBifunctor`
 
@@ -364,13 +411,16 @@ data Join p a
   = Join (p a a)
 ```
 
+`Join` turns a `Bifunctor` into a `Functor` by equating the
+two type arguments.
 
 #### `runJoin`
 
 ``` purescript
 runJoin :: forall p a. Join p a -> p a a
 ```
 
+Remove the `Join` constructor.
 
 #### `joinFunctor`
 
@@ -491,6 +541,7 @@ data Product f g a b
   = Pair (f a b) (g a b)
 ```
 
+The product of two `Bifunctor`s.
 
 #### `productBifunctor`
 
@@ -536,13 +587,16 @@ data Wrap p a b
   = Wrap (p a b)
 ```
 
+A `newtype` wrapper which provides default `Functor`, `Foldable` and `Traversable`
+type class instances for `Bifunctor`s.
 
 #### `unwrap`
 
 ``` purescript
 unwrap :: forall p a b. Wrap p a b -> p a b
 ```
 
+Remove the `Wrap` constructor.
 
 #### `wrapBifunctor`
 
@@ -611,6 +665,13 @@ class (Bifunctor t, Bifoldable t) <= Bitraversable t where
   bisequence :: forall f a b. (Applicative f) => t (f a) (f b) -> f (t a b)
 ```
 
+`Bitraversable` represents data structures with two type arguments which can be 
+traversed.
+
+A traversal for such a structure requires two functions, one for each type 
+argument. Type class instances should choose the appropriate function based
+on the type of the element encountered at each point of the traversal.
+
 
 #### `bitraversableTuple`
 
@@ -637,4 +698,6 @@ instance bitraversableConst :: Bitraversable Const
 
 ``` purescript
 bifor :: forall t f a b c d. (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)
-```
+```
+
+Traverse a data structure, accumulating effects and results using an `Applicative` functor.

src/Control/Biapplicative.purs

@@ -5,6 +5,8 @@ import Data.Tuple
 
 import Control.Biapply
 
+-- | `Biapplicative` captures type constructors of two arguments which support lifting of
+-- | functions of zero or more arguments, in the sense of `Applicative`.
 class (Biapply w) <= Biapplicative w where
   bipure :: forall a b. a -> b -> w a b
 

src/Control/Biapply.purs

@@ -11,21 +11,33 @@ infixl 4 <<*>>
 infixl 4 <<*
 infixl 4 *>>
 
+-- | A convenience function which can be used to apply the result of `bipure` in
+-- | the style of `Applicative`:
+-- |
+-- | ```purescript
+-- | bipure f g <<$>> x <<*>> y
+-- | ```
 (<<$>>) :: forall a b. (a -> b) -> a -> b
 (<<$>>) = id
 
+-- | `Biapply` captures type constructors of two arguments which support lifting of
+-- | functions of one or more arguments, in the sense of `Apply`.
 class (Bifunctor w) <= Biapply w where
   (<<*>>) :: forall a b c d. w (a -> b) (c -> d) -> w a c -> w b d
 
+-- | Keep the results of the second computation
 (*>>) :: forall w a b c d. (Biapply w) => w a b -> w c d -> w c d
 (*>>) a b = bimap (const id) (const id) <<$>> a <<*>> b
 
+-- | Keep the results of the first computation
 (<<*) :: forall w a b c d. (Biapply w) => w a b -> w c d -> w a b
 (<<*) a b = bimap const const <<$>> a <<*>> b
 
+-- | Lift a function of two arguments.
 bilift2 :: forall w a b c d e f. (Biapply w) => (a -> b -> c) -> (d -> e -> f) -> w a d -> w b e -> w c f
 bilift2 f g a b = bimap f g <<$>> a <<*>> b
 
+-- | Lift a function of three arguments.
 bilift3 :: forall w a b c d e f g h. (Biapply w) => (a -> b -> c -> d) -> (e -> f -> g -> h) -> w a e -> w b f -> w c g -> w d h
 bilift3 f g a b c = bimap f g <<$>> a <<*>> b <<*>> c
 

src/Data/Bifoldable.purs

@@ -10,6 +10,13 @@ import Data.Tuple
 import Control.Apply
 import Control.Bind
 
+-- | `Bifoldable` represents data structures with two type arguments which can be 
+-- | folded.
+-- | 
+-- | A fold for such a structure requires two step functions, one for each type 
+-- | argument. Type class instances should choose the appropriate step function based
+-- | on the type of the element encountered at each point of the fold.
+-- | 
 class Bifoldable p where
   bifoldr :: forall a b c. (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
   bifoldl :: forall a b c. (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
@@ -33,20 +40,28 @@ instance bifoldableConst :: Bifoldable Const where
   bifoldr f _ z (Const a) = f a z
   bifoldl f _ z (Const a) = f z a
 
+-- | Fold a data structure, accumulating values in a monoidal type.
 bifold :: forall t m. (Bifoldable t, Monoid m) => t m m -> m
 bifold = bifoldMap id id
 
+-- | Traverse a data structure, accumulating effects using an `Applicative` functor,
+-- | ignoring the final result.
 bitraverse_ :: forall t f a b c d. (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f Unit
 bitraverse_ f g = bifoldr ((*>) <<< f) ((*>) <<< g) (pure unit)
 
+-- | A version of `bitraverse_` with the data structure as the first argument.
 bifor_ :: forall t f a b c d. (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f Unit
 bifor_ t f g = bitraverse_ f g t
 
+-- | Collapse a data structure, collecting effects using an `Applicative` functor,
+-- | ignoring the final result.
 bisequence_ :: forall t f a b. (Bifoldable t, Applicative f) => t (f a) (f b) -> f Unit
 bisequence_ = bitraverse_ id id
 
+-- | Test whether a predicate holds at any position in a data structure.
 biany :: forall t a b. (Bifoldable t) => (a -> Boolean) -> (b -> Boolean) -> t a b -> Boolean
 biany p q = runAny <<< bifoldMap (Any <<< p) (Any <<< q)
 
+-- | Test whether a predicate holds at all positions in a data structure.
 biall :: forall t a b. (Bifoldable t) => (a -> Boolean) -> (b -> Boolean) -> t a b -> Boolean
 biall p q = runAll <<< bifoldMap (All <<< p) (All <<< q)

src/Data/Bifunctor.purs

@@ -4,12 +4,27 @@ import Data.Const
 import Data.Either
 import Data.Tuple
 
+-- | A `Bifunctor` is a `Functor` from the pair category `(Type, Type)` to `Type`.
+-- |
+-- | A type constructor with two type arguments can be made into a `Bifunctor` if
+-- | both of its type arguments are covariant.
+-- | 
+-- | The `bimap` function maps a pair of functions over the two type arguments
+-- | of the bifunctor.
+-- |
+-- | Laws:
+-- |
+-- | - Identity: `bimap id id == id`
+-- | - Composition: `bimap f1 g1 <<< bimap f2 g2 == bimap (f1 <<< f2) (g1 <<< g2)`
+-- |
 class Bifunctor f where
   bimap :: forall a b c d. (a -> b) -> (c -> d) -> f a c -> f b d
 
+-- | Map a function over the first type argument of a `Bifunctor`.
 lmap :: forall f a b c. (Bifunctor f) => (a -> b) -> f a c -> f b c
 lmap f = bimap f id
 
+-- | Map a function over the second type component of a `Bifunctor`.
 rmap :: forall f a b c. (Bifunctor f) => (b -> c) -> f a b -> f a c
 rmap = bimap id
 

src/Data/Bifunctor/Flip.purs

@@ -11,8 +11,11 @@ import Control.Apply
 import Control.Biapplicative
 import Control.Biapply
 
+-- | Flips the order of the type arguments of a `Bifunctor`, creating a
+-- | `Functor` instance for the first type argument.
 data Flip p a b = Flip (p b a)
 
+-- | Remove the `Flip` constructor.
 runFlip :: forall p a b. Flip p a b -> p b a
 runFlip (Flip pba) = pba
 

src/Data/Bifunctor/Join.purs

@@ -11,8 +11,11 @@ import Control.Apply
 import Control.Biapplicative
 import Control.Biapply
 
+-- | `Join` turns a `Bifunctor` into a `Functor` by equating the
+-- | two type arguments.
 data Join p a = Join (p a a)
 
+-- | Remove the `Join` constructor.
 runJoin :: forall p a. Join p a -> p a a
 runJoin (Join paa) = paa
 

src/Data/Bifunctor/Product.purs

@@ -13,6 +13,7 @@ import Control.Apply
 import Control.Biapplicative
 import Control.Biapply
 
+-- | The product of two `Bifunctor`s.
 data Product f g a b = Pair (f a b) (g a b)
 
 instance productBifunctor :: (Bifunctor f, Bifunctor g) => Bifunctor (Product f g) where