Document root, handle, info and path

crates/bevy_asset/src/handle.rs

@@ -15,7 +15,7 @@ use bevy_utils::Uuid;
 use crossbeam_channel::{Receiver, Sender};
 use serde::{Deserialize, Serialize};
 
-/// A unique, stable asset id
+/// An unique, stable asset id.
 #[derive(
     Debug,
     Clone,
@@ -32,7 +32,9 @@ use serde::{Deserialize, Serialize};
 )]
 #[reflect_value(Serialize, Deserialize, PartialEq, Hash)]
 pub enum HandleId {
+    /// A handle id of a loaded asset.
     Id(Uuid, u64),
+    /// A handle id of a pending asset.
     AssetPathId(AssetPathId),
 }
 
@@ -49,25 +51,28 @@ impl<'a> From<AssetPath<'a>> for HandleId {
 }
 
 impl HandleId {
+    /// Creates a random id for an Asset of type `T`.
     #[inline]
     pub fn random<T: Asset>() -> Self {
         HandleId::Id(T::TYPE_UUID, rand::random())
     }
 
+    /// Creates the default id for an Asset of type `T`.
     #[inline]
     pub fn default<T: Asset>() -> Self {
         HandleId::Id(T::TYPE_UUID, 0)
     }
 
+    /// Creates an arbitrary asset id without an explicit type bound.
     #[inline]
     pub const fn new(type_uuid: Uuid, id: u64) -> Self {
         HandleId::Id(type_uuid, id)
     }
 }
 
-/// A handle into a specific Asset of type `T`
+/// A handle into a specific Asset of type `T`.
 ///
-/// Handles contain a unique id that corresponds to a specific asset in the [Assets](crate::Assets)
+/// Handles contain an unique id that corresponds to a specific asset in the [Assets](crate::Assets)
 /// collection.
 ///
 /// # Accessing the Asset
@@ -140,6 +145,7 @@ impl<T: Asset> Handle<T> {
         }
     }
 
