From 0f1c75796b75ce518ae465d8f733c17f852de3a6 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 13 Feb 2025 16:08:09 -0500 Subject: [PATCH] Fill out some missing docs for bevy_assets (#17829) # Objective `bevy_assets` has long been unapproachable for contributors and users. More and better documentation would help that. We're gradually moving towards globally denying missing docs (#3492)! However, writing all of the hundreds of missing doc strings in a single go will be miserable to review. ## Solution Remove the allow for missing docs temporarily, and then pick some easy missing doc warnings largely at random to tackle. Stop when the change set is starting to feel intimidating. --- crates/bevy_asset/src/assets.rs | 2 ++ crates/bevy_asset/src/event.rs | 3 ++ crates/bevy_asset/src/folder.rs | 1 + crates/bevy_asset/src/handle.rs | 9 +++++- crates/bevy_asset/src/id.rs | 28 ++++++++++++++++--- .../src/io/embedded/embedded_watcher.rs | 1 + crates/bevy_asset/src/io/embedded/mod.rs | 3 ++ crates/bevy_asset/src/io/file/file_watcher.rs | 5 +++- crates/bevy_asset/src/io/file/mod.rs | 5 ++-- crates/bevy_asset/src/io/source.rs | 8 ++++++ crates/bevy_asset/src/processor/log.rs | 8 ++++++ crates/bevy_asset/src/render_asset.rs | 2 ++ crates/bevy_asset/src/server/mod.rs | 14 +++++++++- crates/bevy_asset/src/transformer.rs | 1 + 14 files changed, 80 insertions(+), 10 deletions(-) diff --git a/crates/bevy_asset/src/assets.rs b/crates/bevy_asset/src/assets.rs index 936664f631..ebc9a0f588 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, } @@ -631,6 +632,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 832cc212d4..087cb44b5a 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 cd0c5bc6b6..c591c88688 100644 --- a/crates/bevy_asset/src/folder.rs +++ b/crates/bevy_asset/src/folder.rs @@ -10,6 +10,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 825b4775dc..f2401c951b 100644 --- a/crates/bevy_asset/src/handle.rs +++ b/crates/bevy_asset/src/handle.rs @@ -291,7 +291,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), } @@ -535,7 +537,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 a1fe13615e..4caf546163 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 25dd55ff48..89ac9b3826 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 cba775aaa6..fce5149462 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 c8700dcdd5..64d3e711c9 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 719b424e6d..96c43072e8 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 37bdc306b7..58c5006a80 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 533a87d830..aefc3a96c6 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 3bbc3dfd48..5dac114c7f 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 07c9eed9b4..e65bbd2b6a 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 77daa7423c..d2573582f1 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,