From 44c8cc66c4ebf3f897948dd62fa5683f32b05b91 Mon Sep 17 00:00:00 2001
From: Vitaliy Sapronenko <vsapronenko@gmail.com>
Date: Mon, 3 Jun 2024 15:54:29 +0300
Subject: [PATCH] Improvement of AssetServer::load documentation to help find a
 way to load from file with hash in filename (#13272)

# Objective

- Fixes #13192 .
- It is not possible to specify the path of the file and the subasset in
it in one string slice, if there is a hash in the file name, because
hash is separator between filename and subasset, so they must be
separated explicitly

## Solution

- Improved documentation for AssetServer::load.

---------

Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
---
 crates/bevy_asset/src/server/mod.rs | 32 +++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/crates/bevy_asset/src/server/mod.rs b/crates/bevy_asset/src/server/mod.rs
index 99ce54b374..0a43deb0e1 100644
--- a/crates/bevy_asset/src/server/mod.rs
+++ b/crates/bevy_asset/src/server/mod.rs
@@ -264,6 +264,38 @@ impl AssetServer {
     /// it returns a "strong" [`Handle`]. When the [`Asset`] is loaded (and enters [`LoadState::Loaded`]), it will be added to the
     /// associated [`Assets`] resource.
     ///
+    /// In case the file path contains a hashtag (`#`), the `path` must be specified using [`Path`]
+    /// or [`AssetPath`] because otherwise the hashtag would be interpreted as separator between
+    /// the file path and the label. For example:
+    ///
+    /// ```no_run
+    /// # use bevy_asset::{AssetServer, Handle, LoadedUntypedAsset};
+    /// # use bevy_ecs::prelude::Res;
+    /// # use std::path::Path;
+    /// // `#path` is a label.
+    /// # fn setup(asset_server: Res<AssetServer>) {
+    /// # let handle: Handle<LoadedUntypedAsset> =
+    /// asset_server.load("some/file#path");
+    ///
+    /// // `#path` is part of the file name.
+    /// # let handle: Handle<LoadedUntypedAsset> =
+    /// asset_server.load(Path::new("some/file#path"));
+    /// # }
+    /// ```
+    ///
+    /// Furthermore, if you need to load a file with a hashtag in its name _and_ a label, you can
+    /// manually construct an [`AssetPath`].
+    ///
+    /// ```no_run
+    /// # use bevy_asset::{AssetPath, AssetServer, Handle, LoadedUntypedAsset};
+    /// # use bevy_ecs::prelude::Res;
+    /// # use std::path::Path;
+    /// # fn setup(asset_server: Res<AssetServer>) {
+    /// # let handle: Handle<LoadedUntypedAsset> =
+    /// asset_server.load(AssetPath::from_path(Path::new("some/file#path")).with_label("subasset"));
+    /// # }
+    /// ```
+    ///
     /// You can check the asset's load state by reading [`AssetEvent`] events, calling [`AssetServer::load_state`], or checking
     /// the [`Assets`] storage to see if the [`Asset`] exists yet.
     ///