@@ -218,15 +218,18 @@ data AppendState s1 s2 = AppendFirst s1 | AppendSecond s2
218218-- >>> Stream.fold Fold.toList $ s1 `Stream.append` s2
219219-- [1,2,3,4]
220220--
221−-- This function should not be used to dynamically construct a stream. If a
222−-- stream is constructed by successive use of this function it would take
223−-- quadratic time complexity to consume the stream.
221+-- From an implementation perspective, StreamK.'Streamly.Data.StreamK.append'
222+-- translates into a function call whereas Stream.'append' translates into a
223+-- conditional branch (jump). However, the overhead of the function call in
224+-- StreamK.append is incurred only once, while the overhead of the conditional
225+-- branch in fused append is incurred for each element in the stream. As a
226+-- result, StreamK.append has a linear time complexity of O(n), while fused
227+-- append has a quadratic time complexity of O(n^2), where @n@ represents the
228+-- number of 'append's used.
224229--
225230-- This function should only be used to statically fuse a stream with another
226−-- stream. Do not use this recursively or where it cannot be inlined.
227−--
228−-- See "Streamly.Data.StreamK" for an 'append' that can be used to
229−-- construct a stream recursively.
231+-- stream. Do not use it recursively or where it cannot be inlined. Use
232+-- StreamK.'Streamly.Data.StreamK.append' for those cases.
230233--
231234{-# INLINE_NORMAL append #-}
232235append :: Monad m => Stream m a -> Stream m a -> Stream m a