Merge pull request #17 from purescript/docs

Docs

Author: paf31

README.md

@@ -11,6 +11,11 @@ class Foldable f where
   foldMap :: forall a m. (Monoid m) => (a -> m) -> f a -> m
 ```
 
+`Foldable` represents data structures which can be _folded_.
+
+- `foldr` folds a structure from the right
+- `foldl` folds a structure from the left
+- `foldMap` folds a structure by accumulating values in a `Monoid`
 
 #### `foldableArray`
 
@@ -81,111 +86,154 @@ instance foldableMultiplicative :: Foldable Multiplicative
 fold :: forall f m. (Foldable f, Monoid m) => f m -> m
 ```
 
+Fold a data structure, accumulating values in some `Monoid`.
 
 #### `traverse_`
 
 ``` purescript
 traverse_ :: forall a b f m. (Applicative m, Foldable f) => (a -> m b) -> f a -> m Unit
 ```
 
+Traverse a data structure, performing some effects encoded by an
+`Applicative` functor at each value, ignoring the final result.
+
+For example:
+
+```purescript
+traverse_ print [1, 2, 3]
+```
 
 #### `for_`
 
 ``` purescript
 for_ :: forall a b f m. (Applicative m, Foldable f) => f a -> (a -> m b) -> m Unit
 ```
 
+A version of `traverse_` with its arguments flipped.
+
+This can be useful when running an action written using do notation
+for every element in a data structure:
+
+For example:
+
+```purescript
+for_ [1, 2, 3] \n -> do
+  print n
+  trace "squared is"
+  print (n * n)
+```
 
 #### `sequence_`
 
 ``` purescript
 sequence_ :: forall a f m. (Applicative m, Foldable f) => f (m a) -> m Unit
 ```
 
+Perform all of the effects in some data structure in the order
+given by the `Foldable` instance, ignoring the final result.
+
+For example:
+
+```purescript
+sequence_ [ trace "Hello, ", trace " world!" ]
+```
 
 #### `mconcat`
 
 ``` purescript
 mconcat :: forall f m. (Foldable f, Monoid m) => f m -> m
 ```
 
+Fold a data structure, accumulating values in some `Monoid`.
 
 #### `intercalate`
 
 ``` purescript
 intercalate :: forall f m. (Foldable f, Monoid m) => m -> f m -> m
 ```
 
+Fold a data structure, accumulating values in some `Monoid`,
+combining adjacent elements using the specified separator. 
 
 #### `and`
 
 ``` purescript
 and :: forall f. (Foldable f) => f Boolean -> Boolean
 ```
 
+Test whether all `Boolean` values in a data structure are `true`.
 
 #### `or`
 
 ``` purescript
 or :: forall f. (Foldable f) => f Boolean -> Boolean
 ```
 
+Test whether any `Boolean` value in a data structure is `true`.
 
 #### `any`
 
 ``` purescript
 any :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Boolean
 ```
 
+Test whether a predicate holds for any element in a data structure.
 
 #### `all`
 
 ``` purescript
 all :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Boolean
 ```
 
+Test whether a predicate holds for all elements in a data structure.
 
 #### `sum`
 
 ``` purescript
 sum :: forall f. (Foldable f) => f Number -> Number
 ```
 
+Find the sum of the numeric values in a data structure.
 
 #### `product`
 
 ``` purescript
 product :: forall f. (Foldable f) => f Number -> Number
 ```
 
+Find the product of the numeric values in a data structure.
 
 #### `elem`
 
 ``` purescript
 elem :: forall a f. (Eq a, Foldable f) => a -> f a -> Boolean
 ```
 
+Test whether a value is an element of a data structure.
 
 #### `notElem`
 
 ``` purescript
 notElem :: forall a f. (Eq a, Foldable f) => a -> f a -> Boolean
 ```
 
+Test whether a value is not an element of a data structure.
 
 #### `find`
 
 ``` purescript
 find :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Maybe a
 ```
 
