diff --git a/crates/bevy_asset/src/assets.rs b/crates/bevy_asset/src/assets.rs index f16feebdc1856..c137cb7539e97 100644 --- a/crates/bevy_asset/src/assets.rs +++ b/crates/bevy_asset/src/assets.rs @@ -95,6 +95,7 @@ impl AssetIndexAllocator { /// [`AssetPath`]: crate::AssetPath #[derive(Asset, TypePath)] pub struct LoadedUntypedAsset { + /// The handle to the loaded asset. #[dependency] pub handle: UntypedHandle, } @@ -629,6 +630,7 @@ impl<'a, A: Asset> Iterator for AssetsMutIterator<'a, A> { } } +/// An error returned when an [`AssetIndex`] has an invalid generation. #[derive(Error, Debug)] #[error("AssetIndex {index:?} has an invalid generation. The current generation is: '{current_generation}'.")] pub struct InvalidGenerationError { diff --git a/crates/bevy_asset/src/event.rs b/crates/bevy_asset/src/event.rs index 832cc212d4b01..087cb44b5a138 100644 --- a/crates/bevy_asset/src/event.rs +++ b/crates/bevy_asset/src/event.rs @@ -8,6 +8,7 @@ use core::fmt::Debug; /// For an untyped equivalent, see [`UntypedAssetLoadFailedEvent`]. #[derive(Event, Clone, Debug)] pub struct AssetLoadFailedEvent { + /// The stable identifier of the asset that failed to load. pub id: AssetId, /// The asset path that was attempted. pub path: AssetPath<'static>, @@ -25,6 +26,7 @@ impl AssetLoadFailedEvent { /// An untyped version of [`AssetLoadFailedEvent`]. #[derive(Event, Clone, Debug)] pub struct UntypedAssetLoadFailedEvent { + /// The stable identifier of the asset that failed to load. pub id: UntypedAssetId, /// The asset path that was attempted. pub path: AssetPath<'static>, @@ -43,6 +45,7 @@ impl From<&AssetLoadFailedEvent> for UntypedAssetLoadFailedEvent { } /// Events that occur for a specific loaded [`Asset`], such as "value changed" events and "dependency" events. +#[expect(missing_docs, reason = "Documenting the id fields is unhelpful.")] #[derive(Event, Reflect)] pub enum AssetEvent { /// Emitted whenever an [`Asset`] is added. diff --git a/crates/bevy_asset/src/folder.rs b/crates/bevy_asset/src/folder.rs index 698b19d0c257f..a6503cc6754d7 100644 --- a/crates/bevy_asset/src/folder.rs +++ b/crates/bevy_asset/src/folder.rs @@ -8,6 +8,7 @@ use bevy_reflect::TypePath; /// [`AssetPath`]: crate::AssetPath #[derive(Asset, TypePath)] pub struct LoadedFolder { + /// The handles of all assets stored in the folder. #[dependency] pub handles: Vec, } diff --git a/crates/bevy_asset/src/handle.rs b/crates/bevy_asset/src/handle.rs index 661e2fb5d9d25..d9663f26cae4a 100644 --- a/crates/bevy_asset/src/handle.rs +++ b/crates/bevy_asset/src/handle.rs @@ -284,7 +284,9 @@ impl From<&mut Handle> for UntypedAssetId { /// See [`Handle`] for more information. #[derive(Clone)] pub enum UntypedHandle { + /// A strong handle, which will keep the referenced [`Asset`] alive until all strong handles are dropped. Strong(Arc), + /// A weak handle, which does not keep the referenced [`Asset`] alive. Weak(UntypedAssetId), } @@ -528,7 +530,12 @@ pub enum UntypedAssetConversionError { #[error( "This UntypedHandle is for {found:?} and cannot be converted into a Handle<{expected:?}>" )] - TypeIdMismatch { expected: TypeId, found: TypeId }, + TypeIdMismatch { + /// The expected [`TypeId`] of the [`Handle`] being converted to. + expected: TypeId, + /// The [`TypeId`] of the [`UntypedHandle`] being converted from. + found: TypeId, + }, } #[cfg(test)] diff --git a/crates/bevy_asset/src/id.rs b/crates/bevy_asset/src/id.rs index a1fe13615ee8b..4caf546163a75 100644 --- a/crates/bevy_asset/src/id.rs +++ b/crates/bevy_asset/src/id.rs @@ -26,7 +26,9 @@ pub enum AssetId { /// /// [`Assets`]: crate::Assets Index { + /// The unstable, opaque index of the asset. index: AssetIndex, + /// A marker to store the type information of the asset. #[reflect(ignore)] marker: PhantomData A>, }, @@ -34,7 +36,10 @@ pub enum AssetId { /// with one. /// /// [`Assets`]: crate::Assets - Uuid { uuid: Uuid }, + Uuid { + /// The UUID provided during asset registration. + uuid: Uuid, + }, } impl AssetId { @@ -165,12 +170,22 @@ pub enum UntypedAssetId { /// explicitly registered that way. /// /// [`Assets`]: crate::Assets - Index { type_id: TypeId, index: AssetIndex }, + Index { + /// An identifier that records the underlying asset type. + type_id: TypeId, + /// The unstable, opaque index of the asset. + index: AssetIndex, + }, /// A stable-across-runs / const asset identifier. This will only be used if an asset is explicitly registered in [`Assets`] /// with one. /// /// [`Assets`]: crate::Assets - Uuid { type_id: TypeId, uuid: Uuid }, + Uuid { + /// An identifier that records the underlying asset type. + type_id: TypeId, + /// The UUID provided during asset registration. + uuid: Uuid, + }, } impl UntypedAssetId { @@ -404,7 +419,12 @@ impl TryFrom for AssetId { pub enum UntypedAssetIdConversionError { /// Caused when trying to convert an [`UntypedAssetId`] into an [`AssetId`] of the wrong type. #[error("This UntypedAssetId is for {found:?} and cannot be converted into an AssetId<{expected:?}>")] - TypeIdMismatch { expected: TypeId, found: TypeId }, + TypeIdMismatch { + /// The [`TypeId`] of the asset that we are trying to convert to. + expected: TypeId, + /// The [`TypeId`] of the asset that we are trying to convert from. + found: TypeId, + }, } #[cfg(test)] diff --git a/crates/bevy_asset/src/io/embedded/embedded_watcher.rs b/crates/bevy_asset/src/io/embedded/embedded_watcher.rs index 25dd55ff48c8d..89ac9b3826a8f 100644 --- a/crates/bevy_asset/src/io/embedded/embedded_watcher.rs +++ b/crates/bevy_asset/src/io/embedded/embedded_watcher.rs @@ -24,6 +24,7 @@ pub struct EmbeddedWatcher { } impl EmbeddedWatcher { + /// Creates a new `EmbeddedWatcher` that watches for changes to the embedded assets in the given `dir`. pub fn new( dir: Dir, root_paths: Arc, PathBuf>>>, diff --git a/crates/bevy_asset/src/io/embedded/mod.rs b/crates/bevy_asset/src/io/embedded/mod.rs index cba775aaa6ddf..fce5149462247 100644 --- a/crates/bevy_asset/src/io/embedded/mod.rs +++ b/crates/bevy_asset/src/io/embedded/mod.rs @@ -15,6 +15,8 @@ use std::path::{Path, PathBuf}; #[cfg(feature = "embedded_watcher")] use alloc::borrow::ToOwned; +/// The name of the `embedded` [`AssetSource`], +/// as stored in the [`AssetSourceBuilders`] resource. pub const EMBEDDED: &str = "embedded"; /// A [`Resource`] that manages "rust source files" in a virtual in memory [`Dir`], which is intended @@ -77,6 +79,7 @@ impl EmbeddedAssetRegistry { self.dir.remove_asset(full_path) } + /// Registers the [`EMBEDDED`] [`AssetSource`] with the given [`AssetSourceBuilders`]. pub fn register_source(&self, sources: &mut AssetSourceBuilders) { let dir = self.dir.clone(); let processed_dir = self.dir.clone(); diff --git a/crates/bevy_asset/src/io/file/file_watcher.rs b/crates/bevy_asset/src/io/file/file_watcher.rs index c8700dcdd5941..64d3e711c975a 100644 --- a/crates/bevy_asset/src/io/file/file_watcher.rs +++ b/crates/bevy_asset/src/io/file/file_watcher.rs @@ -18,7 +18,9 @@ use std::path::{Path, PathBuf}; use tracing::error; /// An [`AssetWatcher`] that watches the filesystem for changes to asset files in a given root folder and emits [`AssetSourceEvent`] -/// for each relevant change. This uses [`notify_debouncer_full`] to retrieve "debounced" filesystem events. +/// for each relevant change. +/// +/// This uses [`notify_debouncer_full`] to retrieve "debounced" filesystem events. /// "Debouncing" defines a time window to hold on to events and then removes duplicate events that fall into this window. /// This introduces a small delay in processing events, but it helps reduce event duplicates. A small delay is also necessary /// on some systems to avoid processing a change event before it has actually been applied. @@ -27,6 +29,7 @@ pub struct FileWatcher { } impl FileWatcher { + /// Creates a new [`FileWatcher`] that watches for changes to the asset files in the given `path`. pub fn new( path: PathBuf, sender: Sender, diff --git a/crates/bevy_asset/src/io/file/mod.rs b/crates/bevy_asset/src/io/file/mod.rs index 719b424e6da78..96c43072e8f47 100644 --- a/crates/bevy_asset/src/io/file/mod.rs +++ b/crates/bevy_asset/src/io/file/mod.rs @@ -65,15 +65,14 @@ impl FileAssetReader { } } +/// A writer for the local filesystem. pub struct FileAssetWriter { root_path: PathBuf, } impl FileAssetWriter { - /// Creates a new `FileAssetIo` at a path relative to the executable's directory, optionally + /// Creates a new [`FileAssetWriter`] at a path relative to the executable's directory, optionally /// watching for changes. - /// - /// See `get_base_path` below. pub fn new + core::fmt::Debug>(path: P, create_root: bool) -> Self { let root_path = get_base_path().join(path.as_ref()); if create_root { diff --git a/crates/bevy_asset/src/io/source.rs b/crates/bevy_asset/src/io/source.rs index 37bdc306b7cc0..58c5006a8047e 100644 --- a/crates/bevy_asset/src/io/source.rs +++ b/crates/bevy_asset/src/io/source.rs @@ -132,8 +132,11 @@ impl<'a> PartialEq for AssetSourceId<'a> { /// and whether or not the source is processed. #[derive(Default)] pub struct AssetSourceBuilder { + /// The [`ErasedAssetReader`] to use on the unprocessed asset. pub reader: Option Box + Send + Sync>>, + /// The [`ErasedAssetWriter`] to use on the unprocessed asset. pub writer: Option Option> + Send + Sync>>, + /// The [`AssetWatcher`] to use for unprocessed assets, if any. pub watcher: Option< Box< dyn FnMut(crossbeam_channel::Sender) -> Option> @@ -141,9 +144,12 @@ pub struct AssetSourceBuilder { + Sync, >, >, + /// The [`ErasedAssetReader`] to use for processed assets. pub processed_reader: Option Box + Send + Sync>>, + /// The [`ErasedAssetWriter`] to use for processed assets. pub processed_writer: Option Option> + Send + Sync>>, + /// The [`AssetWatcher`] to use for processed assets, if any. pub processed_watcher: Option< Box< dyn FnMut(crossbeam_channel::Sender) -> Option> @@ -151,7 +157,9 @@ pub struct AssetSourceBuilder { + Sync, >, >, + /// The warning message to display when watching an unprocessed asset fails. pub watch_warning: Option<&'static str>, + /// The warning message to display when watching a processed asset fails. pub processed_watch_warning: Option<&'static str>, } diff --git a/crates/bevy_asset/src/processor/log.rs b/crates/bevy_asset/src/processor/log.rs index 533a87d830a04..aefc3a96c631e 100644 --- a/crates/bevy_asset/src/processor/log.rs +++ b/crates/bevy_asset/src/processor/log.rs @@ -32,8 +32,10 @@ pub struct ProcessorTransactionLog { /// An error that occurs when reading from the [`ProcessorTransactionLog`] fails. #[derive(Error, Debug)] pub enum ReadLogError { + /// An invalid log line was encountered, consisting of the contained string. #[error("Encountered an invalid log line: '{0}'")] InvalidLine(String), + /// A file-system-based error occurred while reading the log file. #[error("Failed to read log file: {0}")] Io(#[from] futures_io::Error), } @@ -51,10 +53,13 @@ pub struct WriteLogError { /// An error that occurs when validating the [`ProcessorTransactionLog`] fails. #[derive(Error, Debug)] pub enum ValidateLogError { + /// An error that could not be recovered from. All assets will be reprocessed. #[error("Encountered an unrecoverable error. All assets will be reprocessed.")] UnrecoverableError, + /// A [`ReadLogError`]. #[error(transparent)] ReadLogError(#[from] ReadLogError), + /// Duplicated process asset transactions occurred. #[error("Encountered a duplicate process asset transaction: {0:?}")] EntryErrors(Vec), } @@ -62,10 +67,13 @@ pub enum ValidateLogError { /// An error that occurs when validating individual [`ProcessorTransactionLog`] entries. #[derive(Error, Debug)] pub enum LogEntryError { + /// A duplicate process asset transaction occurred for the given asset path. #[error("Encountered a duplicate process asset transaction: {0}")] DuplicateTransaction(AssetPath<'static>), + /// A transaction was ended that never started for the given asset path. #[error("A transaction was ended that never started {0}")] EndedMissingTransaction(AssetPath<'static>), + /// An asset started processing but never finished at the given asset path. #[error("An asset started processing but never finished: {0}")] UnfinishedTransaction(AssetPath<'static>), } diff --git a/crates/bevy_asset/src/render_asset.rs b/crates/bevy_asset/src/render_asset.rs index 3bbc3dfd48458..5dac114c7f2ca 100644 --- a/crates/bevy_asset/src/render_asset.rs +++ b/crates/bevy_asset/src/render_asset.rs @@ -29,7 +29,9 @@ bitflags::bitflags! { #[reflect(opaque)] #[reflect(Serialize, Deserialize, Hash, PartialEq, Debug)] pub struct RenderAssetUsages: u8 { + /// The bit flag for the main world. const MAIN_WORLD = 1 << 0; + /// The bit flag for the render world. const RENDER_WORLD = 1 << 1; } } diff --git a/crates/bevy_asset/src/server/mod.rs b/crates/bevy_asset/src/server/mod.rs index 07c9eed9b45b3..e65bbd2b6acb7 100644 --- a/crates/bevy_asset/src/server/mod.rs +++ b/crates/bevy_asset/src/server/mod.rs @@ -1737,6 +1737,10 @@ impl RecursiveDependencyLoadState { /// An error that occurs during an [`Asset`] load. #[derive(Error, Debug, Clone)] +#[expect( + missing_docs, + reason = "Adding docs to the variants would not add information beyond the error message and the names" +)] pub enum AssetLoadError { #[error("Requested handle of type {requested:?} for asset '{path}' does not match actual asset type '{actual_asset_name}', which used loader '{loader_name}'")] RequestedHandleTypeMismatch { @@ -1798,6 +1802,7 @@ pub enum AssetLoadError { }, } +/// An error that can occur during asset loading. #[derive(Error, Debug, Clone)] #[error("Failed to load asset '{path}' with asset loader '{loader_name}': {error}")] pub struct AssetLoaderError { @@ -1807,11 +1812,13 @@ pub struct AssetLoaderError { } impl AssetLoaderError { + /// The path of the asset that failed to load. pub fn path(&self) -> &AssetPath<'static> { &self.path } } +/// An error that occurs while resolving an asset added by `add_async`. #[derive(Error, Debug, Clone)] #[error("An error occurred while resolving an asset added by `add_async`: {error}")] pub struct AddAsyncError { @@ -1829,13 +1836,15 @@ pub struct MissingAssetLoaderForExtensionError { #[derive(Error, Debug, Clone, PartialEq, Eq)] #[error("no `AssetLoader` found with the name '{type_name}'")] pub struct MissingAssetLoaderForTypeNameError { - type_name: String, + /// The type name that was not found. + pub type_name: String, } /// An error that occurs when an [`AssetLoader`] is not registered for a given [`Asset`] [`TypeId`]. #[derive(Error, Debug, Clone, PartialEq, Eq)] #[error("no `AssetLoader` found with the ID '{type_id:?}'")] pub struct MissingAssetLoaderForTypeIdError { + /// The type ID that was not found. pub type_id: TypeId, } @@ -1866,10 +1875,13 @@ const UNTYPED_SOURCE_SUFFIX: &str = "--untyped"; /// An error when attempting to wait asynchronously for an [`Asset`] to load. #[derive(Error, Debug, Clone)] pub enum WaitForAssetError { + /// The asset is not being loaded; waiting for it is meaningless. #[error("tried to wait for an asset that is not being loaded")] NotLoaded, + /// The asset failed to load. #[error(transparent)] Failed(Arc), + /// A dependency of the asset failed to load. #[error(transparent)] DependencyFailed(Arc), } diff --git a/crates/bevy_asset/src/transformer.rs b/crates/bevy_asset/src/transformer.rs index 77daa7423c615..d2573582f16f0 100644 --- a/crates/bevy_asset/src/transformer.rs +++ b/crates/bevy_asset/src/transformer.rs @@ -153,6 +153,7 @@ pub struct IdentityAssetTransformer { } impl IdentityAssetTransformer { + /// Creates a new [`IdentityAssetTransformer`] with the correct internal [`PhantomData`] field. pub const fn new() -> Self { Self { _phantom: PhantomData,