From 40228e851d2d79d8543e93c1a158f9ab9e2f6125 Mon Sep 17 00:00:00 2001
From: Konrad `ktoso` Malawski <ktoso@project13.pl>
Date: Wed, 27 Sep 2017 15:32:01 +0900
Subject: [PATCH] =doc #23421 move Kill docs around and fix snippet (#23429)

---
 akka-docs/src/main/paradox/scala/actors.md    | 38 +++++++++++--------
 .../test/java/jdocs/actor/ActorDocTest.java   |  4 +-
 .../test/scala/docs/actor/ActorDocSpec.scala  | 20 +++++++++-
 3 files changed, 43 insertions(+), 19 deletions(-)

diff --git a/akka-docs/src/main/paradox/scala/actors.md b/akka-docs/src/main/paradox/scala/actors.md
index 0d389ca5b0..ed64191921 100644
--- a/akka-docs/src/main/paradox/scala/actors.md
+++ b/akka-docs/src/main/paradox/scala/actors.md
@@ -1014,6 +1014,28 @@ Scala
 Java
 :  @@snip [ActorDocTest.java]($code$/java/jdocs/actor/ActorDocTest.java) { #poison-pill }
 
+<a id="killing-actors"></a>
+### Killing an Actor
+
+You can also "kill" an actor by sending a `Kill` message. Unlike `PoisonPill` this will cause 
+the actor to throw a `ActorKilledException`, triggering a failure. The actor will
+suspend operation and its supervisor will be asked how to handle the failure,
+which may mean resuming the actor, restarting it or terminating it completely.
+See @ref:[What Supervision Means](general/supervision.md#supervision-directives) for more information.
+
+Use `Kill` like this:
+
+Scala
+:  @@snip [ActorDocSpec.scala]($code$/scala/docs/actor/ActorDocSpec.scala) { #kill }
+
+Java
+:  @@snip [ActorDocTest.java]($code$/java/jdocs/actor/ActorDocTest.java) { #kill }
+
+In general though it is not recommended to overly rely on either `PoisonPill` or `Kill` in 
+designing your actor interactions, as often times a protocol-level message like `PleaseCleanupAndStop`
+which the actor knows how to handle is encouraged. The messages are there for being able to stop actors
+over which design you do not have control over.
+
 ### Graceful Stop
 
 `gracefulStop` is useful if you need to wait for termination or compose ordered
@@ -1272,22 +1294,6 @@ then you should use the @scala[`UnboundedStash` trait] @java[`AbstractActorWithU
 
 @@@
 
-<a id="killing-actors"></a>
-## Killing an Actor
-
-You can kill an actor by sending a `Kill` message. This will cause the actor
-to throw a `ActorKilledException`, triggering a failure. The actor will
-suspend operation and its supervisor will be asked how to handle the failure,
-which may mean resuming the actor, restarting it or terminating it completely.
-See @ref:[What Supervision Means](general/supervision.md#supervision-directives) for more information.
-
-Use `Kill` like this:
-
-Scala
-:  @@snip [ActorDocSpec.scala]($code$/scala/docs/actor/ActorDocSpec.scala) { #kill }
-
-Java
-:  @@snip [ActorDocTest.java]($code$/java/jdocs/actor/ActorDocTest.java) { #kill }
 
 ## Actors and exceptions
 
diff --git a/akka-docs/src/test/java/jdocs/actor/ActorDocTest.java b/akka-docs/src/test/java/jdocs/actor/ActorDocTest.java
index 191b7e3f71..16ac702e52 100644
--- a/akka-docs/src/test/java/jdocs/actor/ActorDocTest.java
+++ b/akka-docs/src/test/java/jdocs/actor/ActorDocTest.java
@@ -789,8 +789,10 @@ public class ActorDocTest extends AbstractJavaTest {
         watch(victim);
         //#kill
         victim.tell(akka.actor.Kill.getInstance(), ActorRef.noSender());
-        //#kill
+        
+        // expecting the actor to indeed terminate:
         expectTerminated(Duration.create(3, TimeUnit.SECONDS), victim);
+        //#kill
       }
     };
   }
diff --git a/akka-docs/src/test/scala/docs/actor/ActorDocSpec.scala b/akka-docs/src/test/scala/docs/actor/ActorDocSpec.scala
index 874f1025ce..0ebaa1fc04 100644
--- a/akka-docs/src/test/scala/docs/actor/ActorDocSpec.scala
+++ b/akka-docs/src/test/scala/docs/actor/ActorDocSpec.scala
@@ -3,6 +3,7 @@
  */
 package docs.actor
 
+import akka.actor.Kill
 import jdocs.actor.ImmutableMessage
 
 import language.postfixOps
@@ -586,15 +587,30 @@ class ActorDocSpec extends AkkaSpec("""
         }
       }
       //#watch
+
       val victim = system.actorOf(Props(classOf[WatchActor], this))
       implicit val sender = testActor
-      //#kill
       victim ! "kill"
       expectMsg("finished")
-      //#kill
     }
   }
 
+  "using Kill" in {
+    val victim = system.actorOf(TestActors.echoActorProps)
+    implicit val sender = testActor
+    val context = this
+
+    //#kill
+    context.watch(victim) // watch the Actor to receive Terminated message once it dies
+
+    victim ! Kill
+
+    expectMsgPF(hint = "expecting victim to terminate") {
+      case Terminated(v) if v == victim => v // the Actor has indeed terminated 
+    }
+    //#kill
+  }
+
   "demonstrate ActorSelection" in {
     val context = system
     //#selection-local