Fix misleading documentation of Main schedule (#18579)

# Objective

Fixes #18562.

## Solution

- Specified that `StateTransition` is actually run before `PreStartup`.
- Specified consequences of this and how to actually run systems before
any game logic regardless of state.
- Updated docs of `StateTransition` to reflect that it is run before
`PreStartup` in addition to being run after `PreUpdate`.

## Testing

- `cargo doc`
- `cargo test --doc`

crates/bevy_app/src/main_schedule.rs

@@ -15,6 +15,13 @@ use bevy_ecs::{
 /// By default, it will run the following schedules in the given order:
 ///
 /// On the first run of the schedule (and only on the first run), it will run:
+/// * [`StateTransition`] [^1]
+///      * This means that [`OnEnter(MyState::Foo)`] will be called *before* [`PreStartup`]
+///        if `MyState` was added to the app with `MyState::Foo` as the initial state,
+///        as well as [`OnEnter(MyComputedState)`] if it `compute`s to `Some(Self)` in `MyState::Foo`.
+///      * If you want to run systems before any state transitions, regardless of which state is the starting state,
+///        for example, for registering required components, you can add your own custom startup schedule
+///        before [`StateTransition`]. See [`MainScheduleOrder::insert_startup_before`] for more details.
 /// * [`PreStartup`]
 /// * [`Startup`]
 /// * [`PostStartup`]
@@ -22,7 +29,7 @@ use bevy_ecs::{
 /// Then it will run:
 /// * [`First`]
 /// * [`PreUpdate`]
-/// * [`StateTransition`]
+/// * [`StateTransition`] [^1]
 /// * [`RunFixedMainLoop`]
 ///     * This will run [`FixedMain`] zero to many times, based on how much time has elapsed.
 /// * [`Update`]
@@ -37,7 +44,11 @@ use bevy_ecs::{
 ///
 /// See [`RenderPlugin`] and [`PipelinedRenderingPlugin`] for more details.
 ///
+/// [^1]: [`StateTransition`] is inserted only if you have `bevy_state` feature enabled. It is enabled in `default` features.
+///
 /// [`StateTransition`]: https://docs.rs/bevy/latest/bevy/prelude/struct.StateTransition.html
+/// [`OnEnter(MyState::Foo)`]: https://docs.rs/bevy/latest/bevy/prelude/struct.OnEnter.html
+/// [`OnEnter(MyComputedState)`]: https://docs.rs/bevy/latest/bevy/prelude/struct.OnEnter.html
 /// [`RenderPlugin`]: https://docs.rs/bevy/latest/bevy/render/struct.RenderPlugin.html
 /// [`PipelinedRenderingPlugin`]: https://docs.rs/bevy/latest/bevy/render/pipelined_rendering/struct.PipelinedRenderingPlugin.html
 /// [`SubApp`]: crate::SubApp

crates/bevy_state/src/state/transitions.rs

@@ -37,7 +37,7 @@ pub struct OnTransition<S: States> {
 
 /// Runs [state transitions](States).
 ///
-/// By default, it will be triggered after `PreUpdate`, but
+/// By default, it will be triggered once before [`PreStartup`] and then each frame after [`PreUpdate`], but
 /// you can manually trigger it at arbitrary times by creating an exclusive
 /// system to run the schedule.
 ///
@@ -49,6 +49,9 @@ pub struct OnTransition<S: States> {
 ///     let _ = world.try_run_schedule(StateTransition);
 /// }
 /// ```
+///
+/// [`PreStartup`]: https://docs.rs/bevy/latest/bevy/prelude/struct.PreStartup.html
+/// [`PreUpdate`]: https://docs.rs/bevy/latest/bevy/prelude/struct.PreUpdate.html
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct StateTransition;