From 5beec06d9d0056e0168a10bd6a8252e9259a1399 Mon Sep 17 00:00:00 2001
From: GriffinR <griffin.g.richards@gmail.com>
Date: Sat, 19 Aug 2023 17:20:53 -0400
Subject: [PATCH] Document Task_MapNamePopUpWindow

---
 src/map_name_popup.c | 97 ++++++++++++++++++++++++++++----------------
 1 file changed, 62 insertions(+), 35 deletions(-)

diff --git a/src/map_name_popup.c b/src/map_name_popup.c
index 93a2825833..7e5fbc9095 100644
--- a/src/map_name_popup.c
+++ b/src/map_name_popup.c
@@ -206,22 +206,45 @@ static bool8 StartMenu_ShowMapNamePopup(void)
     return TRUE;
 }
 
+// States and data defines for Task_MapNamePopUpWindow
+enum {
+    STATE_SLIDE_IN,
+    STATE_WAIT,
+    STATE_SLIDE_OUT,
+    STATE_UNUSED,
+    STATE_ERASE,
+    STATE_END,
+    STATE_PRINT, // For some reason the first state is numerically last.
+};
+
+#define POPUP_OFFSCREEN_Y  40
+#define POPUP_SLIDE_SPEED  2
+
+#define tState         data[0]
+#define tOnscreenTimer data[1]
+#define tYOffset       data[2]
+#define tIncomingPopUp data[3]
+#define tPrintTimer    data[4]
+
 void ShowMapNamePopup(void)
 {
     if (FlagGet(FLAG_HIDE_MAP_NAME_POPUP) != TRUE)
     {
         if (!FuncIsActiveTask(Task_MapNamePopUpWindow))
         {
+            // New pop up window
             sPopupTaskId = CreateTask(Task_MapNamePopUpWindow, 90);
-            SetGpuReg(REG_OFFSET_BG0VOFS, 40);
-            gTasks[sPopupTaskId].data[0] = 6;
-            gTasks[sPopupTaskId].data[2] = 40;
+            SetGpuReg(REG_OFFSET_BG0VOFS, POPUP_OFFSCREEN_Y);
+            gTasks[sPopupTaskId].tState = STATE_PRINT;
+            gTasks[sPopupTaskId].tYOffset = POPUP_OFFSCREEN_Y;
         }
         else
         {
-            if (gTasks[sPopupTaskId].data[0] != 2)
-                gTasks[sPopupTaskId].data[0] = 2;
-            gTasks[sPopupTaskId].data[3] = 1;
+            // There's already a pop up window running.
+            // Hurry the old pop up offscreen so the new one can appear.
+            if (gTasks[sPopupTaskId].tState != STATE_SLIDE_OUT)
+                gTasks[sPopupTaskId].tState = STATE_SLIDE_OUT;
+            gTasks[sPopupTaskId].tIncomingPopUp = TRUE;
         }
     }
 }
@@ -230,61 +253,65 @@ static void Task_MapNamePopUpWindow(u8 taskId)
 {
     struct Task *task = &gTasks[taskId];
 
-    switch (task->data[0])
+    switch (task->tState)
     {
-    case 6:
-        task->data[4]++;
-        if (task->data[4] > 30)
+    case STATE_PRINT:
+        // Wait, then create and print the pop up window
+        if (++task->tPrintTimer > 30)
         {
-            task->data[0] = 0;
-            task->data[4] = 0;
+            task->tState = STATE_SLIDE_IN;
+            task->tPrintTimer = 0;
             ShowMapNamePopUpWindow();
         }
         break;
-    case 0:
-        task->data[2] -= 2;
-        if (task->data[2] <= 0 )
+    case STATE_SLIDE_IN:
+        // Slide the window onscreen.
+        task->tYOffset -= POPUP_SLIDE_SPEED;
+        if (task->tYOffset <= 0 )
         {
-            task->data[2] = 0;
-            task->data[0] = 1;
+            task->tYOffset = 0;
+            task->tState = STATE_WAIT;
             gTasks[sPopupTaskId].data[1] = 0;
         }
         break;
-    case 1:
-        task->data[1]++;
-        if (task->data[1] > 120 )
+    case STATE_WAIT:
+        // Wait while the window is fully onscreen.
+        if (++task->tOnscreenTimer > 120)
         {
-            task->data[1] = 0;
-            task->data[0] = 2;
+            task->tOnscreenTimer = 0;
+            task->tState = STATE_SLIDE_OUT;
         }
         break;
-    case 2:
-        task->data[2] += 2;
-        if (task->data[2] > 39)
+    case STATE_SLIDE_OUT:
+        // Slide the window offscreen.
+        task->tYOffset += POPUP_SLIDE_SPEED;
+        if (task->tYOffset >= POPUP_OFFSCREEN_Y)
         {
-            task->data[2] = 40;
-            if (task->data[3])
+            task->tYOffset = POPUP_OFFSCREEN_Y;
+            if (task->tIncomingPopUp)
             {
-                task->data[0] = 6;
-                task->data[4] = 0;
-                task->data[3] = 0;
+                // A new pop up window is incoming,
+                // return to the first state to show it.
+                task->tState = STATE_PRINT;
+                task->tPrintTimer = 0;
+                task->tIncomingPopUp = FALSE;
             }
             else
             {
-                task->data[0] = 4;
+                task->tState = STATE_ERASE;
                 return;
             }
         }
         break;
-    case 4:
+    case STATE_ERASE:
         ClearStdWindowAndFrame(GetMapNamePopUpWindowId(), TRUE);
-        task->data[0] = 5;
+        task->tState = STATE_END;
         break;
-    case 5:
+    case STATE_END:
         HideMapNamePopUpWindow();
         return;
     }
-    SetGpuReg(REG_OFFSET_BG0VOFS, task->data[2]);
+    SetGpuReg(REG_OFFSET_BG0VOFS, task->tYOffset);
 }
 
 void HideMapNamePopUpWindow(void)