Add examples

src/Data/NonEmpty.purs

@@ -33,36 +33,90 @@ import Prim.TypeError (class Warn, Text)
 
 -- | A non-empty container of elements of type a.
 -- |
--- | For example:
--- |
 -- | ```purescript
+-- | import Data.NonEmpty
+-- |
+-- | nonEmptyArray :: NonEmpty Array Int
+-- | nonEmptyArray = NonEmpty 1 [2,3]
+-- |
+-- | import Data.List(List(..), (:))
+-- |
 -- | nonEmptyList :: NonEmpty List Int
--- | nonEmptyList = 0 :| empty
+-- | nonEmptyList = NonEmpty 1 (2 : 3 : Nil)
 -- | ```
 data NonEmpty f a = NonEmpty a (f a)
 
 -- | An infix synonym for `NonEmpty`.
+-- |
+-- | ```purescript
+-- | nonEmptyArray :: NonEmpty Array Int
+-- | nonEmptyArray = 1 :| [2,3]
+-- |
+-- | nonEmptyList :: NonEmpty List Int
+-- | nonEmptyList = 1 :| 2 : 3 : Nil
+-- | ```
 infixr 5 NonEmpty as :|
 
 -- | Create a non-empty structure with a single value.
+-- |
+-- | ```purescript
+-- | import Prelude
+-- |
+-- | singleton 1 == 1 :| []
+-- | singleton 1 == 1 :| Nil
+-- | ```
 singleton :: forall f a. Plus f => a -> NonEmpty f a
 singleton a = a :| empty
 
 -- | Fold a non-empty structure, collecting results using a binary operation.
+-- |
+-- | Deprecated, use 'Data.Semigroup.Foldable.foldl1' instead
+-- |
+-- | ```purescript
+-- | foldl1 (+) (1 :| [2, 3]) == 6
+-- | ```
 foldl1 :: forall f a. Foldable f => Warn (Text "'Data.NonEmpty.foldl1' is deprecated, use 'Data.Semigroup.Foldable.foldl1' instead") => (a -> a -> a) -> NonEmpty f a -> a
 foldl1 = Foldable1.foldl1
 
+-- | Apply a function that takes the `first` element and remaining elements
+-- | as arguments to a non-empty container.
+-- |
+-- | For example, return the remaining elements multiplied by the first element:
+-- |
+-- | ```purescript
+-- | fromNonEmpty (\x xs -> map (_ * x) xs) (3 :| [2, 1]) == [6, 3]
+-- | ```
 fromNonEmpty :: forall f a r. (a -> f a -> r) -> NonEmpty f a -> r
 fromNonEmpty f (a :| fa) = a `f` fa
 
+-- | Returns the `alt` (`<|>`) result of:
+-- | - The first element lifted to the container of the remaining elements.
+-- | - The remaining elements.
+-- |
+-- | ```purescript
+-- | import Data.Maybe(Maybe(..))
+-- |
+-- | oneOf (1 :| Nothing) == Just 1
+-- | oneOf (1 :| Just 2) == Just 1
+-- |
+-- | oneOf (1 :| [2, 3]) == [1,2,3]
+-- | ```
 oneOf :: forall f a. Alternative f => NonEmpty f a -> f a
 oneOf (a :| fa) = pure a <|> fa
 
 -- | Get the 'first' element of a non-empty container.
+-- |
+-- | ```purescript
+-- | head (1 :| [2, 3]) == 1
+-- | ```
 head :: forall f a. NonEmpty f a -> a
 head (x :| _) = x
 
 -- | Get everything but the 'first' element of a non-empty container.
+-- |
+-- | ```purescript
+-- | tail (1 :| [2, 3]) == [2, 3]
+-- | ```
 tail :: forall f a. NonEmpty f a -> f a
 tail (_ :| xs) = xs