First start of stream reference docs template

akka-docs/src/main/paradox/stream/reference/++.md

@@ -0,0 +1,23 @@
+# ++
+
+++
+
+## Signature
+
+## Description
+
+Just a shorthand for concat
+
+
+@@@div { .callout }
+
+**emits** when the current stream has an element available; if the current input completes, it tries the next one
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSource.md

@@ -0,0 +1,17 @@
+# Flow.fromSinkAndSource
+
+Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` 
+and the `Flow` 's output will come from the Source.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSourceCoupled.md

@@ -0,0 +1,16 @@
+# Flow.fromSinkAndSourceCoupled
+
+Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/actorRef.md

@@ -0,0 +1,21 @@
+# actorRef
+
+Send the elements from the stream to an `ActorRef`.
+
+## Signature
+
+## Description
+
+Send the elements from the stream to an `ActorRef`. No backpressure so care must be taken to not overflow the inbox.
+
+
+@@@div { .callout }
+
+**cancels** when the actor terminates
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/actorRefWithAck.md

@@ -0,0 +1,23 @@
+# actorRefWithAck
+
+Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message,
+to provide back pressure onto the sink.
+
+## Signature
+
+## Description
+
+Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message,
+to provide back pressure onto the sink.
+
+
+@@@div { .callout }
+
+**cancels** when the actor terminates
+
+**backpressures** when the actor acknowledgement has not arrived
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/alsoTo.md

@@ -0,0 +1,25 @@
+# alsoTo
+
+Attaches the given `Sink` to this `Flow`, meaning that elements that pass through this `Flow` will also be sent to the `Sink`.
+
+## Signature
+
+## Description
+
+Attaches the given `Sink` to this `Flow`, meaning that elements that pass through this `Flow` will also be sent to the `Sink`.
+
+
+@@@div { .callout }
+
+**emits** when an element is available and demand exists both from the `Sink` and the downstream
+
+**backpressures** when downstream or `Sink` backpressures
+
+**completes** when upstream completes
+
+**cancels** when downstream or `Sink` cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/apply.md

@@ -0,0 +1,32 @@
+# apply
+
+Stream the values of an `immutable.
+
+## Signature
+
+## Description
+
+Stream the values of an `immutable.Seq`.
+
+
+@@@div { .callout }
+
+**emits** the next value of the seq
+
+**completes** when the last element of the seq has been emitted
+
+@@@
+
+@@@ div { .group-java }
+
+### from
+
+Stream the values of an `Iterable`. Make sure the `Iterable` is immutable or at least not modified after being used
+as a source.
+
+@@@
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/asInputStream.md

@@ -0,0 +1,16 @@
+# asInputStream
+
+Create a sink which materializes into an `InputStream` that can be read to trigger demand through the sink.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/asJavaStream.md

@@ -0,0 +1,16 @@
+# asJavaStream
+
+Create a sink which materializes into Java 8 `Stream` that can be run to trigger demand through the sink.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/asOutputStream.md

@@ -0,0 +1,16 @@
+# asOutputStream
+
+Create a source that materializes into an `OutputStream`.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/asPublisher.md

@@ -0,0 +1,16 @@
+# asPublisher
+
+Integration with Reactive Streams, materializes into a `org.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/asSubscriber.md

@@ -0,0 +1,16 @@
+# asSubscriber
+
+Integration with Reactive Streams, materializes into a `org.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/ask.md

@@ -0,0 +1,33 @@
+# ask
+
+Use the `ask` pattern to send a request-reply message to the target `ref` actor.
+
+## Signature
+
+## Description
+
+Use the `ask` pattern to send a request-reply message to the target `ref` actor.
+If any of the asks times out it will fail the stream with a [[akka.pattern.AskTimeoutException]].
+
+The `mapTo` class parameter is used to cast the incoming responses to the expected response type.
+
+Similar to the plain ask pattern, the target actor is allowed to reply with `akka.util.Status`.
+An `akka.util.Status#Failure` will cause the stage to fail with the cause carried in the `Failure` message.
+
+Adheres to the [[ActorAttributes.SupervisionStrategy]] attribute.
+
+
+@@@div { .callout }
+
+**emits** when the ask @scala[`Future`] @java[`CompletionStage`] returned by the provided function finishes for the next element in sequence
+
+
+**backpressures** when the number of ask @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures
+
+**completes** when upstream completes and all ask @scala[`Future` s] @java[`CompletionStage` s] has been completed and all elements has been emitted
+
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/backpressureTimeout.md

@@ -0,0 +1,28 @@
+# backpressureTimeout
+
+If the time between the emission of an element and the following downstream demand exceeds the provided timeout,
+the stream is failed with a `TimeoutException`.
+
+## Signature
+
+## Description
+
+If the time between the emission of an element and the following downstream demand exceeds the provided timeout,
+the stream is failed with a `TimeoutException`. The timeout is checked periodically, so the resolution of the
+check is one period (equals to timeout value).
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes or fails if timeout elapses between element emission and downstream demand.
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/balance.md

