Merge pull request #15 from milosmns/i13_stable_api

Update front page

README.md

@@ -1,6 +1,5 @@
 # Simple State Machines in Kotlin (KSSM)
 
-![Experimental State](https://img.shields.io/badge/state-experimental-orange)
 ![Workflow Status](https://img.shields.io/github/workflow/status/milosmns/kssm/Pre-release%20check)
 ![Code Size](https://img.shields.io/github/languages/code-size/milosmns/kssm)
 ![License](https://img.shields.io/github/license/milosmns/kssm)
@@ -11,12 +10,11 @@
 ## What is this?
 
 **KSSM** (reordered: _Kotlin - Simple State Machines_) provides an easy and simple DSL _(Domain Specific Language)_ for setting up [finite-state machines](https://en.wikipedia.org/wiki/Finite-state_machine), and opens a clean API with built-in threading and conflation mechanisms for manipulating states.
-This library **does not** solve all state machine problems, **nor** does it address all possible use-cases related to state machines (although, it would like to).
+This library **does not** solve all state machine problems, **nor** does it aim to address all possible use-cases related to state machines.
 It currently works only in the JVM environment.
 
 KSSM is based on the [Flow API](https://kotlinlang.org/docs/reference/coroutines/flow.html#flows) from Kotlin's coroutine package,
 more precisely on [State Flow](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/). 
-State Flow is currently in `experimental` phase. This means that the API might be expanded in the future and is not safe for _inheritance_, but it is _safe for invocation/other use_.
 
 ## Quick Intro
 
@@ -53,13 +51,7 @@ job.join() // or job.cancel(), or simply ignore
 
 ## Wiki
 
-If you prefer longer documentation, check out the class documentation for
-[StateMachine API](https://github.com/milosmns/kssm/blob/master/kssm/src/main/kotlin/me/angrybyte/kssm/api/StateMachine.kt). Actually, check it out anyway.
-It's meant to be used in conjuction with the DSL, described in the
-[DSL class docs](https://github.com/milosmns/kssm/blob/master/kssm/src/main/kotlin/me/angrybyte/kssm/dsl/StateMachineDsl.kt).
-
-Website-like documentation is exported into [docs/dokka](https://github.com/milosmns/kssm/tree/master/docs/dokka/kssm)
-directory, so you can also pull that directory to your computer and open `index.html`.
+If you prefer longer documentation, check out the [longer version of the docs](https://milosmns.github.io/kssm/kssm/me.angrybyte.kssm.api).
 
 You want more? There are code samples [in the demo directory](https://github.com/milosmns/kssm/tree/master/demo/src/main/kotlin)
 that showcase the most interesting features of this library.
@@ -70,12 +62,12 @@ It's hosted on JCenter and MavenCentral, and thus easy to depend upon with Gradl
 
 ```gradle
 dependencies {
-  // find the latest `$kssm_version` in a badge in this page's title
+  // find the latest `$kssm_version` on the top of this page
   implementation "me.angrybyte:kssm:$kssm_version"
 }
 ```
 
 ## Contributing & Code of Conduct
 
 Please open [a new issue](https://github.com/milosmns/kssm/issues/new) with any requests, issues, complaints or any other type of communication.
-For sensitive or secure topics, don't hesitate to reach out to any of the maintainers directly.
+For sensitive or security-related topics, don't hesitate to reach out to any maintainer directly.

demo/build.gradle

@@ -14,7 +14,7 @@ dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0"
 
-  implementation "me.angrybyte:kssm:1.0.3"
+  implementation "me.angrybyte:kssm:1.1.0"
 }
 
 compileKotlin {

demo/src/main/kotlin/Demo_Flow.kt

@@ -8,7 +8,6 @@ import WaterState.Empty
 import WaterState.Ice
 import WaterState.Liquid
 import WaterState.Steam
-import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.asCoroutineDispatcher
 import kotlinx.coroutines.flow.collect
@@ -22,7 +21,6 @@ import me.angrybyte.kssm.dsl.stateMachine
 import me.angrybyte.kssm.dsl.to
 import java.util.concurrent.Executors
 
-@ExperimentalCoroutinesApi
 fun main() = runBlocking {
 
   // NOTE: infix function 'to' comes from the DSL package

demo/src/main/kotlin/Demo_Observers.kt

@@ -8,7 +8,6 @@ import WaterState.Empty
 import WaterState.Ice
 import WaterState.Liquid
 import WaterState.Steam
-import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.joinAll
 import kotlinx.coroutines.runBlocking
@@ -18,7 +17,6 @@ import me.angrybyte.kssm.dsl.stateMachine
 import me.angrybyte.kssm.dsl.to
 import java.lang.System.err
 
-@ExperimentalCoroutinesApi
 fun main() = runBlocking {
 
   // NOTE: infix function 'to' comes from the DSL package

demo/src/main/kotlin/Demo_Payloads.kt

@@ -1,7 +1,6 @@
 @file:Suppress("DuplicatedCode")
 
 import WaterState.Empty
-import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.joinAll
 import kotlinx.coroutines.runBlocking
@@ -16,7 +15,6 @@ import java.lang.System.err
 import java.util.concurrent.atomic.AtomicInteger
 
 @Suppress("UNCHECKED_CAST")
-@ExperimentalCoroutinesApi
 fun main() = runBlocking {
 
   // NOTE: we can manipulate the payload as long as it's internally mutable

docs/kssm/index.html

@@ -26,17 +26,17 @@
         <div id="searchBar"></div>
         <script type="text/javascript" src="../scripts/pages.js"></script>
         <script type="text/javascript" src="../scripts/main.js"></script>
-        <div id="content" pageIds="////PointingToDeclaration//-1861854310">
+        <div id="content" pageIds="////PointingToDeclaration//-1173211432">
           <div class="breadcrumbs"><a href="index.html">kssm</a></div>
           <div class="cover ">
             <h1 class="cover"><span>kssm</span></h1>
           </div>
           <h2 class="">Packages</h2>
-          <div class="table"><a data-name="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" anchor-label="me.angrybyte.kssm.api" id="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" data-filterable-set=":dokkaHtml/main"></a>
+          <div class="table"><a data-name="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" anchor-label="me.angrybyte.kssm.api" id="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" data-filterable-set=":dokkaHtml/main"></a>
             <div class="table-row" data-filterable-current=":dokkaHtml/main" data-filterable-set=":dokkaHtml/main">
               <div>
                 <div class="main-subrow ">
-                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.api/index.html">me.angrybyte.kssm.api</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.api/index.html">me.angrybyte.kssm.api</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.api%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"/>
     <path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"/>
 </svg></span>
@@ -49,11 +49,11 @@ <h2 class="">Packages</h2>
                 <div></div>
               </div>
             </div>
-<a data-name="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" anchor-label="me.angrybyte.kssm.api.data" id="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" data-filterable-set=":dokkaHtml/main"></a>
+<a data-name="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" anchor-label="me.angrybyte.kssm.api.data" id="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" data-filterable-set=":dokkaHtml/main"></a>
             <div class="table-row" data-filterable-current=":dokkaHtml/main" data-filterable-set=":dokkaHtml/main">
               <div>
                 <div class="main-subrow ">
-                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.api.data/index.html">me.angrybyte.kssm.api.data</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.api.data/index.html">me.angrybyte.kssm.api.data</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.api.data%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"/>
     <path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"/>
 </svg></span>
@@ -66,11 +66,11 @@ <h2 class="">Packages</h2>
                 <div></div>
               </div>
             </div>
-<a data-name="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" anchor-label="me.angrybyte.kssm.dsl" id="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" data-filterable-set=":dokkaHtml/main"></a>
+<a data-name="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" anchor-label="me.angrybyte.kssm.dsl" id="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" data-filterable-set=":dokkaHtml/main"></a>
             <div class="table-row" data-filterable-current=":dokkaHtml/main" data-filterable-set=":dokkaHtml/main">
               <div>
                 <div class="main-subrow ">
-                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.dsl/index.html">me.angrybyte.kssm.dsl</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.dsl/index.html">me.angrybyte.kssm.dsl</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.dsl%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"/>
     <path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"/>
 </svg></span>
@@ -83,11 +83,11 @@ <h2 class="">Packages</h2>
                 <div></div>
               </div>
             </div>
-<a data-name="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" anchor-label="me.angrybyte.kssm.impl.action" id="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" data-filterable-set=":dokkaHtml/main"></a>
+<a data-name="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" anchor-label="me.angrybyte.kssm.impl.action" id="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" data-filterable-set=":dokkaHtml/main"></a>
             <div class="table-row" data-filterable-current=":dokkaHtml/main" data-filterable-set=":dokkaHtml/main">
               <div>
                 <div class="main-subrow ">
-                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.impl.action/index.html">me.angrybyte.kssm.impl.action</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.impl.action/index.html">me.angrybyte.kssm.impl.action</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.impl.action%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"/>
     <path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"/>
 </svg></span>
@@ -100,11 +100,11 @@ <h2 class="">Packages</h2>
                 <div></div>
               </div>
             </div>
-<a data-name="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" anchor-label="me.angrybyte.kssm.impl.state" id="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310" data-filterable-set=":dokkaHtml/main"></a>
+<a data-name="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" anchor-label="me.angrybyte.kssm.impl.state" id="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432" data-filterable-set=":dokkaHtml/main"></a>
             <div class="table-row" data-filterable-current=":dokkaHtml/main" data-filterable-set=":dokkaHtml/main">
               <div>
                 <div class="main-subrow ">
-                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.impl.state/index.html">me.angrybyte.kssm.impl.state</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1861854310"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                  <div class=""><span class="inline-flex"><a href="me.angrybyte.kssm.impl.state/index.html">me.angrybyte.kssm.impl.state</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="%5Bme.angrybyte.kssm.impl.state%2F%2F%2F%2FPointingToDeclaration%2F%5D%2FPackages%2F-1173211432"><svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"/>
     <path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"/>
 </svg></span>

docs/kssm/me.angrybyte.kssm.api.data/-incubation-exception/cause.html

@@ -26,7 +26,7 @@
         <div id="searchBar"></div>
         <script type="text/javascript" src="../../../scripts/pages.js"></script>
         <script type="text/javascript" src="../../../scripts/main.js"></script>
-        <div id="content" pageIds="me.angrybyte.kssm.api.data/IncubationException/cause/#/PointingToDeclaration//-1861854310">
+        <div id="content" pageIds="me.angrybyte.kssm.api.data/IncubationException/cause/#/PointingToDeclaration//-1173211432">
           <div class="breadcrumbs"><a href="../../index.html">kssm</a>/<a href="../index.html">me.angrybyte.kssm.api.data</a>/<a href="index.html">IncubationException</a>/<a href="cause.html">cause</a></div>
           <div class="cover ">
             <h1 class="cover"><span>cause</span></h1>