various documentation improvements

- document DeathWatch
- actorOf vs. actorFor

akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java

@@ -24,6 +24,10 @@ import static akka.actor.Actors.*;
 import akka.japi.Procedure;
 //#import-procedure
 
+//#import-watch
+import akka.actor.Terminated;
+//#import-watch
+
 import akka.actor.Props;
 import akka.actor.UntypedActor;
 import akka.actor.UntypedActorFactory;
@@ -161,6 +165,15 @@ public class UntypedActorDocTestBase {
     system.shutdown();
   }
 
+  @Test
+  public void useWatch() {
+    ActorSystem system = ActorSystem.create("MySystem");
+    ActorRef myActor = system.actorOf(new Props(WatchActor.class));
+    Future<Object> future = myActor.ask("kill", 1000);
+    assert Await.result(future, Duration.parse("1 second")).equals("finished");
+    system.shutdown();
+  }
+
   public static class MyActor extends UntypedActor {
 
     public MyActor(String s) {
@@ -251,4 +264,27 @@ public class UntypedActorDocTestBase {
   }
   //#hot-swap-actor
 
+  //#watch
+  public static class WatchActor extends UntypedActor {
+    final ActorRef child = this.getContext().actorOf(Props.empty(), "child");
+    {
+      this.getContext().watch(child); // <-- this is the only call needed for registration
+    }
+    ActorRef lastSender = getContext().system().deadLetters();
+
+    @Override
+    public void onReceive(Object message) {
+      if (message.equals("kill")) {
+        getContext().stop(child);
+        lastSender = getSender();
+      } else if (message instanceof Terminated) {
+        final Terminated t = (Terminated) message;
+        if (t.getActor() == child) {
+          lastSender.tell("finished");
+        }
+      }
+    }
+  }
+  //#watch
+
 }