From 739796d81ec00bd46a72e9ac352ef7762629625e Mon Sep 17 00:00:00 2001
From: Patrik Nordwall <patrik.nordwall@gmail.com>
Date: Tue, 14 Apr 2015 11:16:51 +0200
Subject: [PATCH] =str #17173 Clarify CompletionHandling scaladoc

---
 .../main/scala/akka/stream/javadsl/FlexiRoute.scala    | 10 +++++-----
 .../main/scala/akka/stream/scaladsl/FlexiRoute.scala   |  6 ++++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
index ad6f2984f8..c62b587126 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
@@ -91,11 +91,13 @@ object FlexiRoute {
    * How to handle completion or failure from upstream input and how to
    * handle cancel from downstream output.
    *
-   * The `onUpstreamFinish` method is called the upstream input was completed successfully.
-   * It returns next behavior or [[#sameState]] to keep current behavior.
+   * The `onUpstreamFinish` method is called when the upstream input was completed successfully.
+   * The completion will be propagated downstreams unless this function throws an exception, in
+   * which case the streams will be completed with that failure.
    *
    * The `onUpstreamFailure` method is called when the upstream input was completed with failure.
-   * It returns next behavior or [[#SameState]] to keep current behavior.
+   * The failure will be propagated downstreams unless this function throws an exception, in
+   * which case the streams will be completed with that failure instead.
    *
    * The `onDownstreamFinish` method is called when a downstream output cancels.
    * It returns next behavior or [[#sameState]] to keep current behavior.
@@ -163,7 +165,6 @@ object FlexiRoute {
 
     /**
      * When an output cancels it continues with remaining outputs.
-     * Failure or completion from upstream are immediately propagated.
      */
     def defaultCompletionHandling: CompletionHandling[In] =
       new CompletionHandling[In] {
@@ -175,7 +176,6 @@ object FlexiRoute {
 
     /**
      * Completes as soon as any output cancels.
-     * Failure or completion from upstream are immediately propagated.
      */
     def eagerClose[A]: CompletionHandling[In] =
       new CompletionHandling[In] {
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/FlexiRoute.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/FlexiRoute.scala
index b8d439f2ef..46a75722de 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/FlexiRoute.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/FlexiRoute.scala
@@ -136,8 +136,12 @@ object FlexiRoute {
      * handle cancel from downstream output.
      *
      * The `onUpstreamFinish` function is called the upstream input was completed successfully.
+     * The completion will be propagated downstreams unless this function throws an exception, in
+     * which case the streams will be completed with that failure.
      *
      * The `onUpstreamFailure` function is called when the upstream input was completed with failure.
+     * The failure will be propagated downstreams unless this function throws an exception, in
+     * which case the streams will be completed with that failure instead.
      *
      * The `onDownstreamFinish` function is called when a downstream output cancels.
      * It returns next behavior or [[#SameState]] to keep current behavior.
@@ -152,7 +156,6 @@ object FlexiRoute {
 
     /**
      * When an output cancels it continues with remaining outputs.
-     * Failure or completion from upstream are immediately propagated.
      */
     val defaultCompletionHandling: CompletionHandling = CompletionHandling(
       onUpstreamFinish = _ ⇒ (),
@@ -161,7 +164,6 @@ object FlexiRoute {
 
     /**
      * Completes as soon as any output cancels.
-     * Failure or completion from upstream are immediately propagated.
      */
     val eagerClose: CompletionHandling = CompletionHandling(
       onUpstreamFinish = _ ⇒ (),