Fix overview of Parser and ParserK module

core/src/Streamly/Data/Parser.hs

@@ -7,15 +7,28 @@
 -- Stability   : pre-release
 -- Portability : GHC
 --
--- Parsers are stream consumers like folds with the following differences:
+-- Parsers are more powerful 'Streamly.Data.Fold.Fold's:
 --
 -- * folds cannot fail but parsers can fail and backtrack.
 -- * folds can be composed as a Tee but parsers cannot.
 -- * folds can be used for scanning but parsers cannot.
 -- * folds can be converted to parsers.
 --
--- This module implements parsers with stream fusion which compile to efficient
--- loops comparable to the speed of C.
+-- Streamly parsers support all operations offered by popular Haskell parser
+-- libraries. They operate on a generic input type, support streaming, and are
+-- faster.
+--
+-- Like folds, parsers use stream fusion, compiling to efficient low-level code
+-- comparable to the speed of C. Parsers are suitable for high-performance
+-- parsing of streams.
+--
+-- Operations in this module are designed to be composed statically rather than
+-- dynamically. They are inlined to enable static fusion. More importantly,
+-- they are not designed to be used recursively. Recursive use will break
+-- fusion and will lead to quadratic performance slowdown. For dynamic or
+-- recursive composition use the continuation passing style (CPS) operations
+-- from the "Streamly.Data.ParserK" module. 'Parser' and
+-- 'Streamly.Data.ParserK.ParserK' types are interconvertible.
 --
 -- == Using Parsers
 --
@@ -117,23 +130,6 @@
 -- layer (which should be the case almost always) you can just use 'fromEffect'
 -- to execute the lower layer monad effects.
 --
--- == Parser vs ParserK Implementation
---
--- The 'Parser' type represents a stream consumer by composing state as data
--- which enables stream fusion. Stream fusion generates a tight loop without
--- any constructor allocations between the stages, providing C like performance
--- for the loop. Stream fusion works when multiple functions are combined in a
--- pipeline statically. Therefore, the operations in this module must be
--- inlined and must not be used recursively to allow for stream fusion.
---
--- The 'ParserK' type represents a stream consumer by composing function calls,
--- therefore, a function call overhead is incurred at each composition. It is
--- quite fast in general but may be a few times slower than a fused parser.
--- However, it allows for scalable dynamic composition especially parsers can
--- be used in recursive calls. Using the 'ParserK' type operations like
--- 'splitWith' provide linear (O(n)) performance with respect to the number of
--- compositions.
---
 -- == Experimental APIs
 --
 -- Please refer to "Streamly.Internal.Data.Parser" for functions that have not

core/src/Streamly/Data/ParserK.hs

@@ -11,18 +11,24 @@
 -- This module implements a using Continuation Passing Style (CPS) wrapper over
 -- the "Streamly.Data.Parser" module. It is as fast or faster than attoparsec.
 --
--- == Parser vs ParserK
+-- Streamly parsers support all operations offered by popular Haskell parser
+-- libraries. They operate on a generic input type, support streaming, and are
+-- faster.
+--
+-- The 'ParserK' type represents a stream-consumer as a composition of function
+-- calls, therefore, a function call overhead is incurred at each composition.
+-- It is reasonably fast in general but may be a few times slower than a fused
+-- parser represented by the 'Streamly.Data.Parser.Parser' type. However, it
+-- allows for scalable dynamic composition, especially, 'ParserK' can be used
+-- in recursive calls. Operations like 'splitWith' on 'ParserK' type have
+-- linear (O(n)) performance with respect to the number of compositions.
 --
 -- 'ParserK' is preferred over 'Streamly.Data.Parser.Parser' when extensive
 -- applicative, alternative and monadic composition is required, or when
--- recursive or dynamic composition of parsers is required. The
--- 'Streamly.Data.Parser.Parser' type fuses statically and creates efficient
--- loops whereas 'ParserK' uses function call based composition and has
--- comparatively larger runtime overhead but it is better suited to the
--- specific use cases mentioned above. 'ParserK' also allows to efficient parse
--- a stream of arrays, it can also break the input stream into a parse result
--- and remaining stream so that the stream can be parsed independently in
--- segments.
+-- recursive or dynamic composition of parsers is required. 'ParserK' also
+-- allows efficient parsing of a stream of arrays, it can also break the input
+-- stream into a parse result and remaining stream so that the stream can be
+-- parsed independently in segments.
 --
 -- == Using ParserK
 --