Polish documentation

lib/stdlib/src/gen_statem.erl

@@ -548,6 +548,27 @@ State name or state term.
 If the [_callback mode_](`t:callback_mode/0`) is `handle_event_function`,
 the state can be any term. After a _state change_ (`NextState =/= State`),
 all postponed events are retried.
+
+Comparing two states for strict equality is assumed to be a fast operation,
+since for every _state transition_ the `gen_statem` engine has to deduce
+if it is a  _state change_.
+
+> #### Note {: .info }
+> The smaller the state term, in general, the faster the comparison.
+>
+> Note that if the "same" state term is returned for a state transition
+> (or a return action without a `NextState` field is used),
+> the comparison for equality is always fast because that can be seen
+> from the term handle.
+>
+> But if a newly constructed state term is returned,
+> both the old and the new state terms will have to be traversed
+> until an inequality is found, or until both terms
+> have been fully traversed.
+>
+> So it is possible to use large state terms that are fast to compare,
+> but very easy to accidentally mess up.  Using small state terms is
+> the safe choice.
 """.
 -type state() ::
 	state_name() | % For StateName/3 callback functions

system/doc/design_principles/statem.md

@@ -1168,9 +1168,9 @@ in the value changes the set of events that is handled, the value
 should be in the State.  Otherwise no postponed events will be retried
 since only the server `Data` changes.
 
-This is not important if you do not postpone events.  But if you later decide
-to use event postponing, the design flaw of not having separate states
-when they should be, could become a hard-to-find bug.
+This is important if events are postponed.  But remember that an incorrect
+design decision of what belongs in the state, may become a hard to find bug
+some time later, when event postponing is introduced.
 
 ### Fuzzy State Diagrams