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.
This commit is contained in:
Alice Cecile 2025-02-13 14:49:25 -05:00 committed by GitHub
parent 5ec59cf0b9
commit 96a4028862
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 14 additions and 2 deletions

View File

@ -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>,

View File

@ -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>;

View File

@ -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 {

View File

@ -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> {