@@ -572,9 +572,9 @@ concatSmapMWith combine f initial =
572572
573573-- XXX Implement a StreamD version for fusion.
574574
575−-- | Combine streams in pairs using a binary stream combinator, then combine
576−-- the resulting streams in pairs recursively until we get to a single combined
577−-- stream.
575+-- | Combine streams in pairs using a binary combinator, the resulting streams
576+-- are then combined again in pairs recursively until we get to a single
577+-- combined stream. The composition would thus form a binary tree.
578578--
579579-- For example, you can sort a stream using merge sort like this:
580580--
@@ -584,6 +584,10 @@ concatSmapMWith combine f initial =
584584-- >>> Stream.fold Fold.toList $ Stream.concatPairsWith combine generate s
585585-- [1,2,5,7,9]
586586--
587+-- Note that if the stream length is not a power of 2, the binary tree composed
588+-- by concatPairsWith would not be balanced, which may or may not be important
589+-- depending on what you are trying to achieve.
590+--
587591-- /Caution: the stream of streams must be finite/
588592--
589593-- /Pre-release/