chore: update documentation

plugins/barcode-scanner/guest-js/index.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Scan QR codes, EAN-13 and other kinds of barcodes with the device's camera on Android and iOS.
+ *
+ * @module
+ */
+
 import {
   invoke,
   requestPermissions as requestPermissions_,
@@ -10,55 +16,136 @@ import {
 
 export type { PermissionState } from '@tauri-apps/api/core'
 
+/**
+ * The barcode symbologies that can be scanned, or used to restrict a scan via {@link ScanOptions.formats}.
+ */
 export enum Format {
+  /**
+   * QR code, a two-dimensional matrix barcode.
+   */
   QRCode = 'QR_CODE',
   /**
+   * UPC-A, a 12-digit numeric barcode commonly used on retail products in North America.
+   *
    * Not supported on iOS.
    */
   UPC_A = 'UPC_A',
+  /**
+   * UPC-E, a compressed 6-digit variant of UPC-A used on small packaging.
+   */
   UPC_E = 'UPC_E',
+  /**
+   * EAN-8, an 8-digit numeric barcode used on small retail packaging.
+   */
   EAN8 = 'EAN_8',
+  /**
+   * EAN-13, a 13-digit numeric barcode used worldwide on retail products.
+   */
   EAN13 = 'EAN_13',
+  /**
+   * Code 39, an alphanumeric barcode used in logistics and inventory tracking.
+   */
   Code39 = 'CODE_39',
+  /**
+   * Code 93, a compact alphanumeric barcode similar to Code 39.
+   */
   Code93 = 'CODE_93',
+  /**
+   * Code 128, a high-density alphanumeric barcode used in shipping and packaging.
+   */
   Code128 = 'CODE_128',
   /**
+   * Codabar, a numeric barcode commonly used by libraries and blood banks.
+   *
    * Not supported on iOS.
    */
   Codabar = 'CODABAR',
+  /**
+   * ITF (Interleaved 2 of 5), a numeric barcode encoding an even number of digits.
+   */
   ITF = 'ITF',
+  /**
+   * Aztec code, a two-dimensional matrix barcode often used on tickets and boarding passes.
+   */
   Aztec = 'AZTEC',
+  /**
+   * Data Matrix, a two-dimensional matrix barcode used to encode small amounts of data.
+   */
   DataMatrix = 'DATA_MATRIX',
+  /**
+   * PDF417, a stacked linear barcode used on IDs, boarding passes and shipping labels.
+   */
   PDF417 = 'PDF_417',
   /**
+   * GS1 DataBar, a compact barcode used to mark variable-measure items such as fresh food.
+   *
    * Not supported on Android. Requires iOS 15.4+
    */
   GS1DataBar = 'GS1_DATA_BAR',
   /**
+   * The limited variant of {@link Format.GS1DataBar}, encoding fewer digits in a smaller symbol.
+   *
    * Not supported on Android. Requires iOS 15.4+
    */
   GS1DataBarLimited = 'GS1_DATA_BAR_LIMITED',
   /**
+   * The expanded variant of {@link Format.GS1DataBar}, capable of encoding additional data such as weight.
+   *
    * Not supported on Android. Requires iOS 15.4+
    */
   GS1DataBarExpanded = 'GS1_DATA_BAR_EXPANDED'
 }
 
+/**
+ * Options to configure a {@link scan} call.
+ */
 export interface ScanOptions {
+  /**
+   * Which camera to use for scanning. Defaults to `back`.
+   */
   cameraDirection?: 'back' | 'front'
+  /**
+   * The barcode formats to scan for. Defaults to all supported formats.
+   */
   formats?: Format[]
+  /**
+   * Whether to show the camera in a small window instead of taking over the whole screen. Defaults to `false`.
+   */
   windowed?: boolean
 }
 
+/**
+ * The result of a successful {@link scan} call.
+ */
 export interface Scanned {
+  /**
+   * The decoded content of the barcode.
+   */
   content: string
+  /**
+   * The format of the scanned barcode.
+   */
   format: Format
+  /**
+   * The bounding box of the scanned barcode within the camera frame, when reported by the platform.
+   */
   bounds: unknown
 }
 
 /**
- * Start scanning.
- * @param options
+ * Start scanning, opening the device's camera. The returned promise resolves once a barcode
+ * matching the given options has been scanned, or rejects if the scan is cancelled.
+ *
+ * @example
+ * ```typescript
+ * import { scan, Format } from '@tauri-apps/plugin-barcode-scanner';
+ *
+ * const scanned = await scan({ windowed: true, formats: [Format.QRCode] });
+ * ```
+ *
+ * @param options Configuration for the scan.
+ * @returns A promise resolving to the scanned barcode.
+ * @since 2.0.0
  */
 export async function scan(options?: ScanOptions): Promise<Scanned> {
   return await invoke('plugin:barcode-scanner|scan', { ...options })
@@ -66,13 +153,32 @@ export async function scan(options?: ScanOptions): Promise<Scanned> {
 
 /**
  * Cancel the current scan process.
+ *
+ * @example
+ * ```typescript
+ * import { cancel } from '@tauri-apps/plugin-barcode-scanner';
+ *
+ * await cancel();
+ * ```
+ *
+ * @since 2.0.0
  */
 export async function cancel(): Promise<void> {
   await invoke('plugin:barcode-scanner|cancel')
 }
 
 /**
- * Get permission state.
+ * Get the current state of the camera permission.
+ *
+ * @example
+ * ```typescript
+ * import { checkPermissions } from '@tauri-apps/plugin-barcode-scanner';
+ *
+ * const permissionState = await checkPermissions();
+ * ```
+ *
+ * @returns A promise resolving to the current state of the camera permission.
+ * @since 2.0.0
  */
 export async function checkPermissions(): Promise<PermissionState> {
   return await checkPermissions_<{ camera: PermissionState }>(
@@ -82,6 +188,16 @@ export async function checkPermissions(): Promise<PermissionState> {
 
 /**
  * Request permissions to use the camera.
+ *
+ * @example
+ * ```typescript
+ * import { requestPermissions } from '@tauri-apps/plugin-barcode-scanner';
+ *
+ * const permissionState = await requestPermissions();
+ * ```
+ *
+ * @returns A promise resolving to the new state of the camera permission.
+ * @since 2.0.0
  */
 export async function requestPermissions(): Promise<PermissionState> {
   return await requestPermissions_<{ camera: PermissionState }>(
@@ -91,6 +207,15 @@ export async function requestPermissions(): Promise<PermissionState> {
 
 /**
  * Open application settings. Useful if permission was denied and the user must manually enable it.
+ *
+ * @example
+ * ```typescript
+ * import { openAppSettings } from '@tauri-apps/plugin-barcode-scanner';
+ *
+ * await openAppSettings();
+ * ```
+ *
+ * @since 2.0.0
  */
 export async function openAppSettings(): Promise<void> {
   await invoke('plugin:barcode-scanner|open_app_settings')

plugins/barcode-scanner/src/error.rs

@@ -4,12 +4,17 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for the result type returned by this crate's functions.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// The error type returned by this crate's APIs. Serialized as its [`Display`](std::fmt::Display)
+/// string when it crosses the IPC boundary.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// An I/O error occurred.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// Failed to run a command on the mobile plugin implementation (Kotlin on Android, Swift on iOS).
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),

plugins/barcode-scanner/src/lib.rs

@@ -2,6 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Scan QR codes, EAN-13 and other kinds of barcodes with the device's camera.
+//!
+//! - Supported platforms: Android and iOS.
+
 #![cfg(mobile)]
 
 use tauri::{
@@ -29,6 +33,7 @@ impl<R: Runtime> BarcodeScanner<R> {}
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the barcode scanner APIs.
 pub trait BarcodeScannerExt<R: Runtime> {
+    /// Returns the [`BarcodeScanner`] instance managed by the app.
     fn barcode_scanner(&self) -> &BarcodeScanner<R>;
 }