From 2a182a6c4e00e213fd237e7eabe1db416838f37d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sim=C3=A3o=20Martins?= <Lasering@users.noreply.github.com>
Date: Fri, 1 Jul 2016 10:32:20 +0100
Subject: [PATCH] +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                | 19 ++++++++
 .../scala/code/docs/actor/ActorDocSpec.scala  |  2 +-
 .../code/docs/actor/PropsEdgeCaseSpec.scala   | 44 +++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 akka-docs/rst/scala/code/docs/actor/PropsEdgeCaseSpec.scala

diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst
index 8417e10e5c..e9b6dd21ad 100644
--- a/akka-docs/rst/scala/actors.rst
+++ b/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
 ^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala b/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
index 50c7adc846..9085f92537 100644
--- a/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
+++ b/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
@@ -618,4 +618,4 @@ class ActorDocSpec extends AkkaSpec("""
     })
   }
 
-}
+}
\ No newline at end of file
diff --git a/akka-docs/rst/scala/code/docs/actor/PropsEdgeCaseSpec.scala b/akka-docs/rst/scala/code/docs/actor/PropsEdgeCaseSpec.scala
new file mode 100644
index 0000000000..3a538a61fd
--- /dev/null
+++ b/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
+  }
+}