+doc #20794 explain Prop edge cases. (#20861)

* +doc #20794 explain Prop edge cases.

* Create a CompileOnly spec for props edge cases.

akka-docs/rst/scala/actors.rst

@@ -108,6 +108,25 @@ reference needs to be passed as the first argument).
   Declaring one actor within another is very dangerous and breaks actor
   encapsulation. Never pass an actor’s ``this`` reference into :class:`Props`!
 
+Edge cases
+^^^^^^^^^^
+There are two edge cases in actor creation with :class:`Props`:
+
+* An actor with :class:`AnyVal` arguments.
+
+.. includecode:: code/docs/actor/PropsEdgeCaseSpec.scala#props-edge-cases-value-class
+.. includecode:: code/docs/actor/PropsEdgeCaseSpec.scala#props-edge-cases-value-class-example
+
+* An actor with default constructor values.
+
+.. includecode:: code/docs/actor/PropsEdgeCaseSpec.scala#props-edge-cases-default-values
+
+In both cases an :class:`IllegalArgumentException` will be thrown stating
+no matching constructor could be found.
+
+The next section explains the recommended ways to create :class:`Actor` props in a way,
+which simultaneously safe-guards against these edge cases.
+
 Recommended Practices
 ^^^^^^^^^^^^^^^^^^^^^
 

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

@@ -0,0 +1,44 @@
+/**
+ * Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.actor
+
+import akka.actor.{ Actor, Props }
+import docs.CompileOnlySpec
+import org.scalatest.WordSpec
+
+//#props-edge-cases-value-class
+case class MyValueClass(v: Int) extends AnyVal
+
+//#props-edge-cases-value-class
+
+class PropsEdgeCaseSpec extends WordSpec with CompileOnlySpec {
+  "value-class-edge-case-example" in compileOnlySpec {
+    //#props-edge-cases-value-class-example
+    class ValueActor(value: MyValueClass) extends Actor {
+      def receive = {
+        case multiplier: Long => sender() ! (value.v * multiplier)
+      }
+    }
+    val valueClassProp = Props(classOf[ValueActor], MyValueClass(5)) // Unsupported
+    //#props-edge-cases-value-class-example
+
+    //#props-edge-cases-default-values
+    class DefaultValueActor(a: Int, b: Int = 5) extends Actor {
+      def receive = {
+        case x: Int => sender() ! ((a + x) * b)
+      }
+    }
+
+    val defaultValueProp1 = Props(classOf[DefaultValueActor], 2.0) // Unsupported
+
+    class DefaultValueActor2(b: Int = 5) extends Actor {
+      def receive = {
+        case x: Int => sender() ! (x * b)
+      }
+    }
+    val defaultValueProp2 = Props[DefaultValueActor2] // Unsupported
+    val defaultValueProp3 = Props(classOf[DefaultValueActor2]) // Unsupported
+    //#props-edge-cases-default-values
+  }
+}