chore: update documentation

plugins/deep-link/guest-js/index.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Set your Tauri application as the default handler for a URL, or check which URL(s) it was opened with.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 import { type UnlistenFn, listen } from '@tauri-apps/api/event'
 
@@ -17,9 +23,10 @@ import { type UnlistenFn, listen } from '@tauri-apps/api/event'
  * #### Platform-specific
  *
  * - **Windows / Linux:** This function reads the command line arguments and checks if there's only one value, which must be an URL with scheme matching one of the configured values.
- *   Note that you must manually check the arguments when registering deep link schemes dynamically with [`Self::register`].
+ *   Note that you must manually check the arguments when registering deep link schemes dynamically with {@link register}.
  *   Additionally, the deep link might have been provided as a CLI argument so you should check if its format matches what you expect.
  *
+ * @returns A promise resolving to the list of URLs that triggered the deep link, or `null` if the app was not started via a deep link.
  * @since 2.0.0
  */
 export async function getCurrent(): Promise<string[] | null> {
@@ -41,6 +48,7 @@ export async function getCurrent(): Promise<string[] | null> {
  *
  * - **macOS / Android / iOS:** Unsupported.
  *
+ * @returns A promise that resolves once the protocol has been registered.
  * @since 2.0.0
  */
 export async function register(protocol: string): Promise<null> {
@@ -60,8 +68,11 @@ export async function register(protocol: string): Promise<null> {
  *
  * #### Platform-specific
  *
- * - **macOS / Linux / Android / iOS:** Unsupported.
+ * - **Windows:** Requires admin rights if the protocol is registered on the local machine (this can happen when registered from the NSIS installer when the install mode is set to both or per machine).
+ * - **Linux:** Can only unregister the scheme if it was initially registered with {@link register}. May not work on older distros.
+ * - **macOS / Android / iOS:** Unsupported.
  *
+ * @returns A promise that resolves once the protocol has been unregistered.
  * @since 2.0.0
  */
 export async function unregister(protocol: string): Promise<null> {
@@ -83,6 +94,7 @@ export async function unregister(protocol: string): Promise<null> {
  *
  * - **macOS / Android / iOS:** Unsupported.
  *
+ * @returns A promise resolving to `true` if the app is the default handler for the protocol, `false` otherwise.
  * @since 2.0.0
  */
 export async function isRegistered(protocol: string): Promise<boolean> {
@@ -90,9 +102,9 @@ export async function isRegistered(protocol: string): Promise<boolean> {
 }
 
 /**
- * Helper function for the `deep-link://new-url` event to run a function each time the protocol is triggered while the app is running. Use `getCurrent` on app load to check whether your app was started via a deep link.
+ * Helper function for the `deep-link://new-url` event to run a function each time the protocol is triggered while the app is running. Use {@link getCurrent} on app load to check whether your app was started via a deep link.
  *
- * @param protocol The name of the protocol without `://`.
+ * @param handler The function to call with the list of URLs the app was requested to open, every time this happens while the app is running.
  *
  * @example
  * ```typescript
@@ -104,6 +116,7 @@ export async function isRegistered(protocol: string): Promise<boolean> {
  *
  * - **Windows / Linux:** Unsupported without the single-instance plugin. The OS will spawn a new app instance passing the URL as a CLI argument.
  *
+ * @returns A promise resolving to a function that unregisters the event listener.
  * @since 2.0.0
  */
 export async function onOpenUrl(

plugins/deep-link/src/error.rs

@@ -4,25 +4,38 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for a [`Result`](std::result::Result) with the error type [`Error`].
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// The error type for this plugin.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// The requested operation (usually registering or unregistering a protocol scheme at
+    /// runtime) is not supported on the current platform.
     #[error("unsupported platform")]
     UnsupportedPlatform,
+    /// Transparent wrapper around an [`std::io::Error`].
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// Transparent wrapper around a [`tauri::Error`].
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
+    /// Transparent wrapper around a [`windows_result::Error`]. Only used on Windows.
     #[cfg(target_os = "windows")]
     #[error(transparent)]
     Windows(#[from] windows_result::Error),
+    /// Transparent wrapper around an [`ini::Error`], returned when reading or writing the
+    /// `.desktop` file used to register a protocol scheme. Only used on Linux.
     #[cfg(target_os = "linux")]
     #[error(transparent)]
     Ini(#[from] ini::Error),
+    /// Transparent wrapper around an [`ini::ParseError`], returned when parsing the
+    /// `.desktop` file used to register a protocol scheme. Only used on Linux.
     #[cfg(target_os = "linux")]
     #[error(transparent)]
     ParseIni(#[from] ini::ParseError),
+    /// Transparent wrapper around a [`tauri::plugin::mobile::PluginInvokeError`], returned
+    /// when the underlying mobile plugin invocation fails. Only used on mobile.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),

plugins/deep-link/src/lib.rs

@@ -2,6 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Set your Tauri application as the default handler for a URL, or check which URL(s) it was
+//! opened with.
+//!
+//! On Windows and Linux, protocol schemes can additionally be registered and unregistered at
+//! runtime with [`DeepLink::register`] and [`DeepLink::unregister`]. On macOS, Android and iOS
+//! the schemes declared in the Tauri configuration are registered at build time instead, so
+//! calling those methods returns [`Error::UnsupportedPlatform`].
+
 use tauri::{
     plugin::{Builder, PluginApi, TauriPlugin},
     AppHandle, EventId, Listener, Manager, Runtime,
@@ -479,6 +487,7 @@ use url::Url;
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the deep-link APIs.
 pub trait DeepLinkExt<R: Runtime> {
+    /// Returns a reference to the [`DeepLink`] API.
     fn deep_link(&self) -> &DeepLink<R>;
 }