Brings SMF framework closer into alignment with accepted Hierarchical State
Machine operation by:
1. Allowing 'programming by difference' by having some child states handle
   events and prevent propagation up to the parent run actions while others
   propagate events up to a common handler in a parent state.
2. Optionally allow initial transitions within a parent state to determine
   the most nested child state to transition to.
3. Adding a test case for `CONFIG_SMF_INITIAL_TRANSITION` and
   `smf_set_handled()`
4. Updating documentation for the new API (and fixing some references)

There was discussion in zephyrproject-rtos#55344
about not making the initial transition a Kconfig option, but I'm not sure
of any way else of doing it without permanently adding a pointer to each
`smf_state` entry, which is a problem for resource-constrained devices.

This does not fix zephyrproject-rtos#66341
but documentation has been updated to warn users of the issue.

Signed-off-by: Glenn Andrews <glenn.andrews.42@gmail.com>

Fixed where `smf_set_terminate` was written `smf_terminate`

Signed-off-by: Glenn Andrews <glenn.andrews.42@gmail.com>

Added Doxygen markup.

Signed-off-by: Glenn Andrews <glenn.andrews.42@gmail.com>

Incorporated changes requested by @keith-zephyr:
1. Grammar fix
2. Make explicit that transition to self in super-states is not supported

Signed-off-by: Glenn Andrews <glenn.andrews.42@gmail.com>