From dedc5275007fa87631249d1172521cda3dc7a8aa Mon Sep 17 00:00:00 2001 From: AlephCubed Date: Wed, 30 Apr 2025 20:00:33 -0700 Subject: [PATCH] Cleanup pass on docs. --- immediate_stats/README.md | 9 ++++++--- immediate_stats/src/bevy.rs | 2 +- immediate_stats/src/lib.rs | 24 ++++++++++++------------ immediate_stats/src/modifier.rs | 12 ++++++++++-- immediate_stats/src/stat.rs | 9 +++++++-- 5 files changed, 36 insertions(+), 20 deletions(-) diff --git a/immediate_stats/README.md b/immediate_stats/README.md index 7c98289..aeb18b8 100644 --- a/immediate_stats/README.md +++ b/immediate_stats/README.md @@ -43,14 +43,17 @@ fn main() { ### Bevy Butler If you use [Bevy Butler](https://github.com/TGRCdev/bevy-butler/), you can also use the `bevy_butler` feature flag. -This automatically registers the required system(s) using the `add_component` attribute. +This automatically registers the required system(s) using the `add_component` attribute +or the existing `add_resource` macro. ```rust #[butler_plugin] struct MyPlugin; -#[derive(StatContainer, Component)] -#[add_component(plugin = MyPlugin)] // Added by `StatContainer` derive. +// `StatContainer` derive adds the `add_component` attribute and hooks into the existing `add_resource` macro. +#[derive(StatContainer, Component, Resource, Default)] +#[add_component(plugin = MyPlugin)] // Adds `reset_component_modifiers` system. +#[add_resource(plugin = MyPlugin)] // Adds `reset_resource_modifiers` system. struct Speed(Stat); ``` diff --git a/immediate_stats/src/bevy.rs b/immediate_stats/src/bevy.rs index 5f60de5..1eab9df 100644 --- a/immediate_stats/src/bevy.rs +++ b/immediate_stats/src/bevy.rs @@ -22,7 +22,7 @@ impl Plugin for ImmediateStatsPlugin { } } -/// Prevents a [`StatContainers`](StatContainer) from resetting. +/// Prevents any [`StatContainers`](StatContainer) on an entity from resetting. #[derive(Component, Reflect, Eq, PartialEq, Debug, Default, Clone)] #[component(storage = "SparseSet")] #[reflect(Component, PartialEq, Debug, Default, Clone)] diff --git a/immediate_stats/src/lib.rs b/immediate_stats/src/lib.rs index 0f432d8..1898382 100644 --- a/immediate_stats/src/lib.rs +++ b/immediate_stats/src/lib.rs @@ -1,11 +1,9 @@ //! Game stats that reset every frame, inspired by immediate mode rendering. //! //! This makes it easy to implement temporary buffs/debuffs, and effects that change over time. -//! Using a derive macro, stat resets are propagated to any stat fields, +//! Using a [derive macro](macro@StatContainer), stat resets are propagated to any stat fields, //! making it easy to compose stats into more complex or specific objects. //! -//! Includes a [derive macro](macro@StatContainer) which propagates stat resets to any stat fields. -//! //! ```rust no_run //! # use immediate_stats::*; //! #[derive(StatContainer)] @@ -53,7 +51,8 @@ //! //! If you use [Bevy Butler](https://github.com/TGRCdev/bevy-butler/), //! you can also use the `bevy_butler` feature flag. -//! This automatically registers the required system(s) using the `add_component` attribute. +//! This automatically registers the required system(s) using the `add_component` attribute +//! or the existing `add_resource` macro. //! #![cfg_attr(not(feature = "bevy_butler"), doc = "```rust ignore")] #![cfg_attr(feature = "bevy_butler", doc = "```rust")] @@ -83,7 +82,7 @@ mod modifier; mod stat; /// Implements [`reset_modifiers`](StatContainer::reset_modifiers) -/// by propagating the call down to any `StatContainer` fields. +/// by propagating the call down to any stat fields. /// ```rust /// # use immediate_stats::*; /// #[derive(StatContainer, Default, Debug, PartialEq)] @@ -104,7 +103,8 @@ mod stat; /// } /// ``` /// # Configuration -/// By default, it will consider any field whose type contains "Stat" to be a sub-stat. +/// By default, the macro will consider any field whose type contains the word "Stat" +/// to be a sub-stat. /// You can use `#[stat]` to add other sub-stats and `#[stat_ignore]` to ignore one. /// ```rust /// # use immediate_stats::*; @@ -124,7 +124,7 @@ mod stat; /// fn main () { /// let mut partial = PartialReset { /// custom: Health::default(), -/// ignored: Stat::new(1), +/// ignored: Stat::default(), /// }; /// /// partial.custom.max += 10; @@ -133,12 +133,13 @@ mod stat; /// partial.reset_modifiers(); /// /// assert_eq!(partial.custom, Health::default()); -/// assert_eq!(partial.ignored, Stat::new(1).with_bonus(10)); +/// assert_eq!(partial.ignored, Stat::default().with_bonus(10)); /// } /// ``` /// # Bevy Butler /// If the `bevy_butler` feature flag is enabled, you may also use the `add_component` attribute -/// to register [`reset_component_modifiers`] and/or [`reset_resource_modifiers`] automatically. +/// or the existing `add_resource` macro to register [`reset_component_modifiers`] +/// and/or [`reset_resource_modifiers`] automatically. #[cfg_attr(not(feature = "bevy_butler"), doc = "```rust ignore")] #[cfg_attr(feature = "bevy_butler", doc = "```rust")] /// # use bevy_butler::*; @@ -168,10 +169,9 @@ pub use bevy_app::prelude::PreUpdate; /// Types that contain stats that need to be reset. /// -/// It is recommended to use the [derive macro](macro@StatContainer) -/// instead of implementing manually. +/// Consider using the [derive macro](macro@StatContainer) before implementing manually. #[cfg_attr(feature = "bevy", bevy_reflect::reflect_trait)] pub trait StatContainer { - /// Resets all stat bonuses to zero, and stat multipliers to one. + /// Resets all stats to a base value. For most use-cases, this should be called every frame/iteration. fn reset_modifiers(&mut self); } diff --git a/immediate_stats/src/modifier.rs b/immediate_stats/src/modifier.rs index c3d7e24..ba0ceee 100644 --- a/immediate_stats/src/modifier.rs +++ b/immediate_stats/src/modifier.rs @@ -10,9 +10,13 @@ use std::ops::{AddAssign, DivAssign, MulAssign, SubAssign}; reflect(PartialEq, Debug, Clone) )] pub struct Modifier { - /// Added to `base` of a [`super::Stat`] during calculation. + /// Added to `base` of a [`Stat`](super::Stat) during calculation. + /// + /// Can be modified using [`+=`](Modifier::add_assign) and [`-=`](`Modifier::sub_assign`). pub bonus: i32, - /// Multiplies the `base` of a [`super::Stat`] during calculation. + /// Multiplies the `base` of a [`Stat`](super::Stat) during calculation. + /// + /// Can be modified using [`*=`](`Modifier::mul_assign`) and [`/=`](`Modifier::div_assign`). pub multiplier: f32, } @@ -49,24 +53,28 @@ impl Default for Modifier { } impl AddAssign for Modifier { + /// Adds to the modifier's bonus. fn add_assign(&mut self, rhs: i32) { self.bonus += rhs; } } impl SubAssign for Modifier { + /// Subtracts from the modifier's bonus. fn sub_assign(&mut self, rhs: i32) { self.bonus -= rhs; } } impl MulAssign for Modifier { + /// Multiplies the modifier's multiplier. fn mul_assign(&mut self, rhs: f32) { self.multiplier *= rhs; } } impl DivAssign for Modifier { + /// Divides the modifier's multiplier. fn div_assign(&mut self, rhs: f32) { self.multiplier /= rhs; } diff --git a/immediate_stats/src/stat.rs b/immediate_stats/src/stat.rs index 29dce67..70b4e05 100644 --- a/immediate_stats/src/stat.rs +++ b/immediate_stats/src/stat.rs @@ -24,16 +24,17 @@ use std::ops::{AddAssign, DivAssign, MulAssign, SubAssign}; )] pub struct Stat { /// The persistent value of the stat. + /// After being [reset](StatContainer::reset_modifiers), [`Stat::total`] will be equal to `base`. pub base: i32, /// Added to `base` during calculation and gets reset to zero every iteration. /// This is added *before* `multiplier` is applied. /// - /// Can be modified using [`Stat::add_assign`] and [`Stat::sub_assign`] + /// Can be modified using [`+=`](Stat::add_assign) or [`-=`](Stat::sub_assign). pub bonus: i32, /// Multiplies the `base` during calculation and gets reset to one every iteration. /// This is applied *after* `bonus` is added. /// - /// Can be modified using [`Stat::mul_assign`] and [`Stat::div_assign`] + /// Can be modified using [*=](`Stat::mul_assign`) or [/=](`Stat::div_assign`). pub multiplier: f32, } @@ -97,24 +98,28 @@ impl Default for Stat { } impl AddAssign for Stat { + /// Adds to the stat's bonus. fn add_assign(&mut self, rhs: i32) { self.bonus += rhs; } } impl SubAssign for Stat { + /// Subtracts from the stat's bonus. fn sub_assign(&mut self, rhs: i32) { self.bonus -= rhs; } } impl MulAssign for Stat { + /// Multiplies the stat's multiplier. fn mul_assign(&mut self, rhs: f32) { self.multiplier *= rhs; } } impl DivAssign for Stat { + /// Divides the stat's multiplier. fn div_assign(&mut self, rhs: f32) { self.multiplier /= rhs; } -- 2.51.2