Doc AssetServer::load() is async (#3129)

# Objective

Document that `AssetServer::load()` is asynchronous.

## Solution

Document that `AssetServer::load()` is asynchronous, and that the asset
will not be immediately available once the call returns. Instead,
explain that the user must call `AssetServer::get_load_state()` to
monitor the loading state of an asset.
This commit is contained in:
Jerome Humbert 2021-11-13 22:07:19 +00:00
parent ac06ea3d17
commit 94f5d194f4

View file

@ -213,7 +213,7 @@ impl AssetServer {
load_state
}
/// Loads an Asset at the provided relative path.
/// Queue an [`Asset`] at the provided relative path for asynchronous loading.
///
/// The absolute Path to the asset is "ROOT/ASSET_FOLDER_NAME/path".
///
@ -226,6 +226,10 @@ impl AssetServer {
/// The name of the asset folder is set inside the
/// [`AssetServerSettings`](crate::AssetServerSettings) resource. The default name is
/// `"assets"`.
///
/// The asset is loaded asynchronously, and will generally not be available by the time
/// this calls returns. Use [`AssetServer::get_load_state`] to determine when the asset is
/// effectively loaded and available in the [`Assets`] collection.
#[must_use = "not using the returned strong handle may result in the unexpected release of the asset"]
pub fn load<'a, T: Asset, P: Into<AssetPath<'a>>>(&self, path: P) -> Handle<T> {
self.load_untyped(path).typed()