From 2bf34e163a61ed649ab84dc3de7078f8b4d8bb24 Mon Sep 17 00:00:00 2001
From: Ebere Abanonu <eabanonu@yahoo.com>
Date: Tue, 22 Feb 2022 15:51:52 +0100
Subject: [PATCH] Improve code reference hygiene with exisiting code block

---
 docs/articles/actors/finite-state-machine.md  | 38 ++-----------------
 .../FiniteStateMachine/ExampleFSMActor.cs     |  2 +
 2 files changed, 5 insertions(+), 35 deletions(-)

diff --git a/docs/articles/actors/finite-state-machine.md b/docs/articles/actors/finite-state-machine.md
index 61751b86933..3cc336f30b0 100644
--- a/docs/articles/actors/finite-state-machine.md
+++ b/docs/articles/actors/finite-state-machine.md
@@ -99,9 +99,7 @@ The `stateFunction` argument is a `delegate State<TState, TData> StateFunction(E
 
 Each `FSM` needs a starting point, which is declared using
 
-```csharp
-StartWith(state, data[, timeout])
-```
+[!code-csharp[Main](../../../src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs?name=StartWith)]
 
 The optionally given timeout argument overrides any specification given for the desired initial state. If you want to cancel a default timeout, use `null`.
 
@@ -109,21 +107,7 @@ The optionally given timeout argument overrides any specification given for the
 
 If a state doesn't handle a received event a warning is logged. If you want to do something else in this case you can specify that with `WhenUnhandled(stateFunction)`:
 
-```csharp
-WhenUnhandled(state =>
-{
-    if (state.FsmEvent is Queue x)
-    {
-        _log.Info("Received unhandled event: " + x);
-        return Stay();
-    }
-    else
-    {
-        _log.Warning("Received unknown event: " + state.FsmEvent);
-        return Goto(new Error());
-    }
-});
-```
+[!code-csharp[Main](../../../src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs?name=UnhandledHandler)]
 
 Within this handler the state of the `FSM` may be queried using the stateName method.
 
@@ -163,23 +147,7 @@ OnTransition(handler)
 
 which associates actions with a transition instead of with a state and event. The handler is a delegate `void TransitionHandler(TState initialState, TState nextState)` function which takes a pair of states as input; no resulting state is needed as it is not possible to modify the transition in progress.
 
-```csharp
-OnTransition((initialState, nextState) =>
-{
-    if (initialState == State.Active && nextState == State.Idle)
-    {
-        SetTimer("timeout", new Tick(), TimeSpan.FromSeconds(1), repeat: true);
-    } 
-    else if (initialState == State.Active)
-    {
-        CancelTimer("timeout");
-    }
-    else if (nextState == State.Idle)
-    {
-        _log.Info("entering Idle from " + initialState);
-    }
-});
-```
+[!code-csharp[Main](../../../src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs?name=TransitionHandler)]
 
 The handlers registered with this method are stacked, so you can intersperse `OnTransition` blocks with when blocks as suits your design. It should be noted, however, that all handlers will be invoked for each transition, not only the first matching one. This is designed specifically so you can put all transition handling for a certain aspect into one place without having to worry about earlier declarations shadowing later ones; the actions are still executed in declaration order, though.
 
diff --git a/src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs b/src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs
index 7a41fdcc390..3cef746e5a7 100644
--- a/src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs
+++ b/src/core/Akka.Docs.Tests/Actors/FiniteStateMachine/ExampleFSMActor.cs
@@ -19,7 +19,9 @@ public class ExampleFSMActor : FSM<State, IData>
 
         public ExampleFSMActor()
         {
+            // <StartWith>
             StartWith(State.Idle, Uninitialized.Instance);
+            // </StartWith>
 
             #region FSMHandlers
             When(State.Idle, state =>