Merge pull request #910 from akka/wip-docs-∂π

Wip docs ∂π

akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala

@@ -189,6 +189,15 @@ class FSMDocSpec extends MyFavoriteTestFrameWorkPlusAkkaTestKit {
     }
     //#fsm-code-elided
 
+    "demonstrate NullFunction" in {
+      class A extends Actor with FSM[Int, Null] {
+        val SomeState = 0
+        //#NullFunction
+        when(SomeState)(FSM.NullFunction)
+        //#NullFunction
+      }
+    }
+
     "batch correctly" in {
       val buncher = system.actorOf(Props(new Buncher))
       buncher ! SetTarget(testActor)

akka-docs/rst/scala/code/docs/serialization/SerializationDocSpec.scala

@@ -2,19 +2,6 @@
  * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
  */
 
-//#extract-transport
-package object akka {
-  // needs to be inside the akka package because accessing unsupported API !
-  def transportOf(system: actor.ExtendedActorSystem): remote.RemoteTransport =
-    system.provider match {
-      case r: remote.RemoteActorRefProvider ⇒ r.transport
-      case _ ⇒
-        throw new UnsupportedOperationException(
-          "this method requires the RemoteActorRefProvider to be configured")
-    }
-}
-//#extract-transport
-
 package docs.serialization {
 
   import org.scalatest.matchers.MustMatchers
@@ -216,7 +203,7 @@ package docs.serialization {
       object ExternalAddress extends ExtensionKey[ExternalAddressExt]
 
       class ExternalAddressExt(system: ExtendedActorSystem) extends Extension {
-        def addressForAkka: Address = akka.transportOf(system).address
+        def addressForAkka: Address = system.provider.getDefaultAddress
       }
 
       def serializeAkkaDefault(ref: ActorRef): String =

akka-docs/rst/scala/fsm.rst

@@ -179,6 +179,18 @@ demonstrated below:
 The :class:`Event(msg: Any, data: D)` case class is parameterized with the data
 type held by the FSM for convenient pattern matching.
 
+.. warning::
+
+  It is required that you define handlers for each of the possible FSM states,
+  otherwise there will be failures when trying to switch to undeclared states.
+
+It is recommended practice to declare the states as objects extending a
+sealed trait and then verify that there is a ``when`` clause for each of the
+states. If you want to leave the handling of a state “unhandled” (more below),
+it still needs to be declared like this:
+
+.. includecode:: code/docs/actor/FSMDocSpec.scala#NullFunction
+
 Defining the Initial State
 --------------------------
 

akka-docs/rst/scala/serialization.rst

@@ -138,24 +138,12 @@ concrete address handy you can create a dummy one for the right protocol using
 ``Address(protocol, "", "", 0)`` (assuming that the actual transport used is as
 lenient as Akka’s RemoteActorRefProvider).
 
-There is a possible simplification available if you are just using the default
-:class:`NettyRemoteTransport` with the :meth:`RemoteActorRefProvider`, which is
-enabled by the fact that this combination has just a single remote address.
-This approach relies on internal API, which means that it is not guaranteed to
-be supported in future versions. To make this caveat more obvious, some bridge
-code in the ``akka`` package is required to make it work:
-
-.. includecode:: code/docs/serialization/SerializationDocSpec.scala
-   :include: extract-transport
-
-And with this, the address extraction goes like this:
+There is also a default remote address which is the one used by cluster support
+(and typical systems have just this one); you can get it like this:
 
 .. includecode:: code/docs/serialization/SerializationDocSpec.scala
    :include: external-address-default
 
-This solution has to be adapted once other providers are used (like the planned
-extensions for clustering).
-
 Deep serialization of Actors
 ----------------------------