@@ -0,0 +1,25 @@
+# balance
+
+Fan-out the stream to several streams.
+
+## Signature
+
+## Description
+
+Fan-out the stream to several streams. Each upstream element is emitted to the first available downstream consumer.
+
+
+@@@div { .callout }
+
+**emits** when any of the outputs stops backpressuring; emits the element to the first available output
+
+**backpressures** when all of the outputs backpressure
+
+**completes** when upstream completes
+
+**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel.
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/batch.md

@@ -0,0 +1,32 @@
+# batch
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure and a maximum number of batched elements is not yet reached.
+
+## Signature
+
+## Description
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure and a maximum number of batched elements is not yet reached. When the maximum number is reached and
+downstream still backpressures batch will also backpressure.
+
+When backpressure starts or there is no backpressure element is passed into a `seed` function to transform it
+to the summary type.
+
+Will eagerly pull elements, this behavior may result in a single pending (i.e. buffered) element which cannot be
+aggregated to the batched value.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a batched element available
+
+**backpressures** when batched elements reached the max limit of allowed batched elements & downstream backpressures
+
+**completes** when upstream completes and a "possibly pending" element was drained
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/batchWeighted.md

@@ -0,0 +1,30 @@
+# batchWeighted
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure and a maximum weight batched elements is not yet reached.
+
+## Signature
+
+## Description
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure and a maximum weight batched elements is not yet reached. The weight of each element is determined by
+applying `costFn`. When the maximum total weight is reached and downstream still backpressures batch will also
+backpressure.
+
+Will eagerly pull elements, this behavior may result in a single pending (i.e. buffered) element which cannot be
+aggregated to the batched value.
+
+
+@@@div { .callout }
+
+**emits** downstream stops backpressuring and there is a batched element available
+
+**backpressures** batched elements reached the max weight limit of allowed batched elements & downstream backpressures
+
+**completes** upstream completes and a "possibly pending" element was drained
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/broadcast.md

@@ -0,0 +1,25 @@
+# broadcast
+
+Emit each incoming element each of `n` outputs.
+
+## Signature
+
+## Description
+
+Emit each incoming element each of `n` outputs.
+
+
+@@@div { .callout }
+
+**emits** when all of the outputs stops backpressuring and there is an input element available
+
+**backpressures** when any of the outputs backpressures
+
+**completes** when upstream completes
+
+**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel.
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/bufferBackpressure.md

@@ -0,0 +1,24 @@
+# buffer (Backpressure)
+
+Allow for a temporarily faster upstream events by buffering `size` elements.
+
+## Signature
+
+## Description
+
+Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full backpressure
+is applied.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a pending element in the buffer
+
+**backpressures** when buffer is full
+
+**completes** when upstream completes and buffered elements has been drained
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/bufferDrop.md

@@ -0,0 +1,29 @@
+# buffer (Drop)
+
+Allow for a temporarily faster upstream events by buffering `size` elements.
+
+## Signature
+
+## Description
+
+Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full elements are
+dropped according to the specified `OverflowStrategy`:
+
+ * `dropHead` drops the oldest element in the buffer to make space for the new element
+ * `dropTail` drops the youngest element in the buffer to make space for the new element
+ * `dropBuffer` drops the entire buffer and buffers the new element
+ * `dropNew` drops the new element
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a pending element in the buffer
+
+**backpressures** never (when dropping cannot keep up with incoming elements)
+
+**completes** upstream completes and buffered elements has been drained
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/bufferFail.md

@@ -0,0 +1,24 @@
+# buffer (Fail)
+
+Allow for a temporarily faster upstream events by buffering `size` elements.
+
+## Signature
+
+## Description
+
+Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full the stage fails
+the flow with a `BufferOverflowException`.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a pending element in the buffer
+
+**backpressures** never, fails the stream instead of backpressuring when buffer is full
+
+**completes** when upstream completes and buffered elements has been drained
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/cancelled.md

@@ -0,0 +1,19 @@
+# cancelled
+
+cancelled
+
+## Signature
+
+## Description
+
+Immediately cancel the stream
+
+
+@@@div { .callout }
+
+**cancels** immediately
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/collect.md

@@ -0,0 +1,25 @@
+# collect
+
+Apply a partial function to each incoming element, if the partial function is defined for a value the returned
+value is passed downstream.
+
+## Signature
+
+## Description
+
+Apply a partial function to each incoming element, if the partial function is defined for a value the returned
+value is passed downstream. Can often replace `filter` followed by `map` to achieve the same in one single stage.
+
+
+@@@div { .callout }
+
+**emits** when the provided partial function is defined for the element
+
+**backpressures** the partial function is defined for the element and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/collectType.md

@@ -0,0 +1,17 @@
+# collectType 
+
+Transform this stream by testing the type of each of the elements on which the element is an instance of 
+the provided type as they pass through this processing step.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/combine.md

@@ -0,0 +1,21 @@
+# combine
+
+combine
+
+## Signature
+
+## Description
+
+Combine several sinks into one using a user specified strategy
+
+
+@@@div { .callout }
+
+**cancels** depends on the strategy
+
+**backpressures** depends on the strategy
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/completionTimeout.md

