Merge pull request #1933 from akka/wip-3764-props-docs-∂π

clean up docs and deprecation around how to create Props

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

@@ -59,7 +59,7 @@ class DemoActorWrapper extends Actor {
      * @return a Props for creating this actor, which can then be further configured
      *         (e.g. calling `.withDispatcher()` on it)
      */
-    def props(magicNumber: Int): Props = Props(classOf[DemoActor], magicNumber)
+    def props(magicNumber: Int): Props = Props(new DemoActor(magicNumber))
   }
 
   class DemoActor(magicNumber: Int) extends Actor {
@@ -68,9 +68,16 @@ class DemoActorWrapper extends Actor {
     }
   }
 
-  // ...
-
-  context.actorOf(DemoActor.props(42), "demo")
+  class SomeOtherActor extends Actor {
+    // Props(new DemoActor(42)) would not be safe
+    context.actorOf(DemoActor.props(42), "demo")
+    // ...
+    //#props-factory
+    def receive = {
+      case msg =>
+    }
+    //#props-factory
+  }
   //#props-factory
 
   def receive = Actor.emptyBehavior
@@ -239,22 +246,13 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     import akka.actor.Props
 
     val props1 = Props[MyActor]
+    val props2 = Props(new ActorWithArgs("arg")) // careful, see below
     val props3 = Props(classOf[ActorWithArgs], "arg")
     //#creating-props
 
     //#creating-props-deprecated
-    // DEPRECATED: old case class signature
-    val props4 = Props(
-      creator = { () => new MyActor },
-      dispatcher = "my-dispatcher")
-
-    // DEPRECATED due to duplicate functionality with Props.apply()
-    val props5 = props1.withCreator(new MyActor)
-
-    // DEPRECATED due to duplicate functionality with Props.apply()
-    val props6 = props1.withCreator(classOf[MyActor])
-
-    // NOT RECOMMENDED: encourages to close over enclosing class
+    // NOT RECOMMENDED within another actor:
+    // encourages to close over enclosing class
     val props7 = Props(new MyActor)
     //#creating-props-deprecated
   }
@@ -305,7 +303,10 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
         "helloBean")
       //#creating-indirectly
     }
-    val actorRef = a.actorRef
+    val actorRef = {
+      import scala.language.reflectiveCalls
+      a.actorRef
+    }
 
     val message = 42
     implicit val self = testActor