Add missing documentation to bevy_time (#9428)

# Objective

* Add documentation to undocumented items in `bevy_time`.
* Add a warning for undocumented items.

---------

Co-authored-by: Sélène Amanita <134181069+Selene-Amanita@users.noreply.github.com>

crates/bevy_time/README.md

@@ -0,0 +1,3 @@
+# Bevy Time
+
+The built-in timekeeping plugin for the Bevy game engine.

crates/bevy_time/src/fixed_timestep.rs

@@ -28,16 +28,25 @@ use bevy_utils::Duration;
 use thiserror::Error;
 
 /// The amount of time that must pass before the fixed timestep schedule is run again.
+///
+/// For more information, see the [module-level documentation](self).
+///
+/// When using bevy's default configuration, this will be updated using the [`Time`]
+/// resource. To customize how `Time` is updated each frame, see [`TimeUpdateStrategy`].
+///
+/// [`TimeUpdateStrategy`]: crate::TimeUpdateStrategy
 #[derive(Resource, Debug)]
 pub struct FixedTime {
     accumulated: Duration,
+    /// The amount of time spanned by each fixed update.
     /// Defaults to 1/60th of a second.
-    /// To configure this value, simply mutate or overwrite this resource.
+    ///
+    /// To configure this value, simply mutate or overwrite this field.
     pub period: Duration,
 }
 
 impl FixedTime {
-    /// Creates a new [`FixedTime`] struct
+    /// Creates a new [`FixedTime`] struct with a specified period.
     pub fn new(period: Duration) -> Self {
         FixedTime {
             accumulated: Duration::ZERO,
@@ -45,7 +54,7 @@ impl FixedTime {
         }
     }
 
-    /// Creates a new [`FixedTime`] struct with a period specified in `f32` seconds
+    /// Creates a new [`FixedTime`] struct with a period specified in seconds.
     pub fn new_from_secs(period: f32) -> Self {
         FixedTime {
             accumulated: Duration::ZERO,
@@ -53,20 +62,26 @@ impl FixedTime {
         }
     }
 
-    /// Adds the `delta_time` to the accumulated time so far.
+    /// Adds to this instance's accumulated time. `delta_time` should be the amount of in-game time
+    /// that has passed since `tick` was last called.
+    ///
+    /// Note that if you are using the default configuration of bevy, this will be called for you.
     pub fn tick(&mut self, delta_time: Duration) {
         self.accumulated += delta_time;
     }
 
-    /// Returns the current amount of accumulated time
+    /// Returns the current amount of accumulated time.
+    ///
+    /// Approximately, this represents how far behind the fixed update schedule is from the main schedule.
     pub fn accumulated(&self) -> Duration {
         self.accumulated
     }
 
-    /// Expends one `period` of accumulated time.
+    /// Attempts to advance by a single period. This will return [`FixedUpdateError`] if there is not enough
+    /// accumulated time -- in other words, if advancing time would put the fixed update schedule
+    /// ahead of the main schedule.
     ///
-    /// [`Err(FixedUpdateError`)] will be returned if there is
+    /// Note that if you are using the default configuration of bevy, this will be called for you.
-    /// not enough accumulated time to span an entire period.
     pub fn expend(&mut self) -> Result<(), FixedUpdateError> {
         if let Some(new_value) = self.accumulated.checked_sub(self.period) {
             self.accumulated = new_value;
@@ -92,14 +107,19 @@ impl Default for FixedTime {
 /// An error returned when working with [`FixedTime`].
 #[derive(Debug, Error)]
 pub enum FixedUpdateError {
+    /// There is not enough accumulated time to advance the fixed update schedule.
     #[error("At least one period worth of time must be accumulated.")]
     NotEnoughTime {
+        /// The amount of time available to advance the fixed update schedule.
         accumulated: Duration,
+        /// The length of one fixed update.
         period: Duration,
     },
 }
 
 /// Ticks the [`FixedTime`] resource then runs the [`FixedUpdate`].
+///
+/// For more information, see the [module-level documentation](self).
 pub fn run_fixed_update_schedule(world: &mut World) {
     // Tick the time
     let delta_time = world.resource::<Time>().delta();

crates/bevy_time/src/lib.rs

@@ -1,4 +1,6 @@
 #![allow(clippy::type_complexity)]
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
 
 /// Common run conditions
 pub mod common_conditions;
@@ -69,23 +71,28 @@ impl Plugin for TimePlugin {
 /// you may prefer to set the next [`Time`] value manually.
 #[derive(Resource, Default)]
 pub enum TimeUpdateStrategy {
+    /// [`Time`] will be automatically updated each frame using an [`Instant`] sent from the render world via a [`TimeSender`].
+    /// If nothing is sent, the system clock will be used instead.
     #[default]
     Automatic,
-    // Update [`Time`] with an exact `Instant` value
+    /// [`Time`] will be updated to the specified [`Instant`] value each frame.
+    /// In order for time to progress, this value must be manually updated each frame.
+    ///
+    /// Note that the `Time` resource will not be updated until [`TimeSystem`] runs.
     ManualInstant(Instant),
-    // Update [`Time`] with the last update time + a specified `Duration`
+    /// [`Time`] will be incremented by the specified [`Duration`] each frame.
     ManualDuration(Duration),
 }
 
-/// Channel resource used to receive time from render world
+/// Channel resource used to receive time from the render world.
 #[derive(Resource)]
 pub struct TimeReceiver(pub Receiver<Instant>);
 
-/// Channel resource used to send time from render world
+/// Channel resource used to send time from the render world.
 #[derive(Resource)]
 pub struct TimeSender(pub Sender<Instant>);
 
-/// Creates channels used for sending time between render world and app world
+/// Creates channels used for sending time between the render world and the main world.
 pub fn create_time_channels() -> (TimeSender, TimeReceiver) {
     // bound the channel to 2 since when pipelined the render phase can finish before
     // the time system runs.

crates/bevy_time/src/time.rs

@@ -4,6 +4,10 @@ use bevy_utils::{Duration, Instant};
 
 /// A clock that tracks how much it has advanced (and how much real time has elapsed) since
 /// its previous update and since its creation.
+///
+/// See [`TimeUpdateStrategy`], which allows you to customize the way that this is updated each frame.
+///
+/// [`TimeUpdateStrategy`]: crate::TimeUpdateStrategy
 #[derive(Resource, Reflect, Debug, Clone)]
 #[reflect(Resource, Default)]
 pub struct Time {