various documentation patches, found at the bottom of my inbox

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

@@ -66,4 +66,51 @@ This means that:
     5) ``A2`` can see messages from ``A1`` interleaved with messages from ``A3``
     6) Since there is no guaranteed delivery, none, some or all of the messages may arrive to ``A2``
 
+.. _deadletters:
+
+Dead Letters
+============
+
+Messages which cannot be delivered (and for which this can be ascertained) will
+be delivered to a synthetic actor called ``/deadLetters``. This delivery
+happens on a best-effort basis; it may fail even within the local JVM (e.g.
+during actor termination). Messages sent via unreliable network transports will
+be lost without turning up as dead letters.
+
+How do I Receive Dead Letters?
+------------------------------
+
+An actor can subscribe to class :class:`akka.actor.DeadLetter` on the event
+stream, see :ref:`event-stream-java` (Java) or :ref:`event-stream-scala`
+(Scala) for how to do that. The subscribed actor will then receive all dead
+letters published in the (local) system from that point onwards. Dead letters
+are not propagated over the network, if you want to collect them in one place
+you will have to subscribe one actor per network node and forward them
+manually. Also consider that dead letters are generated at that node which can
+determine that a send operation is failed, which for a remote send can be the
+local system (if no network connection can be established) or the remote one
+(if the actor you are sending to does not exist at that point in time).
+
+What Should I Use Dead Letters For?
+-----------------------------------
+
+The dead letter service follows the same rules with respect to delivery
+guarantees as all other message sends, hence it cannot be used to implement
+guaranteed delivery. The main use is for debugging, especially if an actor send
+does not arrive consistently (where usually inspecting the dead letters will
+tell you that the sender or recipient was set wrong somewhere along the way).
+
+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:
+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
+while stopping a hierarchy of actors turning up in dead letters if the parent
+is still watching the child when the parent terminates.
+
 .. _Erlang documentation: http://www.erlang.org/faq/academic.html
+

akka-docs/general/supervision.rst

@@ -141,17 +141,17 @@ re-processed.
 
 The precise sequence of events during a restart is the following:
 
-* suspend the actor
-* call the old instance’s :meth:`supervisionStrategy.handleSupervisorFailing`
-  method (defaults to suspending all children)
-* call the old instance’s :meth:`preRestart` hook (defaults to sending
-  termination requests to all children and calling :meth:`postStop`)
-* wait for all children stopped during :meth:`preRestart` to actually terminate
-* call the old instance’s :meth:`supervisionStrategy.handleSupervisorRestarted`
-  method (defaults to sending restart request to all remaining children)
-* create new actor instance by invoking the originally provided factory again
-* invoke :meth:`postRestart` on the new instance
-* resume the actor
+#. suspend the actor (which means that it will not process normal messages until
+   resumed), and recursively suspend all children
+#. call the old instance’s :meth:`preRestart` hook (defaults to sending
+   termination requests to all children and calling :meth:`postStop`)
+#. 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
+#. send restart request to all children (they will follow the same process
+   recursively, from step 2)
+#. resume the actor
 
 What Lifecycle Monitoring Means
 -------------------------------