From cc19c08ec13613db6b4b05e0cbd95e9e635af66c Mon Sep 17 00:00:00 2001
From: Casey Eickhoff <ceickhoff@adobe.com>
Date: Tue, 3 Dec 2024 17:55:40 -0700
Subject: [PATCH] chore: overlay docs and comments

---
 packages/overlay/src/Overlay.ts | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/packages/overlay/src/Overlay.ts b/packages/overlay/src/Overlay.ts
index 1539847f99..fb0011c0fe 100644
--- a/packages/overlay/src/Overlay.ts
+++ b/packages/overlay/src/Overlay.ts
@@ -664,18 +664,32 @@ export class Overlay extends ComputedOverlayBase {
         event.relatedTarget.dispatchEvent(relationEvent);
     };
 
+    /**
+     * Manages the process of opening or closing the overlay.
+     *
+     * This method handles the necessary steps to open or close the overlay, including updating the state,
+     * managing the overlay stack, and handling focus events.
+     *
+     * @protected
+     * @param {boolean} oldOpen - The previous open state of the overlay.
+     * @returns {Promise<void>} A promise that resolves when the overlay has been fully managed.
+     */
     protected async manageOpen(oldOpen: boolean): Promise<void> {
+        // Prevent entering the manage workflow if the overlay is not connected to the DOM.
         // The `.showPopover()` and `.showModal()` events will error on content that is not connected to the DOM.
-        // Prevent from entering the manage workflow in order to avoid this.
         if (!this.isConnected && this.open) return;
 
+        // Wait for the component to finish updating if it has not already done so.
         if (!this.hasUpdated) {
             await this.updateComplete;
         }
 
         if (this.open) {
+            // Add the overlay to the overlay stack.
             overlayStack.add(this);
+
             if (this.willPreventClose) {
+                // Add an event listener to handle the pointerup event and toggle the 'not-immediately-closable' class.
                 document.addEventListener(
                     'pointerup',
                     () => {
@@ -694,21 +708,29 @@ export class Overlay extends ComputedOverlayBase {
             }
         } else {
             if (oldOpen) {
+                // Dispose of the overlay if it was previously open.
                 this.dispose();
             }
+
+            // Remove the overlay from the overlay stack.
             overlayStack.remove(this);
         }
+
+        // Update the state of the overlay based on the open property.
         if (this.open && this.state !== 'opened') {
             this.state = 'opening';
         } else if (!this.open && this.state !== 'closed') {
             this.state = 'closing';
         }
 
+        // Manage the dialog or popover based on the overlay type.
         if (this.usesDialog) {
             this.manageDialogOpen();
         } else {
             this.managePopoverOpen();
         }
+
+        // Handle focus events for auto type overlays.
         if (this.type === 'auto') {
             const listenerRoot = this.getRootNode() as Document;
             if (this.open) {