chore: update documentation

plugins/dialog/guest-js/index.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Native system dialogs for opening and saving files, along with message, ask and confirm dialogs.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 
 /**
@@ -10,7 +16,7 @@ import { invoke } from '@tauri-apps/api/core'
  * @since 2.0.0
  */
 interface DialogFilter {
-  /** Filter name. */
+  /** The name of the filter, shown to the user in the dialog's filter selector. */
   name: string
   /**
    * Extensions to filter, without a `.` prefix.
@@ -171,11 +177,11 @@ type BanExcept<Allowed extends ButtonKey> = Partial<
  * @since 2.4.0
  */
 export type MessageDialogButtonsYesNoCancel = {
-  /** The Yes button. */
+  /** The label of the Yes button. */
   yes: string
-  /** The No button. */
+  /** The label of the No button. */
   no: string
-  /** The Cancel button. */
+  /** The label of the Cancel button. */
   cancel: string
 } & BanExcept<'yes' | 'no' | 'cancel'>
 
@@ -185,9 +191,9 @@ export type MessageDialogButtonsYesNoCancel = {
  * @since 2.4.0
  */
 export type MessageDialogButtonsOkCancel = {
-  /** The Ok button. */
+  /** The label of the Ok button. */
   ok: string
-  /** The Cancel button. */
+  /** The label of the Cancel button. */
   cancel: string
 } & BanExcept<'ok' | 'cancel'>
 
@@ -197,7 +203,7 @@ export type MessageDialogButtonsOkCancel = {
  * @since 2.4.0
  */
 export type MessageDialogButtonsOk = {
-  /** The Ok button. */
+  /** The label of the Ok button. */
   ok: string
 } & BanExcept<'ok'>
 
@@ -221,6 +227,8 @@ export type MessageDialogButtons =
   | MessageDialogCustomButtons
 
 /**
+ * Options for the message dialog.
+ *
  * @since 2.0.0
  */
 interface MessageDialogOptions {
@@ -282,6 +290,11 @@ function buttonsToRust(buttons: MessageDialogButtons | undefined) {
   return undefined
 }
 
+/**
+ * Options for the {@linkcode ask} and {@linkcode confirm} dialogs.
+ *
+ * @since 2.0.0
+ */
 interface ConfirmDialogOptions {
   /** The title of the dialog. Defaults to the app name. */
   title?: string
@@ -293,6 +306,12 @@ interface ConfirmDialogOptions {
   cancelLabel?: string
 }
 
+/**
+ * The return type of {@linkcode open}, derived from its options: a single path, an array of
+ * paths when {@linkcode OpenDialogOptions.multiple} is `true`, or `null` when the user cancels.
+ *
+ * @since 2.0.0
+ */
 type OpenDialogReturn<T extends OpenDialogOptions> = T['directory'] extends true
   ? T['multiple'] extends true
     ? string[] | null
@@ -349,6 +368,8 @@ type OpenDialogReturn<T extends OpenDialogOptions> = T['directory'] extends true
  * }
  * ```
  *
+ * @param options The dialog's options.
+ *
  * @returns A promise resolving to the selected path(s)
  *
  * @since 2.0.0
@@ -383,6 +404,8 @@ async function open<T extends OpenDialogOptions>(
  * });
  * ```
  *
+ * @param options The dialog's options.
+ *
  * @returns A promise resolving to the selected path.
  *
  * @since 2.0.0

plugins/dialog/guest-js/init.ts

@@ -2,6 +2,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Injected script that replaces `window.alert` and `window.confirm` with implementations backed
+ * by native dialogs.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 
 window.alert = function (message: string) {

plugins/dialog/src/error.rs

@@ -4,21 +4,28 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for `Result<T, Error>` used throughout this crate.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// Errors that can occur while showing or interacting with a dialog.
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
 pub enum Error {
+    /// An error forwarded from the Tauri core.
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
+    /// An I/O error, for example while resolving a picked path.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// Forwarding a request to, or receiving a response from, the mobile plugin failed.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),
+    /// The folder picker was requested through the `open` command, but folder picking is not implemented on mobile.
     #[cfg(mobile)]
     #[error("Folder picker is not implemented on mobile")]
     FolderPickerNotImplemented,
+    /// An error forwarded from the `fs` plugin, returned when granting filesystem scope to a picked path fails.
     #[error(transparent)]
     Fs(#[from] tauri_plugin_fs::Error),
 }

plugins/dialog/src/lib.rs

@@ -49,19 +49,28 @@ pub use desktop::Dialog;
 #[cfg(mobile)]
 pub use mobile::Dialog;
 
+/// The preferred mode of the file picker on mobile platforms (iOS and Android), which have
+/// distinct file and media pickers. On desktop, this option is ignored.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "lowercase")]
 pub enum PickerMode {
+    /// Show the generic document picker.
     Document,
+    /// Show the media picker, allowing both images and videos to be selected.
     Media,
+    /// Show the media picker restricted to images.
     Image,
+    /// Show the media picker restricted to videos.
     Video,
 }
 
+/// The file access mode of the dialog, used to control how a picked file is exposed to the app on iOS.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "lowercase")]
 pub enum FileAccessMode {
+    /// Copy the picked file into the app's sandbox so it can be freely read, edited or deleted.
     Copy,
+    /// Keep the file at its original location and let the system manage security-scoped access to it.
     Scoped,
 }
 
@@ -86,6 +95,7 @@ macro_rules! blocking_fn {
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the dialog APIs.
 pub trait DialogExt<R: Runtime> {
+    /// Returns the [`Dialog`] instance associated with this app/window.
     fn dialog(&self) -> &Dialog<R>;
 }
 

plugins/dialog/src/models.rs

@@ -69,11 +69,16 @@ pub enum MessageDialogButtons {
 /// Result of a message dialog
 #[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub enum MessageDialogResult {
+    /// The user pressed the `Yes` button.
     Yes,
+    /// The user pressed the `No` button.
     No,
+    /// The user pressed the `Ok` button.
     Ok,
+    /// The user pressed the `Cancel` button, or closed the dialog without pressing a button.
     #[default]
     Cancel,
+    /// The user pressed a button with a custom label, holding that label's text.
     #[serde(untagged)]
     Custom(String),
 }