Add kdoc to transitioner and $value to invalid state transition error…

lib/src/main/kotlin/app/cash/kfsm/InvalidStateTransition.kt

@@ -3,5 +3,5 @@ package app.cash.kfsm
 class InvalidStateTransition(transition: Transition<*, *>, value: Value<*, *>) : Exception(
   "Value cannot transition ${
     transition.from.set.toList().sortedBy { it.toString() }.joinToString(", ", prefix = "{", postfix = "}")
-  } to ${transition.to}, because it is currently ${value.state}"
+  } to ${transition.to}, because it is currently ${value.state}. [value=$value]"
 )

lib/src/main/kotlin/app/cash/kfsm/Transitioner.kt

@@ -2,12 +2,22 @@ package app.cash.kfsm
 
 abstract class Transitioner<T : Transition<V, S>, V : Value<V, S>, S : State<S>> {
 
+  /** Will be executed prior to the transition effect. Failure here will terminate the transition */
   open fun preHook(value: V, via: T): Result<Unit> = Result.success(Unit)
 
+  /** Will be executed after the transition effect. Use this to persist the value. */
   open fun persist(value: V, via: T): Result<V> = Result.success(value)
 
+  /** Will be executed after the transition effect & value persistence. Use this to perform side effects such as notifications. */
   open fun postHook(from: S, value: V, via: T): Result<Unit> = Result.success(Unit)
 
+  /**
+   * Execute the given transition on the given value.
+   *
+   * If the target state is already present, then this is a no-op.
+   * If the provided transition cannot apply to the value's state, then this is a failure.
+   * Otherwise, the transition is applied and the state is updated in the returned value.
+   */
   fun transition(
     value: V,
     transition: T

lib/src/test/kotlin/app/cash/kfsm/InvalidStateTransitionTest.kt

@@ -6,11 +6,11 @@ import io.kotest.matchers.shouldBe
 class InvalidStateTransitionTest : StringSpec({
   "with single from-state has correct message" {
     InvalidStateTransition(LetterTransition(A, B), Letter(E)).message shouldBe
-      "Value cannot transition {A} to B, because it is currently E"
+      "Value cannot transition {A} to B, because it is currently E. [value=Letter(state=E)]"
   }
 
   "with many from-states has correct message" {
     InvalidStateTransition(LetterTransition(States(C, B), D), Letter(E)).message shouldBe
-      "Value cannot transition {B, C} to D, because it is currently E"
+      "Value cannot transition {B, C} to D, because it is currently E. [value=Letter(state=E)]"
   }
 })

lib/src/test/kotlin/app/cash/kfsm/TransitionerAsyncTest.kt

@@ -61,7 +61,7 @@ class TransitionerAsyncTest : StringSpec({
     val transitioner = transitioner()
 
     transitioner.transition(Letter(C), transition).shouldBeFailure()
-      .shouldHaveMessage("Value cannot transition {A} to B, because it is currently C")
+      .shouldHaveMessage("Value cannot transition {A} to B, because it is currently C. [value=Letter(state=C)]")
 
     transitioner.preHookExecuted shouldBe 0
     transition.effected shouldBe 0

lib/src/test/kotlin/app/cash/kfsm/TransitionerTest.kt

@@ -61,7 +61,7 @@ class TransitionerTest : StringSpec({
     val transitioner = transitioner()
 
     transitioner.transition(Letter(C), transition).shouldBeFailure()
-      .shouldHaveMessage("Value cannot transition {A} to B, because it is currently C")
+      .shouldHaveMessage("Value cannot transition {A} to B, because it is currently C. [value=Letter(state=C)]")
 
     transitioner.preHookExecuted shouldBe 0
     transition.effected shouldBe 0