various documentation patches, found at the bottom of my inbox

akka-docs/java/remoting.rst

@@ -116,6 +116,16 @@ As you can see from the example above the following pattern is used to find an `
   object, which in most cases is not serializable. It is best to make a static
   inner class which implements :class:`UntypedActorFactory`.
 
+.. warning::
+
+  *Caveat:* Remote deployment ties both systems together in a tight fashion,
+  where it may become impossible to shut down one system after the other has
+  become unreachable. This is due to a missing feature—which will be part of
+  the clustering support—that hooks up network failure detection with
+  DeathWatch. If you want to avoid this strong coupling, do not remote-deploy
+  but send ``Props`` to a remotely looked-up actor and have that create a
+  child, returning the resulting actor reference.
+
 Programmatic Remote Deployment
 ------------------------------
 

akka-docs/java/testing.rst

@@ -46,8 +46,8 @@ The tools offered are described in detail in the following sections.
 
    Be sure to add the module :mod:`akka-testkit` to your dependencies.
 
-Unit Testing with :class:`TestActorRef`
-=======================================
+Synchronous Unit Testing with :class:`TestActorRef`
+===================================================
 
 Testing the business logic inside :class:`Actor` classes can be divided into
 two parts: first, each atomic operation must work in isolation, then sequences
@@ -141,8 +141,8 @@ Feel free to experiment with the possibilities, and if you find useful
 patterns, don't hesitate to let the Akka forums know about them! Who knows,
 common operations might even be worked into nice DSLs.
 
-Integration Testing with :class:`JavaTestKit`
-=============================================
+Asynchronous Integration Testing with :class:`JavaTestKit`
+==========================================================
 
 When you are reasonably sure that your actor's business logic is correct, the
 next step is verifying that it works correctly within its intended environment.
@@ -489,6 +489,15 @@ queued invocations from all threads into its own queue and process them.
 Limitations
 -----------
 
+.. warning::
+
+   In case the CallingThreadDispatcher is used for top-level actors, but
+   without going through TestActorRef, then there is a time window during which
+   the actor is awaiting construction by the user guardian actor. Sending
+   messages to the actor during this time period will result in them being
+   enqueued and then executed on the guardian’s thread instead of the caller’s
+   thread. To avoid this, use TestActorRef.
+
 If an actor's behavior blocks on a something which would normally be affected
 by the calling actor after having sent the message, this will obviously
 dead-lock when using this dispatcher. This is a common scenario in actor tests