+    /// Creates a weak handle into an Asset identified by `id`.
     #[inline]
     pub fn weak(id: HandleId) -> Self {
         Self {
@@ -149,7 +155,7 @@ impl<T: Asset> Handle<T> {
         }
     }
 
-    /// Get a copy of this handle as a Weak handle
+    /// Recasts this handle as a weak handle of an Asset `U`.
     pub fn as_weak<U: Asset>(&self) -> Handle<U> {
         Handle {
             id: self.id,
@@ -158,10 +164,12 @@ impl<T: Asset> Handle<T> {
         }
     }
 
+    /// Returns `true` if this is a weak handle.
     pub fn is_weak(&self) -> bool {
         matches!(self.handle_type, HandleType::Weak)
     }
 
+    /// Returns `true` if this is a strong handle.
     pub fn is_strong(&self) -> bool {
         matches!(self.handle_type, HandleType::Strong(_))
     }
@@ -178,18 +186,21 @@ impl<T: Asset> Handle<T> {
         self.handle_type = HandleType::Strong(sender);
     }
 
+    /// Creates a weak copy of this handle.
     #[inline]
     pub fn clone_weak(&self) -> Self {
         Handle::weak(self.id)
     }
 
+    /// Creates an untyped copy of this handle.
     pub fn clone_untyped(&self) -> HandleUntyped {
         match &self.handle_type {
             HandleType::Strong(sender) => HandleUntyped::strong(self.id, sender.clone()),
             HandleType::Weak => HandleUntyped::weak(self.id),
         }
     }
 
+    /// Creates a weak, untyped copy of this handle.
     pub fn clone_weak_untyped(&self) -> HandleUntyped {
         HandleUntyped::weak(self.id)
     }
@@ -292,19 +303,21 @@ impl<T: Asset> Clone for Handle<T> {
     }
 }
 
-/// A non-generic version of [Handle]
+/// A non-generic version of [`Handle`].
 ///
 /// This allows handles to be mingled in a cross asset context. For example, storing `Handle<A>` and
 /// `Handle<B>` in the same `HashSet<HandleUntyped>`.
 ///
 /// To convert back to a typed handle, use the [typed](HandleUntyped::typed) method.
 #[derive(Debug)]
 pub struct HandleUntyped {
+    /// An unique identifier to an Asset.
     pub id: HandleId,
     handle_type: HandleType,
 }
 
 impl HandleUntyped {
+    /// Creates a weak untyped handle with an arbitrary id.
     pub const fn weak_from_u64(uuid: Uuid, id: u64) -> Self {
         Self {
             id: HandleId::new(uuid, id),
@@ -320,28 +333,36 @@ impl HandleUntyped {
         }
     }
 
+    /// Create a weak untyped into an Asset identified by `id`.
     pub fn weak(id: HandleId) -> Self {
         Self {
             id,
             handle_type: HandleType::Weak,
         }
     }
 
+    /// Creates a weak copy of this handle.
     pub fn clone_weak(&self) -> HandleUntyped {
         HandleUntyped::weak(self.id)
     }
 
+    /// Returns `true` if this a weak handle.
     pub fn is_weak(&self) -> bool {
         matches!(self.handle_type, HandleType::Weak)
     }
 
+    /// Returns `true` if this is a strong handle.
     pub fn is_strong(&self) -> bool {
         matches!(self.handle_type, HandleType::Strong(_))
     }
 
-    /// Convert this handle into a typed [Handle].
+    /// Converts this handle into a typed [`Handle`] of an Asset `T`.
     ///
     /// The new handle will maintain the Strong or Weak status of the current handle.
+    ///
+    /// # Panics
+    ///
+    /// Will panic if type `T` doesn't match this handle's actual asset type.
     pub fn typed<T: Asset>(mut self) -> Handle<T> {
         if let HandleId::Id(type_uuid, _) = self.id {
             if T::TYPE_UUID != type_uuid {

crates/bevy_asset/src/info.rs

@@ -3,42 +3,56 @@ use bevy_utils::{HashMap, HashSet, Uuid};
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 
+/// Metadata for an asset source.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct SourceMeta {
+    /// A collection of asset metadata.
     pub assets: Vec<AssetMeta>,
 }
 
+/// Metadata for an asset.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct AssetMeta {
+    /// Asset label.
     pub label: Option<String>,
+    /// Asset dependencies.
     pub dependencies: Vec<AssetPath<'static>>,
+    /// An unique identifier for an asset type.
     pub type_uuid: Uuid,
 }
 
-/// Info about a specific asset, such as its path and its current load state
+/// Information about an asset source, such as its path, load state and asset metadata.
 #[derive(Clone, Debug)]
 pub struct SourceInfo {
+    /// Metadata for the source.
     pub meta: Option<SourceMeta>,
+    /// The path of the source.
     pub path: PathBuf,
+    /// A map of assets and their type identifiers.
     pub asset_types: HashMap<LabelId, Uuid>,
+    /// The load state of the source.
     pub load_state: LoadState,
+    /// A collection to track which assets were sent to their asset storages.
     pub committed_assets: HashSet<LabelId>,
+    /// Current versison of the source.
     pub version: usize,
 }
 
 impl SourceInfo {
+    /// Returns `true` if all assets tracked by the source were loaded into their asset storages.
     pub fn is_loaded(&self) -> bool {
         self.meta.as_ref().map_or(false, |meta| {
             self.committed_assets.len() == meta.assets.len()
         })
     }
 
+    /// Gets the type identifier for an asset identified by `label_id`.
     pub fn get_asset_type(&self, label_id: LabelId) -> Option<Uuid> {
         self.asset_types.get(&label_id).cloned()
     }
 }
 
-/// The load state of an asset
+/// The load state of an asset.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
 pub enum LoadState {
     /// The asset has not be loaded.

crates/bevy_asset/src/lib.rs

@@ -12,6 +12,7 @@ mod io;
 mod loader;
 mod path;
 
+/// The `bevy_asset` prelude.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{AddAsset, AssetEvent, AssetServer, Assets, Handle, HandleUntyped};
@@ -37,12 +38,16 @@ pub enum AssetStage {
     AssetEvents,
 }
 
-/// Adds support for Assets to an App. Assets are typed collections with change tracking, which are
-/// added as App Resources. Examples of assets: textures, sounds, 3d models, maps, scenes
+/// Adds support for Assets to an App.
+///
+/// Assets are typed collections with change tracking, which are added as App Resources. Examples of
+/// assets: textures, sounds, 3d models, maps, scenes
 #[derive(Default)]
 pub struct AssetPlugin;
 
+/// `AssetPlugin` settings
 pub struct AssetServerSettings {
+    /// The base folder where assets are loaded from, relative to the executable.
     pub asset_folder: String,
 }
 
@@ -54,7 +59,7 @@ impl Default for AssetServerSettings {
     }
 }
 
-/// Create an instance of the platform default `AssetIo`
+/// Creates an instance of the platform's default `AssetIo`.
 ///
 /// This is useful when providing a custom `AssetIo` instance that needs to
 /// delegate to the default `AssetIo` for the platform.

crates/bevy_asset/src/path.rs

@@ -7,13 +7,15 @@ use std::{
     path::{Path, PathBuf},
 };
 
+/// Represents a path ti an asset in the file system.
 #[derive(Debug, Hash, Clone, Serialize, Deserialize)]
 pub struct AssetPath<'a> {
     path: Cow<'a, Path>,
     label: Option<Cow<'a, str>>,
 }
 
 impl<'a> AssetPath<'a> {
+    /// Creates a new asset path using borrowed information.
     #[inline]
     pub fn new_ref(path: &'a Path, label: Option<&'a str>) -> AssetPath<'a> {
         AssetPath {
@@ -22,6 +24,7 @@ impl<'a> AssetPath<'a> {
         }
     }
 
+    /// Creates a new asset path.
     #[inline]
     pub fn new(path: PathBuf, label: Option<String>) -> AssetPath<'a> {
         AssetPath {
@@ -30,21 +33,25 @@ impl<'a> AssetPath<'a> {
         }
     }
 
+    /// Constructs an identifier from this asset path.
     #[inline]
     pub fn get_id(&self) -> AssetPathId {
         AssetPathId::from(self)
     }
 
+    /// Gets the sub-asset label.
     #[inline]
     pub fn label(&self) -> Option<&str> {
         self.label.as_ref().map(|label| label.as_ref())
     }
 
+    /// Gets the path to the asset in the filesystem.
     #[inline]
     pub fn path(&self) -> &Path {
         &self.path
     }
 
+    /// Converts the borrowed path data to owned.
     #[inline]
     pub fn to_owned(&self) -> AssetPath<'static> {
         AssetPath {
@@ -57,18 +64,21 @@ impl<'a> AssetPath<'a> {
     }
 }
 
+/// An unique identifier to an asset path.
 #[derive(
     Debug, Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd, Serialize, Deserialize, Reflect,
 )]
 #[reflect_value(PartialEq, Hash, Serialize, Deserialize)]
 pub struct AssetPathId(SourcePathId, LabelId);
 
+/// An unique identifier to the source path of an asset.
 #[derive(
     Debug, Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd, Serialize, Deserialize, Reflect,
 )]
 #[reflect_value(PartialEq, Hash, Serialize, Deserialize)]
 pub struct SourcePathId(u64);
 
+/// An unique identifier to a sub-asset label.
 #[derive(
     Debug, Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd, Serialize, Deserialize, Reflect,
 )]
@@ -104,10 +114,12 @@ impl<'a> From<Option<&'a str>> for LabelId {
 }
 
 impl AssetPathId {
+    /// Gets the id of the source path.
     pub fn source_path_id(&self) -> SourcePathId {
         self.0
     }
 
+    /// Gets the id of the sub-asset label.
     pub fn label_id(&self) -> LabelId {
         self.1
     }