From 5cf2e7f8fd31324395fae122a31138add5043f12 Mon Sep 17 00:00:00 2001
From: Roland <rk@rkuhn.info>
Date: Wed, 28 Nov 2012 15:43:42 +0100
Subject: [PATCH] #2644 - doc FSM.NullFunction and when-requirements

---
 akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala |  9 +++++++++
 akka-docs/rst/scala/fsm.rst                          | 12 ++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala b/akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala
index cc88416b0e1..15821419d47 100644
--- a/akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala
+++ b/akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala
@@ -189,6 +189,15 @@ class FSMDocSpec extends MyFavoriteTestFrameWorkPlusAkkaTestKit {
     }
     //#fsm-code-elided
 
+    "demonstrate NullFunction" in {
+      class A extends Actor with FSM[Int, Null] {
+        val SomeState = 0
+        //#NullFunction
+        when(SomeState)(FSM.NullFunction)
+        //#NullFunction
+      }
+    }
+
     "batch correctly" in {
       val buncher = system.actorOf(Props(new Buncher))
       buncher ! SetTarget(testActor)
diff --git a/akka-docs/rst/scala/fsm.rst b/akka-docs/rst/scala/fsm.rst
index 4ace396a14b..1d87890db34 100644
--- a/akka-docs/rst/scala/fsm.rst
+++ b/akka-docs/rst/scala/fsm.rst
@@ -179,6 +179,18 @@ demonstrated below:
 The :class:`Event(msg: Any, data: D)` case class is parameterized with the data
 type held by the FSM for convenient pattern matching.
 
+.. warning::
+
+  It is required that you define handlers for each of the possible FSM states,
+  otherwise there will be failures when trying to switch to undeclared states.
+
+It is recommended practice to declare the states as objects extending a
+sealed trait and then verify that there is a ``when`` clause for each of the
+states. If you want to leave the handling of a state “unhandled” (more below),
+it still needs to be declared like this:
+
+.. includecode:: code/docs/actor/FSMDocSpec.scala#NullFunction
+
 Defining the Initial State
 --------------------------