chore: update documentation

plugins/window-state/guest-js/index.ts

@@ -2,21 +2,48 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Save and restore window positions and sizes.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 import { type WindowLabel, getCurrentWindow } from '@tauri-apps/api/window'
 
+/**
+ * Flags controlling which parts of a window's state are saved and restored.
+ * Combine multiple flags with the bitwise OR operator (`|`).
+ */
 export enum StateFlags {
+  /** Save and restore the window size. */
   SIZE = 1 << 0,
+  /** Save and restore the window position. */
   POSITION = 1 << 1,
+  /** Save and restore whether the window is maximized. */
   MAXIMIZED = 1 << 2,
+  /** Save and restore whether the window is visible. */
   VISIBLE = 1 << 3,
+  /** Save and restore whether the window has decorations. */
   DECORATIONS = 1 << 4,
+  /** Save and restore whether the window is fullscreen. */
   FULLSCREEN = 1 << 5,
+  /** Save and restore every flag above. */
   ALL = SIZE | POSITION | MAXIMIZED | VISIBLE | DECORATIONS | FULLSCREEN
 }
 
 /**
  *  Save the state of all open windows to disk.
+ *
+ * @example
+ * ```typescript
+ * import { saveWindowState, StateFlags } from '@tauri-apps/plugin-window-state';
+ *
+ * await saveWindowState(StateFlags.ALL);
+ * ```
+ *
+ * @param flags Which parts of the state to save. Defaults to the flags passed to the plugin `Builder` (all flags if none were set).
+ * @since 2.0.0
  */
 async function saveWindowState(flags?: StateFlags): Promise<void> {
   await invoke('plugin:window-state|save_window_state', { flags })
@@ -24,6 +51,17 @@ async function saveWindowState(flags?: StateFlags): Promise<void> {
 
 /**
  *  Restore the state for the specified window from disk.
+ *
+ * @example
+ * ```typescript
+ * import { restoreState, StateFlags } from '@tauri-apps/plugin-window-state';
+ *
+ * await restoreState('main', StateFlags.ALL);
+ * ```
+ *
+ * @param label The label of the window to restore.
+ * @param flags Which parts of the state to restore. Defaults to the flags passed to the plugin `Builder` (all flags if none were set).
+ * @since 2.0.0
  */
 async function restoreState(
   label: WindowLabel,
@@ -34,12 +72,32 @@ async function restoreState(
 
 /**
  *  Restore the state for the current window from disk.
+ *
+ * @example
+ * ```typescript
+ * import { restoreStateCurrent, StateFlags } from '@tauri-apps/plugin-window-state';
+ *
+ * await restoreStateCurrent(StateFlags.ALL);
+ * ```
+ *
+ * @param flags Which parts of the state to restore. Defaults to the flags passed to the plugin `Builder` (all flags if none were set).
+ * @since 2.0.0
  */
 async function restoreStateCurrent(flags?: StateFlags): Promise<void> {
   await restoreState(getCurrentWindow().label, flags)
 }
 /**
  *  Get the name of the file used to store window state.
+ *
+ * @example
+ * ```typescript
+ * import { filename } from '@tauri-apps/plugin-window-state';
+ *
+ * const name = await filename();
+ * ```
+ *
+ * @returns A promise resolving to the name of the file used to store window state.
+ * @since 2.0.0
  */
 async function filename(): Promise<string> {
   return await invoke('plugin:window-state|filename')

plugins/window-state/src/lib.rs

@@ -35,26 +35,41 @@ type FilterCallbackFn = dyn Fn(&str) -> bool + Send + Sync;
 /// If using a custom filename, you should probably use [`AppHandleExt::filename`] instead.
 pub const DEFAULT_FILENAME: &str = ".window-state.json";
 
+/// The error type returned by this plugin's fallible functions.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// An I/O error occurred while reading or writing the window state file.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// An error occurred while calling into Tauri, e.g. while resolving the app config directory
+    /// or manipulating a window.
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
+    /// An error occurred while serializing or deserializing the window state file.
     #[error(transparent)]
     SerdeJson(#[from] serde_json::Error),
 }
 
+/// Alias for a [`Result`](std::result::Result) with the error type [`Error`].
 pub type Result<T> = std::result::Result<T, Error>;
 
 bitflags! {
+    /// Flags controlling which parts of a window's state are saved and restored.
+    ///
+    /// Flags can be combined with the bitwise OR operator (`|`), e.g. `StateFlags::SIZE | StateFlags::POSITION`.
     #[derive(Clone, Copy, Debug)]
     pub struct StateFlags: u32 {
+        /// Save and restore the window size.
         const SIZE        = 1 << 0;
+        /// Save and restore the window position.
         const POSITION    = 1 << 1;
+        /// Save and restore whether the window is maximized.
         const MAXIMIZED   = 1 << 2;
+        /// Save and restore whether the window is visible.
         const VISIBLE     = 1 << 3;
+        /// Save and restore whether the window has decorations.
         const DECORATIONS = 1 << 4;
+        /// Save and restore whether the window is fullscreen.
         const FULLSCREEN  = 1 << 5;
     }
 }
@@ -110,6 +125,7 @@ struct WindowStateCache(Arc<Mutex<HashMap<String, WindowState>>>);
 /// Used to prevent deadlocks from resize and position event listeners setting the cached state on restoring states
 struct RestoringWindowState(Mutex<()>);
 
+/// Extension trait for [`AppHandle`] exposing window state APIs.
 pub trait AppHandleExt {
     /// Saves all open windows state to disk
     fn save_window_state(&self, flags: StateFlags) -> Result<()>;
@@ -151,6 +167,7 @@ impl<R: Runtime> AppHandleExt for tauri::AppHandle<R> {
     }
 }
 
+/// Extension trait for [`Window`] and [`WebviewWindow`] exposing window state APIs.
 pub trait WindowExt {
     /// Restores this window state from disk
     fn restore_state(&self, flags: StateFlags) -> tauri::Result<()>;
@@ -321,6 +338,7 @@ impl<R: Runtime> WindowExtInternal for Window<R> {
     }
 }
 
+/// Builder for the window-state [plugin](TauriPlugin).
 #[derive(Default)]
 pub struct Builder {
     denylist: HashSet<String>,
@@ -332,6 +350,8 @@ pub struct Builder {
 }
 
 impl Builder {
+    /// Creates a new [`Builder`] with the default configuration:
+    /// all [`StateFlags`] enabled, no denylist, no filter, and the [`DEFAULT_FILENAME`].
     pub fn new() -> Self {
         Self::default()
     }
@@ -382,6 +402,12 @@ impl Builder {
         self
     }
 
+    /// Builds the [`TauriPlugin`].
+    ///
+    /// The plugin loads the previously saved window state on setup, restores each window's
+    /// state when it becomes ready (unless denylisted, filtered out, or opted out with
+    /// [`Builder::skip_initial_state`]), tracks move/resize events to keep the state up to date,
+    /// and saves the state of all windows to disk when the app exits.
     pub fn build<R: Runtime>(self) -> TauriPlugin<R> {
         let state_flags = self.state_flags;
         let filename = self.filename.unwrap_or_else(|| DEFAULT_FILENAME.into());