chore: update documentation

plugins/opener/guest-js/init.ts

@@ -2,6 +2,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Webview script injected by the opener plugin on every page load.
+ *
+ * It installs a `click` listener on `window` that intercepts clicks on `<a>` elements whose
+ * `target` is `_blank` (or that are clicked while holding `Ctrl` or `Shift`) and whose `href`
+ * uses the `http:`, `https:`, `mailto:` or `tel:` protocol, cancels the navigation and opens the
+ * link with the system's default browser through the `plugin:opener|open_url` command instead.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 
 // open <a href="..."> links with the API

plugins/opener/src/error.rs

@@ -6,37 +6,61 @@ use std::path::PathBuf;
 
 use serde::{Serialize, Serializer};
 
+/// The error type returned by the opener plugin's commands and APIs.
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
 pub enum Error {
+    /// Forwarded from a failed call into the mobile plugin runtime.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),
+    /// Forwarded from a [`tauri::Error`], e.g. when resolving a scoped path fails.
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
+    /// Forwarded from an [`std::io::Error`] raised while opening or revealing a path.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// Forwarded from a [`serde_json::Error`] raised while (de)serializing a mobile plugin payload.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// The program passed as `with` is not a program name known by the underlying opener.
     #[error("unknown program {0}")]
     UnknownProgramName(String),
+    /// The path is not allowed by the opener scope, optionally together with the program it was requested to be opened with.
     #[error("Not allowed to open path {}{}", .path, .with.as_ref().map(|w| format!(" with {w}")).unwrap_or_default())]
-    ForbiddenPath { path: String, with: Option<String> },
+    ForbiddenPath {
+        /// The path that was rejected by the scope.
+        path: String,
+        /// The program the path was requested to be opened with, if any.
+        with: Option<String>,
+    },
+    /// The URL is not allowed by the opener scope, optionally together with the program it was requested to be opened with.
     #[error("Not allowed to open url {}{}", .url, .with.as_ref().map(|w| format!(" with {w}")).unwrap_or_default())]
-    ForbiddenUrl { url: String, with: Option<String> },
+    ForbiddenUrl {
+        /// The URL that was rejected by the scope.
+        url: String,
+        /// The program the URL was requested to be opened with, if any.
+        with: Option<String>,
+    },
+    /// The requested API is not supported on the current platform, e.g. [`crate::reveal_item_in_dir`] on Android and iOS.
     #[error("API not supported on the current platform")]
     UnsupportedPlatform,
+    /// Forwarded from a Win32 API call, see [`windows::core::Error`].
     #[error(transparent)]
     #[cfg(windows)]
     Win32Error(#[from] windows::core::Error),
+    /// The given path has no parent directory, so it cannot be revealed in its containing folder.
     #[error("Path doesn't have a parent: {0}")]
     NoParent(PathBuf),
     // TODO: Add the underlying io::Error to this variant
+    /// Failed to convert the path to a Windows `ITEMIDLIST` while preparing it to be revealed in the file explorer.
     #[cfg(windows)]
     #[error("Failed to convert path '{0}' to ITEMIDLIST")]
     FailedToConvertPathToItemIdList(PathBuf),
+    /// Failed to convert the path to a `file://` URL, which is required to reveal it via D-Bus on Linux and BSD.
     #[error("Failed to convert path to file:// url")]
     FailedToConvertPathToFileUrl,
+    /// Forwarded from a [`zbus::Error`] raised while talking to the file manager or the desktop portal over D-Bus.
     #[error(transparent)]
     #[cfg(any(
         target_os = "linux",

plugins/opener/src/lib.rs

@@ -2,6 +2,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Open files and URLs using their default application, and reveal files in the system's file explorer.
+//!
+//! Use the [`OpenerExt`] trait to access [`Opener::open_url`] and [`Opener::open_path`] from a
+//! running Tauri app; the plugin's `open_url` and `open_path` commands enforce the scope
+//! configured for the plugin before delegating to them. The [`open_url`] and [`open_path`] free
+//! functions and the [`Opener`] methods themselves do not perform any scope check.
+//! [`reveal_item_in_dir`] and [`reveal_items_in_dir`] return [`Error::UnsupportedPlatform`] on
+//! Android and iOS.
+
 use std::path::Path;
 
 use tauri::{plugin::TauriPlugin, Manager, Runtime};
@@ -29,6 +38,9 @@ type Result<T> = std::result::Result<T, Error>;
 pub use open::{open_path, open_url};
 pub use reveal_item_in_dir::{reveal_item_in_dir, reveal_items_in_dir};
 
+/// Access to the opener APIs, managed by the plugin as app state.
+///
+/// Obtain an instance via [`OpenerExt::opener`].
 pub struct Opener<R: Runtime> {
     // we use `fn() -> R` to silence the unused generic error
     // while keeping this struct `Send + Sync` without requiring `R` to be
@@ -153,10 +165,20 @@ impl<R: Runtime> Opener<R> {
             .map_err(Into::into)
     }
 
+    /// Reveal a path in the system's default explorer. See [`reveal_item_in_dir`] for details.
+    ///
+    /// ## Platform-specific:
+    ///
+    /// - **Android / iOS:** Unsupported, returns [`Error::UnsupportedPlatform`].
     pub fn reveal_item_in_dir<P: AsRef<Path>>(&self, p: P) -> Result<()> {
         reveal_item_in_dir(p)
     }
 
+    /// Reveal multiple paths in the system's default explorer. See [`reveal_items_in_dir`] for details.
+    ///
+    /// ## Platform-specific:
+    ///
+    /// - **Android / iOS:** Unsupported, returns [`Error::UnsupportedPlatform`].
     pub fn reveal_items_in_dir<I, P>(&self, paths: I) -> Result<()>
     where
         I: IntoIterator<Item = P>,
@@ -168,6 +190,7 @@ impl<R: Runtime> Opener<R> {
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the opener APIs.
 pub trait OpenerExt<R: Runtime> {
+    /// Returns the [`Opener`] instance managed by the plugin.
     fn opener(&self) -> &Opener<R>;
 }