fix docs around StateTransition and remove references to `apply_sta… (

#13772)

The documentation for the `State` resource still referenced the use of
`apply_state_transition` to manually force a state transition to occur,
and the question around how to force transitions had come up a few times
on discord.

This is a docs-only change, that does the following:
- Properly references `StateTransition` in the `MainSchedule` docs
- replace the explanations for applying `NextState` with ones that
explain the `StateTransition` schedule, and mentions the possibility of
calling it manually
- Add an example of calling `StateTransition` manually in the docs for
the state transition schedule itself.

---------

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

crates/bevy_app/src/main_schedule.rs

@@ -17,7 +17,7 @@ use bevy_ecs::{
 /// Then it will run:
 /// * [`First`]
 /// * [`PreUpdate`]
-/// * [`StateTransition`]
+/// * [`StateTransition`](bevy_state::transition::StateTransition)
 /// * [`RunFixedMainLoop`]
 ///     * This will run [`FixedMain`] zero to many times, based on how much time has elapsed.
 /// * [`Update`]

crates/bevy_state/src/state/resources.rs

@@ -15,8 +15,11 @@ use bevy_ecs::prelude::ReflectResource;
 /// ([`OnEnter(state)`](crate::state::OnEnter) and [`OnExit(state)`](crate::state::OnExit)).
 ///
 /// The current state value can be accessed through this resource. To *change* the state,
-/// queue a transition in the [`NextState<S>`] resource, and it will be applied by the next
-/// [`apply_state_transition::<S>`](crate::state::apply_state_transition) system.
+/// queue a transition in the [`NextState<S>`] resource, and it will be applied during the
+/// [`StateTransition`](crate::transition::StateTransition) schedule - which by default runs after `PreUpdate`.
+///
+/// You can also manually trigger the [`StateTransition`](crate::transition::StateTransition) schedule to apply the changes
+/// at an arbitrary time.
 ///
 /// The starting state is defined via the [`Default`] implementation for `S`.
 ///
@@ -90,7 +93,7 @@ impl<S: States> Deref for State<S> {
 /// To queue a transition, call [`NextState::set`] or mutate the value to [`NextState::Pending`] directly.
 ///
 /// Note that these transitions can be overridden by other systems:
-/// only the actual value of this resource at the time of [`apply_state_transition`](crate::state::apply_state_transition) matters.
+/// only the actual value of this resource during the [`StateTransition`](crate::transition::StateTransition) schedule matters.
 ///
 /// ```
 /// use bevy_state::prelude::*;

crates/bevy_state/src/state/transitions.rs

@@ -38,6 +38,19 @@ pub struct OnTransition<S: States> {
 }
 
 /// Runs [state transitions](States).
+///
+/// By default, it will be triggered after `PreUpdate`, but
+/// you can manually trigger it at arbitrary times by creating an exclusive
+/// system to run the schedule.
+///
+/// ```rust
+/// use bevy_state::prelude::*;
+/// use bevy_ecs::prelude::*;
+///
+/// fn run_state_transitions(world: &mut World) {
+///     let _ = world.try_run_schedule(StateTransition);
+/// }
+/// ```
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct StateTransition;