From ab54598f8cab0551b453294c4ca9ef0feaee1c5d Mon Sep 17 00:00:00 2001
From: Mikhail Fedotov <nosik90@gmail.com>
Date: Mon, 5 Sep 2022 00:32:38 +0300
Subject: [PATCH] [docs] Add history states docs Add startFrom overload with
 stateName argument.

---
 docs/index.md                                 | 22 +++++++++++++++++++
 .../kotlin/ru/nsk/kstatemachine/Testing.kt    |  3 +++
 2 files changed, 25 insertions(+)

diff --git a/docs/index.md b/docs/index.md
index 60e5a36a..f09d2a1c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -412,6 +412,28 @@ choiceState {
 }
 ```
 
+### History states
+
+There are two types of history states, shallow and deep. Shallow history state is used to represent the most recently
+active child (its neighbour) of a parent state. It does not recurse into this child's active configuration (sub states),
+initial states will be used. Deep history state in contrast reflects the most recent active configuration of the parent
+state (including all sub states).
+You can specify default state which will be used if history was not recorded yet (parent was not active).
+When default state is not specified, parent initial state will be entered on transition to history state.
+
+```kotlin
+val machine = createStateMachine {
+    state {
+        val state11 = initialState()
+        val state12 = state()
+        historyState(defultState = state12)
+    }
+    state {
+        // ...
+    }
+}
+```
+
 ## Typesafe transitions
 
 It is a common case when a state expects to receive some data from an event. Library provides typesafe API for such
diff --git a/kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/Testing.kt b/kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/Testing.kt
index aad999e2..facf0afe 100644
--- a/kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/Testing.kt
+++ b/kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/Testing.kt
@@ -6,4 +6,7 @@ object Testing {
      */
     fun StateMachine.startFrom(state: IState, argument: Any? = null) =
         (this as InternalStateMachine).startFrom(state, argument)
+
+    fun StateMachine.startFrom(stateName: String, argument: Any? = null) =
+        startFrom(requireState(stateName), argument)
 }
\ No newline at end of file