Merge branch 'raimo/kernel/gen_statem-progress/OTP-14114' into maint

* raimo/kernel/gen_statem-progress/OTP-14114:
  Make code_change/4 optional
  Implement fallback for terminate/3
  Clarify code_change and callback mode change
  Stop pampering with stacktraces
  Clean up timer handling
  Remove event timer optimization
  Clean up timer handling
  Reduce number of loop variables hence code mass
  Optimize by using async cancel_timer
  Bugfix: callback mode not cached after code change
  Implement repeat_state and repeat_state_and_data
  Correct type checking function for action {next_event,,}
  Change arity of type to init_result/1

1 files changed, 11 insertions, 0 deletions

diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index d08ddd0036..f4d84ab163 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -1180,6 +1180,17 @@ open(state_timeout, lock, Data) ->
     {next_state, locked, Data};
 ...
     ]]></code>
+    <p>
+      You can repeat the state entry code by returning one of
+      <c>{repeat_state, ...}</c>, <c>{repeat_state_and_data,_}</c>
+      or <c>repeat_state_and_data</c> that otherwise behaves
+      exactly like their <c>keep_state</c> siblings.
+      See the type
+      <seealso marker="stdlib:gen_statem#type-state_callback_result">
+	<c>state_callback_result()</c>
+      </seealso>
+      in the reference manual.
+    </p>
   </section>
 
 <!-- =================================================================== -->