@@ -0,0 +1,27 @@
+# completionTimeout
+
+If the completion of the stream does not happen until the provided timeout, the stream is failed
+with a `TimeoutException`.
+
+## Signature
+
+## Description
+
+If the completion of the stream does not happen until the provided timeout, the stream is failed
+with a `TimeoutException`.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes or fails if timeout elapses before upstream completes
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/concat.md

@@ -0,0 +1,23 @@
+# concat
+
+After completion of the original upstream the elements of the given source will be emitted.
+
+## Signature
+
+## Description
+
+After completion of the original upstream the elements of the given source will be emitted.
+
+
+@@@div { .callout }
+
+**emits** when the current stream has an element available; if the current input completes, it tries the next one
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/conflate.md

@@ -0,0 +1,26 @@
+# conflate
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as
+there is backpressure.
+
+## Signature
+
+## Description
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as
+there is backpressure. The summary value must be of the same type as the incoming elements, for example the sum or
+average of incoming numbers, if aggregation should lead to a different type `conflateWithSeed` can be used:
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a conflated element available
+
+**backpressures** when the aggregate function cannot keep up with incoming elements
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/conflateWithSeed.md

@@ -0,0 +1,26 @@
+# conflateWithSeed
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure.
+
+## Signature
+
+## Description
+
+Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there
+is backpressure. When backpressure starts or there is no backpressure element is passed into a `seed` function to
+transform it to the summary type.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring and there is a conflated element available
+
+**backpressures** when the aggregate or seed functions cannot keep up with incoming elements
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/cycle.md

@@ -0,0 +1,24 @@
+# cycle
+
+Stream iterator in cycled manner.
+
+## Signature
+
+## Description
+
+Stream iterator in cycled manner. Internally new iterator is being created to cycle the one provided via argument meaning
+when original iterator runs out of elements process will start all over again from the beginning of the iterator
+provided by the evaluation of provided parameter. If method argument provides empty iterator stream will be terminated with
+exception.
+
+
+@@@div { .callout }
+
+**emits** the next value returned from cycled iterator
+
+**completes** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/delay.md

@@ -0,0 +1,24 @@
+# delay
+
+Delay every element passed through with a specific duration.
+
+## Signature
+
+## Description
+
+Delay every element passed through with a specific duration.
+
+
+@@@div { .callout }
+
+**emits** there is a pending element in the buffer and configured time for this element elapsed
+
+**backpressures** differs, depends on `OverflowStrategy` set
+
+**completes** when upstream completes and buffered elements has been drained
+
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/detach.md

@@ -0,0 +1,23 @@
+# detach
+
+Detach upstream demand from downstream demand without detaching the stream rates.
+
+## Signature
+
+## Description
+
+Detach upstream demand from downstream demand without detaching the stream rates.
+
+
+@@@div { .callout }
+
+**emits** when the upstream stage has emitted and there is demand
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/divertTo.md

@@ -0,0 +1,25 @@
+# divertTo
+
+Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element.
+
+## Signature
+
+## Description
+
+Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element.
+
+
+@@@div { .callout }
+
+**emits** when the chosen output stops backpressuring and there is an input element available
+
+**backpressures** when the chosen output backpressures
+
+**completes** when upstream completes and no output is pending
+
+**cancels** when any of the downstreams cancel
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/drop.md

@@ -0,0 +1,23 @@
+# drop
+
+Drop `n` elements and then pass any subsequent element downstream.
+
+## Signature
+
+## Description
+
+Drop `n` elements and then pass any subsequent element downstream.
+
+
+@@@div { .callout }
+
+**emits** when the specified number of elements has been dropped already
+
+**backpressures** when the specified number of elements has been dropped and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/dropWhile.md

@@ -0,0 +1,23 @@
+# dropWhile
+
+dropWhile
+
+## Signature
+
+## Description
+
+Drop elements as long as a predicate function return true for the element
+
+
+@@@div { .callout }
+
+**emits** when the predicate returned false and for all following stream elements
+
+**backpressures** predicate returned false and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/dropWithin.md

@@ -0,0 +1,23 @@
+# dropWithin
+
+dropWithin
+
+## Signature
+
+## Description
+
+Drop elements until a timeout has fired
+
+
+@@@div { .callout }
+
+**emits** after the timer fired and a new upstream element arrives
+
+**backpressures** when downstream backpressures
+
+**completes** upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/empty.md

@@ -0,0 +1,22 @@
+# empty
+
+Complete right away without ever emitting any elements.
+
+## Signature
+
+## Description
+
+Complete right away without ever emitting any elements. Useful when you have to provide a source to
+an API but there are no elements to emit.
+
+
+@@@div { .callout }
+
+**emits** never
+
+**completes** directly
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/expand.md

