Docs: document why the eventstate is cleared while refreshing a popup

Also correct a comments grammar.

scripts/startup/bl_operators/wm.py

@@ -1286,7 +1286,7 @@ class WM_OT_doc_view_manual(Operator):
         # Adding case into all ID's isn't worth the hassle so force lowercase.
         rna_id = rna_id.lower()
 
-        # NOTE: `fnmatch` in Python is slow as it translate the string to a regular-expression
+        # NOTE: `fnmatch` in Python is slow as it translates the string to a regular-expression
         # which needs to be compiled (as of Python 3.11), this is slow enough to cause a noticeable
         # delay when opening manual links (approaching half a second).
         #

source/blender/editors/interface/regions/interface_region_popup.cc

@@ -649,7 +649,19 @@ uiBlock *ui_popup_block_refresh(bContext *C,
   /* callbacks _must_ leave this for us, otherwise we can't call UI_block_update_from_old */
   BLI_assert(!block->endblock);
 
-  /* ensure we don't use mouse coords here! */
+  /* Ensure we don't use mouse coords here.
+   *
+   * NOTE(@ideasman42): Important because failing to do will cause glitches refreshing the popup.
+   *
+   * - Many popups use #wmEvent::xy to position them.
+   * - Refreshing a pop-up must only ever change it's contents. Consider that refreshing
+   *   might be used to show a menu item as grayed out, or change a text label,
+   *   we *never* want the popup to move based on the cursor location while refreshing.
+   * - The location of the cursor at the time of creation is stored in:
+   *   `handle->popup_create_vars.event_xy` which must be used instead.
+   *
+   * Since it's difficult to control logic which is called indirectly here,
+   * clear the `eventstate` entirely to ensure it's never used when refreshing a popup. */
 #ifndef NDEBUG
   window->eventstate = nullptr;
 #endif