chore: update documentation

plugins/haptics/api-iife.js

@@ -1 +1 @@
-if("__TAURI__"in window){var __TAURI_PLUGIN_HAPTICS__=function(t,r){"use strict";const e={async vibrate(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|vibrate",{duration:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async impactFeedback(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|impact_feedback",{style:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async notificationFeedback(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|notification_feedback",{type:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async selectionFeedback(){try{return{status:"ok",data:await r.invoke("plugin:haptics|selection_feedback")}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}}},{vibrate:a,impactFeedback:i,notificationFeedback:c,selectionFeedback:n}=e;return t.impactFeedback=i,t.notificationFeedback=c,t.selectionFeedback=n,t.vibrate=a,t}({},window.__TAURI__.core);Object.defineProperty(window.__TAURI__,"haptics",{value:__TAURI_PLUGIN_HAPTICS__})}
+if("__TAURI__"in window){var __TAURI_PLUGIN_HAPTICS__=function(t,r){"use strict";const e={async vibrate(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|vibrate",{duration:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async impactFeedback(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|impact_feedback",{style:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async notificationFeedback(t){try{return{status:"ok",data:await r.invoke("plugin:haptics|notification_feedback",{type:t})}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}},async selectionFeedback(){try{return{status:"ok",data:await r.invoke("plugin:haptics|selection_feedback")}}catch(t){if(t instanceof Error)throw t;return{status:"error",error:t}}}};return t.impactFeedback=async function(t){return e.impactFeedback(t)},t.notificationFeedback=async function(t){return e.notificationFeedback(t)},t.selectionFeedback=async function(){return e.selectionFeedback()},t.vibrate=async function(t){return e.vibrate(t)},t}({},window.__TAURI__.core);Object.defineProperty(window.__TAURI__,"haptics",{value:__TAURI_PLUGIN_HAPTICS__})}

plugins/haptics/guest-js/bindings.ts

@@ -73,12 +73,26 @@ export const commands = {
 /** user-defined types **/
 
 export type Error = never
+/**
+ * The style of an impact-feedback haptic.
+ *
+ * On iOS this maps directly to a `UIImpactFeedbackGenerator.FeedbackStyle` case. On Android,
+ * which has no equivalent system API, each style instead plays a distinct vibration waveform of
+ * increasing intensity. Has no effect on desktop platforms. Defaults to `Medium`.
+ */
 export type ImpactFeedbackStyle =
   | 'light'
   | 'medium'
   | 'heavy'
   | 'soft'
   | 'rigid'
+/**
+ * The type of notification feedback, indicating the outcome of a task or action.
+ *
+ * On iOS this maps directly to a `UINotificationFeedbackGenerator.FeedbackType` case. On
+ * Android, which has no equivalent system API, each type instead plays a distinct vibration
+ * waveform. Has no effect on desktop platforms. Defaults to `Success`.
+ */
 export type NotificationFeedbackType = 'success' | 'warning' | 'error'
 //export type RandomNumber = number;
 

plugins/haptics/guest-js/index.ts

@@ -2,16 +2,102 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-/* eslint-disable @typescript-eslint/unbound-method */
+/**
+ * Trigger haptic feedback on Android and iOS.
+ *
+ * @module
+ */
 
 import { commands } from './bindings'
+import type {
+  ImpactFeedbackStyle,
+  NotificationFeedbackType,
+  Result,
+  Error
+} from './bindings'
 
-export const {
-  vibrate,
-  impactFeedback,
-  notificationFeedback,
-  selectionFeedback
-} = commands
+/**
+ * Triggers a vibration for `duration` milliseconds.
+ *
+ * Has no effect on desktop platforms.
+ *
+ * @example
+ * ```typescript
+ * import { vibrate } from '@tauri-apps/plugin-haptics'
+ * await vibrate(300)
+ * ```
+ *
+ * @param duration Duration of the vibration, in milliseconds.
+ * @returns A promise resolving to the {@link Result} of the operation.
+ * @since 2.0.0
+ */
+export async function vibrate(duration: number): Promise<Result<null, Error>> {
+  return commands.vibrate(duration)
+}
+
+/**
+ * Triggers an impact-feedback haptic, indicating a collision between user interface elements.
+ *
+ * On iOS this maps to a `UIImpactFeedbackGenerator` of the given style. On Android, which has
+ * no equivalent system API, each style plays a distinct vibration waveform. Has no effect on
+ * desktop platforms.
+ *
+ * @example
+ * ```typescript
+ * import { impactFeedback } from '@tauri-apps/plugin-haptics'
+ * await impactFeedback('medium')
+ * ```
+ *
+ * @param style The style of the impact.
+ * @returns A promise resolving to the {@link Result} of the operation.
+ * @since 2.0.0
+ */
+export async function impactFeedback(
+  style: ImpactFeedbackStyle
+): Promise<Result<null, Error>> {
+  return commands.impactFeedback(style)
+}
+
+/**
+ * Triggers a notification-feedback haptic, indicating the outcome of a task or action.
+ *
+ * On iOS this maps to a `UINotificationFeedbackGenerator` of the given type. On Android, which
+ * has no equivalent system API, each type plays a distinct vibration waveform. Has no effect on
+ * desktop platforms.
+ *
+ * @example
+ * ```typescript
+ * import { notificationFeedback } from '@tauri-apps/plugin-haptics'
+ * await notificationFeedback('success')
+ * ```
+ *
+ * @param type The outcome to convey.
+ * @returns A promise resolving to the {@link Result} of the operation.
+ * @since 2.0.0
+ */
+export async function notificationFeedback(
+  type: NotificationFeedbackType
+): Promise<Result<null, Error>> {
+  return commands.notificationFeedback(type)
+}
+
+/**
+ * Triggers a haptic indicating that a selection changed, e.g. the value of a picker control.
+ *
+ * Has no effect on desktop platforms.
+ *
+ * @example
+ * ```typescript
+ * import { selectionFeedback } from '@tauri-apps/plugin-haptics'
+ * await selectionFeedback()
+ * ```
+ *
+ * @returns A promise resolving to the {@link Result} of the operation.
+ * @since 2.0.0
+ */
+export async function selectionFeedback(): Promise<Result<null, Error>> {
+  return commands.selectionFeedback()
+}
 
 export { ImpactFeedbackStyle, NotificationFeedbackType } from './bindings'
 

plugins/haptics/src/desktop.rs

@@ -18,18 +18,26 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Haptics<R: Runtime>(AppHandle<R>);
 
 impl<R: Runtime> Haptics<R> {
+    /// No-op on desktop; haptic feedback is not supported on Linux, macOS or Windows. Always
+    /// returns `Ok`.
     pub fn vibrate(&self, _duration: u32) -> crate::Result<()> {
         Ok(())
     }
 
+    /// No-op on desktop; haptic feedback is not supported on Linux, macOS or Windows. Always
+    /// returns `Ok`.
     pub fn impact_feedback(&self, _style: ImpactFeedbackStyle) -> crate::Result<()> {
         Ok(())
     }
 
+    /// No-op on desktop; haptic feedback is not supported on Linux, macOS or Windows. Always
+    /// returns `Ok`.
     pub fn notification_feedback(&self, _type: NotificationFeedbackType) -> crate::Result<()> {
         Ok(())
     }
 
+    /// No-op on desktop; haptic feedback is not supported on Linux, macOS or Windows. Always
+    /// returns `Ok`.
     pub fn selection_feedback(&self) -> crate::Result<()> {
         Ok(())
     }

plugins/haptics/src/error.rs

@@ -4,13 +4,18 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for a [`std::result::Result`] with the error type [`Error`].
 pub type Result<T> = std::result::Result<T, Error>;
 
 // TODO: Improve Error handling (different typed errors instead of one (stringified) PluginInvokeError for all mobile errors)
 
+/// Errors returned by the haptics APIs.
 #[derive(Debug, thiserror::Error)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 pub enum Error {
+    /// The call to the Android or iOS plugin implementation failed, either because the
+    /// arguments could not be serialized, the response could not be deserialized, or the
+    /// native side rejected the call. Only produced on Android and iOS.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(

plugins/haptics/src/lib.rs

@@ -33,6 +33,7 @@ pub use mobile::Haptics;
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the haptics APIs.
 pub trait HapticsExt<R: Runtime> {
+    /// Returns a handle to the [`Haptics`] APIs.
     fn haptics(&self) -> &Haptics<R>;
 }
 

plugins/haptics/src/mobile.rs

@@ -32,18 +32,40 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Haptics<R: Runtime>(PluginHandle<R>);
 
 impl<R: Runtime> Haptics<R> {
+    /// Triggers a vibration for `duration` milliseconds.
+    ///
+    /// On iOS this plays a continuous [Core Haptics](https://developer.apple.com/documentation/corehaptics)
+    /// pattern when the device supports it, falling back to the system alert vibration
+    /// otherwise. On Android it uses [`Vibrator`](https://developer.android.com/reference/android/os/Vibrator).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::PluginInvoke`](crate::Error::PluginInvoke) if the underlying Android or
+    /// iOS plugin invocation fails.
     pub fn vibrate(&self, duration: u32) -> crate::Result<()> {
         self.0
             .run_mobile_plugin("vibrate", VibratePayload { duration })
             .map_err(Into::into)
     }
 
+    /// Triggers an impact-feedback haptic with the given [`ImpactFeedbackStyle`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::PluginInvoke`](crate::Error::PluginInvoke) if the underlying Android or
+    /// iOS plugin invocation fails.
     pub fn impact_feedback(&self, style: ImpactFeedbackStyle) -> crate::Result<()> {
         self.0
             .run_mobile_plugin("impactFeedback", ImpactFeedbackPayload { style })
             .map_err(Into::into)
     }
 
+    /// Triggers a notification-feedback haptic for the given [`NotificationFeedbackType`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::PluginInvoke`](crate::Error::PluginInvoke) if the underlying Android or
+    /// iOS plugin invocation fails.
     pub fn notification_feedback(&self, r#type: NotificationFeedbackType) -> crate::Result<()> {
         self.0
             .run_mobile_plugin(
@@ -53,6 +75,13 @@ impl<R: Runtime> Haptics<R> {
             .map_err(Into::into)
     }
 
+    /// Triggers a haptic indicating that a selection changed, e.g. when the value of a picker
+    /// control changes.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::PluginInvoke`](crate::Error::PluginInvoke) if the underlying Android or
+    /// iOS plugin invocation fails.
     pub fn selection_feedback(&self) -> crate::Result<()> {
         self.0
             .run_mobile_plugin("selectionFeedback", ())

plugins/haptics/src/models.rs

@@ -13,24 +13,42 @@ pub struct HapticsOptions {
 }
  */
 
+/// The style of an impact-feedback haptic.
+///
+/// On iOS this maps directly to a `UIImpactFeedbackGenerator.FeedbackStyle` case. On Android,
+/// which has no equivalent system API, each style instead plays a distinct vibration waveform of
+/// increasing intensity. Has no effect on desktop platforms. Defaults to `Medium`.
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
 pub enum ImpactFeedbackStyle {
+    /// A collision between small, light user interface elements.
     Light,
+    /// A collision between moderately sized user interface elements.
     #[default]
     Medium,
+    /// A collision between large, heavy user interface elements.
     Heavy,
+    /// A soft, muted impact between user interface elements.
     Soft,
+    /// A sharp, rigid impact between user interface elements.
     Rigid,
 }
 
+/// The type of notification feedback, indicating the outcome of a task or action.
+///
+/// On iOS this maps directly to a `UINotificationFeedbackGenerator.FeedbackType` case. On
+/// Android, which has no equivalent system API, each type instead plays a distinct vibration
+/// waveform. Has no effect on desktop platforms. Defaults to `Success`.
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
 pub enum NotificationFeedbackType {
+    /// A task or action has completed successfully.
     #[default]
     Success,
+    /// A task or action has produced a warning.
     Warning,
+    /// A task or action has failed.
     Error,
 }