+Try to find an element in a data structure which satisfies a predicate.
 
 #### `lookup`
 
 ``` purescript
 lookup :: forall a b f. (Eq a, Foldable f) => a -> f (Tuple a b) -> Maybe b
 ```
 
+Lookup a value in a data structure of `Tuple`s, generalizing association lists.
 
 #### `foldrArray`
 
@@ -212,6 +260,24 @@ class (Functor t, Foldable t) <= Traversable t where
   sequence :: forall a m. (Applicative m) => t (m a) -> m (t a)
 ```
 
+`Traversable` represents data structures which can be _traversed_,
+accumulating results and effects in some `Applicative` functor.
+
+- `traverse` runs an action for every element in a data structure,
+  and accumulates the results.
+- `sequence` runs the actions _contained_ in a data structure,
+  and accumulates the results.
+
+The `traverse` and `sequence` functions should be compatible in the
+following sense:
+
+- `traverse f xs = sequence (f <$> xs)`
+- `sequence = traverse id` 
+
+`Traversable` instances should also be compatible with the corresponding
+`Foldable` instances, in the following sense:
+
+- `foldMap f = runConst <<< traverse (Const <<< f)`
 
 #### `traversableArray`
 
@@ -282,13 +348,28 @@ instance traversableMultiplicative :: Traversable Multiplicative
 for :: forall a b m t. (Applicative m, Traversable t) => t a -> (a -> m b) -> m (t b)
 ```
 
+A version of `traverse` with its arguments flipped.
+
+
+This can be useful when running an action written using do notation
+for every element in a data structure:
+
+For example:
+
+```purescript
+for [1, 2, 3] \n -> do
+  print n
+  return (n * n)
+```
 
 #### `zipWithA`
 
 ``` purescript
 zipWithA :: forall m a b c. (Applicative m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
 ```
 
+A generalization of `zipWith` which accumulates results in some `Applicative`
+functor.
 
 #### `functorStateL`
 
@@ -317,13 +398,20 @@ instance applicativeStateL :: Applicative (StateL s)
 scanl :: forall a b f. (Traversable f) => (b -> a -> b) -> b -> f a -> f b
 ```
 
+Fold a data structure from the left, keeping all intermediate results
+instead of only the final result.
 
 #### `mapAccumL`
 
 ``` purescript
 mapAccumL :: forall a b s f. (Traversable f) => (s -> a -> Tuple s b) -> s -> f a -> Tuple s (f b)
 ```
 
+Fold a data structure from the left, keeping all intermediate results
+instead of only the final result.
+
+Unlike `scanl`, `mapAccumL` allows the type of accumulator to differ
+from the element type of the final data structure.
 
 #### `functorStateR`
 
@@ -352,9 +440,17 @@ instance applicativeStateR :: Applicative (StateR s)
 scanr :: forall a b f. (Traversable f) => (a -> b -> b) -> b -> f a -> f b
 ```
 
+Fold a data structure from the right, keeping all intermediate results
+instead of only the final result.
 
 #### `mapAccumR`
 
 ``` purescript
 mapAccumR :: forall a b s f. (Traversable f) => (s -> a -> Tuple s b) -> s -> f a -> Tuple s (f b)
-```
+```
+
+Fold a data structure from the right, keeping all intermediate results
+instead of only the final result.
+
+Unlike `scanr`, `mapAccumR` allows the type of accumulator to differ
+from the element type of the final data structure.

src/Data/Foldable.purs

@@ -11,6 +11,11 @@ import Data.Monoid.Last
 import Data.Monoid.Multiplicative
 import Data.Tuple
 
+-- | `Foldable` represents data structures which can be _folded_.
+-- |
+-- | - `foldr` folds a structure from the right
+-- | - `foldl` folds a structure from the left
+-- | - `foldMap` folds a structure by accumulating values in a `Monoid`
 class Foldable f where
   foldr :: forall a b. (a -> b -> b) -> b -> f a -> b
   foldl :: forall a b. (b -> a -> b) -> b -> f a -> b
@@ -67,56 +72,99 @@ instance foldableMultiplicative :: Foldable Multiplicative where
   foldl f z (Multiplicative x) = z `f` x
   foldMap f (Multiplicative x) = f x
 
+-- | Fold a data structure, accumulating values in some `Monoid`.
 fold :: forall f m. (Foldable f, Monoid m) => f m -> m
 fold = foldMap id
 
+-- | Traverse a data structure, performing some effects encoded by an
+-- | `Applicative` functor at each value, ignoring the final result.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | traverse_ print [1, 2, 3]
+-- | ```
 traverse_ :: forall a b f m. (Applicative m, Foldable f) => (a -> m b) -> f a -> m Unit
 traverse_ f = foldr ((*>) <<< f) (pure unit)
 
