Add some doc/comments to fold functions

Author: harendra-kumar

core/src/Streamly/Internal/Data/Fold/Combinators.hs

@@ -593,8 +593,7 @@ repeated = error "Not implemented yet!"
 -- >>> drainMapM f = Fold.lmapM f Fold.drain
 -- >>> drainMapM f = Fold.foldMapM (void . f)
 --
--- Drain all input after passing it through a monadic function. This is the
--- dual of mapM_ on stream producers.
+-- Drain all input after passing it through a monadic function.
 --
 {-# INLINE drainMapM #-}
 drainMapM ::  Monad m => (a -> m b) -> Fold m a ()
@@ -1742,7 +1741,7 @@ tee = teeWith (,)
 -- XXX use "List" instead of "[]"?, use Array for output to scale it to a large
 -- number of consumers? For polymorphic case a vector could be helpful. For
 -- Unboxs we can use arrays. Will need separate APIs for those.
---
+
 -- | Distribute one copy of the stream to each fold and collect the results in
 -- a container.
 --
@@ -1760,8 +1759,6 @@ tee = teeWith (,)
 --
 -- >>> distribute = Prelude.foldr (Fold.teeWith (:)) (Fold.fromPure [])
 --
--- This is the consumer side dual of the producer side 'sequence' operation.
---
 -- Stops when all the folds stop.
 --
 {-# INLINE distribute #-}
@@ -1877,8 +1874,6 @@ partitionByMUsing t f fld1 fld2 =
 -- (67,33)
 --
 --
--- This is the consumer side dual of the producer side 'mergeBy' operation.
---
 -- When one fold is done, any input meant for it is ignored until the other
 -- fold is also done.
 --
@@ -1922,7 +1917,9 @@ partitionByMinM = partitionByMUsing teeWithMin
 -- :}
 -- ("Even 50","Odd 50")
 --
--- /Pre-release/
+-- NOTE: This is the exact analogue of the @choose@ method of the Contravariant
+-- functor typeclass Decidable.
+--
 {-# INLINE partitionBy #-}
 partitionBy :: Monad m
     => (a -> Either b c) -> Fold m b x -> Fold m c y -> Fold m a (x, y)
@@ -2005,7 +2002,9 @@ unzipWithMinM = unzipWithMUsing teeWithMin
 --
 -- This fold terminates when both the input folds terminate.
 --
--- /Pre-release/
+-- NOTE: This is the exact analogue of the @divide@ method of the Contravariant
+-- functor typeclass Divisible.
+--
 {-# INLINE unzipWith #-}
 unzipWith :: Monad m
     => (a -> (b,c)) -> Fold m b x -> Fold m c y -> Fold m a (x,y)
@@ -2026,8 +2025,6 @@ unzipWith f = unzipWithM (return . f)
 --
 -- >>> unzip = Fold.unzipWith id
 --
--- This is the consumer side dual of the producer side 'zip' operation.
---
 {-# INLINE unzip #-}
 unzip :: Monad m => Fold m a x -> Fold m b y -> Fold m (a,b) (x,y)
 unzip = unzipWith id

core/src/Streamly/Internal/Data/Fold/Type.hs

@@ -342,6 +342,16 @@
 -- can be expressed using 'mconcat' and a suitable 'Monoid'.  Instead of
 -- writing folds we can write Monoids and turn them into folds.
 --
+-- = Initial, Final Duality
+--
+-- Currently there is a discrepancy between folds and streams, folds have an
+-- "initial" to initialize the fold without any input. A producer side dual
+-- would be a finalizer called whenever the stream stops.
+--
+-- However, the initial action in folds creates a discrepancy with the CPS
+-- folds, and the same may be the case if we have a stop/cleanup operation in
+-- streams.
+
 module Streamly.Internal.Data.Fold.Type
     (
       module Streamly.Internal.Data.Fold.Step
@@ -816,6 +826,8 @@ fromRefold (Refold step inject extract) c =
 -- Basic Folds
 ------------------------------------------------------------------------------
 
+-- drain is a dual of infinite streams. This is the /dev/null of folds.
+
 -- | A fold that drains all its input, running the effects and discarding the
 -- results.
 --
@@ -830,6 +842,8 @@ drain = fromScanl Scanl.drain
 -- To Containers
 ------------------------------------------------------------------------------
 
+-- toList is a dual of Stream.fromList.
+
 -- | Folds the input stream to a list.
 --
 -- /Warning!/ working on large lists accumulated as buffers in memory could be
@@ -876,6 +890,8 @@ toListRev = foldl' (flip (:)) []
 toStreamKRev :: Monad m => Fold m a (K.StreamK n a)
 toStreamKRev = fromScanl Scanl.toStreamKRev
 
+-- toStreamK is a dual of Stream.fromStreamK
+
 -- | A fold that buffers its input to a pure stream.
 --
 -- >>> toStreamK = foldr StreamK.cons StreamK.nil
@@ -909,6 +925,9 @@ genericLength = fromScanl Scanl.genericLength
 length :: Monad m => Fold m a Int
 length = fromScanl Scanl.length
 
+-- Naming: "last" makes better sense for folds whereas "latest" makes better
+-- sense for scans.
+
 -- | Returns the latest element of the input stream, if any.
 --
 -- >>> latest = Fold.foldl1' (\_ x -> x)
@@ -939,39 +958,27 @@ instance Functor m => Functor (Fold m a) where
         step s b = fmap2 f (step1 s b)
         fmap2 g = fmap (fmap g)
 
--- XXX These are singleton folds that are closed for input. The correspondence
--- to a nil stream would be a nil fold that returns "Done" in "initial" i.e. it
--- does not produce any accumulator value. However, we do not have a
--- representation of an empty value in folds, because the Done constructor
--- always produces a value (Done b). We can potentially use "Partial s b" and
--- "Done" to make the type correspond to the stream type. That may be possible
--- if we introduce the "Skip" constructor as well because after the last
--- "Partial s b" we have to emit a "Skip to Done" state to keep cranking the
--- fold until it is done.
---
--- There is also the asymmetry between folds and streams because folds have an
--- "initial" to initialize the fold without any input. A similar concept is
--- possible in streams as well to stop the stream. That would be a "closing"
--- operation for the stream which can be called even without consuming any item
--- from the stream or when we are done consuming.
+-- NOTE: Canonical producer side dual of this is "Stream.nil" which generates a
+-- nil stream regardless of the seed. This folds a nil stream to some known
+-- value, reversing the producer side process.
 --
--- However, the initial action in folds creates a discrepancy with the CPS
--- folds, and the same may be the case if we have a stop/cleanup operation in
--- streams.
+-- Alternate names: const
 
--- | Make a fold that yields the supplied value without consuming any further
--- input.
---
--- /Pre-release/
+-- | Make a fold that immediately returns a constant output without consuming
+-- any input.
 --
 {-# INLINE fromPure #-}
 fromPure :: Applicative m => b -> Fold m a b
 fromPure b = Fold undefined (pure $ Done b) pure pure
 
--- | Make a fold that yields the result of the supplied effectful action
--- without consuming any further input.
+-- NOTE: Canonical producer side dual of this is "Stream.nilM" which generates
+-- a nil stream and an effect. This folds a nil stream to some known value and
+-- an effect, reverse of the producer.
 --
--- /Pre-release/
+-- Alternative names: constM
+
+-- | Make a fold that immediately returns a constant output along with an
+-- effect without consuming any input.
 --
 {-# INLINE fromEffect #-}
 fromEffect :: Applicative m => m b -> Fold m a b
@@ -980,6 +987,9 @@ fromEffect b = Fold undefined (Done <$> b) pure pure
 {-# ANN type SeqFoldState Fuse #-}
 data SeqFoldState sl f sr = SeqFoldL !sl | SeqFoldR !f !sr
 
+-- dual of Stream.append
+-- Alternative names: appendWith, serialWith.
+
 -- | Sequential fold application. Apply two folds sequentially to an input
 -- stream.  The input is provided to the first fold, when it is done - the
 -- remaining input is provided to the second fold. When the second fold is done
@@ -2054,6 +2064,8 @@ ifThen predicate
 -- 'duplicate' essentially appends a stream to the fold without finishing the
 -- fold.  Compare with 'snoc' which appends a singleton value to the fold.
 --
+-- See 'Fold.addStream' as well.
+--
 -- /Pre-release/
 {-# INLINE duplicate #-}
 duplicate :: Monad m => Fold m a b -> Fold m a (Fold m a b)
@@ -2086,7 +2098,7 @@ reduce (Fold step initial extract final) = do
     i <- initial
     return $ Fold step (return i) extract final
 
--- This is the dual of Stream @cons@.
+-- This is a fold builder equivalent of the stream builder @cons@.
 
 -- | Append an effect to the fold lazily, in other words run a single
 -- step of the fold.