@@ -0,0 +1,28 @@
+# expand
+
+Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original 
+element, allowing for it to be rewritten and/or filtered.
+
+## Signature
+
+## Description
+
+Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original 
+element, allowing for it to be rewritten and/or filtered.
+
+See @ref:[Understanding extrapolate and expand](../stream-rate.md#understanding-extrapolate-and-expand) for more information
+and examples.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/extrapolate.md

@@ -0,0 +1,32 @@
+# extrapolate
+
+Allow for a faster downstream by expanding the last emitted element to an `Iterator`.
+
+## Signature
+
+## Description
+
+Allow for a faster downstream by expanding the last emitted element to an `Iterator`. For example, an
+`Iterator.continually(element)` will cause `extrapolate` to keep repeating the last emitted element. 
+
+All original elements are always emitted unchanged - the `Iterator` is only used whenever there is downstream
+ demand before upstream emits a new element.
+
+Includes an optional `initial` argument to prevent blocking the entire stream when there are multiple producers.
+
+See @ref:[Understanding extrapolate and expand](../stream-rate.md#understanding-extrapolate-and-expand) for more information
+and examples.
+
+
+@@@div { .callout }
+
+**emits** when downstream stops backpressuring
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/failed.md

@@ -0,0 +1,21 @@
+# failed
+
+Fail directly with a user specified exception.
+
+## Signature
+
+## Description
+
+Fail directly with a user specified exception.
+
+
+@@@div { .callout }
+
+**emits** never
+
+**completes** fails the stream directly with the given exception
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/filter.md

@@ -0,0 +1,24 @@
+# filter
+
+Filter the incoming elements using a predicate.
+
+## Signature
+
+## Description
+
+Filter the incoming elements using a predicate. If the predicate returns true the element is passed downstream, if
+it returns false the element is discarded.
+
+
+@@@div { .callout }
+
+**emits** when the given predicate returns true for the element
+
+**backpressures** when the given predicate returns true for the element and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/filterNot.md

@@ -0,0 +1,24 @@
+# filterNot
+
+Filter the incoming elements using a predicate.
+
+## Signature
+
+## Description
+
+Filter the incoming elements using a predicate. If the predicate returns false the element is passed downstream, if
+it returns true the element is discarded.
+
+
+@@@div { .callout }
+
+**emits** when the given predicate returns false for the element
+
+**backpressures** when the given predicate returns false for the element and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/flatMapConcat.md

@@ -0,0 +1,25 @@
+# flatMapConcat
+
+Transform each input element into a `Source` whose elements are then flattened into the output stream through
+concatenation.
+
+## Signature
+
+## Description
+
+Transform each input element into a `Source` whose elements are then flattened into the output stream through
+concatenation. This means each source is fully consumed before consumption of the next source starts.
+
+
+@@@div { .callout }
+
+**emits** when the current consumed substream has an element available
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes and all consumed substreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/flatMapMerge.md

@@ -0,0 +1,25 @@
+# flatMapMerge
+
+Transform each input element into a `Source` whose elements are then flattened into the output stream through
+merging.
+
+## Signature
+
+## Description
+
+Transform each input element into a `Source` whose elements are then flattened into the output stream through
+merging. The maximum number of merged sources has to be specified.
+
+
+@@@div { .callout }
+
+**emits** when one of the currently consumed substreams has an element available
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes and all consumed substreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fold.md

@@ -0,0 +1,25 @@
+# fold
+
+Start with current value `zero` and then apply the current and next value to the given function, when upstream
+complete the current value is emitted downstream.
+
+## Signature
+
+## Description
+
+Start with current value `zero` and then apply the current and next value to the given function, when upstream
+complete the current value is emitted downstream.
+
+
+@@@div { .callout }
+
+**emits** when upstream completes
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/foldAsync.md

@@ -0,0 +1,23 @@
+# foldAsync
+
+Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value.
+
+## Signature
+
+## Description
+
+Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value.
+
+
+@@@div { .callout }
+
+**emits** when upstream completes and the last @scala[`Future`] @java[`CompletionStage`] is resolved
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes and the last @scala[`Future`] @java[`CompletionStage`] is resolved
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/foreach.md

@@ -0,0 +1,26 @@
+# foreach
+
+Invoke a given procedure for each element received.
+
+## Signature
+
+## Description
+
+Invoke a given procedure for each element received. Note that it is not safe to mutate shared state from the procedure.
+
+The sink materializes into a  @scala[`Future[Option[Done]]`] @java[`CompletionStage<Optional<Done>`] which completes when the
+stream completes, or fails if the stream fails.
+
+Note that it is not safe to mutate state from the procedure.
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** when the previous procedure invocation has not yet completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/foreachParallel.md

@@ -0,0 +1,21 @@
+# foreachParallel
+
+Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel.
+
+## Signature
+
+## Description
+
+Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel.
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** when the previous parallel procedure invocations has not yet completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromCompletionStage.md

@@ -0,0 +1,22 @@
+# fromCompletionStage
+
+Send the single value of the `CompletionStage` when it completes and there is demand.
+
+## Signature
+
+## Description
+
+Send the single value of the `CompletionStage` when it completes and there is demand.
+If the future fails the stream is failed with that exception.
+
+
+@@@div { .callout }
+
+**emits** the future completes
+
+**completes** after the future has completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromFuture.md

@@ -0,0 +1,22 @@
+# fromFuture
+
+Send the single value of the `Future` when it completes and there is demand.
+
+## Signature
+
+## Description
+
+Send the single value of the `Future` when it completes and there is demand.
+If the future fails the stream is failed with that exception.
+
+
+@@@div { .callout }
+
+**emits** the future completes
+
+**completes** after the future has completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromFutureSource.md

@@ -0,0 +1,22 @@
+# fromFutureSource
+
+Streams the elements of the given future source once it successfully completes.
+
+## Signature
+
+## Description
+
+Streams the elements of the given future source once it successfully completes. 
+If the future fails the stream is failed.
+
+
+@@@div { .callout }
+
+**emits** the next value from the *future* source, once it has completed
+
+**completes** after the *future* source completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromInputStream.md

@@ -0,0 +1,16 @@
+# fromInputStream
+
+Create a source that wraps an `InputStream`.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromIterator.md

@@ -0,0 +1,24 @@
+# fromIterator
+
+Stream the values from an `Iterator`, requesting the next value when there is demand.
+
+## Signature
+
+## Description
+
+Stream the values from an `Iterator`, requesting the next value when there is demand. The iterator will be created anew
+for each materialization, which is the reason the @scala[`method`] @java[`factory`] takes a @scala[`function`] @java[`Creator`] rather than an `Iterator` directly.
+
+If the iterator perform blocking operations, make sure to run it on a separate dispatcher.
+
+
+@@@div { .callout }
+
+**emits** the next value returned from the iterator
+
+**completes** when the iterator reaches its end
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromJavaStream.md

@@ -0,0 +1,16 @@
+# fromJavaStream
+
+Create a source that wraps a Java 8 `Stream`.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromOutputStream.md

@@ -0,0 +1,16 @@
+# fromOutputStream
+
+Create a sink that wraps an `OutputStream`.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromPath.md

@@ -0,0 +1,17 @@
+# fromPath
+
+Emit the contents of a file, as `ByteString` s, materializes into a @scala[`Future`] @java[`CompletionStage`]` which will be completed with
+a `IOResult` upon reaching the end of the file or if there is a failure.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromPublisher.md

@@ -0,0 +1,16 @@
+# fromPublisher
+
+Integration with Reactive Streams, subscribes to a `org.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromSourceCompletionStage.md

@@ -0,0 +1,22 @@
+# fromSourceCompletionStage
+
+Streams the elements of an asynchronous source once its given *completion* stage completes.
+
+## Signature
+
+## Description
+
+Streams the elements of an asynchronous source once its given *completion* stage completes.
+If the *completion* fails the stream is failed with that exception.
+
+
+@@@div { .callout }
+
+**emits** the next value from the asynchronous source, once its *completion stage* has completed
+
+**completes** after the asynchronous source completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/fromSubscriber.md

@@ -0,0 +1,16 @@
+# fromSubscriber
+
+Integration with Reactive Streams, wraps a `org.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/groupBy.md

@@ -0,0 +1,22 @@
+# groupBy
+
+Demultiplex the incoming stream into separate output streams.
+
+## Signature
+
+## Description
+
+Demultiplex the incoming stream into separate output streams.
+
+
+@@@div { .callout }
+
+**emits** an element for which the grouping function returns a group that has not yet been created. Emits the new group
+there is an element pending for a group whose substream backpressures
+
+**completes** when upstream completes (Until the end of stream it is not possible to know whether new substreams will be needed or not)
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/grouped.md

@@ -0,0 +1,25 @@
+# grouped
+
+Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of
+elements downstream.
+
+## Signature
+
+## Description
+
+Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of
+elements downstream.
+
+
+@@@div { .callout }
+
+**emits** when the specified number of elements has been accumulated or upstream completed
+
+**backpressures** when a group has been assembled and downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/groupedWeightedWithin.md

@@ -0,0 +1,27 @@
+# groupedWeightedWithin
+
+Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements,
+whatever happens first.
+
+## Signature
+
+## Description
+
+Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements,
+whatever happens first. Empty groups will not be emitted if no elements are received from upstream.
+The last group before end-of-stream will contain the buffered elements since the previously emitted group.
+
+
+@@@div { .callout }
+
+**emits** when the configured time elapses since the last group has been emitted,
+but not if no elements has been grouped (i.e: no empty groups), or when weight limit has been reached.
+
+**backpressures** downstream backpressures, and buffered group (+ pending element) weighs more than *maxWeight*
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/groupedWithin.md

@@ -0,0 +1,27 @@
+# groupedWithin
+
+Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements,
+whatever happens first.
+
+## Signature
+
+## Description
+
+Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements,
+whatever happens first. Empty groups will not be emitted if no elements are received from upstream.
+The last group before end-of-stream will contain the buffered elements since the previously emitted group.
+
+
+@@@div { .callout }
+
+**emits** when the configured time elapses since the last group has been emitted,
+but not if no elements has been grouped (i.e: no empty groups), or when limit has been reached.
+
+**backpressures** downstream backpressures, and there are *n+1* buffered elements
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/head.md

@@ -0,0 +1,23 @@
+# head
+
+Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving,
+after this the stream is canceled.
+
+## Signature
+
+## Description
+
+Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving,
+after this the stream is canceled. If no element is emitted, the @scala[`Future`] @java[`CompletionStage`] is failed.
+
+
+@@@div { .callout }
+
+**cancels** after receiving one element
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/headOption.md

@@ -0,0 +1,23 @@
+# headOption
+
+Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage<Optional<T>>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`],
+or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted.
+
+## Signature
+
+## Description
+
+Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage<Optional<T>>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`],
+or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted.
+
+
+@@@div { .callout }
+
+**cancels** after receiving one element
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/idleTimeout.md

@@ -0,0 +1,28 @@
+# idleTimeout
+
+If the time between two processed elements exceeds the provided timeout, the stream is failed
+with a `TimeoutException`.
+
+## Signature
+
+## Description
+
+If the time between two processed elements exceeds the provided timeout, the stream is failed
+with a `TimeoutException`. The timeout is checked periodically, so the resolution of the
+check is one period (equals to timeout value).
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes or fails if timeout elapses between two emitted elements
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/ignore.md

@@ -0,0 +1,22 @@
+# ignore
+
+Consume all elements but discards them.
+
+## Signature
+
+## Description
+
+Consume all elements but discards them. Useful when a stream has to be consumed but there is no use to actually
+do anything with the elements.
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/initialDelay.md

@@ -0,0 +1,25 @@
+# initialDelay
+
+Delays the initial element by the specified duration.
+
+## Signature
+
+## Description
+
+Delays the initial element by the specified duration.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element if the initial delay is already elapsed
+
+**backpressures** when downstream backpressures or initial delay is not yet elapsed
+
+**completes** when upstream completes
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/initialTimeout.md

@@ -0,0 +1,27 @@
+# initialTimeout
+
+If the first element has not passed through this stage before the provided timeout, the stream is failed
+with a `TimeoutException`.
+
+## Signature
+
+## Description
+
+If the first element has not passed through this stage before the provided timeout, the stream is failed
+with a `TimeoutException`.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes or fails if timeout elapses before first element arrives
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/interleave.md

@@ -0,0 +1,24 @@
+# interleave
+
+Emits a specifiable number of elements from the original source, then from the provided source and repeats.
+
+## Signature
+
+## Description
+
+Emits a specifiable number of elements from the original source, then from the provided source and repeats. If one
+source completes the rest of the other stream will be emitted.
+
+
+@@@div { .callout }
+
+**emits** when element is available from the currently consumed upstream
+
+**backpressures** when upstream backpressures
+
+**completes** when both upstreams have completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/intersperse.md

@@ -0,0 +1,23 @@
+# intersperse
+
+Intersperse stream with provided element similar to `List.
+
+## Signature
+
+## Description
+
+Intersperse stream with provided element similar to `List.mkString`. It can inject start and end marker elements to stream.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element or before with the *start* element if provided
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/javaCollector.md

@@ -0,0 +1,17 @@
+# javaCollector
+
+Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector`
+transformation and reduction operations.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/javaCollectorParallelUnordered.md

@@ -0,0 +1,17 @@
+# javaCollectorParallelUnordered
+
+Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector`
+transformation and reduction operations.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/keepAlive.md

@@ -0,0 +1,25 @@
+# keepAlive
+
+Injects additional (configured) elements if upstream does not emit for a configured amount of time.
+
+## Signature
+
+## Description
+
+Injects additional (configured) elements if upstream does not emit for a configured amount of time.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element or if the upstream was idle for the configured period
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+**cancels** when downstream cancels
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/last.md

@@ -0,0 +1,23 @@
+# last
+
+Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream
+completes.
+
+## Signature
+
+## Description
+
+Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream
+completes. If the stream completes with no elements the @scala[`Future`] @java[`CompletionStage`] is failed.
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/lastOption.md

@@ -0,0 +1,24 @@
+# lastOption
+
+Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage<Optional<T>>`] which completes with the last value
+emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes.
+
+## Signature
+
+## Description
+
+Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage<Optional<T>>`] which completes with the last value
+emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes. if the stream completes with no elements the `CompletionStage` is
+completed with @scala[`None`] @java[an empty `Optional`].
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/lazily.md

