From 4f75bf5bdb98505b076463d432ac4270fc17b531 Mon Sep 17 00:00:00 2001
From: geeseofbeverlyroad
 <157734038+geeseofbeverlyroad@users.noreply.github.com>
Date: Mon, 5 May 2025 14:25:30 +0200
Subject: [PATCH] docs: Added more detailed comments to menu `popup` method and
 DPI-related classes (#13368)

* Detailed function description for popup()

* Expanded DPI class descriptions

* fmt

---------

Co-authored-by: Lucas Nogueira <lucas@tauri.app>
---
 packages/api/src/dpi.ts       | 13 +++++++++++++
 packages/api/src/menu/menu.ts |  3 ++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/api/src/dpi.ts b/packages/api/src/dpi.ts
index 714694d60..cf96901bc 100644
--- a/packages/api/src/dpi.ts
+++ b/packages/api/src/dpi.ts
@@ -6,6 +6,10 @@ import { SERIALIZE_TO_IPC_FN } from './core'
 
 /**
  * A size represented in logical pixels.
+ * Logical pixels are scaled according to the window's DPI scale.
+ * Most browser APIs (i.e. `MouseEvent`'s `clientX`) will return logical pixels.
+ *
+ * For logical-pixel-based position, see {@linkcode LogicalPosition}.
  *
  * @since 2.0.0
  */
@@ -72,6 +76,12 @@ class LogicalSize {
 /**
  * A size represented in physical pixels.
  *
+ * Physical pixels represent actual screen pixels, and are DPI-independent.
+ * For high-DPI windows, this means that any point in the window on the screen
+ * will have a different position in logical pixels (@linkcode LogicalSize).
+ *
+ * For physical-pixel-based position, see {@linkcode PhysicalPosition}.
+ *
  * @since 2.0.0
  */
 class PhysicalSize {
@@ -197,6 +207,7 @@ class Size {
 
 /**
  *  A position represented in logical pixels.
+ * For an explanation of what logical pixels are, see description of {@linkcode LogicalSize}.
  *
  * @since 2.0.0
  */
@@ -263,6 +274,8 @@ class LogicalPosition {
 /**
  *  A position represented in physical pixels.
  *
+ * For an explanation of what physical pixels are, see description of {@linkcode PhysicalSize}.
+ *
  * @since 2.0.0
  */
 class PhysicalPosition {
diff --git a/packages/api/src/menu/menu.ts b/packages/api/src/menu/menu.ts
index aefef713a..c4a3191b3 100644
--- a/packages/api/src/menu/menu.ts
+++ b/packages/api/src/menu/menu.ts
@@ -213,7 +213,8 @@ export class Menu extends MenuItemBase {
   /**
    * Popup this menu as a context menu on the specified window.
    *
-   * If the position, is provided, it is relative to the window's top-left corner.
+   * @param at If a position is provided, it is relative to the window's top-left corner.
+   * If there isn't one provided, the menu will pop up at the current location of the mouse.
    */
   async popup(
     at?: PhysicalPosition | LogicalPosition | Position,