From 96a40288622f29209e659b0bcc913a0e0eb79359 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 13 Feb 2025 14:49:25 -0500 Subject: [PATCH] Improve clarity of existing bevy_assets documentation (#17830) # Objective While surveying the state of documentation for bevy_assets, I noticed a few minor issues. ## Solution Revise the docs to focus on clear explanations of core ideas and cross-linking related objects. --- crates/bevy_asset/src/assets.rs | 2 ++ crates/bevy_asset/src/direct_access_ext.rs | 1 + crates/bevy_asset/src/folder.rs | 2 ++ crates/bevy_asset/src/handle.rs | 11 +++++++++-- 4 files changed, 14 insertions(+), 2 deletions(-) diff --git a/crates/bevy_asset/src/assets.rs b/crates/bevy_asset/src/assets.rs index f16feebdc1..936664f631 100644 --- a/crates/bevy_asset/src/assets.rs +++ b/crates/bevy_asset/src/assets.rs @@ -280,6 +280,8 @@ impl DenseAssetStorage { /// 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 { dense_storage: DenseAssetStorage, diff --git a/crates/bevy_asset/src/direct_access_ext.rs b/crates/bevy_asset/src/direct_access_ext.rs index bfa7fa17b2..792d523a30 100644 --- a/crates/bevy_asset/src/direct_access_ext.rs +++ b/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(&mut self, asset: impl Into) -> Handle; diff --git a/crates/bevy_asset/src/folder.rs b/crates/bevy_asset/src/folder.rs index 698b19d0c2..cd0c5bc6b6 100644 --- a/crates/bevy_asset/src/folder.rs +++ b/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 { diff --git a/crates/bevy_asset/src/handle.rs b/crates/bevy_asset/src/handle.rs index 661e2fb5d9..825b4775dc 100644 --- a/crates/bevy_asset/src/handle.rs +++ b/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`](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 {