chore: update documentation

plugins/positioner/guest-js/index.ts

@@ -3,6 +3,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Move the window to well-known positions, including positions relative to the tray icon.
+ *
+ * @module
+ */
+
 import { invoke } from '@tauri-apps/api/core'
 import type { TrayIconEvent } from '@tauri-apps/api/tray'
 
@@ -10,20 +16,53 @@ import type { TrayIconEvent } from '@tauri-apps/api/tray'
  * Well known window positions.
  */
 export enum Position {
+  /** Top left corner of the screen. */
   TopLeft = 0,
+  /** Top right corner of the screen. */
   TopRight,
+  /** Bottom left corner of the screen. */
   BottomLeft,
+  /** Bottom right corner of the screen. */
   BottomRight,
+  /** Top center of the screen. */
   TopCenter,
+  /** Bottom center of the screen. */
   BottomCenter,
+  /** Vertically centered on the left edge of the screen. */
   LeftCenter,
+  /** Vertically centered on the right edge of the screen. */
   RightCenter,
+  /** Center of the screen. */
   Center,
+  /**
+   * Above the tray icon, aligned with its left edge. Requires the `tray-icon` feature and the
+   * tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayLeft,
+  /**
+   * Directly below the tray icon, aligned with its left edge. Requires the `tray-icon` feature
+   * and the tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayBottomLeft,
+  /**
+   * Above the tray icon, aligned with its right edge. Requires the `tray-icon` feature and the
+   * tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayRight,
+  /**
+   * Directly below the tray icon, aligned with its right edge. Requires the `tray-icon` feature
+   * and the tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayBottomRight,
+  /**
+   * Above the tray icon, horizontally centered on it. Requires the `tray-icon` feature and the
+   * tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayCenter,
+  /**
+   * Directly below the tray icon, horizontally centered on it. Requires the `tray-icon` feature
+   * and the tray icon's events to be forwarded through {@link handleIconState}.
+   */
   TrayBottomCenter
 }
 
