make all FSM doc code snippets compiled, see #1871

- also remove gratuitious (aka wrong) type parameters from StopEvent
- document new “transform” funcitonality

akka-docs/scala/code/akka/docs/actor/FSMDocSpec.scala

@@ -37,11 +37,15 @@ class FSMDocSpec extends AkkaSpec {
     //#simple-fsm
     class Buncher extends Actor with FSM[State, Data] {
 
+      //#fsm-body
       startWith(Idle, Uninitialized)
 
+      //#when-syntax
       when(Idle) {
-        case Event(SetTarget(ref), Uninitialized) ⇒ stay using Todo(ref, Vector.empty)
+        case Event(SetTarget(ref), Uninitialized) ⇒
+          stay using Todo(ref, Vector.empty)
       }
+      //#when-syntax
 
       //#transition-elided
       onTransition {
@@ -51,10 +55,13 @@ class FSMDocSpec extends AkkaSpec {
           }
       }
       //#transition-elided
+      //#when-syntax
 
       when(Active, stateTimeout = 1 second) {
-        case Event(Flush | FSM.StateTimeout, t: Todo) ⇒ goto(Idle) using t.copy(queue = Vector.empty)
+        case Event(Flush | StateTimeout, t: Todo) ⇒
+          goto(Idle) using t.copy(queue = Vector.empty)
       }
+      //#when-syntax
 
       //#unhandled-elided
       whenUnhandled {
@@ -67,10 +74,116 @@ class FSMDocSpec extends AkkaSpec {
           stay
       }
       //#unhandled-elided
+      //#fsm-body
 
       initialize
     }
     //#simple-fsm
+    object DemoCode {
+      trait StateType
+      case object SomeState extends StateType
+      case object Processing extends StateType
+      case object Error extends StateType
+      case object Idle extends StateType
+      case object Active extends StateType
+
+      class Dummy extends Actor with FSM[StateType, Int] {
+        class X
+        val newData = 42
+        object WillDo
+        object Tick
+
+        //#modifier-syntax
+        when(SomeState) {
+          case Event(msg, _) ⇒
+            goto(Processing) using (newData) forMax (5 seconds) replying (WillDo)
+        }
+        //#modifier-syntax
+
+        //#transition-syntax
+        onTransition {
+          case Idle -> Active ⇒ setTimer("timeout", Tick, 1 second, true)
+          case Active -> _    ⇒ cancelTimer("timeout")
+          case x -> Idle      ⇒ log.info("entering Idle from " + x)
+        }
+        //#transition-syntax
+
+        //#alt-transition-syntax
+        onTransition(handler _)
+
+        def handler(from: StateType, to: StateType) {
+          // handle it here ...
+        }
+        //#alt-transition-syntax
+
+        //#stop-syntax
+        when(Error) {
+          case Event("stop", _) ⇒
+            // do cleanup ...
+            stop()
+        }
+        //#stop-syntax
+
+        //#transform-syntax
+        when(SomeState)(transform {
+          case Event(bytes: Array[Byte], read) ⇒ stay using (read + bytes.length)
+          case Event(bytes: List[Byte], read)  ⇒ stay using (read + bytes.size)
+        } {
+          case s @ FSM.State(state, read, timeout, stopReason, replies) if read > 1000 ⇒
+            goto(Processing)
+        })
+        //#transform-syntax
+
+        //#alt-transform-syntax
+        val processingTrigger: PartialFunction[State, State] = {
+          case s @ FSM.State(state, read, timeout, stopReason, replies) if read > 1000 ⇒
+            goto(Processing)
+        }
+
+        when(SomeState)(transform {
+          case Event(bytes: Array[Byte], read) ⇒ stay using (read + bytes.length)
+          case Event(bytes: List[Byte], read)  ⇒ stay using (read + bytes.size)
+        }(processingTrigger))
+        //#alt-transform-syntax
+
+        //#termination-syntax
+        onTermination {
+          case StopEvent(FSM.Normal, state, data)         ⇒ // ...
+          case StopEvent(FSM.Shutdown, state, data)       ⇒ // ...
+          case StopEvent(FSM.Failure(cause), state, data) ⇒ // ...
+        }
+        //#termination-syntax
+
+        //#unhandled-syntax
+        whenUnhandled {
+          case Event(x: X, data) ⇒
+            log.info("Received unhandled event: " + x)
+            stay
+          case Event(msg, _) ⇒
+            log.warning("Received unknown event: " + msg)
+            goto(Error)
+        }
+        //#unhandled-syntax
+
+      }
+
+      //#logging-fsm
+      import akka.actor.LoggingFSM
+      class MyFSM extends Actor with LoggingFSM[StateType, Data] {
+        //#body-elided
+        override def logDepth = 12
+        onTermination {
+          case StopEvent(FSM.Failure(_), state, data) ⇒
+            val lastEvents = getLog.mkString("\n\t")
+            log.warning("Failure in state " + state + " with data " + data + "\n" +
+              "Events leading up to this point:\n\t" + lastEvents)
+        }
+        // ...
+        //#body-elided
+      }
+      //#logging-fsm
+
+    }
     //#fsm-code-elided
 
     "batch correctly" in {