docs: where does resource dir resolve to (#13640)

* docs: where does resource dir resolve to

* Add note about potential change

Author: Legend-Master

crates/tauri-utils/src/platform.rs

@@ -252,20 +252,19 @@ fn is_cargo_output_directory(path: &std::path::Path) -> bool {
 
 /// Computes the resource directory of the current environment.
 ///
-/// On Windows, it's the path to the executable.
+/// ## Platform-specific
 ///
-/// On Linux, when running in an AppImage the `APPDIR` variable will be set to
-/// the mounted location of the app, and the resource dir will be
-/// `${APPDIR}/usr/lib/${exe_name}`. If not running in an AppImage, the path is
-/// `/usr/lib/${exe_name}`.  When running the app from
-/// `src-tauri/target/(debug|release)/`, the path is
-/// `${exe_dir}/../lib/${exe_name}`.
-///
-/// On MacOS, it's `${exe_dir}../Resources` (inside .app).
-///
-/// On iOS, it's `${exe_dir}/assets`.
-///
-/// Android uses a special URI prefix that is resolved by the Tauri file system plugin `asset://localhost/`
+/// - **Windows:** Resolves to the directory that contains the main executable.
+/// - **Linux:** When running in an AppImage, the `APPDIR` variable will be set to
+///   the mounted location of the app, and the resource dir will be `${APPDIR}/usr/lib/${exe_name}`.
+///   If not running in an AppImage, the path is `/usr/lib/${exe_name}`.
+///   When running the app from `src-tauri/target/(debug|release)/`, the path is `${exe_dir}/../lib/${exe_name}`.
+/// - **macOS:** Resolves to `${exe_dir}/../Resources` (inside .app).
+/// - **iOS:** Resolves to `${exe_dir}/assets`.
+/// - **Android:** Currently the resources are stored in the APK as assets so it's not a normal file system path,
+///   we return a special URI prefix `asset://localhost/` here that can be used with the [file system plugin](https://tauri.app/plugin/file-system/),
+///   with that, you can read the files through [`FsExt::fs`](https://docs.rs/tauri-plugin-fs/latest/tauri_plugin_fs/trait.FsExt.html#tymethod.fs)
+///   like this: `app.fs().read_to_string(app.path().resource_dir().unwrap().join("resource"));`
 pub fn resource_dir(package_info: &PackageInfo, env: &Env) -> crate::Result<PathBuf> {
   #[cfg(target_os = "android")]
   return resource_dir_android(package_info, env);

crates/tauri/src/path/desktop.rs

@@ -209,6 +209,23 @@ impl<R: Runtime> PathResolver<R> {
   }
 
   /// Returns the path to the resource directory of this app.
+  ///
+  /// ## Platform-specific
+  ///
+  /// Although we provide the exact path where this function resolves to,
+  /// this is not a contract and things might change in the future
+  ///
+  /// - **Windows:** Resolves to the directory that contains the main executable.
+  /// - **Linux:** When running in an AppImage, the `APPDIR` variable will be set to
+  ///   the mounted location of the app, and the resource dir will be `${APPDIR}/usr/lib/${exe_name}`.
+  ///   If not running in an AppImage, the path is `/usr/lib/${exe_name}`.
+  ///   When running the app from `src-tauri/target/(debug|release)/`, the path is `${exe_dir}/../lib/${exe_name}`.
+  /// - **macOS:** Resolves to `${exe_dir}/../Resources` (inside .app).
+  /// - **iOS:** Resolves to `${exe_dir}/assets`.
+  /// - **Android:** Currently the resources are stored in the APK as assets so it's not a normal file system path,
+  ///   we return a special URI prefix `asset://localhost/` here that can be used with the [file system plugin](https://tauri.app/plugin/file-system/),
+  ///   with that, you can read the files through [`FsExt::fs`](https://docs.rs/tauri-plugin-fs/latest/tauri_plugin_fs/trait.FsExt.html#tymethod.fs)
+  ///   like this: `app.fs().read_to_string(app.path().resource_dir().unwrap().join("resource"));`
   pub fn resource_dir(&self) -> Result<PathBuf> {
     crate::utils::platform::resource_dir(self.0.package_info(), &self.0.env())
       .map_err(|_| Error::UnknownPath)

packages/api/src/path.ts

@@ -467,7 +467,23 @@ async function publicDir(): Promise<string> {
 
 /**
  * Returns the path to the application's resource directory.
- * To resolve a resource path, see the [[resolveResource | `resolveResource API`]].
+ * To resolve a resource path, see {@linkcode resolveResource}.
+ *
+ * ## Platform-specific
+ *
+ * Although we provide the exact path where this function resolves to,
+ * this is not a contract and things might change in the future
+ *
+ * - **Windows:** Resolves to the directory that contains the main executable.
+ * - **Linux:** When running in an AppImage, the `APPDIR` variable will be set to
+ *   the mounted location of the app, and the resource dir will be `${APPDIR}/usr/lib/${exe_name}`.
+ *   If not running in an AppImage, the path is `/usr/lib/${exe_name}`.
+ *   When running the app from `src-tauri/target/(debug|release)/`, the path is `${exe_dir}/../lib/${exe_name}`.
+ * - **macOS:** Resolves to `${exe_dir}/../Resources` (inside .app).
+ * - **iOS:** Resolves to `${exe_dir}/assets`.
+ * - **Android:** Currently the resources are stored in the APK as assets so it's not a normal file system path,
+ *   we return a special URI prefix `asset://localhost/` here that can be used with the [file system plugin](https://tauri.app/plugin/file-system/),
+ *
  * @example
  * ```typescript
  * import { resourceDir } from '@tauri-apps/api/path';