@@ -31,7 +70,15 @@ export enum Position {
  * Moves the `Window` to the given {@link Position} using `WindowExt.move_window()`
  * All positions are relative to the **current** screen.
  *
+ * @example
+ * ```typescript
+ * import { moveWindow, Position } from '@tauri-apps/plugin-positioner'
+ *
+ * await moveWindow(Position.TopRight)
+ * ```
+ *
  * @param to The {@link Position} to move to.
+ * @since 2.0.0
  */
 export async function moveWindow(to: Position): Promise<void> {
   await invoke('plugin:positioner|move_window', {
@@ -44,7 +91,16 @@ export async function moveWindow(to: Position): Promise<void> {
  *
  * This move operation constrains the window to the screen dimensions in case of
  * tray-icon positions.
+ *
+ * @example
+ * ```typescript
+ * import { moveWindowConstrained, Position } from '@tauri-apps/plugin-positioner'
+ *
+ * await moveWindowConstrained(Position.TrayCenter)
+ * ```
+ *
  * @param to The (tray) {@link Position} to move to.
+ * @since 2.1.0
  */
 export async function moveWindowConstrained(to: Position): Promise<void> {
   await invoke('plugin:positioner|move_window_constrained', {
@@ -52,6 +108,30 @@ export async function moveWindowConstrained(to: Position): Promise<void> {
   })
 }
 
+/**
+ * Reports the tray icon's current position and size so the `Tray*` {@link Position} variants
+ * can be resolved.
+ *
+ * This is an internal helper meant to be called from the tray icon's event handler (the
+ * `action` callback passed to `TrayIcon.new()`), forwarding every {@link TrayIconEvent} it
+ * receives so that {@link moveWindow} and {@link moveWindowConstrained} can later position the
+ * window relative to the tray icon.
+ *
+ * @example
+ * ```typescript
+ * import { handleIconState } from '@tauri-apps/plugin-positioner'
+ * import { TrayIcon, type TrayIconEvent } from '@tauri-apps/api/tray'
+ *
+ * const action = async (event: TrayIconEvent) => {
+ *   await handleIconState(event)
+ * }
+ *
+ * const tray = await TrayIcon.new({ id: 'main', action })
+ * ```
+ *
+ * @param event The tray icon event to read the position and size from.
+ * @since 2.0.0
+ */
 export async function handleIconState(event: TrayIconEvent): Promise<void> {
   await invoke('plugin:positioner|set_tray_icon_state', {
     position: event.rect.position,

plugins/positioner/src/ext.rs

@@ -13,28 +13,53 @@ use tauri::Monitor;
 use tauri::{PhysicalPosition, PhysicalSize, Result, Runtime, WebviewWindow, Window};
 
 /// Well known window positions.
+///
+/// The `Tray*` variants require the `tray-icon` feature and only resolve once the tray icon has
+/// reported its position (see `on_tray_event`); using one before that happens returns an error.
 #[derive(Debug, Deserialize_repr)]
 #[repr(u16)]
 pub enum Position {
+    /// Top left corner of the current screen.
     TopLeft = 0,
+    /// Top right corner of the current screen.
     TopRight,
+    /// Bottom left corner of the current screen.
     BottomLeft,
+    /// Bottom right corner of the current screen.
     BottomRight,
+    /// Top center of the current screen.
     TopCenter,
+    /// Bottom center of the current screen.
     BottomCenter,
+    /// Vertically centered on the left edge of the current screen.
     LeftCenter,
+    /// Vertically centered on the right edge of the current screen.
     RightCenter,
+    /// Center of the current screen.
     Center,
+    /// Above the tray icon, aligning the window's left edge with the tray icon's left edge. On
+    /// Windows and macOS the window moves below the icon instead when there is not enough room
+    /// above.
     #[cfg(feature = "tray-icon")]
     TrayLeft,
+    /// Directly below the tray icon, aligning the window's left edge with the tray icon's left
+    /// edge.
     #[cfg(feature = "tray-icon")]
     TrayBottomLeft,
+    /// Above the tray icon, aligning the window's left edge with the tray icon's right edge. On
+    /// Windows and macOS the window moves below the icon instead when there is not enough room
+    /// above.
     #[cfg(feature = "tray-icon")]
     TrayRight,
+    /// Directly below the tray icon, aligning the window's left edge with the tray icon's right
+    /// edge.
     #[cfg(feature = "tray-icon")]
     TrayBottomRight,
+    /// Above the tray icon, horizontally centered on it. On Windows and macOS the window moves
+    /// below the icon instead when there is not enough room above.
     #[cfg(feature = "tray-icon")]
     TrayCenter,
+    /// Directly below the tray icon, horizontally centered on it.
     #[cfg(feature = "tray-icon")]
     TrayBottomCenter,
 }

plugins/positioner/src/lib.rs

@@ -31,6 +31,16 @@ use tauri::{tray::TrayIconEvent, AppHandle, Manager, PhysicalPosition, PhysicalS
 #[cfg(feature = "tray-icon")]
 struct Tray(std::sync::Mutex<Option<(PhysicalPosition<f64>, PhysicalSize<f64>)>>);
 
+/// Records the tray icon's latest position and size so that the `Tray*` [`Position`] variants
+/// (e.g. [`Position::TrayLeft`]) can be resolved by [`WindowExt::move_window`] and
+/// [`WindowExt::move_window_constrained`].
+///
+/// Call this from your tray icon's event handler. Only [`TrayIconEvent::Click`],
+/// [`TrayIconEvent::Enter`], [`TrayIconEvent::Leave`] and [`TrayIconEvent::Move`] carry the
+/// icon's position and update the tracked value; other events are ignored. Until this has been
+/// called at least once, moving a window to a `Tray*` position fails.
+///
+/// Requires the `tray-icon` feature.
 #[cfg(feature = "tray-icon")]
 pub fn on_tray_event<R: Runtime>(app: &AppHandle<R>, event: &TrayIconEvent) {
     let (position, size) = {