Improve clarity of existing bevy_assets documentation

crates/bevy_asset/src/assets.rs

@@ -280,6 +280,8 @@ impl<A: Asset> DenseAssetStorage<A> {
 /// at compile time.
 ///
 /// This tracks (and queues) [`AssetEvent`] events whenever changes to the collection occur.
+/// To check whether the asset used by a given component has changed (due to a change in the handle or the underlying asset)
+/// use the [`AssetChanged`](crate::asset_changed::AssetChanged) query filter.
 #[derive(Resource)]
 pub struct Assets<A: Asset> {
     dense_storage: DenseAssetStorage<A>,

crates/bevy_asset/src/direct_access_ext.rs

@@ -5,6 +5,7 @@ use bevy_ecs::world::World;
 
 use crate::{meta::Settings, Asset, AssetPath, AssetServer, Assets, Handle};
 
+/// An extension trait for methods for working with assets directly from a [`World`].
 pub trait DirectAssetAccessExt {
     /// Insert an asset similarly to [`Assets::add`].
     fn add_asset<A: Asset>(&mut self, asset: impl Into<A>) -> Handle<A>;

crates/bevy_asset/src/folder.rs

@@ -5,6 +5,8 @@ use bevy_reflect::TypePath;
 
 /// A "loaded folder" containing handles for all assets stored in a given [`AssetPath`].
 ///
+/// This is produced by [`AssetServer::load_folder`](crate::prelude::AssetServer::load_folder).
+///
 /// [`AssetPath`]: crate::AssetPath
 #[derive(Asset, TypePath)]
 pub struct LoadedFolder {

crates/bevy_asset/src/handle.rs

@@ -113,14 +113,21 @@ impl core::fmt::Debug for StrongHandle {
     }
 }
 
-/// A strong or weak handle to a specific [`Asset`]. If a [`Handle`] is [`Handle::Strong`], the [`Asset`] will be kept
+/// A handle to a specific [`Asset`] of type `A`. Handles act as abstract "references" to
+/// assets, whose data are stored in the [`Assets<A>`](crate::prelude::Assets) resource,
+/// avoiding the need to store multiple copies of the same data.
+///
+/// If a [`Handle`] is [`Handle::Strong`], the [`Asset`] will be kept
 /// alive until the [`Handle`] is dropped. If a [`Handle`] is [`Handle::Weak`], it does not necessarily reference a live [`Asset`],
 /// nor will it keep assets alive.
 ///
+/// Modifying a *handle* will change which existing asset is referenced, but modifying the *asset*
+/// (by mutating the [`Assets`](crate::prelude::Assets) resource) will change the asset for all handles referencing it.
+///
 /// [`Handle`] can be cloned. If a [`Handle::Strong`] is cloned, the referenced [`Asset`] will not be freed until _all_ instances
 /// of the [`Handle`] are dropped.
 ///
-/// [`Handle::Strong`] also provides access to useful [`Asset`] metadata, such as the [`AssetPath`] (if it exists).
+/// [`Handle::Strong`], via [`StrongHandle`] also provides access to useful [`Asset`] metadata, such as the [`AssetPath`] (if it exists).
 #[derive(Reflect)]
 #[reflect(Default, Debug, Hash, PartialEq)]
 pub enum Handle<A: Asset> {