=doc 3764 revise recommended practice for Props creation

- it is not recommended to use Props.apply(=> Actor) within an Actor
- it is recommended to use that method in the Props factory method in
  an actor’s companion object

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,6 +246,7 @@ 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
 
@@ -254,7 +262,8 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     // 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 +314,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