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 <[email protected]>

Author: geeseofbeverlyroad

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 {

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,