@@ -0,0 +1,21 @@
+# lazily
+
+Defers creation and materialization of a `Source` until there is demand.
+
+## Signature
+
+## Description
+
+Defers creation and materialization of a `Source` until there is demand.
+
+
+@@@div { .callout }
+
+**emits** depends on the wrapped `Source`
+
+**completes** depends on the wrapped `Source`
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/lazilyAsync.md

@@ -0,0 +1,21 @@
+# lazilyAsync
+
+Defers creation and materialization of a `CompletionStage` until there is demand.
+
+## Signature
+
+## Description
+
+Defers creation and materialization of a `CompletionStage` until there is demand.
+
+
+@@@div { .callout }
+
+**emits** the future completes
+
+**completes** after the future has completed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/lazyInitAsync.md

@@ -0,0 +1,34 @@
+# lazyInitAsync
+
+Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument.
+
+## Signature
+
+## Description
+
+Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument.
+Internal `Flow` will not be created if there are no elements, because of completion or error.
+The materialized value of the `Flow` will be the materialized value of the created internal flow.
+
+The materialized value of the `Flow` is a @scala[`Future[Option[M]]`]@java[`CompletionStage<Optional<M>>`] that is 
+completed with @scala[`Some(mat)`]@java[`Optional.of(mat)`] when the internal flow gets materialized or with @scala[`None`]
+@java[an empty optional] when there where no elements. If the flow materialization (including the call of the `flowFactory`) 
+fails then the future is completed with a failure.
+
+Adheres to the `ActorAttributes.SupervisionStrategy` attribute.
+
+
+@@@div { .callout }
+
+**emits** when the internal flow is successfully created and it emits
+
+**backpressures** when the internal flow is successfully created and it backpressures
+
+**completes** when upstream completes and all elements have been emitted from the internal flow
+
+**completes** when upstream completes and all futures have been completed and all elements have been emitted
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/limit.md

