Doc changes after review of PR 724

akka-docs/general/message-send-semantics.rst

@@ -104,8 +104,8 @@ Dead Letters Which are (Usually) not Worrisome
 ----------------------------------------------
 
 Every time an actor does not terminate by its own decision, there is a chance
-that some messages are lost which it sends to itself. There is one which may
-happen in complex shutdown scenarios quite easily which is usually benign:
+that some messages which it sends to itself are lost. There is one which
+happens quite easily in complex shutdown scenarios that is usually benign:
 seeing a :class:`akka.dispatch.Terminate` message dropped means that two
 termination requests were given, but of course only one can succeed. In the
 same vein, you might see :class:`akka.actor.Terminated` messages from children

akka-docs/general/supervision.rst

@@ -148,7 +148,7 @@ The precise sequence of events during a restart is the following:
 #. wait for all children which were requested to terminate (using
    ``context.stop()``) during :meth:`preRestart` to actually terminate
 #. create new actor instance by invoking the originally provided factory again
-#. invoke :meth:`postRestart` on the new instance
+#. invoke :meth:`postRestart` on the new instance (which by default also calls :meth:`preStart`)
 #. send restart request to all children (they will follow the same process
    recursively, from step 2)
 #. resume the actor

akka-docs/java/remoting.rst

@@ -126,6 +126,10 @@ As you can see from the example above the following pattern is used to find an `
   but send ``Props`` to a remotely looked-up actor and have that create a
   child, returning the resulting actor reference.
 
+.. warning::
+
+  *Caveat:* Akka Remoting does not trigger Death Watch for lost connections.
+
 Programmatic Remote Deployment
 ------------------------------