Add state app builder docs (#1746)

This is intended to help protect users against #1671. It doesn't resolve the issue, but I think its a good stop-gap solution for 0.5. A "full" fix would be very involved (and maybe not worth the added complexity).

Author: cart

crates/bevy_app/src/app_builder.rs

@@ -178,20 +178,29 @@ impl AppBuilder {
         self
     }
 
+    /// Adds a new [State] with the given `initial` value.
+    /// This inserts a new `State<T>` resource and adds a new "driver" to [CoreStage::Update].
+    /// Each stage that uses `State<T>` for system run criteria needs a driver. If you need to use your state in a
+    /// different stage, consider using [Self::add_state_to_stage] or manually adding [State::get_driver] to additional stages
+    /// you need it in.
     pub fn add_state<T>(&mut self, initial: T) -> &mut Self
     where
         T: Component + Debug + Clone + Eq + Hash,
     {
-        self.insert_resource(State::new(initial))
-            .add_system_set(State::<T>::make_driver())
+        self.add_state_to_stage(CoreStage::Update, initial)
     }
 
+    /// Adds a new [State] with the given `initial` value.
+    /// This inserts a new `State<T>` resource and adds a new "driver" to the given stage.
+    /// Each stage that uses `State<T>` for system run criteria needs a driver. If you need to use your state in
+    /// more than one stage, consider manually adding [State::get_driver] to the stages
+    /// you need it in.
     pub fn add_state_to_stage<T>(&mut self, stage: impl StageLabel, initial: T) -> &mut Self
     where
         T: Component + Debug + Clone + Eq + Hash,
     {
         self.insert_resource(State::new(initial))
-            .add_system_set_to_stage(stage, State::<T>::make_driver())
+            .add_system_set_to_stage(stage, State::<T>::get_driver())
     }
 
     pub fn add_default_stages(&mut self) -> &mut Self {

crates/bevy_ecs/src/schedule/state.rs

@@ -258,7 +258,7 @@ where
     ///
     /// Important note: this set must be inserted **before** all other state-dependant sets to work
     /// properly!
-    pub fn make_driver() -> SystemSet {
+    pub fn get_driver() -> SystemSet {
         SystemSet::default()
             .with_run_criteria(state_cleaner::<T>.system().label(DriverLabel::of::<T>()))
     }
@@ -510,7 +510,7 @@ mod test {
 
         let mut stage = SystemStage::parallel();
 
-        stage.add_system_set(State::<MyState>::make_driver());
+        stage.add_system_set(State::<MyState>::get_driver());
         stage
             .add_system_set(
                 State::on_enter_set(MyState::S1)