@@ -0,0 +1,23 @@
+# limit
+
+Limit number of element from upstream to given `max` number.
+
+## Signature
+
+## Description
+
+Limit number of element from upstream to given `max` number.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits and the number of emitted elements has not reached max
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes and the number of emitted elements has not reached max
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/limitWeighted.md

@@ -0,0 +1,24 @@
+# limitWeighted
+
+Ensure stream boundedness by evaluating the cost of incoming elements using a cost function.
+
+## Signature
+
+## Description
+
+Ensure stream boundedness by evaluating the cost of incoming elements using a cost function.
+Evaluated cost of each element defines how many elements will be allowed to travel downstream.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits and the number of emitted elements has not reached max
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes and the number of emitted elements has not reached max
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/log.md

@@ -0,0 +1,25 @@
+# log
+
+Log elements flowing through the stream as well as completion and erroring.
+
+## Signature
+
+## Description
+
+Log elements flowing through the stream as well as completion and erroring. By default element and
+completion signals are logged on debug level, and errors are logged on Error level.
+This can be changed by calling @scala[`Attributes.logLevels(...)`] @java[`Attributes.createLogLevels(...)`] on the given Flow.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/map.md

@@ -0,0 +1,23 @@
+# map
+
+Transform each element in the stream by calling a mapping function with it and passing the returned value downstream.
+
+## Signature
+
+## Description
+
+Transform each element in the stream by calling a mapping function with it and passing the returned value downstream.
+
+
+@@@div { .callout }
+
+**emits** when the mapping function returns an element
+
+**backpressures** when downstream backpressures
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mapAsync.md

