[docs] Update docs regarding FinishingEvent

Author: nsk90

docs/index.md

@@ -334,17 +334,31 @@ createStateMachine {
 
 ## Finishing states and state machine
 
-Some of state machines are infinite, but other ones may finish. State machine that was finished stops processing
-incoming events. To make state machine finishing, add `FinalState` to it with `finalState()` function or add any
-subclass of `FinalState` with `addFinalState()` function. In `ChildMode.EXCLUSIVE` state machine finishes when enters
-top-level `FinalState`. In `ChildMode.PARALLEL` state machine finishes when all its children has finished.
+Some of state machines and states are infinite, but other ones may finish.
 
-Composite states also may have `FinalState` children. Whole state machine is not finished in this case and transitions 
-of finished states are still active. But notification is triggered and `isFinished` property set.
+* In `ChildMode.EXCLUSIVE` state or state machine finishes when enters top-level final state.
+* In `ChildMode.PARALLEL` state or state machine finishes when all its children has finished.
+
+To make a state final, it must implement `FinalState` marker interface.
+Built-in implementation of such state is `DefaultFinalState`.
+It can be created directly with `finalState()` function or be subclassed and added with `addFinalState()` function.
+Alternatively you can inherit basic `DefaultState` and mark it with `FinalState` explicitly like here:
+
+```kotlin
+sealed class States : DefaultState() {
+    object State1 : States()
+    object State2 : States(), FinalState
+}
+```
+
+Finishing of states and state machines is treated little differently.
+State machine that was finished stops processing incoming events.
+But when some nested state is finished its transitions are still active,
+only notification is triggered and `isFinished` property set.
 
 Notifications about finishing are available in two forms:
 
-1) Triggering of `onFinished()` listener callback. This is the only option for StateMachines.
+1) Triggering of `onFinished()` listener callback. This is the only option for `StateMachine`.
     ```kotlin
     val machine = createStateMachine {
         val final = finalState("final")
@@ -354,10 +368,9 @@ Notifications about finishing are available in two forms:
     }
     machine.isFinished // is true
     ```
-2) Generation and processing of special `FinishedEvent`. This option is also available for composite states and useful 
-   for performing transitions on finishing. Transitions for `FinishedEvent` are matched with this event in special way,
-   so such transition is triggered only for `FinishedEvent` generated by finishing of a state that defines such 
-   transition, not another one.
+2) Generation and processing of special `FinishedEvent`. This option is also available for composite states and useful
+   for performing transitions on finishing:
+
     ```kotlin
     createStateMachine {
         val state2 = state("state2")
@@ -371,6 +384,9 @@ Notifications about finishing are available in two forms:
         }
     }
     ```
+   Transition for `FinishedEvent` is detected by the library and matched by special kind of `EventMatcher`,
+   so such transition is triggered only for `FinishedEvent` that corresponds to this state.
+   `FinishingEvent` generated by finishing of another state will not trigger such transition.
 
 ## Nested states