@@ -194,7 +194,7 @@ import Prelude hiding
194194-- >>> import qualified Streamly.Prelude as Stream
195195-- >>> import qualified Streamly.Internal.Data.Stream.IsStream as Stream
196196-- >>> import qualified Streamly.Internal.Data.Parser as Parser
197−-- >>> import qualified Streamly.Data.Fold as Fold
197+-- >>> import qualified Streamly.Internal.Data.Fold as Fold
198198
199199------------------------------------------------------------------------------
200200-- Deconstruction
@@ -204,14 +204,25 @@ import Prelude hiding
204204-- 'Nothing'. If the stream is non-empty, returns @Just (a, ma)@, where @a@ is
205205-- the head of the stream and @ma@ its tail.
206206--
207−-- This is a brute force primitive. Avoid using it as long as possible, use it
208−-- when no other combinator can do the job. This can be used to do pretty much
209−-- anything in an imperative manner, as it just breaks down the stream into
210−-- individual elements and we can loop over them as we deem fit. For example,
211−-- this can be used to convert a streamly stream into other stream types.
207+-- This can be used to do pretty much anything in an imperative manner, as it
208+-- just breaks down the stream into individual elements and we can loop over
209+-- them as we deem fit. For example, this can be used to convert a streamly
210+-- stream into other stream types.
212211--
213−-- All the folds in this module can be expressed in terms of 'uncons', however
214−-- the specific implementations are generally more efficient.
212+-- All the folds in this module can be expressed in terms of 'uncons', however,
213+-- this is generally less efficient than specific folds because it takes apart
214+-- the stream one element at a time, therefore, does not take adavantage of
215+-- stream fusion.
216+--
217+-- 'foldBreak' is a more general way of consuming a stream piecemeal.
218+--
219+-- >>> :{
220+-- uncons xs = do
221+-- r <- Stream.foldBreak Fold.one xs
222+-- return $ case r of
223+-- (Nothing, _) -> Nothing
224+-- (Just h, t) -> Just (h, Stream.fromSerial t)
225+-- :}
215226--
216227-- @since 0.1.0
217228{-# INLINE uncons #-}