Warning for actors with value class arguments

Update documentation to specify that value class arguments are not
supported for Prop creation using the recommended classOf[] approach.

Issue: #20735, #16444

akka-docs/rst/scala/actors.rst

@@ -81,6 +81,11 @@ verified during construction of the :class:`Props` object, resulting in an
 :class:`IllegalArgumentException` if no or multiple matching constructors are
 found.
 
+.. note::
+
+  The recommended approach to create the actor :class:`Props` is not supported
+  for cases when the actor constructor takes value classes as arguments.
+
 Dangerous Variants
 ^^^^^^^^^^^^^^^^^^
 
@@ -162,6 +167,18 @@ another child to the same parent an :class:`InvalidActorNameException` is thrown
 
 Actors are automatically started asynchronously when created.
 
+Value classes as constructor arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The recommended way to instantiate actor props uses reflection at runtime
+to determine the correct actor constructor to be invoked and due to technical
+limitations is not supported when said constructor takes arguments that are
+value classes.
+In these cases you should either unpack the arguments or create the props by
+calling the constructor manually:
+
+.. includecode:: code/docs/actor/ActorDocSpec.scala#actor-with-value-class-argument
+
 Dependency Injection
 --------------------
 

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

@@ -50,6 +50,19 @@ class ActorWithArgs(arg: String) extends Actor {
   def receive = { case _ => () }
 }
 
+//#actor-with-value-class-argument
+class Argument(val value: String) extends AnyVal
+class ValueClassActor(arg: Argument) extends Actor {
+  def receive = {case _ => () }
+}
+
+object ValueClassActor {
+  def props1(arg: Argument) = Props(classOf[ValueClassActor], arg) // fails at runtime
+  def props2(arg: Argument) = Props(classOf[ValueClassActor], arg.value) // ok
+  def props3(arg: Argument) = Props(new ValueClassActor(arg)) // ok
+}
+//#actor-with-value-class-argument
+
 class DemoActorWrapper extends Actor {
   //#props-factory
   object DemoActor {
@@ -312,7 +325,7 @@ class ActorDocSpec extends AkkaSpec("""
 
     val props1 = Props[MyActor]
     val props2 = Props(new ActorWithArgs("arg")) // careful, see below
-    val props3 = Props(classOf[ActorWithArgs], "arg")
+    val props3 = Props(classOf[ActorWithArgs], "arg") // no support for value class arguments
     //#creating-props
 
     //#creating-props-deprecated