State example (#13322)

# Objective
adopted from #10716
adds example for updating state

---------

Co-authored-by: Stepan Koltsov <stepan.koltsov@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

crates/bevy_state/src/state/mod.rs

@@ -6,6 +6,7 @@ mod states;
 mod sub_states;
 mod transitions;
 
+pub use bevy_state_macros::*;
 pub use computed_states::*;
 pub use freely_mutable_state::*;
 pub use resources::*;
@@ -16,16 +17,13 @@ pub use transitions::*;
 
 #[cfg(test)]
 mod tests {
+    use bevy_ecs::event::EventRegistry;
     use bevy_ecs::prelude::*;
     use bevy_ecs::schedule::ScheduleLabel;
+    use bevy_state_macros::States;
     use bevy_state_macros::SubStates;
 
     use super::*;
-
-    use bevy_ecs::event::EventRegistry;
-
-    use bevy_ecs::prelude::ResMut;
-
     use crate as bevy_state;
 
     #[derive(States, PartialEq, Eq, Debug, Default, Hash, Clone)]

crates/bevy_state/src/state/resources.rs

@@ -22,6 +22,7 @@ use bevy_ecs::prelude::ReflectResource;
 /// ```
 /// use bevy_state::prelude::*;
 /// use bevy_ecs::prelude::*;
+/// use bevy_state_macros::States;
 ///
 /// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
 /// enum GameState {

crates/bevy_state/src/state/states.rs

@@ -2,8 +2,6 @@ use std::fmt::Debug;
 
 use std::hash::Hash;
 
-pub use bevy_state_macros::States;
-
 /// Types that can define world-wide states in a finite-state machine.
 ///
 /// The [`Default`] trait defines the starting state.
@@ -22,7 +20,10 @@ pub use bevy_state_macros::States;
 /// # Example
 ///
 /// ```
-/// use bevy_state::prelude::States;
+/// use bevy_state::prelude::*;
+/// use bevy_ecs::prelude::IntoSystemConfigs;
+/// use bevy_ecs::system::ResMut;
+///
 ///
 /// #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
 /// enum GameState {
@@ -32,6 +33,26 @@ pub use bevy_state_macros::States;
 ///   InGame,
 /// }
 ///
+/// fn handle_escape_pressed(mut next_state: ResMut<NextState<GameState>>) {
+/// #   let escape_pressed = true;
+///     if escape_pressed {
+///         next_state.set(GameState::SettingsMenu);
+///     }
+/// }
+///
+/// fn open_settings_menu() {
+///     // Show the settings menu...
+/// }
+///
+/// # struct AppMock;
+/// # impl AppMock {
+/// #     fn add_systems<S, M>(&mut self, schedule: S, systems: impl IntoSystemConfigs<M>) {}
+/// # }
+/// # struct Update;
+/// # let mut app = AppMock;
+///
+/// app.add_systems(Update, handle_escape_pressed.run_if(in_state(GameState::MainMenu)));
+/// app.add_systems(OnEnter(GameState::SettingsMenu), open_settings_menu);
 /// ```
 pub trait States: 'static + Send + Sync + Clone + PartialEq + Eq + Hash + Debug {
     /// How many other states this state depends on.