Merge pull request #52 from hdgarrood/improve-docs

Improve docs

Author: garyb

.travis.yml

@@ -1,7 +1,8 @@
 language: node_js
 sudo: false
 node_js:
-  - 0.10
+  - 4
+  - 5
 env:
   - PATH=$HOME/purescript:$PATH
 install:

docs/Data/Array.md

@@ -8,12 +8,36 @@ use cases. This module is useful when integrating with JavaScript libraries
 which use arrays, but immutable arrays are not a practical data structure
 for many use cases due to their poor asymptotics.
 
+In addition to the functions in this module, Arrays have a number of
+useful instances:
+
+* `Functor`, which provides `map :: forall a b. (a -> b) -> Array a ->
+  Array b`
+* `Apply`, which provides `(<*>) :: forall a b. Array (a -> b) -> Array a
+  -> Array b`. This function works a bit like a Cartesian product; the
+  result array is constructed by applying each function in the first
+  array to each value in the second, so that the result array ends up with
+  a length equal to the product of the two arguments' lengths.
+* `Bind`, which provides `(>>=) :: forall a b. (a -> Array b) -> Array a
+  -> Array b` (this is the same as `concatMap`).
+* `Semigroup`, which provides `(<>) :: forall a. Array a -> Array a ->
+  Array a`, for concatenating arrays.
+* `Foldable`, which provides a slew of functions for *folding* (also known
+  as *reducing*) arrays down to one value. For example,
+  `Data.Foldable.any` tests whether an array of `Boolean` values contains
+  at least one `true`.
+* `Traversable`, which provides the PureScript version of a for-loop,
+  allowing you to iterate over an array and accumulate effects.
+
+
 #### `singleton`
 
 ``` purescript
 singleton :: forall a. a -> Array a
 ```
 
+Create an array of one element
+
 #### `range`
 
 ``` purescript
@@ -453,7 +477,7 @@ specified equivalence relation to detemine equality.
 nub :: forall a. (Eq a) => Array a -> Array a
 ```
 
-Special case of `nubBy`: `nubBy eq`
+Remove the duplicates from an array, creating a new array.
 
 #### `nubBy`
 
@@ -462,8 +486,7 @@ nubBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a
 ```
 
 Remove the duplicates from an array, where element equality is determined
-by the specified equivalence relation, creating a new array. The first
-occurence of an element is always the one that is kept.
+by the specified equivalence relation, creating a new array.
 
 #### `union`
 
@@ -537,6 +560,17 @@ relation to compare elements, creating a new array.
 zipWith :: forall a b c. (a -> b -> c) -> Array a -> Array b -> Array c
 ```
 
+Apply a function to pairs of elements at the same index in two arrays,
+collecting the results in a new array.
+
+If one array is longer, elements will be discarded from the longer array.
+
+For example
+
+```purescript
+zipWith (*) [1, 2, 3] [4, 5, 6, 7] == [4, 10, 18]
+```
+
 #### `zipWithA`
 
 ``` purescript
@@ -569,3 +603,7 @@ second components.
 ``` purescript
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> Array b -> m a
 ```
+
+Perform a fold using a monadic step function.
+
+

docs/Data/Array/ST.md

@@ -15,7 +15,7 @@ A reference to a mutable array.
 The first type parameter represents the memory region which the array belongs to.
 The second type parameter defines the type of elements of the mutable array.
 
-The runtime representation of a value of type `STArray h a` is the same as that of `[a]`,
+The runtime representation of a value of type `STArray h a` is the same as that of `Array a`,
 except that mutation is allowed.
 
 #### `Assoc`
@@ -24,7 +24,7 @@ except that mutation is allowed.
 type Assoc a = { value :: a, index :: Int }
 ```
 
-An element and its index
+An element and its index.
 
 #### `runSTArray`
 

src/Data/Array.purs

@@ -5,6 +5,28 @@
 -- | use cases. This module is useful when integrating with JavaScript libraries
 -- | which use arrays, but immutable arrays are not a practical data structure
 -- | for many use cases due to their poor asymptotics.
