updated documentation

README.adoc

@@ -221,7 +221,7 @@ repositories {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-jvm:0.9.1'
+    implementation 'io.jumpco.open:kfsm-jvm:0.9.2'
 }
 ----
 
@@ -230,7 +230,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-js:0.9.1'
+    implementation 'io.jumpco.open:kfsm-js:0.9.2'
 }
 ----
 
@@ -239,7 +239,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-linuxX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-linuxX64:0.9.2'
 }
 ----
 
@@ -248,7 +248,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-mingwX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-mingwX64:0.9.2'
 }
 ----
 
@@ -257,7 +257,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-macosX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-macosX64:0.9.2'
 }
 ----
 

build.gradle

@@ -16,7 +16,7 @@ repositories {
     mavenCentral()
 }
 group = 'io.jumpco.open'
-version = '0.9.2-SNAPSHOT'
+version = '0.9.2'
 description = 'Kotlin Finite-state machine'
 
 java {

src/commonMain/kotlin/io/jumpco/open/kfsm/StateMachineBuilder.kt

@@ -54,7 +54,6 @@ class StateMachineBuilder<S, E : Enum<E>, C>(validMapStates: Set<S>) {
     fun complete(): StateMachineDefinition<S, E, C> {
         completed = true
         if (namedStateMaps.isNotEmpty()) {
-            require(this.deriveInitialStateMap != null) { "initialMap must be defined when using named state maps" }
             require(this.deriveInitialState == null) { "deriveInitialState cannot be used with named state maps" }
         }
         return StateMachineDefinition(

src/commonMain/kotlin/io/jumpco/open/kfsm/StateMachineDefinition.kt

@@ -15,7 +15,13 @@ package io.jumpco.open.kfsm
 class StateMachineDefinition<S, E : Enum<E>, C>(
     private val deriveInitialState: StateQuery<C, S>?,
     private val deriveInitialMap: StateMapQuery<C, S>?,
+    /**
+     * The top level state map will be created when the state machine is created.
+     */
     val defaultStateMap: StateMapDefinition<S, E, C>,
+    /**
+     * The named state maps can be accessed via a push transition.
+     */
     val namedStateMaps: Map<String, StateMapDefinition<S, E, C>>
 
 ) {
@@ -76,12 +82,29 @@ class StateMachineDefinition<S, E : Enum<E>, C>(
             namedStateMaps[name] ?: error("Named map $name not found")
         )
 
+    /**
+     * This function will create a state machine instance and set it to the state to a previously externalised state.
+     * @param context The instance will operate on the provided context
+     * @param initialExternalState The previously externalised state
+     */
     fun create(context: C, initialExternalState: ExternalState<S>): StateMachineInstance<S, E, C> =
         StateMachineInstance<S, E, C>(context, this, null, initialExternalState)
 
+    /**
+     * This function will create a state machine instance and set it to the initial state.
+     * @param context The instance will operate on the provided context
+     * @param initial The initial state
+     *
+     */
     fun create(context: C, initial: S? = null): StateMachineInstance<S, E, C> =
         StateMachineInstance<S, E, C>(context, this, initial)
 
+    /**
+     * This function will provide a list of possible events given a specific state.
+     * The actual events may fail because of guard conditions or named state maps and the default state map behaviour being different.
+     * @param state The given state
+     * @param includeDefault consider the default state and event handlers
+     */
     fun possibleEvents(state: S, includeDefault: Boolean): Set<E> {
         val result = mutableSetOf<E>()
         result.addAll(defaultStateMap.allowed(state, includeDefault))

src/commonMain/kotlin/io/jumpco/open/kfsm/StateMachineInstance.kt

@@ -31,6 +31,12 @@ class StateMachineInstance<S, E : Enum<E>, C>(
     initialState: S? = null,
     initialExternalState: ExternalState<S>? = null
 ) {
+    /**
+     * Create a state machine using a specific definition and a previous externalised state.
+     * @param context The instane will operate on the context
+     * @param definition The definition of the state machine instance.
+     * @param initialExternalState The previously externalised state.
+     */
     constructor(context: C, definition: StateMachineDefinition<S, E, C>, initialExternalState: ExternalState<S>) :
         this(context, definition, null, initialExternalState) {
     }

src/commonMain/kotlin/io/jumpco/open/kfsm/StateMapBuilder.kt

@@ -9,6 +9,10 @@
 
 package io.jumpco.open.kfsm
 
+/**
+ * The build will be created to assist with create the top level or named state maps.
+ * All transitions are assigned to a state map.
+ */
 class StateMapBuilder<S, E : Enum<E>, C>(
     /**
      * The set of states the state map supports

src/commonMain/kotlin/io/jumpco/open/kfsm/kfsm.kt

@@ -149,20 +149,26 @@ class Stack<T> {
     }
 
     /**
+     * Indicates that the stack is empty.
      * @return true if the stack is empty
      */
     fun isEmpty() = elements.isEmpty()
 
     /**
-     *
+     * Indicates that the stack is not empty.
      * @return true if the stack is not empty
      */
     fun isNotEmpty() = elements.isNotEmpty()
 
     /**
+     * Provides access to the top of the stack.
      * @return the element at the top of the stack without removing or `null` is the stack is empty.
      */
     fun peek(): T? = elements.lastOrNull()
 
+    /**
+     * Provides access to all the entries on the stack.
+     * @return An immutable list of entries with the top of the stack at the end.
+     */
     fun peekContent(): List<T> = elements.toList()
 }

src/commonTest/kotlin/io/jumpco/open/kfsm/turnstile-payment.kt

@@ -87,18 +87,6 @@ class PayingTurnstileFSM(turnstile: PayingTurnstile, initialState: ExternalState
             PayingTurnstileEvents::class,
             PayingTurnstile::class
         ) {
-            initialMap {
-                mutableListOf<StateMapItem<PayingTurnstileStates>>().apply {
-                    if (locked) {
-                        this.add(PayingTurnstileStates.LOCKED to "default")
-                    } else {
-                        this.add(PayingTurnstileStates.UNLOCKED to "default")
-                    }
-                    if (coins > 0) {
-                        this.add(PayingTurnstileStates.COINS to "coins")
-                    }
-                }
-            }
             default {
                 entry { _, targetState, args ->
                     if (args.isNotEmpty()) {
@@ -178,7 +166,7 @@ class PayingTurnstileFSM(turnstile: PayingTurnstile, initialState: ExternalState
         }.build()
     }
 
-    val fsm = if (initialState != null) definition.create(turnstile, initialState) else definition.create(turnstile)
+    val fsm = if (initialState != null) definition.create(turnstile, initialState) else definition.create(turnstile, PayingTurnstileStates.LOCKED)
 
     fun coin(value: Int) {
         println("sendEvent:COIN:$value")

src/doc/asciidoc/documentation.adoc

@@ -17,7 +17,7 @@ repositories {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-jvm:0.9.1'
+    implementation 'io.jumpco.open:kfsm-jvm:0.9.2'
 }
 ----
 
@@ -26,7 +26,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-js:0.9.1'
+    implementation 'io.jumpco.open:kfsm-js:0.9.2'
 }
 ----
 
@@ -35,7 +35,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-wasm32:0.9.1'
+    implementation 'io.jumpco.open:kfsm-wasm32:0.9.2'
 }
 ----
 
@@ -44,7 +44,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-linuxX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-linuxX64:0.9.2'
 }
 ----
 
@@ -53,7 +53,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-mingwX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-mingwX64:0.9.2'
 }
 ----
 
@@ -62,7 +62,7 @@ dependencies {
 [source,groovy]
 ----
 dependencies {
-    implementation 'io.jumpco.open:kfsm-macosX64:0.9.1'
+    implementation 'io.jumpco.open:kfsm-macosX64:0.9.2'
 }
 ----
 == Operation