Add documentation to AssetChanged

crates/bevy_asset/src/query.rs

@@ -9,7 +9,7 @@ use bevy_ecs::{
     archetype::{Archetype, ArchetypeComponentId},
     change_detection::MAX_CHANGE_AGE,
     component::ComponentId,
-    prelude::World,
+    prelude::{Changed, Or, World},
     query::{
         Access, ComponentIdState, Fetch, FetchState, FilteredAccess, QueryItem, ReadFetch,
         ReadOnlyWorldQuery, WorldQuery, WorldQueryGats,
@@ -150,17 +150,56 @@ impl<'w> AssetChangeCheck<'w> {
     }
 }
 
+/// A shortcut for the commonly used `Or<(Changed<Handle<T>>, AssetChanged<T>)>`
+/// query.
+///
+/// If you want to react to changes to `Handle<T>` component of an entity, you have
+/// two cases to worry about:
+/// - The `Handle<T>` was changed through a `Query<&mut Handle<T>>`.
+/// - The `T` in `Assets<T>` pointed by `Handle<T>` was changed through a
+///   `ResMut<Assets<T>>::get_mut`.
+///
+/// To properly handle both those cases, you need to combine the `Changed` and `AssetChanged`
+/// filters. This query type does it for you.
+pub type AssetOrHandleChanged<T> = Or<(Changed<Handle<T>>, AssetChanged<T>)>;
+
 /// Query filter to get all entities which `Handle<T>` component underlying asset changed.
+///
+/// Unlike `Changed<Handle<T>>`, this filter returns entities for which **the underlying `T`
+/// asset** was changed. For example, when modifying a `Mesh`, you would do so through the
+/// [`Assets<Mesh>::get_mut`] method. This does not change the `Handle<T>` that entities have
+/// as component, so `Changed<Handle<T>>` **will not do anything**. While with `AssetChanged<T>`,
+/// all entities with the modifyed mesh will be queried.
+///
+/// # Notes
+/// **performance**: this should be as fast as querying `Handle<T>` in case where no asset
+/// were changed, this may slow down quite a bit if more than 15 `Handle<T>` changed since last
+/// call of the system.
+///
+/// **frame delay**: The list of changed assets only gets updated during the
+/// [`AssetStage::AssetEvents`] stage. Which means asset changes are not immediately visible to
+/// this query. Therefore, asset change detection will have one frame of delay.
+///
+/// **incompatible system parameters**: this query filter reads the [`AssetChanges`] resource,
+/// therefore, it is an error to have both a `ResMut<AssetChanges>` and `AssetChanged` query
+/// filter on the same system.
+///
+/// Since oftentime, it is necessary to check for both handle and asset changes, the
+/// [`AssetOrHandleChanged`] query is provided for conviniance.
+///
+/// [`AssetStage::AssetEvents`]: crate::AssetStage::AssetEvents
+/// [`Assets<Mesh>::get_mut`]: crate::Assets::get_mut
 pub struct AssetChanged<T>(PhantomData<T>);
 
-/// Fetch for [`AssetChanged`]
+/// Fetch for [`AssetChanged`].
 #[doc(hidden)]
 pub struct AssetChangedFetch<'w, T: Asset> {
     inner: ReadFetch<'w, Handle<T>>,
     check: AssetChangeCheck<'w>,
 }
 
-/// State for [`AssetChanged`]
+/// State for [`AssetChanged`].
+#[doc(hidden)]
 pub struct AssetChangedState<T: Asset> {
     inner: ComponentIdState<Handle<T>>,
     asset_changed_id: ComponentId,