@@ -9,6 +9,26 @@
99--
1010-- Streams using Continuation Passing Style (CPS). See notes in "Data.Stream"
1111-- module to know when to use this module.
12+--
13+-- 'StreamK' operations have more overhead than 'Stream' operations, however,
14+-- 'Stream' operations fuse only when the pipeline is statically composed, is
15+-- not too large, and does not involve recursion. For such cases, a typical
16+-- example is creating a large or infinite stream by appending, 'StreamK'
17+-- should be used.
18+--
19+-- You can use operations from "Streamly.Data.Stream" for StreamK as well by
20+-- converting StreamK to Stream, and vice-versa. Most of the time converting to
21+-- 'Stream' is better than using native StreamK operations, however in certain
22+-- cases using native StreamK operations may work better. Using 'Stream'
23+-- operations are especially when multiple contiguous operations can fuse
24+-- together.
25+--
26+-- There are no native exception handling operations in the StreamK module,
27+-- please use 'toStream' to convert to 'Stream' type and use exception
28+-- handling operations from "Streamly.Data.Stream".
29+--
30+-- See "Streamly.Internal.Data.Stream.StreamK" for more native StreamK
31+-- operations.
1232
1333-- primitive/open loop operations that can be used recursively e.g. uncons,
1434-- foldBreak, parseBreak should not be converted from StreamD for use in