@@ -469,6 +469,12 @@ fromListM = Unfold step inject
469469 step (x:xs) = x >>= \r -> return $ Yield r xs
470470 step [] = return Stop
471471
472+-- | Build a stream by unfolding a /monadic/ step function starting from a seed.
473+-- The step function returns the next element in the stream and the next seed
474+-- value. When it is done it returns 'Nothing' and the stream ends.
475+--
476+-- /Internal/
477+--
472478{-# INLINE unfoldrM #-}
473479unfoldrM :: Monad m => (a -> m (Maybe (b, a))) -> Unfold m a b
474480unfoldrM next = Unfold step return
@@ -486,6 +492,8 @@ unfoldrM next = Unfold step return
486492
487493-- | Generates a stream replicating the seed @n@ times.
488494--
495+-- /Internal/
496+--
489497{-# INLINE replicateM #-}
490498replicateM :: Monad m => Int -> Unfold m (m a) a
491499replicateM n = Unfold step inject
@@ -504,6 +512,8 @@ replicateM n = Unfold step inject
504512
505513-- | Generates an infinite stream repeating the seed.
506514--
515+-- /Internal/
516+--
507517{-# INLINE repeatM #-}
508518repeatM :: Monad m => Unfold m (m a) a
509519repeatM = Unfold step return
@@ -514,6 +524,8 @@ repeatM = Unfold step return
514524-- | Generates an infinite stream starting with the given seed and applying the
515525-- given function repeteadly.
516526--
527+-- /Internal/
528+--
517529{-# INLINE iterateM #-}
518530iterateM :: Monad m => (a -> m a) -> Unfold m a a
519531iterateM f = Unfold step f
@@ -526,6 +538,8 @@ iterateM f = Unfold step f
526538-- | @fromIndicesM gen@ generates an infinite stream of values using @gen@
527539-- starting from the seed.
528540--
541+-- /Internal/
542+--
529543{-# INLINE_NORMAL fromIndicesM #-}
530544fromIndicesM :: Monad m => (Int -> m a) -> Unfold m Int a
531545fromIndicesM gen = Unfold step return
@@ -591,6 +605,10 @@ filterM f (Unfold step1 inject1) = Unfold step inject1
591605filter :: Monad m => (b -> Bool) -> Unfold m a b -> Unfold m a b
592606filter f = filterM (return . f)
593607
608+-- | @drop n unf@ drops @n@ elements from the stream generated by @unf@.
609+--
610+-- /Internal/
611+--
594612{-# INLINE_NORMAL drop #-}
595613drop :: Monad m => Int -> Unfold m a b -> Unfold m a b
596614drop n (Unfold step inject) = Unfold step' inject'
@@ -618,6 +636,11 @@ drop n (Unfold step inject) = Unfold step' inject'
618636 Skip s -> Skip (s, 0)
619637 Stop -> Stop
620638
639+-- | @dropWhileM f unf@ drops elements from the stream generated by @unf@ while
640+-- the condition holds true. The condition function @f@ is /monadic/ in nature.
641+--
642+-- /Internal/
643+--
621644{-# INLINE_NORMAL dropWhileM #-}
622645dropWhileM :: Monad m => (b -> m Bool) -> Unfold m a b -> Unfold m a b
623646dropWhileM f (Unfold step inject) = Unfold step' inject'
@@ -648,6 +671,10 @@ dropWhileM f (Unfold step inject) = Unfold step' inject'
648671 Skip s -> Skip (Right s)
649672 Stop -> Stop
650673
674+-- | Similar to 'dropWhileM' but with a pure condition function.
675+--
676+-- /Internal/
677+--
651678{-# INLINE dropWhile #-}
652679dropWhile :: Monad m => (b -> Bool) -> Unfold m a b -> Unfold m a b
653680dropWhile f = dropWhileM (return . f)
@@ -677,6 +704,11 @@ enumerateFromToIntegral to =
677704enumerateFromIntegral :: (Monad m, Integral a, Bounded a) => Unfold m a a
678705enumerateFromIntegral = enumerateFromToIntegral maxBound
679706
707+-- | Generate an infinite stream starting from the seed with increments of the
708+-- given stride.
709+--
710+-- /Internal/
711+--
680712{-# INLINE enumerateFromStepNum #-}
681713enumerateFromStepNum :: (Monad m, Num a) => a -> Unfold m a a
682714enumerateFromStepNum stride = Unfold step return
@@ -684,10 +716,16 @@ enumerateFromStepNum stride = Unfold step return
684716 {-# INLINE_LATE step #-}
685717 step !s = return $ (Yield $! s) $! (s + stride)
686718
719+-- | @numFrom = enumerateFromStepNum 1@
720+--
721+-- /Internal/
722+--
687723{-# INLINE_NORMAL numFrom #-}
688724numFrom :: (Monad m, Num a) => Unfold m a a
689725numFrom = enumerateFromStepNum 1
690726
727+-- | /Internal/
728+--
691729{-# INLINE_NORMAL enumerateFromToFractional #-}
692730enumerateFromToFractional :: (Monad m, Fractional a, Ord a) => a -> Unfold m a a
693731enumerateFromToFractional to =
@@ -703,6 +741,8 @@ data FromSVarState t m a =
703741 | FromSVarLoop (SVar t m a) [ChildEvent a]
704742 | FromSVarDone (SVar t m a)
705743
744+-- | /Internal/
745+--
706746{-# INLINE_NORMAL fromSVar #-}
707747fromSVar :: MonadAsync m => Unfold m (SVar t m a) a
708748fromSVar = Unfold step (return . FromSVarInit)
@@ -782,7 +822,10 @@ fromSVar = Unfold step (return . FromSVarInit)
782822-- Process events received by a fold consumer from a stream producer
783823-------------------------------------------------------------------------------
784824
785−-- XXX Why don't we do the same thing for "FromSVarInit" that we did in "fromSVar"?
825+-- XXX Have an error for "FromSVarInit" instead of undefined. The error can
826+-- redirect the user to report the failure to the developers.
827+-- | /Internal/
828+--
786829{-# INLINE_NORMAL fromProducer #-}
787830fromProducer :: MonadAsync m => Unfold m (SVar t m a) a
788831fromProducer = Unfold step (return . FromSVarRead)