fix typos + consistency + update filter docs

why is dereferenced so hard to spell

Author: maniwani

crates/bevy_ecs/src/change_detection.rs

@@ -43,19 +43,18 @@ pub const MAX_CHANGE_AGE: u32 = u32::MAX - (2 * CHECK_TICK_THRESHOLD - 1);
 /// ```
 ///
 pub trait DetectChanges {
-    /// Returns true if (and only if) this value been added since the last execution of this
-    /// system.
+    /// Returns `true` if this value was added after the system last ran, `false` otherwise.
     fn is_added(&self) -> bool;
 
-    /// Returns true if (and only if) this value been changed since the last execution of this
-    /// system.
+    /// Returns `true` if this value was added or mutably dereferenced after the system last ran, `false` otherwise.
     fn is_changed(&self) -> bool;
 
-    /// Manually flags this value as having been changed. This normally isn't
-    /// required because accessing this pointer mutably automatically flags this
-    /// value as "changed".
+    /// Flags this value as having been changed.
+    /// 
+    /// Mutably accessing this smart pointer will automatically flag this value as having been changed.
+    /// However, mutation through interior mutability requires manual reporting.
     ///
-    /// **Note**: This operation is irreversible.
+    /// **Note**: This operation cannot be undone.
     fn set_changed(&mut self);
 }
 

crates/bevy_ecs/src/component.rs

@@ -339,7 +339,7 @@ impl Components {
     }
 }
 
-/// Stores two [`World`](crate::world::World) "ticks" denoting when the component was added and when it was last changed (added or mutably-deferenced).
+/// Records when a component was added and when it was last mutably dereferenced (or added).
 #[derive(Clone, Debug)]
 pub struct ComponentTicks {
     pub(crate) added: u32,
@@ -364,7 +364,7 @@ impl ComponentTicks {
     }
 
     #[inline]
-    /// Returns `true` if the component was added or mutably-dereferenced after the system last ran, `false` otherwise.
+    /// Returns `true` if the component was added or mutably dereferenced after the system last ran, `false` otherwise.
     pub fn is_changed(&self, last_change_tick: u32, change_tick: u32) -> bool {
         // This works even with wraparound because the world tick (`change_tick`) is always "newer" than
         // `last_change_tick` and `self.changed`, and we scan periodically to clamp `ComponentTicks` values

crates/bevy_ecs/src/query/filter.rs

@@ -593,17 +593,12 @@ macro_rules! impl_tick_filter {
 }
 
 impl_tick_filter!(
-    /// Filter that retrieves components of type `T` that have been added since the last execution
-    /// of this system.
+    /// A filter on a component that only retains results added after the system last ran.
     ///
-    /// This filter is useful to do one-time post-processing on components.
+    /// A common use for this filter is one-time initialization.
     ///
-    /// Because the ordering of systems can change and this filter is only effective on changes
-    /// before the query executes you need to use explicit dependency ordering or ordered stages to
-    /// avoid frame delays.
-    ///
-    /// If instead behavior is meant to change on whether the component changed or not
-    /// [`ChangeTrackers`](crate::query::ChangeTrackers) may be used.
+    /// To retain all results without filtering but still check whether they were added after the
+    /// system last ran, use [`ChangeTrackers<T>`](crate::query::ChangeTrackers).
     ///
     /// # Examples
     ///
@@ -633,18 +628,15 @@ impl_tick_filter!(
 );
 
 impl_tick_filter!(
-    /// Filter that retrieves components of type `T` that have been changed since the last
-    /// execution of this system.
-    ///
-    /// This filter is useful for synchronizing components, and as a performance optimization as it
-    /// means that the query contains fewer items for a system to iterate over.
+    /// A filter on a component that only retains results added or mutably dereferenced after the system last ran.
+    ///  
+    /// A common use for this filter is avoiding redundant work when values have not changed.
     ///
-    /// Because the ordering of systems can change and this filter is only effective on changes
-    /// before the query executes you need to use explicit dependency ordering or ordered
-    /// stages to avoid frame delays.
+    /// **Note** that simply *mutably dereferencing* a component is considered a change ([`DerefMut`](std::ops::DerefMut)).
+    /// Bevy does not compare components to their previous values.
     ///
-    /// If instead behavior is meant to change on whether the component changed or not
-    /// [`ChangeTrackers`](crate::query::ChangeTrackers) may be used.
+    /// To retain all results without filtering but still check whether they were changed after the
+    /// system last ran, use [`ChangeTrackers<T>`](crate::query::ChangeTrackers).
     ///
     /// # Examples
     ///

crates/bevy_ecs/src/system/system_param.rs

@@ -225,7 +225,7 @@ impl<'w, T: Resource> Res<'w, T> {
         self.ticks.is_added(self.last_change_tick, self.change_tick)
     }
 
-    /// Returns `true` if the resource was added or mutably-dereferenced after the system last ran, `false` otherwise.
+    /// Returns `true` if the resource was added or mutably dereferenced after the system last ran, `false` otherwise.
     pub fn is_changed(&self) -> bool {
         self.ticks
             .is_changed(self.last_change_tick, self.change_tick)
@@ -780,7 +780,7 @@ impl<'w, T: 'static> NonSend<'w, T> {
         self.ticks.is_added(self.last_change_tick, self.change_tick)
     }
 
-    /// Returns `true` if the resource was added or mutably-dereferenced after the system last ran, `false` otherwise.
+    /// Returns `true` if the resource was added or mutably dereferenced after the system last ran, `false` otherwise.
     pub fn is_changed(&self) -> bool {
         self.ticks
             .is_changed(self.last_change_tick, self.change_tick)