+-- | A version of `traverse_` with its arguments flipped.
+-- |
+-- | This can be useful when running an action written using do notation
+-- | for every element in a data structure:
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | for_ [1, 2, 3] \n -> do
+-- |   print n
+-- |   trace "squared is"
+-- |   print (n * n)
+-- | ```
 for_ :: forall a b f m. (Applicative m, Foldable f) => f a -> (a -> m b) -> m Unit
 for_ = flip traverse_
 
+-- | Perform all of the effects in some data structure in the order
+-- | given by the `Foldable` instance, ignoring the final result.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | sequence_ [ trace "Hello, ", trace " world!" ]
+-- | ```
 sequence_ :: forall a f m. (Applicative m, Foldable f) => f (m a) -> m Unit
 sequence_ = traverse_ id
 
+-- | Fold a data structure, accumulating values in some `Monoid`.
 mconcat :: forall f m. (Foldable f, Monoid m) => f m -> m
 mconcat = foldl (<>) mempty
 
+-- | Fold a data structure, accumulating values in some `Monoid`,
+-- | combining adjacent elements using the specified separator. 
 intercalate :: forall f m. (Foldable f, Monoid m) => m -> f m -> m
 intercalate sep xs = (foldl go { init: true, acc: mempty } xs).acc
   where
   go { init = true } x = { init: false, acc: x }
   go { acc = acc } x   = { init: false, acc: acc <> sep <> x }
 
+-- | Test whether all `Boolean` values in a data structure are `true`.
 and :: forall f. (Foldable f) => f Boolean -> Boolean
 and = foldl (&&) true
 
+-- | Test whether any `Boolean` value in a data structure is `true`.
 or :: forall f. (Foldable f) => f Boolean -> Boolean
 or = foldl (||) false
 
+-- | Test whether a predicate holds for any element in a data structure.
 any :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Boolean
 any p = or <<< foldMap (\x -> [p x])
 
+-- | Test whether a predicate holds for all elements in a data structure.
 all :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Boolean
 all p = and <<< foldMap (\x -> [p x])
 
+-- | Find the sum of the numeric values in a data structure.
 sum :: forall f. (Foldable f) => f Number -> Number
 sum = foldl (+) 0
 
+-- | Find the product of the numeric values in a data structure.
 product :: forall f. (Foldable f) => f Number -> Number
 product = foldl (*) 1
 
+-- | Test whether a value is an element of a data structure.
 elem :: forall a f. (Eq a, Foldable f) => a -> f a -> Boolean
 elem = any <<< (==)
 
+-- | Test whether a value is not an element of a data structure.
 notElem :: forall a f. (Eq a, Foldable f) => a -> f a -> Boolean
 notElem x = not <<< elem x
 
+-- | Try to find an element in a data structure which satisfies a predicate.
 find :: forall a f. (Foldable f) => (a -> Boolean) -> f a -> Maybe a
 find p f = case foldMap (\x -> if p x then [x] else []) f of
   (x:_) -> Just x
   []    -> Nothing
 
+-- | Lookup a value in a data structure of `Tuple`s, generalizing association lists.
 lookup :: forall a b f. (Eq a, Foldable f) => a -> f (Tuple a b) -> Maybe b
 lookup a f = runFirst $ foldMap (\(Tuple a' b) -> First (if a == a' then Just b else Nothing)) f