From 8394e9b720ea6a24acecaeab011f32bf891c8617 Mon Sep 17 00:00:00 2001 From: Joy <51241057+maniwani@users.noreply.github.com> Date: Mon, 7 Mar 2022 08:49:10 -0800 Subject: [PATCH] docs --- crates/bevy_core/src/time/fixed_timestep.rs | 66 ++++++++++----------- crates/bevy_core/src/time/time.rs | 36 +++++------ 2 files changed, 51 insertions(+), 51 deletions(-) diff --git a/crates/bevy_core/src/time/fixed_timestep.rs b/crates/bevy_core/src/time/fixed_timestep.rs index 27d5d9e59abac7..802894f0eb12a4 100644 --- a/crates/bevy_core/src/time/fixed_timestep.rs +++ b/crates/bevy_core/src/time/fixed_timestep.rs @@ -7,14 +7,14 @@ use bevy_utils::{Duration, Instant}; use crate::Time; -/// The default step size used for the fixed timestep. +/// The default step size used by [`FixedTimestep`]. // 60Hz is a popular tick rate, but it can't be expressed as an exact float. // The nearby power of two, 64Hz, is more stable for numerical integration. pub const DEFAULT_TIMESTEP: Duration = Duration::from_micros(15625); // 64Hz -/// `FixedTime` tracks how much time has advanced since its previous update and since the app was started. +/// Tracks how much time has advanced since its previous update and since the app was started. /// -/// It's just like [`Time`](super::time::Time) (and internally coupled to it), except it updates in fixed increments. +/// It's just like [`Time`] (and internally coupled to it), except it advances in fixed increments. #[derive(Debug, Clone)] pub struct FixedTime { startup: Instant, @@ -69,7 +69,7 @@ impl FixedTime { self.update_with_instant(now); } - /// Advances fixed time by the fixed delta and records the [`Instant`] it happened. + /// Advances time by [`FixedTime::delta`] and records the [`Instant`] it happened. pub(crate) fn update_with_instant(&mut self, instant: Instant) { if self.last_update.is_none() { self.first_update = Some(instant); @@ -86,40 +86,40 @@ impl FixedTime { self.startup } - /// Returns the [`Instant`] when [`FixedTime::update`] was first called, if it exists. + /// Returns the [`Instant`] when [`update`](FixedTime::update) was first called, if it exists. #[inline] pub fn first_update(&self) -> Option { self.first_update } - /// Returns the [`Instant`] when [`FixedTime::update`] was last called, if it exists. + /// Returns the [`Instant`] when [`update`](FixedTime::update) was last called, if it exists. #[inline] pub fn last_update(&self) -> Option { self.last_update } - /// Returns how much fixed time advances in each update, as a [`Duration`]. + /// Returns how much time advances with each [`update`](FixedTime::update), as a [`Duration`]. #[inline] pub fn delta(&self) -> Duration { self.delta } - /// Returns how much fixed time advances in each update, as [`f32`] seconds. + /// Returns how much time advances with each [`update`](FixedTime::update), as [`f32`] seconds. #[inline] pub fn delta_seconds(&self) -> f32 { self.delta_seconds } - /// Returns how much fixed time advances in each update, as [`f64`] seconds. + /// Returns how much time advances with each [`update`](FixedTime::update), as [`f64`] seconds. #[inline] pub fn delta_seconds_f64(&self) -> f64 { self.delta_seconds_f64 } - /// Sets the timestep to `delta`, given as [`Duration`]. + /// Sets the timestep te `delta`, given as [`Duration`]. /// - /// Outside of startup, users should prefer using [`Time::set_relative_speed`] - /// as changing the timestep itself will change system behavior. + /// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`] + /// as changing the timestep itself will likely change system behavior. /// /// # Panics /// @@ -131,37 +131,37 @@ impl FixedTime { self.delta_seconds_f64 = self.delta.as_secs_f64(); } - /// Sets the timestep to `delta`, given as [`f32`]. + /// Sets the timestep te `delta`, given as [`f32`]. /// - /// Outside of startup, users should prefer using [`Time::set_relative_speed`] - /// as changing the timestep itself will change system behavior. + /// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`] + /// as changing the timestep itself will likely change system behavior. /// /// # Panics /// - /// Panics if `delta` is less than or equal to zero, not finite, or overflows the `Duration`. + /// Panics if `delta` is less than or equal to zero, not finite, or overflows a `Duration`. pub fn set_delta_f32(&mut self, delta: f32) { self.set_delta(Duration::from_secs_f32(delta)); } - /// Sets the timestep to `delta`, given as [`f64`]. + /// Sets the timestep te `delta`, given as [`f64`]. /// - /// Outside of startup, users should prefer using [`Time::set_relative_speed`] - /// as changing the timestep itself will change system behavior. + /// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`] + /// as changing the timestep itself will likely change system behavior. /// /// # Panics /// - /// Panics if `delta` is less than or equal to zero, not finite, or overflows the `Duration`. + /// Panics if `delta` is less than or equal to zero, not finite, or overflows a `Duration`. pub fn set_delta_f64(&mut self, delta: f64) { self.set_delta(Duration::from_secs_f64(delta)); } - /// Returns the nominal fixed update rate (reciprocal of [`FixedTime::delta`]) as [`f32`]. + /// Returns the nominal update rate (reciprocal of [`FixedTime::delta`]) as [`f32`]. #[inline] pub fn steps_per_second(&self) -> f32 { 1.0 / self.delta_seconds } - /// Returns the nominal fixed update rate (reciprocal of [`FixedTime::delta`]) as [`f64`]. + /// Returns the nominal update rate (reciprocal of [`FixedTime::delta`]) as [`f64`]. #[inline] pub fn steps_per_second_f64(&self) -> f64 { 1.0 / self.delta_seconds_f64 @@ -169,8 +169,8 @@ impl FixedTime { /// Sets the timestep to the reciprocal of `rate`, given as [`f32`]. /// - /// Outside of startup, users should prefer using [`Time::set_relative_speed`] - /// as changing the timestep itself will change system behavior. + /// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`] + /// as changing the timestep itself will likely change system behavior. /// /// # Panics /// @@ -183,8 +183,8 @@ impl FixedTime { /// Sets the timestep to the reciprocal of `rate`, given as [`f64`]. /// - /// Outside of startup, users should prefer using [`Time::set_relative_speed`] - /// as changing the timestep itself will change system behavior. + /// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`] + /// as changing the timestep itself will likely change system behavior. /// /// # Panics /// @@ -195,26 +195,26 @@ impl FixedTime { self.set_delta(Duration::from_secs_f64(1.0 / rate)); } - /// Returns how much fixed time has advanced since startup, as [`Duration`]. + /// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`Duration`]. #[inline] pub fn elapsed_since_startup(&self) -> Duration { self.elapsed_since_startup } - /// Returns how much fixed time has advanced since startup, as [`f32`] seconds. + /// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`f32`] seconds. #[inline] pub fn seconds_since_startup(&self) -> f32 { self.seconds_since_startup } - /// Returns how much fixed time has advanced since startup, as [`f64`] seconds. + /// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`f64`] seconds. #[inline] pub fn seconds_since_startup_f64(&self) -> f64 { self.seconds_since_startup_f64 } } -/// Accumulates time and converts it into steps: one step per `timestep` accumulated. Used to drive [`FixedTime`]. +/// Accumulates time and converts it into steps: one step per [`FixedTime::delta`] accumulated. Used to drive [`FixedTime`] and [`FixedTimestep`]. #[derive(Debug, Clone)] pub struct FixedTimestepState { steps: u32, @@ -250,7 +250,7 @@ impl FixedTimestepState { /// Returns the amount of time accumulated toward new steps, as an [`f32`] fraction of `timestep`. /// - /// Use this function when interpolating data between two timesteps. + /// Use this function when interpolating data between consecutive [`FixedTimestep`] iterations. /// /// # Panics /// @@ -262,7 +262,7 @@ impl FixedTimestepState { /// Returns the amount of time accumulated toward new steps, as an [`f64`] fraction of `timestep`. /// - /// Use this function when interpolating data between two timesteps. + /// Use this function when interpolating data between consecutive [`FixedTimestep`] iterations. /// /// # Panics /// @@ -273,7 +273,7 @@ impl FixedTimestepState { } /// Adds `time` to the internal `overstep`, then converts the `overstep` accumulated into - /// as many steps of size `timestep` as possible. + /// as many `timestep`-sized steps as possible. /// /// # Panics /// diff --git a/crates/bevy_core/src/time/time.rs b/crates/bevy_core/src/time/time.rs index e2b761d76b5833..b98774e93dd54a 100644 --- a/crates/bevy_core/src/time/time.rs +++ b/crates/bevy_core/src/time/time.rs @@ -3,7 +3,7 @@ use bevy_utils::{Duration, Instant}; use crate::{FixedTime, FixedTimestepState}; -/// `Time` tracks how much time has advanced (and also the raw CPU time elapsed) since its previous update and since the app was started. +/// Tracks how much time has advanced (and also the raw CPU time elapsed) since its previous update and since the app was started. #[derive(Debug, Clone)] pub struct Time { startup: Instant, @@ -103,13 +103,13 @@ impl Time { self.startup } - /// Returns the [`Instant`] when [`Time::update`] was first called, if it exists. + /// Returns the [`Instant`] when [`update`](Time::update) was first called, if it exists. #[inline] pub fn first_update(&self) -> Option { self.first_update } - /// Returns the [`Instant`] when [`Time::update`] was last called, if it exists. + /// Returns the [`Instant`] when [`update`](Time::update) was last called, if it exists. #[inline] pub fn last_update(&self) -> Option { self.last_update @@ -135,7 +135,7 @@ impl Time { /// /// # Panics /// - /// Panics if `ratio` negative or not finite. + /// Panics if `ratio` is negative or not finite. pub fn set_relative_speed(&mut self, ratio: f32) { assert!(ratio.is_finite(), "tried to go infinitely fast"); assert!(ratio.is_sign_positive(), "tried to go back in time"); @@ -146,87 +146,87 @@ impl Time { /// /// # Panics /// - /// Panics if `ratio` negative or not finite. + /// Panics if `ratio` is negative or not finite. pub fn set_relative_speed_f64(&mut self, ratio: f64) { assert!(ratio.is_finite(), "tried to go infinitely fast"); assert!(ratio.is_sign_positive(), "tried to go back in time"); self.relative_speed = ratio; } - /// Returns how much time has advanced since the last update, as a [`Duration`]. + /// Returns how much time has advanced since the last [`update`](Time::update), as a [`Duration`]. #[inline] pub fn delta(&self) -> Duration { self.delta } - /// Returns how much time has advanced since the last update, as [`f32`] seconds. + /// Returns how much time has advanced since the last [`update`](Time::update), as [`f32`] seconds. #[inline] pub fn delta_seconds(&self) -> f32 { self.delta_seconds } - /// Returns how much time has advanced since the last update, as [`f64`] seconds. + /// Returns how much time has advanced since the last [`update`](Time::update), as [`f64`] seconds. #[inline] pub fn delta_seconds_f64(&self) -> f64 { self.delta_seconds_f64 } - /// Returns the exact CPU time elapsed since the last update, as a [`Duration`]. + /// Returns the exact CPU time elapsed since the last [`update`](Time::update), as a [`Duration`]. #[inline] pub fn raw_delta(&self) -> Duration { self.raw_delta } - /// Returns the exact CPU time elapsed since the last update, as [`f32`] seconds. + /// Returns the exact CPU time elapsed since the last [`update`](Time::update), as [`f32`] seconds. #[inline] pub fn raw_delta_seconds(&self) -> f32 { self.raw_delta_seconds } - /// Returns the exact CPU time elapsed since the last update, as [`f64`] seconds. + /// Returns the exact CPU time elapsed since the last [`update`](Time::update), as [`f64`] seconds. #[inline] pub fn raw_delta_seconds_f64(&self) -> f64 { self.raw_delta_seconds_f64 } - /// Returns how much time has advanced since startup, as [`Duration`]. + /// Returns how much time has advanced since [`startup`](Time::startup), as [`Duration`]. #[inline] pub fn elapsed_since_startup(&self) -> Duration { self.elapsed_since_startup } - /// Returns how much time has advanced since startup, as [`f32`] seconds. + /// Returns how much time has advanced since [`startup`](Time::startup), as [`f32`] seconds. #[inline] pub fn seconds_since_startup(&self) -> f32 { self.seconds_since_startup } - /// Returns how much time has advanced since startup, as [`f64`] seconds. + /// Returns how much time has advanced since [`startup`](Time::startup), as [`f64`] seconds. #[inline] pub fn seconds_since_startup_f64(&self) -> f64 { self.seconds_since_startup_f64 } - /// Returns the exact CPU time elapsed since startup, as [`Duration`]. + /// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`Duration`]. #[inline] pub fn raw_elapsed_since_startup(&self) -> Duration { self.raw_elapsed_since_startup } - /// Returns the exact CPU time elapsed since startup, as [`f32`] seconds. + /// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`f32`] seconds. #[inline] pub fn raw_seconds_since_startup(&self) -> f32 { self.raw_seconds_since_startup } - /// Returns the exact CPU time elapsed since startup, as [`f64`] seconds. + /// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`f64`] seconds. #[inline] pub fn raw_seconds_since_startup_f64(&self) -> f64 { self.raw_seconds_since_startup_f64 } } -/// Advances `Time` and accumulates the amount advanced for `FixedTime`. +/// Advances [`Time`] and accumulates the amount advanced for [`FixedTime`]. pub(crate) fn update_time( mut time: ResMut