From ffa8f0f50d9dc4e955cc04d5bf5f01af2b0d3614 Mon Sep 17 00:00:00 2001
From: iamgodot <xugodot@gmail.com>
Date: Mon, 20 Mar 2023 21:14:52 +0800
Subject: [PATCH 1/2] docs: minor fix for consistency

---
 docs/actions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/actions.md b/docs/actions.md
index 3f3df110..1ed5e64e 100644
--- a/docs/actions.md
+++ b/docs/actions.md
@@ -341,7 +341,7 @@ Actions and Guards will be executed in the following order:
 Guards. This means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
 library will match your method signature of what's expected to receive with the provided arguments.
 
-This means that if on your `on_enter_<state.id>()` or `on_execute_<event>()` method, you need to know
+This means that if on your `on_enter_<state.id>()` or `on_<event>()` method, you need to know
 the `source` ({ref}`state`), or the `event` ({ref}`event`), or access a keyword
 argument passed with the trigger, just add this parameter to the method and It will be passed
 by the dispatch mechanics.

From 8c36e9ecec6f3b400865dd5a5303909a927da490 Mon Sep 17 00:00:00 2001
From: iamgodot <xugodot@gmail.com>
Date: Mon, 20 Mar 2023 22:20:24 +0800
Subject: [PATCH 2/2] docs: add explanation for action return values

---
 docs/actions.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/actions.md b/docs/actions.md
index 1ed5e64e..b022d2ee 100644
--- a/docs/actions.md
+++ b/docs/actions.md
@@ -333,6 +333,48 @@ Actions and Guards will be executed in the following order:
 - `after_transition()`
 
 
+## Return values
+
+Currently only certain actions' return values will be combined as a list and returned for
+a triggered transition:
+
+- `before_transition()`
+
+- `before_<event>()`
+
+- `on_transition()`
+
+- `on_<event>()`
+
+Note that `None` will be used if the action callback does not return anything, but only when it is
+defined explicitly. The following provides an example:
+
+```py
+>>> class ExampleStateMachine(StateMachine):
+...     initial = State(initial=True)
+...
+...     loop = initial.to.itself()
+...
+...     def before_loop(self):
+...         return "Before loop"
+...
+...     def on_transition(self):
+...         pass
+...
+...     def on_loop(self):
+...         return "On loop"
+...
+
+>>> sm = ExampleStateMachine()
+
+>>> sm.loop()
+['Before loop', None, 'On loop']
+
+```
+
+For {ref}`RTC model`, only the main event will get its value list, while the chained ones simply get
+`None` returned. For {ref}`Non-RTC model`, results for every event will always be collected and returned.
+
 
 (dynamic-dispatch)=
 ## Dynamic dispatch