Merge branch 'wip-2366-document-topLevelNames-∂π'

akka-docs/scala/actors.rst

@@ -22,10 +22,13 @@ its syntax from Erlang.
 Creating Actors
 ===============
 
-Since Akka enforces parental supervision every actor is supervised and
-(potentially) the supervisor of its children; it is advisable that you
-familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it
-may also help to read :ref:`actorOf-vs-actorFor`.
+.. note::
+
+  Since Akka enforces parental supervision every actor is supervised and
+  (potentially) the supervisor of its children, it is advisable that you
+  familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it
+  may also help to read :ref:`actorOf-vs-actorFor` (the whole of
+  :ref:`addressing` is recommended reading in any case).
 
 Defining an Actor class
 -----------------------

akka-docs/scala/fault-tolerance.rst

@@ -53,7 +53,7 @@ which is a ``PartialFunction[Throwable, Directive]``. This
 is the piece which maps child failure types to their corresponding directives.
 
 Default Supervisor Strategy
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``Escalate`` is used if the defined strategy doesn't cover the exception that was thrown.
 
@@ -68,6 +68,23 @@ exceptions are handled by default:
 If the exception escalate all the way up to the root guardian it will handle it
 in the same way as the default strategy defined above.
 
+Stopping Supervisor Strategy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Closer to the Erlang way is the strategy to just stop children when they fail
+and then take corrective action in the supervisor when DeathWatch signals the
+loss of the child. This strategy is also provided pre-packaged as
+:obj:`SupervisorStrategy.stoppingStrategy` with an accompanying
+:class:`StoppingSupervisorStrategy` configurator to be used when you want the
+``"/user"`` guardian to apply it.
+
+Supervision of Top-Level Actors
+-------------------------------
+
+Toplevel actors means those which are created using ``system.actorOf()``, and
+they are children of the :ref:`User Guardian <user-guardian>`. There are no
+special rules applied in this case, the guardian simply applies the configured
+strategy.
 
 Test Application
 ----------------

akka-docs/scala/remoting.rst

@@ -77,7 +77,9 @@ Once you obtained a reference to the actor you can interact with it they same wa
 
   actor ! "Pretty awesome feature"
 
-For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`.
+.. note::
+
+  For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`.
 
 Creating Actors Remotely
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -281,6 +283,16 @@ you simply register as listener to the below described types in on the ``ActorSy
     To subscribe to any inbound-related events, subscribe to ``RemoteServerLifeCycleEvent``
     To subscribe to any remote events, subscribe to ``RemoteLifeCycleEvent``
 
+By default an event listener is registered which logs all of the events
+described below. This default was chosen to help setting up a system, but it is
+quite common to switch this logging off once that phase of the project is
+finished.
+
+.. note::
+  In order to switch off the logging, set
+  ``akka.remote.log-remote-lifecycle-events = off`` in your
+  ``application.conf``.
+
 To intercept when an outbound connection is disconnected, you listen to ``RemoteClientDisconnected`` which
 holds the transport used (RemoteTransport) and the outbound address that was disconnected (Address).