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:
parent
5ec59cf0b9
commit
96a4028862
@ -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>,
|
||||
|
@ -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>;
|
||||
|
@ -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 {
|
||||
|
@ -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> {
|
||||
|
Loading…
Reference in New Issue
Block a user