+-- |
+-- | In addition to the functions in this module, Arrays have a number of
+-- | useful instances:
+-- |
+-- | * `Functor`, which provides `map :: forall a b. (a -> b) -> Array a ->
+-- |   Array b`
+-- | * `Apply`, which provides `(<*>) :: forall a b. Array (a -> b) -> Array a
+-- |   -> Array b`. This function works a bit like a Cartesian product; the
+-- |   result array is constructed by applying each function in the first
+-- |   array to each value in the second, so that the result array ends up with
+-- |   a length equal to the product of the two arguments' lengths.
+-- | * `Bind`, which provides `(>>=) :: forall a b. (a -> Array b) -> Array a
+-- |   -> Array b` (this is the same as `concatMap`).
+-- | * `Semigroup`, which provides `(<>) :: forall a. Array a -> Array a ->
+-- |   Array a`, for concatenating arrays.
+-- | * `Foldable`, which provides a slew of functions for *folding* (also known
+-- |   as *reducing*) arrays down to one value. For example,
+-- |   `Data.Foldable.any` tests whether an array of `Boolean` values contains
+-- |   at least one `true`.
+-- | * `Traversable`, which provides the PureScript version of a for-loop,
+-- |   allowing you to iterate over an array and accumulate effects.
+-- |
 module Data.Array
   ( singleton
   , (..), range
@@ -94,10 +116,6 @@ import Data.Traversable (sequence)
 import Data.Tuple (Tuple(..))
 import qualified Data.Maybe.Unsafe as U
 
---------------------------------------------------------------------------------
--- Array creation --------------------------------------------------------------
---------------------------------------------------------------------------------
-
 -- | Create an array of one element
 singleton :: forall a. a -> Array a
 singleton a = [a]
@@ -464,10 +482,6 @@ groupBy op = go []
               in go ((o.head : sp.init) : acc) sp.rest
     Nothing -> reverse acc
 
---------------------------------------------------------------------------------
--- Set-like operations ---------------------------------------------------------
---------------------------------------------------------------------------------
-
 -- | Remove the duplicates from an array, creating a new array.
 nub :: forall a. (Eq a) => Array a -> Array a
 nub = nubBy eq
@@ -519,10 +533,6 @@ intersect = intersectBy eq
 intersectBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a -> Array a
 intersectBy eq xs ys = filter (\x -> isJust (findIndex (eq x) ys)) xs
 
---------------------------------------------------------------------------------
--- Zipping ---------------------------------------------------------------------
---------------------------------------------------------------------------------
-
 -- | Apply a function to pairs of elements at the same index in two arrays,
 -- | collecting the results in a new array.
 -- |
@@ -551,10 +561,6 @@ unzip :: forall a b. Array (Tuple a b) -> Tuple (Array a) (Array b)
 unzip = uncons' (\_ -> Tuple [] []) \(Tuple a b) ts -> case unzip ts of
   Tuple as bs -> Tuple (a : as) (b : bs)
 
---------------------------------------------------------------------------------
--- Folding ---------------------------------------------------------------------
---------------------------------------------------------------------------------
-
 -- | Perform a fold using a monadic step function.
 foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> Array b -> m a
 foldM f a = uncons' (\_ -> return a) (\b bs -> f a b >>= \a' -> foldM f a' bs)

src/Data/Array/ST.purs

@@ -28,11 +28,11 @@ import Data.Maybe (Maybe(..))
 -- | The first type parameter represents the memory region which the array belongs to.
 -- | The second type parameter defines the type of elements of the mutable array.
 -- |
--- | The runtime representation of a value of type `STArray h a` is the same as that of `[a]`,
+-- | The runtime representation of a value of type `STArray h a` is the same as that of `Array a`,
 -- | except that mutation is allowed.
 foreign import data STArray :: * -> * -> *
 
--- | An element and its index
+-- | An element and its index.
 type Assoc a = { value :: a, index :: Int }
 
 -- | Freeze a mutable array, creating an immutable array. Use this function as you would use