@@ -568,10 +568,33 @@ forEachWith = P.forEachWith
568568-- $concurrency
569569--
570570-- These combinators can be used at any point in a stream composition to set
571−-- parameters to control the concurrency of the enclosed stream. A parameter
572−-- set at any point remains effective for any concurrent combinators used
573−-- downstream until it is reset. These control parameters have no effect on
574−-- non-concurrent combinators in the stream, or on non-concurrent streams.
571+-- parameters to control the concurrency of the /argument stream/. A control
572+-- parameter set at any point remains effective for any concurrent combinators
573+-- used in the argument stream until it is reset by using the combinator again.
574+-- These control parameters have no effect on non-concurrent combinators in the
575+-- stream, or on non-concurrent streams.
576+--
577+-- /Pitfall:/ Remember that 'maxBuffer' in the following example applies to
578+-- 'mapM' and any other combinators that may follow it, and it does not apply
579+-- to the combinators before it:
580+--
581+-- @
582+-- ...
583+-- $ maxBuffer 10
584+-- $ S.mapM ...
585+-- ...
586+-- @
587+--
588+-- If we use '&' instead of '$' the situation will reverse, in the following
589+-- example, 'maxBuffer' does not apply to 'mapM', it applies to combinators
590+-- that come before it, because those are the arguments to 'maxBuffer':
591+--
592+-- @
593+-- ...
594+-- & maxBuffer 10
595+-- & S.mapM ...
596+-- ...
597+-- @
575598
576599-- $adapters
577600--