@@ -0,0 +1,27 @@
+# mapAsync
+
+Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result.
+
+## Signature
+
+## Description
+
+Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result. When the @scala[`Future`] @java[`CompletionStage`] arrives the result is passed
+downstream. Up to `n` elements can be processed concurrently, but regardless of their completion time the incoming
+order will be kept when results complete. For use cases where order does not matter `mapAsyncUnordered` can be used.
+
+If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unless a different supervision strategy is applied)
+
+
+@@@div { .callout }
+
+**emits** when the @scala[`Future`] @java[`CompletionStage`] returned by the provided function finishes for the next element in sequence
+
+**backpressures** when the number of @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures
+
+**completes** when upstream completes and all @scala[`Future` s] @java[`CompletionStage` s] has been completed and all elements has been emitted
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mapAsyncUnordered.md

@@ -0,0 +1,27 @@
+# mapAsyncUnordered
+
+Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements
+that triggered them.
+
+## Signature
+
+## Description
+
+Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements
+that triggered them.
+
+If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unless a different supervision strategy is applied)
+
+
+@@@div { .callout }
+
+**emits** any of the @scala[`Future` s] @java[`CompletionStage` s] returned by the provided function complete
+
+**backpressures** when the number of @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures
+
+**completes** upstream completes and all @scala[`Future` s] @java[`CompletionStage` s] has been completed  and all elements has been emitted
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mapConcat.md

@@ -0,0 +1,23 @@
+# mapConcat
+
+Transform each element into zero or more elements that are individually passed downstream.
+
+## Signature
+
+## Description
+
+Transform each element into zero or more elements that are individually passed downstream.
+
+
+@@@div { .callout }
+
+**emits** when the mapping function returns an element or there are still remaining elements from the previously calculated collection
+
+**backpressures** when downstream backpressures or there are still available elements from the previously calculated collection
+
+**completes** when upstream completes and all remaining elements has been emitted
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mapError.md

@@ -0,0 +1,29 @@
+# mapError
+
+While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging
+it as an error in the process.
+
+## Signature
+
+## Description
+
+While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging
+it as an error in the process. So in that sense it is NOT exactly equivalent to `recover(t => throw t2)` since recover
+would log the `t2` error.
+
+Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements.
+This stage can recover the failure signal, but not the skipped elements, which will be dropped.
+
+Similarily to `recover` throwing an exception inside `mapError` _will_ be logged on ERROR level automatically.
+
+
+@@@div { .callout }
+
+**emits** when element is available from the upstream or upstream is failed and pf returns an element
+**backpressures** when downstream backpressures
+**completes** when upstream completes or upstream failed with exception pf can handle
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/maybe.md

@@ -0,0 +1,23 @@
+# maybe
+
+Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] 
+will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away.
+
+## Signature
+
+## Description
+
+Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] 
+will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away.
+
+
+@@@div { .callout }
+
+**emits** when the returned promise is completed with some value
+
+**completes** after emitting some value, or directly if the promise is completed with no value
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/merge.md

@@ -0,0 +1,23 @@
+# merge
+
+Merge multiple sources.
+
+## Signature
+
+## Description
+
+Merge multiple sources. Picks elements randomly if all sources has elements ready.
+
+
+@@@div { .callout }
+
+**emits** when one of the inputs has an element available
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.)
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mergePreferred.md

