More docs improvements

- Give every function at least one example
- Use List rather than Array (for consistency)
- Fix a couple of minor errors (e.g. extra argument to `range`)

Author: hdgarrood

src/Data/Unfoldable.purs

@@ -55,7 +55,7 @@ foreign import unfoldrArrayImpl
 -- | For example:
 -- |
 -- | ``` purescript
--- | replicate 2 "foo" == ["foo", "foo"] :: Array String
+-- | replicate 2 "foo" == (["foo", "foo"] :: Array String)
 -- | ```
 replicate :: forall f a. Unfoldable f => Int -> a -> f a
 replicate n v = unfoldr step n
@@ -66,6 +66,11 @@ replicate n v = unfoldr step n
       else Just (Tuple v (i - 1))
 
 -- | Perform an Applicative action `n` times, and accumulate all the results.
+-- |
+-- | ``` purescript
+-- | > replicateA 5 (randomInt 1 10) :: Effect (Array Int)
+-- | [1,3,2,7,5]
+-- | ```
 replicateA
   :: forall m f a
    . Applicative m
@@ -80,11 +85,16 @@ replicateA n m = sequence (replicate n m)
 -- | For example:
 -- |
 -- | ``` purescript
--- | none == [] :: forall a. Array a
+-- | none == ([] :: Array Unit)
 -- | ```
 none :: forall f a. Unfoldable f => f a
 none = unfoldr (const Nothing) unit
 
--- | Convert a Maybe to any Unfoldable like lists and arrays.
+-- | Convert a Maybe to any Unfoldable, such as lists or arrays.
+-- |
+-- | ``` purescript
+-- | fromMaybe (Nothing :: Maybe Int) == []
+-- | fromMaybe (Just 1) == [1]
+-- | ```
 fromMaybe :: forall f a. Unfoldable f => Maybe a -> f a
 fromMaybe = unfoldr (\b -> flip Tuple Nothing <$> b)

src/Data/Unfoldable1.purs

@@ -21,20 +21,20 @@ import Partial.Unsafe (unsafePartial)
 -- |
 -- | Note that, in order to provide an `Unfoldable1 t` instance, `t` need not
 -- | be a type which is guaranteed to be non-empty. For example, the fact that
--- | arrays can be empty does not prevent us from providing an `Unfoldable1
--- | Array` instance. However, the result of `unfoldr1` should always be
--- | non-empty.
+-- | lists can be empty does not prevent us from providing an
+-- | `Unfoldable1 List` instance. However, the result of `unfoldr1` should
+-- | always be non-empty.
 -- |
 -- | Every type which has an `Unfoldable` instance can be given an
 -- | `Unfoldable1` instance (and, in fact, is required to, because
 -- | `Unfoldable1` is a superclass of `Unfoldable`). However, there are types
 -- | which have `Unfoldable1` instances but cannot have `Unfoldable` instances.
 -- | In particular, types which are guaranteed to be non-empty, such as
--- | `NonEmptyArray`, cannot be given `Unfoldable` instances.
+-- | `NonEmptyList`, cannot be given `Unfoldable` instances.
 -- |
 -- | The utility of this class, then, is that it provides an `Unfoldable`-like
 -- | interface while still permitting instances for guaranteed-non-empty types
--- | like `NonEmptyArray`.
+-- | like `NonEmptyList`.
 class Unfoldable1 t where
   unfoldr1 :: forall a b. (b -> Tuple a (Maybe b)) -> b -> t a
 
@@ -52,11 +52,11 @@ foreign import unfoldr1ArrayImpl
   -> Array a
 
 -- | Replicate a value `n` times. At least one value will be produced, so values
--- | `n < 1` less than one will be ignored.
+-- | `n` less than 1 will be treated as 1.
 -- |
 -- | ``` purescript
--- | replicate1 0 "foo" == NEL.singleton "foo" :: NEL.NonEmptyList String
--- | replicate1 2 "foo" == NEL.cons "foo" (NEL.singleton "foo") :: NEL.NonEmptyList String
+-- | replicate1 2 "foo" == (NEL.cons "foo" (NEL.singleton "foo") :: NEL.NonEmptyList String)
+-- | replicate1 0 "foo" == (NEL.singleton "foo" :: NEL.NonEmptyList String)
 -- | ```
 replicate1 :: forall f a. Unfoldable1 f => Int -> a -> f a
 replicate1 n v = unfoldr1 step (n - 1)
@@ -66,8 +66,15 @@ replicate1 n v = unfoldr1 step (n - 1)
       | i <= 0 = Tuple v Nothing
       | otherwise = Tuple v (Just (i - 1))
 
--- | Perform an `Apply` action `n` times (at least once, so values `n < 1`
--- | less than one will be ignored), and accumulate the results.
+-- | Perform an `Apply` action `n` times (at least once, so values `n` less
+-- | than 1 will be treated as 1), and accumulate the results.
+-- |
+-- | ``` purescript
+-- | > replicate1A 2 (randomInt 1 10) :: Effect (NEL.NonEmptyList Int)
+-- | (NonEmptyList (NonEmpty 8 (2 : Nil)))
+-- | > replicate1A 0 (randomInt 1 10) :: Effect (NEL.NonEmptyList Int)
+-- | (NonEmptyList (NonEmpty 4 Nil))
+-- | ```
 replicate1A
   :: forall m f a
    . Apply m
@@ -81,7 +88,7 @@ replicate1A n m = sequence1 (replicate1 n m)
 -- | Contain a single value. For example:
 -- |
 -- | ``` purescript
--- | singleton "foo" == NEL.singleton "foo" :: NEL.NonEmptyList String
+-- | singleton "foo" == (NEL.singleton "foo" :: NEL.NonEmptyList String)
 -- | ```
 singleton :: forall f a. Unfoldable1 f => a -> f a
 singleton = replicate1 1
@@ -90,9 +97,9 @@ singleton = replicate1 1
 -- | endpoints.
 -- |
 -- | ``` purescript
--- | range 0 0 "foo" == NEL.singleton 0 :: NEL.NonEmptyList Int
--- | range 1 2 "foo" == NEL.cons 1 (NEL.singleton 2) :: NEL.NonEmptyList Int
--- | range 2 0 "foo" == NEL.cons 2 (NEL.cons 1 (NEL.singleton 0)) :: NEL.NonEmptyList Int
+-- | range 0 0 == (NEL.singleton 0 :: NEL.NonEmptyList Int)
+-- | range 1 2 == (NEL.cons 1 (NEL.singleton 2) :: NEL.NonEmptyList Int)
+-- | range 2 0 == (NEL.cons 2 (NEL.cons 1 (NEL.singleton 0)) :: NEL.NonEmptyList Int)
 -- | ```
 range :: forall f. Unfoldable1 f => Int -> Int -> f Int
 range start end =