Merge pull request #24 from purescript/expand-docs

Expand docs

Author: hdgarrood

src/Data/Unfoldable.purs

@@ -21,13 +21,20 @@ import Data.Tuple (Tuple(..), fst, snd)
 import Data.Unfoldable1 (class Unfoldable1, unfoldr1, singleton, range, replicate1, replicate1A)
 import Partial.Unsafe (unsafePartial)
 
--- | This class identifies data structures which can be _unfolded_.
+-- | This class identifies (possibly empty) data structures which can be
+-- | _unfolded_.
 -- |
--- | The generating function `f` in `unfoldr f` in understood as follows:
+-- | The generating function `f` in `unfoldr f` is understood as follows:
 -- |
 -- | - If `f b` is `Nothing`, then `unfoldr f b` should be empty.
 -- | - If `f b` is `Just (Tuple a b1)`, then `unfoldr f b` should consist of `a`
 -- |   appended to the result of `unfoldr f b1`.
+-- |
+-- | Note that it is not possible to give `Unfoldable` instances to types which
+-- | represent structures which are guaranteed to be non-empty, such as
+-- | `NonEmptyArray`: consider what `unfoldr (const Nothing)` should produce.
+-- | Structures which are guaranteed to be non-empty can instead be given
+-- | `Unfoldable1` instances.
 class Unfoldable1 t <= Unfoldable t where
   unfoldr :: forall a b. (b -> Maybe (Tuple a b)) -> b -> t a
 

src/Data/Unfoldable1.purs

@@ -13,11 +13,28 @@ import Data.Semigroup.Traversable (class Traversable1, sequence1)
 import Data.Tuple (Tuple(..), fst, snd)
 import Partial.Unsafe (unsafePartial)
 
--- | This class identifies non-empty data structures which can be _unfolded_.
+-- | This class identifies data structures which can be _unfolded_.
 -- |
--- | The generating function `f` corresponds to the `uncons` operation of a
--- | non-empty list or array; it always return a value, and then optionally
--- | a value to continue unfolding from.
+-- | The generating function `f` in `unfoldr1 f` corresponds to the `uncons`
+-- | operation of a non-empty list or array; it always returns a value, and
+-- | then optionally a value to continue unfolding from.
+-- |
+-- | 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.
+-- |
+-- | 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.
+-- |
+-- | 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`.
 class Unfoldable1 t where
   unfoldr1 :: forall a b. (b -> Tuple a (Maybe b)) -> b -> t a