@@ -0,0 +1,23 @@
+# mergePreferred
+
+Merge multiple sources.
+
+## Signature
+
+## Description
+
+Merge multiple sources. Prefer one source if all sources has elements ready.
+
+
+@@@div { .callout }
+
+**emits** when one of the inputs has an element available, preferring a defined input if multiple have elements available
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.)
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mergePrioritized.md

@@ -0,0 +1,24 @@
+# mergePrioritized
+
+Merge multiple sources.
+
+## Signature
+
+## Description
+
+Merge multiple sources. Prefer sources depending on priorities if all sources has elements ready. If a subset of all
+sources has elements ready the relative priorities for those sources are used to prioritise.
+
+
+@@@div { .callout }
+
+**emits** when one of the inputs has an element available, preferring inputs based on their priorities if multiple have elements available
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.)
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/mergeSorted.md

@@ -0,0 +1,24 @@
+# mergeSorted
+
+Merge multiple sources.
+
+## Signature
+
+## Description
+
+Merge multiple sources. Waits for one element to be ready from each input stream and emits the
+smallest element.
+
+
+@@@div { .callout }
+
+**emits** when all of the inputs have an element available
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/monitor.md

@@ -0,0 +1,25 @@
+# monitor
+
+Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage.
+
+## Signature
+
+## Description
+
+Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. The stage otherwise
+passes through elements unchanged. Note that the `FlowMonitor` inserts a memory barrier every time it processes an
+event, and may therefore affect performance.
+
+
+@@@div { .callout }
+
+**emits** when upstream emits an element
+
+**backpressures** when downstream **backpressures**
+
+**completes** when upstream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/onComplete.md

@@ -0,0 +1,21 @@
+# onComplete
+
+Invoke a callback when the stream has completed or failed.
+
+## Signature
+
+## Description
+
+Invoke a callback when the stream has completed or failed.
+
+
+@@@div { .callout }
+
+**cancels** never
+
+**backpressures** never
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/orElse.md

@@ -0,0 +1,32 @@
+# orElse
+
+If the primary source completes without emitting any elements, the elements from the secondary source
+are emitted.
+
+## Signature
+
+## Description
+
+If the primary source completes without emitting any elements, the elements from the secondary source
+are emitted. If the primary source emits any elements the secondary source is cancelled.
+
+Note that both sources are materialized directly and the secondary source is backpressured until it becomes
+the source of elements or is cancelled.
+
+Signal errors downstream, regardless which of the two sources emitted the error.
+
+
+@@@div { .callout }
+
+**emits** when an element is available from first stream or first stream closed without emitting any elements and an element
+is available from the second stream
+
+**backpressures** when downstream backpressures
+
+**completes** the primary stream completes after emitting at least one element, when the primary stream completes
+without emitting and the secondary stream already has completed or when the secondary stream completes
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/partition.md

@@ -0,0 +1,26 @@
+# partition
+
+Fan-out the stream to several streams.
+
+## Signature
+
+## Description
+
+Fan-out the stream to several streams. Each upstream element is emitted to one downstream consumer according to the
+partitioner function applied to the element.
+
+
+@@@div { .callout }
+
+**emits** when the chosen output stops backpressuring and there is an input element available
+
+**backpressures** when the chosen output backpressures
+
+**completes** when upstream completes and no output is pending
+
+**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel.
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/preMaterialize.md

@@ -0,0 +1,16 @@
+# preMaterialize
+
+Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one.
+
+## Signature
+
+## Description
+
+
+
+@@@div { .callout }
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/prefixAndTail.md

@@ -0,0 +1,25 @@
+# prefixAndTail
+
+Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements)
+and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements.
+
+## Signature
+
+## Description
+
+Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements)
+and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements.
+
+
+@@@div { .callout }
+
+**emits** when the configured number of prefix elements are available. Emits this prefix, and the rest as a substream
+
+**backpressures** when downstream backpressures or substream backpressures
+
+**completes** when prefix elements has been consumed and substream has been consumed
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/prepend.md

@@ -0,0 +1,25 @@
+# prepend
+
+Prepends the given source to the flow, consuming it until completion before the original source is consumed.
+
+## Signature
+
+## Description
+
+Prepends the given source to the flow, consuming it until completion before the original source is consumed.
+
+If materialized values needs to be collected `prependMat` is available.
+
+
+@@@div { .callout }
+
+**emits** when the given stream has an element available; if the given input completes, it tries the current one
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete
+
+@@@
+
+## Example
+

akka-docs/src/main/paradox/stream/reference/queue.md

@@ -0,0 +1,22 @@
+# queue
+
+Materialize a `SinkQueue` that can be pulled to trigger demand through the sink.
+
+## Signature
+
+## Description
+
+Materialize a `SinkQueue` that can be pulled to trigger demand through the sink. The queue contains
+a buffer in case stream emitting elements faster than queue pulling them.
+
+
+@@@div { .callout }
+
+**cancels** when  `SinkQueue.cancel` is called
+
+**backpressures** when buffer has some space
+
+@@@
+
+## Example
+