document deadlock risk of TestProbe.watch(TestActorRef), see #2916

akka-docs/rst/scala/code/docs/testkit/TestkitDocSpec.scala

@@ -206,6 +206,16 @@ class TestkitDocSpec extends AkkaSpec with DefaultTimeout with ImplicitSender {
     //#test-special-probe
   }
 
+  "demonstrate probe watch" in {
+    import akka.testkit.TestProbe
+    val target = system.actorFor("/buh")
+    //#test-probe-watch
+    val probe = TestProbe()
+    probe watch target
+    probe.expectMsgType[Terminated].actor must be(target)
+    //#test-probe-watch
+  }
+
   "demonstrate probe reply" in {
     import akka.testkit.TestProbe
     import scala.concurrent.duration._

akka-docs/rst/scala/testing.rst

@@ -446,6 +446,23 @@ facilities with your own checks and choosing an intuitive name for it. In real
 life your code will probably be a bit more complicated than the example given
 above; just use the power!
 
+.. warning::
+
+  Any message send from a ``TestProbe`` to another actor which runs on the
+  CallingThreadDispatcher runs the risk of dead-lock, if that other actor might
+  also send to this probe. The implementation of :meth:`TestProbe.watch` and
+  :meth:`TestProbe.unwatch` will also send a message to the watchee, which
+  means that it is dangerous to try watching e.g. :class:`TestActorRef` from a
+  :meth:`TestProbe`.
+
+Watching Other Actors from Probes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A :class:`TestKit` can register itself for DeathWatch of any other actor:
+
+.. includecode:: code/docs/testkit/TestkitDocSpec.scala
+   :include: test-probe-watch
+
 Replying to Messages Received by Probes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^