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

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

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<A: Asset> {
+    /// The stable identifier of the asset that failed to load.
     pub id: AssetId<A>,
     /// The asset path that was attempted.
     pub path: AssetPath<'static>,
@@ -25,6 +26,7 @@ impl<A: Asset> AssetLoadFailedEvent<A> {
 /// 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<A: Asset> From<&AssetLoadFailedEvent<A>> 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<A: Asset> {
     /// Emitted whenever an [`Asset`] is added.

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<UntypedHandle>,
 }

crates/bevy_asset/src/handle.rs

@@ -291,7 +291,9 @@ impl<A: Asset> From<&mut Handle<A>> 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<StrongHandle>),
+    /// 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)]

crates/bevy_asset/src/id.rs

@@ -26,7 +26,9 @@ pub enum AssetId<A: Asset> {
     ///
     /// [`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<fn() -> A>,
     },
@@ -34,7 +36,10 @@ pub enum AssetId<A: Asset> {
     /// with one.
     ///
     /// [`Assets`]: crate::Assets
-    Uuid { uuid: Uuid },
+    Uuid {
+        /// The UUID provided during asset registration.
+        uuid: Uuid,
+    },
 }
 
 impl<A: Asset> AssetId<A> {
@@ -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<A: Asset> TryFrom<UntypedAssetId> for AssetId<A> {
 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)]

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<RwLock<HashMap<Box<Path>, PathBuf>>>,

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();

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

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<P: AsRef<Path> + core::fmt::Debug>(path: P, create_root: bool) -> Self {
         let root_path = get_base_path().join(path.as_ref());
         if create_root {

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<dyn FnMut() -> Box<dyn ErasedAssetReader> + Send + Sync>>,
+    /// The [`ErasedAssetWriter`] to use on the unprocessed asset.
     pub writer: Option<Box<dyn FnMut(bool) -> Option<Box<dyn ErasedAssetWriter>> + Send + Sync>>,
+    /// The [`AssetWatcher`] to use for unprocessed assets, if any.
     pub watcher: Option<
         Box<
             dyn FnMut(crossbeam_channel::Sender<AssetSourceEvent>) -> Option<Box<dyn AssetWatcher>>
@@ -141,9 +144,12 @@ pub struct AssetSourceBuilder {
                 + Sync,
         >,
     >,
+    /// The [`ErasedAssetReader`] to use for processed assets.
     pub processed_reader: Option<Box<dyn FnMut() -> Box<dyn ErasedAssetReader> + Send + Sync>>,
+    /// The [`ErasedAssetWriter`] to use for processed assets.
     pub processed_writer:
         Option<Box<dyn FnMut(bool) -> Option<Box<dyn ErasedAssetWriter>> + Send + Sync>>,
+    /// The [`AssetWatcher`] to use for processed assets, if any.
     pub processed_watcher: Option<
         Box<
             dyn FnMut(crossbeam_channel::Sender<AssetSourceEvent>) -> Option<Box<dyn AssetWatcher>>
@@ -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>,
 }
 

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<LogEntryError>),
 }
@@ -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>),
 }

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

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<AssetLoadError>),
+    /// A dependency of the asset failed to load.
     #[error(transparent)]
     DependencyFailed(Arc<AssetLoadError>),
 }

crates/bevy_asset/src/transformer.rs

@@ -153,6 +153,7 @@ pub struct IdentityAssetTransformer<A: Asset> {
 }
 
 impl<A: Asset> IdentityAssetTransformer<A> {
+    /// Creates a new [`IdentityAssetTransformer`] with the correct internal [`PhantomData`] field.
     pub const fn new() -> Self {
         Self {
             _phantom: PhantomData,