chore(api.js): better platform-specific notes (#2253)

tooling/api/src/app.ts

@@ -6,7 +6,7 @@
  * Get application metadata.
  *
  * This package is also accessible with `window.__TAURI__.app` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/cli.ts

@@ -6,7 +6,7 @@
  * Parse arguments from your Command Line Interface.
  *
  * This package is also accessible with `window.__TAURI__.cli` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/clipboard.ts

@@ -6,7 +6,7 @@
  * Read and write to the system clipboard.
  *
  * This package is also accessible with `window.__TAURI__.clipboard` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/dialog.ts

@@ -22,7 +22,7 @@
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/event.ts

@@ -6,7 +6,7 @@
  * The event system allows you to emit events to the backend and listen to events from it.
  *
  * This package is also accessible with `window.__TAURI__.event` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/fs.ts

@@ -30,7 +30,7 @@
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/globalShortcut.ts

@@ -20,7 +20,7 @@
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/http.ts

@@ -21,7 +21,7 @@
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/notification.ts

@@ -21,7 +21,7 @@
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'

tooling/api/src/path.ts

@@ -24,7 +24,7 @@ import { BaseDirectory } from './fs'
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 /**
@@ -46,12 +46,12 @@ async function appDir(): Promise<string> {
 
 /**
  * Returns the path to the user's audio directory.
- * # Linux
- * Resolves to `$XDG_MUSIC_DIR`.
- * # macOS
- * Resolves to `$HOME/Music`.
- * # Windows
- * Resolves to `{FOLDERID_Music}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_MUSIC_DIR`.
+ * - **macOS:** Resolves to `$HOME/Music`.
+ * - **Windows:** Resolves to `{FOLDERID_Music}`.
  *
  * @returns
  */
@@ -68,12 +68,12 @@ async function audioDir(): Promise<string> {
 
 /**
  * Returns the path to the user's cache directory.
- * # Linux
- * Resolves to `$XDG_CACHE_HOME` or `$HOME/.cache`.
- * # macOS
- * Resolves to `$HOME/Library/Caches`.
- * # Windows
- * Resolves to `{FOLDERID_LocalAppData}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_CACHE_HOME` or `$HOME/.cache`.
+ * - **macOS:** Resolves to `$HOME/Library/Caches`.
+ * - **Windows:** Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -90,12 +90,12 @@ async function cacheDir(): Promise<string> {
 
 /**
  * Returns the path to the user's config directory.
- * # Linux
- * Resolves to `$XDG_CONFIG_HOME` or `$HOME/.config`.
- * # macOS
- * Resolves to `$HOME/Library/Application Support`.
- * # Windows
- * Resolves to `{FOLDERID_LocalAppData}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_CONFIG_HOME` or `$HOME/.config`.
+ * - **macOS:** Resolves to `$HOME/Library/Application Support`.
+ * - **Windows:** Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -112,12 +112,12 @@ async function configDir(): Promise<string> {
 
 /**
  * Returns the path to the user's data directory.
- * # Linux
- * Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
- * # macOS
- * Resolves to `$HOME/Library/Application Support`.
- * # Windows
- * Resolves to `{FOLDERID_RoamingAppData}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
+ * - **macOS:** Resolves to `$HOME/Library/Application Support`.
+ * - **Windows:** Resolves to `{FOLDERID_RoamingAppData}`.
  *
  * @returns
  */
@@ -134,12 +134,12 @@ async function dataDir(): Promise<string> {
 
 /**
  * Returns the path to the user's desktop directory.
- * # Linux
- * Resolves to `$XDG_DESKTOP_DIR`.
- * # macOS
- * Resolves to `$HOME/Library/Desktop`.
- * # Windows
- * Resolves to `{FOLDERID_Desktop}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_DESKTOP_DIR`.
+ * - **macOS:** Resolves to `$HOME/Library/Desktop`.
+ * - **Windows:** Resolves to `{FOLDERID_Desktop}`.
 
  * @returns
  */
@@ -156,12 +156,12 @@ async function desktopDir(): Promise<string> {
 
 /**
  * Returns the path to the user's document directory.
- * # Linux
- * Resolves to `$XDG_DOCUMENTS_DIR`.
- * # macOS
- * Resolves to `$HOME/Documents`.
- * # Windows
- * Resolves to `{FOLDERID_Documents}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_DOCUMENTS_DIR`.
+ * - **macOS:** Resolves to `$HOME/Documents`.
+ * - **Windows:** Resolves to `{FOLDERID_Documents}`.
  *
  * @returns
  */
@@ -178,12 +178,12 @@ async function documentDir(): Promise<string> {
 
 /**
  * Returns the path to the user's download directory.
- * # Linux
- * Resolves to `$XDG_DOWNLOAD_DIR`.
- * # macOS
- * Resolves to `$HOME/Downloads`.
- * # Windows
- * Resolves to `{FOLDERID_Downloads}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux**: Resolves to `$XDG_DOWNLOAD_DIR`.
+ * - **macOS**: Resolves to `$HOME/Downloads`.
+ * - **Windows**: Resolves to `{FOLDERID_Downloads}`.
  *
  * @returns
  */
@@ -200,12 +200,12 @@ async function downloadDir(): Promise<string> {
 
 /**
  * Returns the path to the user's executable directory.
- * # Linux
- * Resolves to `$XDG_BIN_HOME/../bin` or `$XDG_DATA_HOME/../bin` or `$HOME/.local/bin`.
- * # macOS
- * Not supported.
- * # Windows
- * Not supported.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_BIN_HOME/../bin` or `$XDG_DATA_HOME/../bin` or `$HOME/.local/bin`.
+ * - **macOS:** Not supported.
+ * - **Windows:** Not supported.
  *
  * @returns
  */
@@ -222,12 +222,12 @@ async function executableDir(): Promise<string> {
 
 /**
  * Returns the path to the user's font directory.
- * # Linux
- * Resolves to `$XDG_DATA_HOME/fonts` or `$HOME/.local/share/fonts`.
- * # macOS
- * Resolves to `$HOME/Library/Fonts`.
- * # Windows
- * Not supported.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_DATA_HOME/fonts` or `$HOME/.local/share/fonts`.
+ * - **macOS:** Resolves to `$HOME/Library/Fonts`.
+ * - **Windows:** Not supported.
  *
  * @returns
  */
@@ -244,12 +244,12 @@ async function fontDir(): Promise<string> {
 
 /**
  * Returns the path to the user's home directory.
- * # Linux
- * Resolves to `$HOME`.
- * # macOS
- * Resolves to `$HOME`.
- * # Windows
- * Resolves to `{FOLDERID_Profile}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$HOME`.
+ * - **macOS:** Resolves to `$HOME`.
+ * - **Windows:** Resolves to `{FOLDERID_Profile}`.
  *
  * @returns
  */
@@ -266,12 +266,12 @@ async function homeDir(): Promise<string> {
 
 /**
  * Returns the path to the user's local data directory.
- * # Linux
- * Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
- * # macOS
- * Resolves to `$HOME/Library/Application Support`.
- * # Windows
- * Resolves to `{FOLDERID_LocalAppData}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
+ * - **macOS:** Resolves to `$HOME/Library/Application Support`.
+ * - **Windows:** Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -288,12 +288,12 @@ async function localDataDir(): Promise<string> {
 
 /**
  * Returns the path to the user's picture directory.
- * # Linux
- * Resolves to `$XDG_PICTURES_DIR`.
- * # macOS
- * Resolves to `$HOME/Pictures`.
- * # Windows
- * Resolves to `{FOLDERID_Pictures}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_PICTURES_DIR`.
+ * - **macOS:** Resolves to `$HOME/Pictures`.
+ * - **Windows:** Resolves to `{FOLDERID_Pictures}`.
  *
  * @returns
  */
@@ -310,12 +310,12 @@ async function pictureDir(): Promise<string> {
 
 /**
  * Returns the path to the user's public directory.
- * # Linux
- * Resolves to `$XDG_PUBLICSHARE_DIR`.
- * # macOS
- * Resolves to `$HOME/Public`.
- * # Windows
- * Resolves to `{FOLDERID_Public}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_PUBLICSHARE_DIR`.
+ * - **macOS:** Resolves to `$HOME/Public`.
+ * - **Windows:** Resolves to `{FOLDERID_Public}`.
  *
  * @returns
  */
@@ -348,12 +348,12 @@ async function resourceDir(): Promise<string> {
 
 /**
  * Returns the path to the user's runtime directory.
- * # Linux
- * Resolves to `$XDG_RUNTIME_DIR`.
- * # macOS
- * Not supported.
- * # Windows
- * Not supported.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_RUNTIME_DIR`.
+ * - **macOS:** Not supported.
+ * - **Windows:** Not supported.
  *
  * @returns
  */
@@ -370,12 +370,12 @@ async function runtimeDir(): Promise<string> {
 
 /**
  * Returns the path to the user's template directory.
- * # Linux
- * Resolves to `$XDG_TEMPLATES_DIR`.
- * # macOS
- * Not supported.
- * # Windows
- * Resolves to `{FOLDERID_Templates}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_TEMPLATES_DIR`.
+ * - **macOS:** Not supported.
+ * - **Windows:** Resolves to `{FOLDERID_Templates}`.
  *
  * @returns
  */
@@ -392,12 +392,12 @@ async function templateDir(): Promise<string> {
 
 /**
  * Returns the path to the user's video directory.
- * # Linux
- * Resolves to `$XDG_VIDEOS_DIR`.
- * # macOS
- * Resolves to `$HOME/Movies`.
- * # Windows
- * Resolves to `{FOLDERID_Videos}`.
+ *
+ * ## Platform-specific
+ *
+ * - **Linux:** Resolves to `$XDG_VIDEOS_DIR`.
+ * - **macOS:** Resolves to `$HOME/Movies`.
+ * - **Windows:** Resolves to `{FOLDERID_Videos}`.
  *
  * @returns
  */

tooling/api/src/process.ts

@@ -8,7 +8,7 @@ import { invokeTauriCommand } from './helpers/tauri'
  * Perform operations on the current process.
  *
  * This package is also accessible with `window.__TAURI__.process` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 /**

tooling/api/src/shell.ts

@@ -26,7 +26,7 @@ import { transformCallback } from './tauri'
  * }
  * ```
  * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
- * @packageDocumentation
+ * @module
  */
 
 interface SpawnOptions {

tooling/api/src/tauri.ts

@@ -6,7 +6,7 @@
  * Invoke your custom commands.
  *
  * This package is also accessible with `window.__TAURI__.tauri` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 /** @ignore */

tooling/api/src/updater.ts

@@ -6,7 +6,7 @@
  * Customize the auto updater flow.
  *
  * This package is also accessible with `window.__TAURI__.updater` when `tauri.conf.json > build > withGlobalTauri` is set to true.
- * @packageDocumentation
+ * @module
  */
 
 import { once, listen, emit, UnlistenFn } from './event'

tooling/api/src/window.ts

@@ -81,7 +81,7 @@
  * type MenuClicked = string
  * ```
  *
- * @packageDocumentation
+ * @module
  */
 
 import { invokeTauriCommand } from './helpers/tauri'