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.

Author: alice-i-cecile

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,15 +26,20 @@ 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>,
     },
     /// 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 { 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,26 +132,34 @@ 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>>
                 + Send
                 + 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>>
                 + Send
                 + 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>,
 }