@@ -120,15 +120,31 @@ module Streamly.Prelude
120 -- ** Folding
120 -- ** Folding
121-- | In imperative terms a fold can be considered as a loop over the stream
121-- | In imperative terms a fold can be considered as a loop over the stream
122-- that reduces the stream to a single value.
122-- that reduces the stream to a single value.
123−-- Left and right folds use a fold function @f@ and an identity element @z@
123+-- Left and right folds both use a fold function @f@ and an identity element
124−-- (@zero@) to recursively deconstruct a structure and then combine and reduce
124+-- @z@ (@zero@) to deconstruct a recursive data structure and reconstruct a
125−-- the values or transform and reconstruct a new container.
125+-- new data structure. The new structure may be a recursive construction (a
126+-- container) or a non-recursive single value reduction of the original
127−-- In general, a right fold is suitable for transforming and reconstructing a
129+-- Both right and left folds are mathematical duals of each other, they are
130+-- functionally equivalent. Operationally, a left fold on a left associated
131+-- structure behaves exactly in the same way as a right fold on a right
132+-- associated structure. Similarly, a left fold on a right associated structure
133+-- behaves in the same way as a right fold on a left associated structure.
128−-- right associated structure (e.g. cons lists and streamly streams) and a left
134+-- However, the behavior of a right fold on a right associated structure is
129−-- fold is suitable for reducing a right associated structure. The behavior of
135+-- operationally different (even though functionally equivalent) than a left
136+-- fold on the same structure.
138+-- On right associated structures like Haskell @cons@ lists or Streamly
139+-- streams, a lazy right fold is naturally suitable for lazy recursive
140+-- reconstruction of a new structure, while a strict left fold is naturally
141+-- suitable for efficient reduction. In right folds control is in the hand of
142+-- the @puller@ whereas in left folds the control is in the hand of the
130−-- right and left folds are described in detail in the individual fold's
145+-- The behavior of right and left folds are described in detail in the
131−-- documentation. To illustrate the two folds for cons lists:
146+-- individual fold's documentation. To illustrate the two folds for right
147+-- associated @cons@ lists:
133-- > foldr :: (a -> b -> b) -> b -> [a] -> b
149-- > foldr :: (a -> b -> b) -> b -> [a] -> b
134-- > foldr f z [] = z
150-- > foldr f z [] = z