Cleanup exports in Data.Fold, minor doc updates

core/src/Streamly/Data/Fold.hs

@@ -288,12 +288,12 @@ module Streamly.Data.Fold
     , duplicate
     -- , isClosed
 
-    -- * Tranformation
-    -- | Combinators are modifiers of folds.  In the type @Fold m a b@, @a@ is
-    -- the input type and @b@ is the output type.  Transformations can be
+    -- * Transformations
+    -- | Transformations are modifiers of folds.  In the type @Fold m a b@, @a@
+    -- is the input type and @b@ is the output type.  Transformations can be
     -- applied either on the input side (contravariant) or on the output side
-    -- (covariant).  Therefore, combinators are of one of the following general
-    -- shapes:
+    -- (covariant).  Therefore, transformations have one of the following
+    -- general shapes:
     --
     -- * @... -> Fold m a b -> Fold m c b@ (input transformation)
     -- * @... -> Fold m a b -> Fold m a c@ (output transformation)
@@ -316,10 +316,7 @@ module Streamly.Data.Fold
     , lmap
     , lmapM
 
-    -- ** Scanning and Filtering
-    , scan
-    , postscan
-    , scanMaybe
+    -- ** Filtering
     , filter
     , filterM
 
@@ -332,16 +329,32 @@ module Streamly.Data.Fold
 
     -- ** Trimming
     , take
-    -- , takeInterval
     , takeEndBy
     , takeEndBy_
 
+    -- ** Key-value Collectors
+    , toMap
+    , toMapIO
+
+    -- ** Key-value Scanners
+    , classify
+    , classifyIO
+
+    -- ** Transforming the Monad
+    , morphInner
+
     -- * Combinators
+    -- | Transformations that combine two or more folds.
+
+    -- ** Scanning
+    , scan
+    , postscan
+    , scanMaybe
+
     -- ** Splitting
     , splitWith
     , many
     , groupsOf
-    -- , intervalsOf
 
     -- ** Parallel Distribution
     -- | For applicative composition using distribution see
@@ -363,27 +376,24 @@ module Streamly.Data.Fold
     --, partitionByMinM
     --, partitionBy
 
+    -- ** Unzipping
+    , unzip
+
+    -- * Dynamic Combinators
+    -- | The fold to be used is generated dynamically based on the input or
+    -- based on the output of the previous fold.
+
     -- ** Key-value Collectors
-    , toMap
-    , toMapIO
     , demuxToMap
     , demuxToMapIO
 
     -- ** Key-value Scanners
-    , classify
-    , classifyIO
     , demux
     , demuxIO
 
-    -- ** Unzipping
-    , unzip
-
     -- ** Nesting
     , concatMap
 
-    -- * Transforming the Monad
-    , morphInner
-
     -- * Deprecated
     , chunksOf
     , foldr

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

@@ -256,11 +256,14 @@ countDistinctInt = fmap (\(Tuple' _ n) -> n) $ foldl' step initial
 --
 -- XXX If we use Refold in it, it can perhaps fuse/be more efficient. For
 -- example we can store just the result rather than storing the whole fold in
--- the Map.
+-- the Map. This would be similar to a refold based classify.
 --
 -- Note: There are separate functions to determine Key and Fold from the input
 -- because key is to be determined on each input whereas fold is to be
 -- determined only once for a key.
+--
+-- XXX Should we use (k -> m (Fold m a b)) instead since the fold is key
+-- specific? This should give better safety.
 
 -- | This is the most general of all demux, classify operations.
 --
@@ -528,6 +531,9 @@ demuxKvToMap = demuxKvToContainer
 -- done then initial would set a flag in the state to ignore the input or
 -- return an error.
 
+-- XXX Use a Refold m k a b so that we can make the fold key specifc.
+-- XXX Is using a function (a -> k) better than using the input (k,a)?
+
 {-# INLINE classifyGeneric #-}
 classifyGeneric :: (Monad m, IsMap f, Traversable f, Ord (Key f)) =>
     -- Note: we need to return the Map itself to display the in-progress values

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

@@ -1230,7 +1230,9 @@ data ConcatMapState m sa a b c
     | forall s. C (s -> a -> m (Step s c)) !s (s -> m c) (s -> m c)
 
 -- | Map a 'Fold' returning function on the result of a 'Fold' and run the
--- returned fold. This operation can be used to express data dependencies
+-- returned fold. This is akin to an n-ary version of 'splitWith' where the
+-- next fold for splitting the input is decided dynamically using the previous
+-- result. This operation can be used to express data dependencies
 -- between fold operations.
 --
 -- Let's say the first element in the stream is a count of the following