From f99dcadf8a6f8f0aa93d88475d311a1bf77b71e4 Mon Sep 17 00:00:00 2001 From: Joseph <21144246+JoJoJet@users.noreply.github.com> Date: Tue, 15 Aug 2023 17:48:37 -0400 Subject: [PATCH] Add missing documentation to `bevy_time` (#9428) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 | 3 +++ crates/bevy_time/src/fixed_timestep.rs | 36 ++++++++++++++++++++------ crates/bevy_time/src/lib.rs | 17 ++++++++---- crates/bevy_time/src/time.rs | 4 +++ 4 files changed, 47 insertions(+), 13 deletions(-) create mode 100644 crates/bevy_time/README.md diff --git a/crates/bevy_time/README.md b/crates/bevy_time/README.md new file mode 100644 index 0000000000000..3b5652cd1d626 --- /dev/null +++ b/crates/bevy_time/README.md @@ -0,0 +1,3 @@ +# Bevy Time + +The built-in timekeeping plugin for the Bevy game engine. diff --git a/crates/bevy_time/src/fixed_timestep.rs b/crates/bevy_time/src/fixed_timestep.rs index 66be2f41ef2ff..655a19ba774d7 100644 --- a/crates/bevy_time/src/fixed_timestep.rs +++ b/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 - /// not enough accumulated time to span an entire period. + /// Note that if you are using the default configuration of bevy, this will be called for you. 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::