@@ -568,10 +568,33 @@ forEachWith = P.forEachWith
568-- $concurrency
568-- $concurrency
570-- These combinators can be used at any point in a stream composition to set
570-- 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
571+-- parameters to control the concurrency of the /argument stream/. A control
572−-- set at any point remains effective for any concurrent combinators used
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.
573−-- downstream until it is reset. These control parameters have no effect on
574+-- These control parameters have no effect on non-concurrent combinators in the
574−-- non-concurrent combinators in the stream, or on non-concurrent streams.
575+-- stream, or on non-concurrent streams.
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:
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':
576-- $adapters
599-- $adapters