Cleanup: comments in wm_event_system.c

1 files changed, 158 insertions, 149 deletions

diff --git a/source/blender/windowmanager/intern/wm_event_system.c b/source/blender/windowmanager/intern/wm_event_system.c
index b531467c52d..cd8be110c36 100644
--- a/source/blender/windowmanager/intern/wm_event_system.c
+++ b/source/blender/windowmanager/intern/wm_event_system.c
@@ -4,7 +4,7 @@
 /** \file
  * \ingroup wm
  *
- * Handle events and notifiers from GHOST input (mouse, keyboard, tablet, ndof).
+ * Handle events and notifiers from GHOST input (mouse, keyboard, tablet, NDOF).
  *
  * Also some operator reports utility functions.
  */
@@ -174,7 +174,7 @@ void wm_event_free(wmEvent *event)
 
   if (event->customdata) {
     if (event->customdata_free) {
-      /* NOTE: pointer to listbase struct elsewhere. */
+      /* NOTE: pointer to #ListBase struct elsewhere. */
       if (event->custom == EVT_DATA_DRAGDROP) {
         ListBase *lb = event->customdata;
         WM_drag_free_list(lb);
@@ -335,21 +335,19 @@ void WM_main_remap_editor_id_reference(const struct IDRemapper *mappings)
 
 static void wm_notifier_clear(wmNotifier *note)
 {
-  /* NULL the entire notifier, only leaving (next, prev) members intact. */
+  /* NULL the entire notifier, only leaving (`next`, `prev`) members intact. */
   memset(((char *)note) + sizeof(Link), 0, sizeof(*note) - sizeof(Link));
 }
 
 void wm_event_do_depsgraph(bContext *C, bool is_after_open_file)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
-  /* The whole idea of locked interface is to prevent viewport and whatever
-   * thread from modifying the same data. Because of this, we can not perform
-   * dependency graph update.
-   */
+  /* The whole idea of locked interface is to prevent viewport and whatever thread from
+   * modifying the same data. Because of this, we can not perform dependency graph update. */
   if (wm->is_interface_locked) {
     return;
   }
-  /* Combine datamasks so one window doesn't disable UV's in another T26448. */
+  /* Combine data-masks so one window doesn't disable UV's in another T26448. */
   CustomData_MeshMasks win_combine_v3d_datamask = {0};
   LISTBASE_FOREACH (wmWindow *, win, &wm->windows) {
     const Scene *scene = WM_window_get_active_scene(win);
@@ -364,14 +362,13 @@ void wm_event_do_depsgraph(bContext *C, bool is_after_open_file)
     Main *bmain = CTX_data_main(C);
     /* Copied to set's in scene_update_tagged_recursive() */
     scene->customdata_mask = win_combine_v3d_datamask;
-    /* XXX, hack so operators can enforce datamasks T26482, gl render */
+    /* XXX, hack so operators can enforce data-masks T26482, GPU render. */
     CustomData_MeshMasks_update(&scene->customdata_mask, &scene->customdata_mask_modal);
     /* TODO(sergey): For now all dependency graphs which are evaluated from
      * workspace are considered active. This will work all fine with "locked"
      * view layer and time across windows. This is to be granted separately,
      * and for until then we have to accept ambiguities when object is shared
-     * across visible view layers and has overrides on it.
-     */
+     * across visible view layers and has overrides on it. */
     Depsgraph *depsgraph = BKE_scene_ensure_depsgraph(bmain, scene, view_layer);
     if (is_after_open_file) {
       DEG_graph_tag_on_visible_update(depsgraph, true);
@@ -421,7 +418,7 @@ static void wm_event_execute_timers(bContext *C)
 
 void wm_event_do_notifiers(bContext *C)
 {
-  /* Run the timer before assigning 'wm' in the unlikely case a timer loads a file, see T80028. */
+  /* Run the timer before assigning `wm` in the unlikely case a timer loads a file, see T80028. */
   wm_event_execute_timers(C);
 
   wmWindowManager *wm = CTX_wm_manager(C);
@@ -468,7 +465,7 @@ void wm_event_do_notifiers(bContext *C)
             WorkSpace *workspace = note->reference;
 
             ED_workspace_delete(
-                workspace, CTX_data_main(C), C, wm); /* XXX hrms, think this over! */
+                workspace, CTX_data_main(C), C, wm); /* XXX: hum, think this over! */
             if (G.debug & G_DEBUG_EVENTS) {
               printf("%s: Workspace delete %p\n", __func__, workspace);
             }
@@ -476,10 +473,10 @@ void wm_event_do_notifiers(bContext *C)
           else if (note->data == ND_LAYOUTBROWSE) {
             bScreen *ref_screen = BKE_workspace_layout_screen_get(note->reference);
 
-            /* free popup handlers only T35434. */
+            /* Free popup handlers only T35434. */
             UI_popup_handlers_remove_all(C, &win->modalhandlers);
 
-            ED_screen_change(C, ref_screen); /* XXX hrms, think this over! */
+            ED_screen_change(C, ref_screen); /* XXX: hum, think this over! */
             if (G.debug & G_DEBUG_EVENTS) {
               printf("%s: screen set %p\n", __func__, note->reference);
             }
@@ -488,7 +485,7 @@ void wm_event_do_notifiers(bContext *C)
             WorkSpace *workspace = WM_window_get_active_workspace(win);
             WorkSpaceLayout *layout = note->reference;
 
-            ED_workspace_layout_delete(workspace, layout, C); /* XXX hrms, think this over! */
+            ED_workspace_layout_delete(workspace, layout, C); /* XXX: hum, think this over! */
             if (G.debug & G_DEBUG_EVENTS) {
               printf("%s: screen delete %p\n", __func__, note->reference);
             }
@@ -517,9 +514,9 @@ void wm_event_do_notifiers(bContext *C)
 
     if (do_anim) {
 
-      /* XXX, quick frame changes can cause a crash if framechange and rendering
+      /* XXX: quick frame changes can cause a crash if frame-change and rendering
        * collide (happens on slow scenes), BKE_scene_graph_update_for_newframe can be called
-       * twice which can depgraph update the same object at once */
+       * twice which can depsgraph update the same object at once. */
       if (G.is_rendering == false) {
         /* Depsgraph gets called, might send more notifiers. */
         Depsgraph *depsgraph = CTX_data_depsgraph_pointer(C);
@@ -598,7 +595,7 @@ void wm_event_do_notifiers(bContext *C)
 
     MEM_freeN(note);
   }
-#endif /* if 1 (postpone disabling for in favor of message-bus), eventually. */
+#endif /* If 1 (postpone disabling for in favor of message-bus), eventually. */
 
   /* Handle message bus. */
   {
@@ -611,7 +608,7 @@ void wm_event_do_notifiers(bContext *C)
 
   wm_event_do_refresh_wm_and_depsgraph(C);
 
-  /* Status bar */
+  /* Status bar. */
   if (wm->winactive) {
     wmWindow *win = wm->winactive;
     CTX_wm_window_set(C, win);
@@ -661,14 +658,14 @@ static int wm_handler_ui_call(bContext *C,
   const bool is_wheel = ELEM(event->type, WHEELUPMOUSE, WHEELDOWNMOUSE, MOUSEPAN);
 
   /* UI code doesn't handle return values - it just always returns break.
-   * to make the DBL_CLICK conversion work, we just don't send this to UI, except mouse clicks. */
+   * to make the #DBL_CLICK conversion work, we just don't send this to UI, except mouse clicks. */
   if (((handler->head.flag & WM_HANDLER_ACCEPT_DBL_CLICK) == 0) && !ISMOUSE_BUTTON(event->type) &&
       (event->val == KM_DBL_CLICK)) {
     return WM_HANDLER_CONTINUE;
   }
 
   /* UI is quite aggressive with swallowing events, like scroll-wheel. */
-  /* I realize this is not extremely nice code... when UI gets keymaps it can be maybe smarter. */
+  /* I realize this is not extremely nice code... when UI gets key-maps it can be maybe smarter. */
   if (do_wheel_ui == false) {
     if (is_wheel) {
       return WM_HANDLER_CONTINUE;
@@ -697,7 +694,7 @@ static int wm_handler_ui_call(bContext *C,
 
   int retval = handler->handle_fn(C, event, handler->user_data);
 
-  /* putting back screen context */
+  /* Putting back screen context. */
   if ((retval != WM_UI_HANDLER_BREAK) || always_pass) {
     CTX_wm_area_set(C, area);
     CTX_wm_region_set(C, region);
@@ -714,7 +711,7 @@ static int wm_handler_ui_call(bContext *C,
     return WM_HANDLER_BREAK;
   }
 
-  /* event not handled in UI, if wheel then we temporarily disable it */
+  /* Event not handled in UI, if wheel then we temporarily disable it. */
   if (is_wheel) {
     do_wheel_ui = false;
   }
@@ -768,7 +765,7 @@ void WM_report_banner_show(void)
   /* After adding reports to the global list, reset the report timer. */
   WM_event_remove_timer(wm, NULL, wm_reports->reporttimer);
 
-  /* Records time since last report was added */
+  /* Records time since last report was added. */
   wm_reports->reporttimer = WM_event_add_timer(wm, wm->winactive, TIMERREPORT, 0.05);
 
   ReportTimerInfo *rti = MEM_callocN(sizeof(ReportTimerInfo), "ReportTimerInfo");
@@ -795,7 +792,7 @@ static void wm_add_reports(ReportList *reports)
   if (reports->list.first && (reports->flag & RPT_OP_HOLD) == 0) {
     wmWindowManager *wm = G_MAIN->wm.first;
 
-    /* add reports to the global list, otherwise they are not seen */
+    /* Add reports to the global list, otherwise they are not seen. */
     BLI_movelisttolist(&wm->reports.list, &reports->list);
 
     WM_report_banner_show();
@@ -905,10 +902,12 @@ void WM_operator_region_active_win_set(bContext *C)
   }
 }
 
-/* (caller_owns_reports == true) when called from python. */
+/**
+ * \param caller_owns_reports: True when called from Python.
+ */
 static void wm_operator_reports(bContext *C, wmOperator *op, int retval, bool caller_owns_reports)
 {
-  if (G.background == 0 && caller_owns_reports == false) { /* popup */
+  if (G.background == 0 && caller_owns_reports == false) { /* Popup. */
     if (op->reports->list.first) {
       /* FIXME: temp setting window, see other call to #UI_popup_menu_reports for why. */
       wmWindow *win_prev = CTX_wm_window(C);
@@ -944,7 +943,7 @@ static void wm_operator_reports(bContext *C, wmOperator *op, int retval, bool ca
     }
   }
 
-  /* Refresh Info Editor with reports immediately, even if op returned OPERATOR_CANCELLED. */
+  /* Refresh Info Editor with reports immediately, even if op returned #OPERATOR_CANCELLED. */
   if ((retval & OPERATOR_CANCELLED) && !BLI_listbase_is_empty(&op->reports->list)) {
     WM_event_add_notifier(C, NC_SPACE | ND_SPACE_INFO_REPORT, NULL);
   }
@@ -1004,7 +1003,7 @@ static void wm_operator_finished(bContext *C, wmOperator *op, const bool repeat,
     }
 
     if (wm_operator_register_check(wm, op->type)) {
-      /* take ownership of reports (in case python provided own) */
+      /* Take ownership of reports (in case python provided own). */
       op->reports->flag |= RPT_FREE;
 
       wm_operator_register(C, op);
@@ -1036,7 +1035,9 @@ static void wm_operator_finished(bContext *C, wmOperator *op, const bool repeat,
   }
 }
 
-/* If repeat is true, it doesn't register again, nor does it free. */
+/**
+ * \param repeat: When true, it doesn't register again, nor does it free.
+ */
 static int wm_operator_exec(bContext *C, wmOperator *op, const bool repeat, const bool store)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
@@ -1076,7 +1077,7 @@ static int wm_operator_exec(bContext *C, wmOperator *op, const bool repeat, cons
     wm_operator_finished(C, op, repeat, store && wm->op_undo_depth == 0);
   }
   else if (repeat == 0) {
-    /* warning: modal from exec is bad practice, but avoid crashing. */
+    /* WARNING: modal from exec is bad practice, but avoid crashing. */
     if (retval & (OPERATOR_FINISHED | OPERATOR_CANCELLED)) {
       WM_operator_free(op);
     }
@@ -1085,7 +1086,9 @@ static int wm_operator_exec(bContext *C, wmOperator *op, const bool repeat, cons
   return retval | OPERATOR_HANDLED;
 }
 
-/* Simply calls exec with basic checks. */
+/**
+ * Simply calls exec with basic checks.
+ */
 static int wm_operator_exec_notest(bContext *C, wmOperator *op)
 {
   int retval = OPERATOR_CANCELLED;
@@ -1137,7 +1140,7 @@ bool WM_operator_repeat_check(const bContext *UNUSED(C), wmOperator *op)
     return true;
   }
   if (op->opm) {
-    /* for macros, check all have exec() we can call */
+    /* For macros, check all have exec() we can call. */
     LISTBASE_FOREACH (wmOperatorTypeMacro *, macro, &op->opm->type->macro) {
       wmOperatorType *otm = WM_operatortype_find(macro->idname, 0);
       if (otm && otm->exec == NULL) {
@@ -1169,10 +1172,10 @@ static wmOperator *wm_operator_create(wmWindowManager *wm,
                                       PointerRNA *properties,
                                       ReportList *reports)
 {
-  /* XXX operatortype names are static still. for debug */
+  /* Operator-type names are static still. pass to allocation name for debugging. */
   wmOperator *op = MEM_callocN(sizeof(wmOperator), ot->idname);
 
-  /* XXX adding new operator could be function, only happens here now */
+  /* Adding new operator could be function, only happens here now. */
   op->type = ot;
   BLI_strncpy(op->idname, ot->idname, OP_MAX_TYPENAME);
 
@@ -1262,7 +1265,7 @@ static void wm_region_mouse_co(bContext *C, wmEvent *event)
     event->mval[1] = event->xy[1] - region->winrct.ymin;
   }
   else {
-    /* These values are invalid (avoid odd behavior by relying on old mval values). */
+    /* These values are invalid (avoid odd behavior by relying on old #wmEvent.mval values). */
     event->mval[0] = -1;
     event->mval[1] = -1;
   }
@@ -1290,7 +1293,7 @@ static int wm_operator_invoke(bContext *C,
   if (WM_operator_poll(C, ot)) {
     wmWindowManager *wm = CTX_wm_manager(C);
 
-    /* If reports == NULL, they'll be initialized. */
+    /* If `reports == NULL`, they'll be initialized. */
     wmOperator *op = wm_operator_create(wm, ot, properties, reports);
 
     const bool is_nested_call = (wm->op_undo_depth != 0);
@@ -1300,7 +1303,7 @@ static int wm_operator_invoke(bContext *C,
     }
 
     /* Initialize setting from previous run. */
-    if (!is_nested_call && use_last_properties) { /* Not called by py script. */
+    if (!is_nested_call && use_last_properties) { /* Not called by a Python script. */
       WM_operator_last_properties_init(op);
     }
 
@@ -1352,7 +1355,7 @@ static int wm_operator_invoke(bContext *C,
     }
 
     if (retval & OPERATOR_HANDLED) {
-      /* Do nothing, wm_operator_exec() has been called somewhere. */
+      /* Do nothing, #wm_operator_exec() has been called somewhere. */
     }
     else if (retval & OPERATOR_FINISHED) {
       const bool store = !is_nested_call && use_last_properties;
@@ -1362,9 +1365,8 @@ static int wm_operator_invoke(bContext *C,
       /* Take ownership of reports (in case python provided own). */
       op->reports->flag |= RPT_FREE;
 
-      /* Grab cursor during blocking modal ops (X11)
-       * Also check for macro.
-       */
+      /* Grab cursor during blocking modal operators (X11)
+       * Also check for macro. */
       if (ot->flag & OPTYPE_BLOCKING || (op->opm && op->opm->type->flag & OPTYPE_BLOCKING)) {
         int bounds[4] = {-1, -1, -1, -1};
         int wrap = WM_CURSOR_WRAP_NONE;
@@ -1413,7 +1415,7 @@ static int wm_operator_invoke(bContext *C,
         WM_cursor_grab_enable(CTX_wm_window(C), wrap, false, bounds);
       }
 
-      /* Cancel UI handlers, typically tooltips that can hang around
+      /* Cancel UI handlers, typically tool-tips that can hang around
        * while dragging the view or worse, that stay there permanently
        * after the modal operator has swallowed all events and passed
        * none to the UI handler. */
@@ -1494,8 +1496,7 @@ static int wm_operator_call_internal(bContext *C,
       case WM_OP_EXEC_REGION_PREVIEW:
       case WM_OP_INVOKE_REGION_PREVIEW: {
         /* Forces operator to go to the region window/channels/preview, for header menus,
-         * but we stay in the same region if we are already in one.
-         */
+         * but we stay in the same region if we are already in one. */
         ARegion *region = CTX_wm_region(C);
         ScrArea *area = CTX_wm_area(C);
         int type = RGN_TYPE_WINDOW;
@@ -1826,7 +1827,7 @@ void WM_operator_name_call_ptr_with_depends_on_cursor(bContext *C,
 
 void wm_event_free_handler(wmEventHandler *handler)
 {
-  /* Future extra customa-data free? */
+  /* Future extra custom-data free? */
   MEM_freeN(handler);
 }
 
@@ -1834,7 +1835,7 @@ void wm_event_free_handler(wmEventHandler *handler)
 static void wm_handler_op_context(bContext *C, wmEventHandler_Op *handler, const wmEvent *event)
 {
   wmWindow *win = handler->context.win ? handler->context.win : CTX_wm_window(C);
-  /* It's probably fine to always use WM_window_get_active_screen() to get the screen. But this
+  /* It's probably fine to always use #WM_window_get_active_screen() to get the screen. But this
    * code has been getting it through context since forever, so play safe and stick to that when
    * possible. */
   bScreen *screen = handler->context.win ? WM_window_get_active_screen(win) : CTX_wm_screen(C);
@@ -1889,7 +1890,7 @@ static void wm_handler_op_context(bContext *C, wmEventHandler_Op *handler, const
         }
       }
 
-      /* XXX no warning print here, after full-area and back regions are remade. */
+      /* No warning print here, after full-area and back regions are remade. */
       if (region) {
         CTX_wm_region_set(C, region);
       }
@@ -1901,7 +1902,7 @@ void WM_event_remove_handlers(bContext *C, ListBase *handlers)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
 
-  /* C is zero on freeing database, modal handlers then already were freed */
+  /* C is zero on freeing database, modal handlers then already were freed. */
   wmEventHandler *handler_base;
   while ((handler_base = BLI_pophead(handlers))) {
     BLI_assert(handler_base->type != 0);
@@ -1993,8 +1994,8 @@ static bool wm_eventmatch(const wmEvent *winevent, const wmKeyMapItem *kmi)
   /* The matching rules. */
   if (kmitype == KM_TEXTINPUT) {
     if (winevent->val == KM_PRESS) { /* Prevent double clicks. */
-      /* NOT using ISTEXTINPUT anymore because (at least on Windows) some key codes above 255
-       * could have printable ascii keys - BUG T30479. */
+      /* Not using #ISTEXTINPUT anymore because (at least on Windows) some key codes above 255
+       * could have printable ascii keys, See T30479. */
       if (ISKEYBOARD(winevent->type) && (winevent->ascii || winevent->utf8_buf[0])) {
         return true;
       }
@@ -2006,7 +2007,7 @@ static bool wm_eventmatch(const wmEvent *winevent, const wmKeyMapItem *kmi)
       const wmTabletData *wmtab = &winevent->tablet;
 
       if (winevent->type != LEFTMOUSE) {
-        /* Tablet events can occur on hover + keypress. */
+        /* Tablet events can occur on hover + key-press. */
         return false;
       }
       if ((kmitype == TABLET_STYLUS) && (wmtab->active != EVT_TABLET_STYLUS)) {
@@ -2063,7 +2064,7 @@ static bool wm_eventmatch(const wmEvent *winevent, const wmKeyMapItem *kmi)
     }
   }
 
-  /* Only keymap entry with keymodifier is checked,
+  /* Only key-map entry with key-modifier is checked,
    * means all keys without modifier get handled too. */
   /* That is currently needed to make overlapping events work (when you press A - G fast or so). */
   if (kmi->keymodifier) {
@@ -2101,7 +2102,7 @@ struct wmEvent_ModalMapStore {
 /**
  * This function prepares events for use with #wmOperatorType.modal by:
  *
- * - Matching keymap items with the operators modal keymap.
+ * - Matching key-map items with the operators modal key-map.
  * - Converting double click events into press events,
  *   allowing them to be restored when the events aren't handled.
  *
@@ -2115,7 +2116,7 @@ static void wm_event_modalkeymap_begin(const bContext *C,
 {
   BLI_assert(event->type != EVT_MODAL_MAP);
 
-  /* Support for modal keymap in macros. */
+  /* Support for modal key-map in macros. */
   if (op->opm) {
     op = op->opm;
   }
@@ -2149,8 +2150,8 @@ static void wm_event_modalkeymap_begin(const bContext *C,
       event->type = EVT_MODAL_MAP;
       event->val = kmi->propvalue;
 
-      /* Avoid double-click events even in the case of 'EVT_MODAL_MAP',
-       * since it's possible users configure double-click keymap items
+      /* Avoid double-click events even in the case of #EVT_MODAL_MAP,
+       * since it's possible users configure double-click key-map items
        * which would break when modal functions expect press/release. */
       if (event->prev_type == KM_DBL_CLICK) {
         event->prev_type = KM_PRESS;
@@ -2191,7 +2192,9 @@ static void wm_event_modalkeymap_end(wmEvent *event,
   }
 }
 
-/* Warning: this function removes a modal handler, when finished */
+/**
+ * \warning this function removes a modal handler, when finished.
+ */
 static int wm_handler_operator_call(bContext *C,
                                     ListBase *handlers,
                                     wmEventHandler *handler_base,
@@ -2210,8 +2213,7 @@ static int wm_handler_operator_call(bContext *C,
 
     if (!wm_operator_check_locked_interface(C, ot)) {
       /* Interface is locked and operator is not allowed to run,
-       * nothing to do in this case.
-       */
+       * nothing to do in this case. */
     }
     else if (ot->modal) {
       /* We set context to where modal handler came from. */
@@ -2259,7 +2261,7 @@ static int wm_handler_operator_call(bContext *C,
           }
         }
 
-        /* Important to run 'wm_operator_finished' before NULLing the context members. */
+        /* Important to run 'wm_operator_finished' before NULL-ing the context members. */
         if (retval & OPERATOR_FINISHED) {
           wm_operator_finished(C, op, false, true);
           handler->op = NULL;
@@ -2269,7 +2271,7 @@ static int wm_handler_operator_call(bContext *C,
           handler->op = NULL;
         }
 
-        /* Putting back screen context, reval can pass through after modal failures! */
+        /* Putting back screen context, `reval` can pass through after modal failures! */
         if ((retval & OPERATOR_PASS_THROUGH) || wm_event_always_pass(event)) {
           CTX_wm_area_set(C, area);
           CTX_wm_region_set(C, region);
@@ -2290,7 +2292,7 @@ static int wm_handler_operator_call(bContext *C,
           BLI_remlink(handlers, handler);
           wm_event_free_handler(&handler->head);
 
-          /* prevent silly errors from operator users */
+          /* Prevent silly errors from operator users. */
           // retval &= ~OPERATOR_PASS_THROUGH;
         }
       }
@@ -2334,7 +2336,7 @@ static int wm_handler_operator_call(bContext *C,
         WM_operator_properties_free(&tool_properties);
       }
 
-      /* Link gizmo if 'WM_GIZMOGROUPTYPE_TOOL_INIT' is set. */
+      /* Link gizmo if #WM_GIZMOGROUPTYPE_TOOL_INIT is set. */
       if (retval & OPERATOR_FINISHED) {
         if (is_tool) {
           bToolRef_Runtime *tref_rt = keymap_tool->runtime;
@@ -2361,7 +2363,6 @@ static int wm_handler_operator_call(bContext *C,
       /* Done linking gizmo. */
     }
   }
-  /* Finished and pass through flag as handled. */
 
   /* Finished and pass through flag as handled. */
   if (retval == (OPERATOR_FINISHED | OPERATOR_PASS_THROUGH)) {
@@ -2380,8 +2381,10 @@ static int wm_handler_operator_call(bContext *C,
   return WM_HANDLER_BREAK;
 }
 
-/* Fileselect handlers are only in the window queue,
- * so it's safe to switch screens or area types. */
+/**
+ * File-select handlers are only in the window queue,
+ * so it's safe to switch screens or area types.
+ */
 static int wm_handler_fileselect_do(bContext *C,
                                     ListBase *handlers,
                                     wmEventHandler_Op *handler,
@@ -2409,10 +2412,10 @@ static int wm_handler_fileselect_do(bContext *C,
         BLI_assert(area->spacetype == SPACE_FILE);
 
         region_header->flag |= RGN_FLAG_HIDDEN;
-        /* Header on bottom, AZone triangle to toggle header looks misplaced at the top. */
+        /* Header on bottom, #AZone triangle to toggle header looks misplaced at the top. */
         region_header->alignment = RGN_ALIGN_BOTTOM;
 
-        /* Settings for filebrowser, #sfile is not operator owner but sends events. */
+        /* Settings for file-browser, #sfile is not operator owner but sends events. */
         SpaceFile *sfile = (SpaceFile *)area->spacedata.first;
         sfile->op = handler->op;
 
@@ -2454,9 +2457,9 @@ static int wm_handler_fileselect_do(bContext *C,
           }
 
           if (file_area->full) {
-            /* Users should not be able to maximize/fullscreen an area in a temporary screen. So if
-             * there's a maximized file browser in a temporary screen, it was likely opened by
-             * #EVT_FILESELECT_FULL_OPEN. */
+            /* Users should not be able to maximize/full-screen an area in a temporary screen.
+             * So if there's a maximized file browser in a temporary screen,
+             * it was likely opened by #EVT_FILESELECT_FULL_OPEN. */
             continue;
           }
 
@@ -2471,10 +2474,10 @@ static int wm_handler_fileselect_do(bContext *C,
             wm_window_close(C, wm, win);
 
             CTX_wm_window_set(C, ctx_win); /* #wm_window_close() NULLs. */
-            /* Some operators expect a drawable context (for EVT_FILESELECT_EXEC). */
+            /* Some operators expect a drawable context (for #EVT_FILESELECT_EXEC). */
             wm_window_make_drawable(wm, ctx_win);
             /* Ensure correct cursor position, otherwise, popups may close immediately after
-             * opening (UI_BLOCK_MOVEMOUSE_QUIT). */
+             * opening (#UI_BLOCK_MOVEMOUSE_QUIT). */
             wm_cursor_position_get(
                 ctx_win, &ctx_win->eventstate->xy[0], &ctx_win->eventstate->xy[1]);
             wm->winactive = ctx_win; /* Reports use this... */
@@ -2517,12 +2520,12 @@ static int wm_handler_fileselect_do(bContext *C,
 
         retval = handler->op->type->exec(C, handler->op);
 
-        /* XXX check this carefully, CTX_wm_manager(C) == wm is a bit hackish */
+        /* XXX check this carefully, `CTX_wm_manager(C) == wm` is a bit hackish. */
         if (handler->op->type->flag & OPTYPE_UNDO && CTX_wm_manager(C) == wm) {
           wm->op_undo_depth--;
         }
 
-        /* XXX check this carefully, CTX_wm_manager(C) == wm is a bit hackish */
+        /* XXX check this carefully, `CTX_wm_manager(C) == wm` is a bit hackish. */
         if (CTX_wm_manager(C) == wm && wm->op_undo_depth == 0) {
           if (handler->op->type->flag & OPTYPE_UNDO) {
             ED_undo_push_op(C, handler->op);
@@ -2534,7 +2537,7 @@ static int wm_handler_fileselect_do(bContext *C,
 
         if (handler->op->reports->list.first) {
 
-          /* FIXME(campbell): temp setting window, this is really bad!
+          /* FIXME(@campbellbarton): temp setting window, this is really bad!
            * only have because lib linking errors need to be seen by users :(
            * it can be removed without breaking anything but then no linking errors. */
           wmWindow *win_prev = CTX_wm_window(C);
@@ -2548,11 +2551,11 @@ static int wm_handler_fileselect_do(bContext *C,
           BKE_report_print_level_set(handler->op->reports, RPT_WARNING);
           UI_popup_menu_reports(C, handler->op->reports);
 
-          /* XXX: copied from 'wm_operator_finished()'. */
-          /* add reports to the global list, otherwise they are not seen */
+          /* XXX: copied from #wm_operator_finished(). */
+          /* Add reports to the global list, otherwise they are not seen. */
           BLI_movelisttolist(&CTX_wm_reports(C)->list, &handler->op->reports->list);
 
-          /* More hacks, since we meddle with reports, banner display doesn't happen automaticM */
+          /* More hacks, since we meddle with reports, banner display doesn't happen automatic. */
           WM_report_banner_show();
 
           CTX_wm_window_set(C, win_prev);
@@ -2560,7 +2563,7 @@ static int wm_handler_fileselect_do(bContext *C,
           CTX_wm_region_set(C, region_prev);
         }
 
-        /* For WM_operator_pystring only, custom report handling is done above. */
+        /* For #WM_operator_pystring only, custom report handling is done above. */
         wm_operator_reports(C, handler->op, retval, true);
 
         if (retval & OPERATOR_FINISHED) {
@@ -2638,7 +2641,7 @@ static int wm_handlers_do_keymap_with_keymap_handler(
   int action = WM_HANDLER_CONTINUE;
 
   if (keymap == NULL) {
-    /* Only callback is allowed to have NULL keymaps. */
+    /* Only callback is allowed to have NULL key-maps. */
     BLI_assert(handler->dynamic.keymap_fn);
   }
   else {
@@ -2735,7 +2738,7 @@ static int wm_handlers_do_keymap_with_gizmo_handler(
 
         CTX_wm_gizmo_group_set(C, gzgroup);
 
-        /* handler->op is called later, we want keymap op to be triggered here. */
+        /* `handler->op` is called later, we want key-map op to be triggered here. */
         action |= wm_handler_operator_call(
             C, handlers, &handler->head, event, kmi->ptr, kmi->idname);
 
@@ -2903,7 +2906,7 @@ static int wm_handlers_do_gizmo_handler(bContext *C,
           }
         }
       }
-#endif /* USE_GIZMO_MOUSE_PRIORITY_HACK */
+#endif /* `USE_GIZMO_MOUSE_PRIORITY_HACK` */
     }
 
     /* Don't use from now on. */
@@ -2943,7 +2946,7 @@ static int wm_handlers_do_gizmo_handler(bContext *C,
     }
   }
 
-  /* restore the area */
+  /* Restore the area. */
   CTX_wm_area_set(C, area);
   CTX_wm_region_set(C, region);
 
@@ -3038,7 +3041,7 @@ static int wm_handlers_do_intern(bContext *C, wmWindow *win, wmEvent *event, Lis
                 if (drop->poll(C, drag, event)) {
                   wm_drop_prepare(C, drag, drop);
 
-                  /* Pass single matched wmDrag onto the operator. */
+                  /* Pass single matched #wmDrag onto the operator. */
                   BLI_remlink(lb, drag);
                   ListBase single_lb = {0};
                   BLI_addtail(&single_lb, drag);
@@ -3064,7 +3067,7 @@ static int wm_handlers_do_intern(bContext *C, wmWindow *win, wmEvent *event, Lis
 
                   wm_drop_end(C, drag, drop);
 
-                  /* XXX fileread case. */
+                  /* XXX file-read case. */
                   if (CTX_wm_window(C) == NULL) {
                     return action;
                   }
@@ -3110,17 +3113,17 @@ static int wm_handlers_do_intern(bContext *C, wmWindow *win, wmEvent *event, Lis
       }
     }
 
-    /* XXX fileread case, if the wm is freed then the handler's
+    /* File-read case, if the wm is freed then the handler's
      * will have been too so the code below need not run. */
     if (CTX_wm_window(C) == NULL) {
       return action;
     }
 
-    /* XXX code this for all modal ops, and ensure free only happens here. */
+    /* Code this for all modal ops, and ensure free only happens here. */
 
-    /* Modal UI handler can be tagged to be freed. */
-    if (BLI_findindex(handlers, handler_base) !=
-        -1) { /* Could be freed already by regular modal ops. */
+    /* The handler Could be freed already by regular modal ops. */
+    if (BLI_findindex(handlers, handler_base) != -1) {
+      /* Modal UI handler can be tagged to be freed. */
       if (handler_base->flag & WM_HANDLER_DO_FREE) {
         BLI_remlink(handlers, handler_base);
         wm_event_free_handler(handler_base);
@@ -3203,12 +3206,12 @@ static int wm_handlers_do(bContext *C, wmEvent *event, ListBase *handlers)
     }
   }
   else if (ISMOUSE_BUTTON(event->type) || ISKEYBOARD(event->type)) {
-    /* All events that don't set wmEvent.prev_type must be ignored. */
+    /* All events that don't set #wmEvent.prev_type must be ignored. */
 
     /* Test for CLICK events. */
     if (wm_action_not_handled(action)) {
-      /* eventstate stores if previous event was a KM_PRESS, in case that
-       * wasn't handled, the KM_RELEASE will become a KM_CLICK */
+      /* #wmWindow.eventstate stores if previous event was a #KM_PRESS, in case that
+       * wasn't handled, the #KM_RELEASE will become a #KM_CLICK. */
 
       if (event->val == KM_PRESS) {
         if ((event->flag & WM_EVENT_IS_REPEAT) == 0) {
@@ -3262,7 +3265,7 @@ static int wm_handlers_do(bContext *C, wmEvent *event, ListBase *handlers)
           event->val = KM_PRESS;
           action |= wm_handlers_do_intern(C, win, event, handlers);
 
-          /* revert value if not handled */
+          /* Revert value if not handled. */
           if (wm_action_not_handled(action)) {
             event->val = KM_DBL_CLICK;
           }
@@ -3278,7 +3281,7 @@ static int wm_handlers_do(bContext *C, wmEvent *event, ListBase *handlers)
     /* Modifiers which can trigger click event's,
      * however we don't want this if the mouse wheel has been used, see T74607. */
     if (wm_action_not_handled(action)) {
-      /* pass */
+      /* Pass. */
     }
     else {
       if (ISKEYMODIFIER(event->prev_type)) {
@@ -3352,8 +3355,11 @@ static void wm_paintcursor_tag(bContext *C, wmPaintCursor *pc, ARegion *region)
   }
 }
 
-/* Called on mousemove, check updates for paintcursors. */
-/* Context was set on active area and region. */
+/**
+ * Called on mouse-move, check updates for `wm->paintcursors`.
+ *
+ * \note Context was set on active area and region.
+ */
 static void wm_paintcursor_test(bContext *C, const wmEvent *event)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
@@ -3400,7 +3406,7 @@ static void wm_event_drag_and_drop_test(wmWindowManager *wm, wmWindow *win, wmEv
   else if (event->type == LEFTMOUSE && event->val == KM_RELEASE) {
     event->type = EVT_DROP;
 
-    /* Create customdata, first free existing. */
+    /* Create custom-data, first free existing. */
     if (event->customdata) {
       if (event->customdata_free) {
         MEM_freeN(event->customdata);
@@ -3414,12 +3420,14 @@ static void wm_event_drag_and_drop_test(wmWindowManager *wm, wmWindow *win, wmEv
     /* Clear drop icon. */
     screen->do_draw_drag = true;
 
-    /* restore cursor (disabled, see wm_dragdrop.c) */
+    /* Restore cursor (disabled, see `wm_dragdrop.c`) */
     // WM_cursor_modal_restore(win);
   }
 }
 
-/* Filter out all events of the pie that spawned the last pie unless it's a release event. */
+/**
+ * Filter out all events of the pie that spawned the last pie unless it's a release event.
+ */
 static bool wm_event_pie_filter(wmWindow *win, const wmEvent *event)
 {
   if (win->pie_event_type_lock && win->pie_event_type_lock == event->type) {
@@ -3527,7 +3535,7 @@ static int wm_event_do_region_handlers(bContext *C, wmEvent *event, ARegion *reg
 {
   CTX_wm_region_set(C, region);
 
-  /* Call even on non mouse events, since the */
+  /* Call even on non mouse events, since the. */
   wm_region_mouse_co(C, event);
 
   const wmWindowManager *wm = CTX_wm_manager(C);
@@ -3692,21 +3700,21 @@ void wm_event_do_handlers(bContext *C)
       CTX_wm_region_set(C, region_event_inside(C, event->xy));
 
       /* MVC demands to not draw in event handlers...
-       * but we need to leave it for ogl selecting etc. */
+       * but we need to leave it for GPU selecting etc. */
       wm_window_make_drawable(wm, win);
 
       wm_region_mouse_co(C, event);
 
-      /* First we do priority handlers, modal + some limited keymaps. */
+      /* First we do priority handlers, modal + some limited key-maps. */
       action |= wm_handlers_do(C, event, &win->modalhandlers);
 
-      /* Fileread case. */
+      /* File-read case. */
       if (CTX_wm_window(C) == NULL) {
         wm_event_free_and_remove_from_queue_if_valid(event);
         return;
       }
 
-      /* Check for a tooltip. */
+      /* Check for a tool-tip. */
       if (screen == WM_window_get_active_screen(win)) {
         if (screen->tool_tip && screen->tool_tip->timer) {
           if ((event->type == TIMER) && (event->customdata == screen->tool_tip->timer)) {
@@ -3719,10 +3727,11 @@ void wm_event_do_handlers(bContext *C)
       wm_event_drag_and_drop_test(wm, win, event);
 
       if ((action & WM_HANDLER_BREAK) == 0) {
-        /* NOTE: setting subwin active should be done here, after modal handlers have been done. */
+        /* NOTE: setting sub-window active should be done here,
+         * after modal handlers have been done. */
         if (event->type == MOUSEMOVE) {
           /* State variables in screen, cursors.
-           * Also used in wm_draw.c, fails for modal handlers though. */
+           * Also used in `wm_draw.c`, fails for modal handlers though. */
           ED_screen_set_active_region(C, win, event->xy);
           /* For regions having custom cursors. */
           wm_paintcursor_test(C, event);
@@ -3742,8 +3751,8 @@ void wm_event_do_handlers(bContext *C)
             break;
           }
 
-          /* Update azones if needed - done here because it needs to be independent from redraws.
-           */
+          /* Update action-zones if needed,
+           * done here because it needs to be independent from redraws. */
           if (area->flag & AREA_FLAG_ACTIONZONES_UPDATE) {
             ED_area_azones_update(area, event->xy);
           }
@@ -3753,7 +3762,7 @@ void wm_event_do_handlers(bContext *C)
 
             action |= wm_event_do_handlers_area_regions(C, event, area);
 
-            /* Fileread case (python), T29489. */
+            /* File-read case (Python), T29489. */
             if (CTX_wm_window(C) == NULL) {
               wm_event_free_and_remove_from_queue_if_valid(event);
               return;
@@ -3762,7 +3771,7 @@ void wm_event_do_handlers(bContext *C)
             CTX_wm_region_set(C, NULL);
 
             if ((action & WM_HANDLER_BREAK) == 0) {
-              wm_region_mouse_co(C, event); /* Only invalidates event->mval in this case. */
+              wm_region_mouse_co(C, event); /* Only invalidates `event->mval` in this case. */
               action |= wm_handlers_do(C, event, &area->handlers);
             }
             CTX_wm_area_set(C, NULL);
@@ -3781,7 +3790,7 @@ void wm_event_do_handlers(bContext *C)
 
           action |= wm_handlers_do(C, event, &win->handlers);
 
-          /* Fileread case. */
+          /* File-read case. */
           if (CTX_wm_window(C) == NULL) {
             wm_event_free_and_remove_from_queue_if_valid(event);
             return;
@@ -3806,7 +3815,7 @@ void wm_event_do_handlers(bContext *C)
       /* Update previous mouse position for following events to use. */
       copy_v2_v2_int(win->eventstate->prev_xy, event->xy);
 
-      /* Unlink and free here, blender-quit then frees all. */
+      /* Un-link and free here, Blender-quit then frees all. */
       BLI_remlink(&win->event_queue, event);
       wm_event_free(event);
     }
@@ -3914,7 +3923,7 @@ void WM_event_add_fileselect(bContext *C, wmOperator *op)
  * \{ */
 
 #if 0
-/* lets not expose struct outside wm? */
+/* Lets not expose struct outside wm? */
 static void WM_event_set_handler_flag(wmEventHandler *handler, int flag)
 {
   handler->flag = flag;
@@ -3931,7 +3940,7 @@ wmEventHandler_Op *WM_event_add_modal_handler(bContext *C, wmOperator *op)
   if (op->opm) {
     /* Give the mother macro to the handler. */
     handler->op = op->opm;
-    /* Mother macro opm becomes the macro element. */
+    /* Mother macro `opm` becomes the macro element. */
     handler->op->opm = op;
   }
   else {
@@ -3957,7 +3966,7 @@ void WM_event_modal_handler_area_replace(wmWindow *win, const ScrArea *old_area,
   LISTBASE_FOREACH (wmEventHandler *, handler_base, &win->modalhandlers) {
     if (handler_base->type == WM_HANDLER_TYPE_OP) {
       wmEventHandler_Op *handler = (wmEventHandler_Op *)handler_base;
-      /* Fileselect handler is quite special...
+      /* File-select handler is quite special.
        * it needs to keep old area stored in handler, so don't change it. */
       if ((handler->context.area == old_area) && (handler->is_fileselect == false)) {
         handler->context.area = new_area;
@@ -3973,7 +3982,7 @@ void WM_event_modal_handler_region_replace(wmWindow *win,
   LISTBASE_FOREACH (wmEventHandler *, handler_base, &win->modalhandlers) {
     if (handler_base->type == WM_HANDLER_TYPE_OP) {
       wmEventHandler_Op *handler = (wmEventHandler_Op *)handler_base;
-      /* Fileselect handler is quite special...
+      /* File-select handler is quite special.
        * it needs to keep old region stored in handler, so don't change it. */
       if ((handler->context.region == old_region) && (handler->is_fileselect == false)) {
         handler->context.region = new_region;
@@ -3986,11 +3995,11 @@ void WM_event_modal_handler_region_replace(wmWindow *win,
 wmEventHandler_Keymap *WM_event_add_keymap_handler(ListBase *handlers, wmKeyMap *keymap)
 {
   if (!keymap) {
-    CLOG_WARN(WM_LOG_HANDLERS, "called with NULL keymap");
+    CLOG_WARN(WM_LOG_HANDLERS, "called with NULL key-map");
     return NULL;
   }
 
-  /* Only allow same keymap once. */
+  /* Only allow same key-map once. */
   LISTBASE_FOREACH (wmEventHandler *, handler_base, handlers) {
     if (handler_base->type == WM_HANDLER_TYPE_KEYMAP) {
       wmEventHandler_Keymap *handler = (wmEventHandler_Keymap *)handler_base;
@@ -4053,7 +4062,7 @@ static void wm_event_get_keymap_from_toolsystem_ex(wmWindowManager *wm,
   if ((tref_rt && tref_rt->keymap_fallback[0]) &&
       (scene && (scene->toolsettings->workspace_tool_type == SCE_WORKSPACE_TOOL_FALLBACK))) {
     bool add_keymap = false;
-    /* Support for the gizmo owning the tool keymap. */
+    /* Support for the gizmo owning the tool key-map. */
 
     if (tref_rt->flag & TOOLREF_FLAG_FALLBACK_KEYMAP) {
       add_keymap = true;
@@ -4101,9 +4110,9 @@ static void wm_event_get_keymap_from_toolsystem_ex(wmWindowManager *wm,
 
     wmKeyMap *km = WM_keymap_list_find_spaceid_or_empty(
         &wm->userconf->keymaps, keymap_id, area->spacetype, RGN_TYPE_WINDOW);
-    /* We shouldn't use keymaps from unrelated spaces. */
+    /* We shouldn't use key-maps from unrelated spaces. */
     if (km == NULL) {
-      printf("Keymap: '%s' not found for tool '%s'\n", keymap_id, area->runtime.tool->idname);
+      printf("Key-map: '%s' not found for tool '%s'\n", keymap_id, area->runtime.tool->idname);
       continue;
     }
     handler->keymap_tool = area->runtime.tool;
@@ -4135,7 +4144,7 @@ struct wmEventHandler_Keymap *WM_event_add_keymap_handler_dynamic(
     return NULL;
   }
 
-  /* Only allow same keymap once. */
+  /* Only allow same key-map once. */
   LISTBASE_FOREACH (wmEventHandler *, handler_base, handlers) {
     if (handler_base->type == WM_HANDLER_TYPE_KEYMAP) {
       wmEventHandler_Keymap *handler = (wmEventHandler_Keymap *)handler_base;
@@ -4162,7 +4171,7 @@ wmEventHandler_Keymap *WM_event_add_keymap_handler_priority(ListBase *handlers,
 {
   WM_event_remove_keymap_handler(handlers, keymap);
 
-  wmEventHandler_Keymap *handler = MEM_callocN(sizeof(*handler), "event keymap handler");
+  wmEventHandler_Keymap *handler = MEM_callocN(sizeof(*handler), "event key-map handler");
   handler->head.type = WM_HANDLER_TYPE_KEYMAP;
 
   BLI_addhead(handlers, handler);
@@ -4273,7 +4282,7 @@ void WM_event_remove_ui_handler(ListBase *handlers,
       wmEventHandler_UI *handler = (wmEventHandler_UI *)handler_base;
       if ((handler->handle_fn == handle_fn) && (handler->remove_fn == remove_fn) &&
           (handler->user_data == user_data)) {
-        /* Handlers will be freed in wm_handlers_do(). */
+        /* Handlers will be freed in #wm_handlers_do(). */
         if (postpone) {
           handler->head.flag |= WM_HANDLER_DO_FREE;
         }
@@ -4328,7 +4337,7 @@ wmEventHandler_Dropbox *WM_event_add_dropbox_handler(ListBase *handlers, ListBas
 
 void WM_event_remove_area_handler(ListBase *handlers, void *area)
 {
-  /* XXX(ton): solution works, still better check the real cause. */
+  /* XXX(@ton): solution works, still better check the real cause. */
 
   LISTBASE_FOREACH_MUTABLE (wmEventHandler *, handler_base, handlers) {
     if (handler_base->type == WM_HANDLER_TYPE_UI) {
@@ -4495,7 +4504,7 @@ static int convert_key(GHOST_TKey key)
       return EVT_MEDIALAST;
 
     default:
-      return EVT_UNKNOWNKEY; /* GHOST_kKeyUnknown */
+      return EVT_UNKNOWNKEY; /* #GHOST_kKeyUnknown (this could be asserted). */
   }
 }
 
@@ -4543,7 +4552,7 @@ static void wm_eventemulation(wmEvent *event, bool test_only)
     }
   }
 
-  /* Numpad emulation. */
+  /* Numeric-pad emulation. */
   if (U.flag & USER_NONUMPAD) {
     switch (event->type) {
       case EVT_ZEROKEY:
@@ -4620,10 +4629,10 @@ void wm_tablet_data_from_ghost(const GHOST_TabletData *tablet_data, wmTabletData
 }
 
 #ifdef WITH_INPUT_NDOF
-/* Adds customdata to event. */
+/* Adds custom-data to event. */
 static void attach_ndof_data(wmEvent *event, const GHOST_TEventNDOFMotionData *ghost)
 {
-  wmNDOFMotionData *data = MEM_mallocN(sizeof(wmNDOFMotionData), "customdata NDOF");
+  wmNDOFMotionData *data = MEM_mallocN(sizeof(wmNDOFMotionData), "Custom-data NDOF");
 
   const float ts = U.ndof_sensitivity;
   const float rs = U.ndof_orbit_sensitivity;
@@ -4659,11 +4668,11 @@ static wmWindow *wm_event_cursor_other_windows(wmWindowManager *wm, wmWindow *wi
 
   /* In order to use window size and mouse position (pixels), we have to use a WM function. */
 
-  /* check if outside, include top window bar... */
+  /* Check if outside, include top window bar. */
   if (mval[0] < 0 || mval[1] < 0 || mval[0] > WM_window_pixels_x(win) ||
       mval[1] > WM_window_pixels_y(win) + 30) {
-    /* Let's skip windows having modal handlers now */
-    /* potential XXX ugly... I wouldn't have added a modalhandlers list
+    /* Let's skip windows having modal handlers now. */
+    /* Potential XXX ugly... I wouldn't have added a `modalhandlers` list
      * (introduced in rev 23331, ton). */
     LISTBASE_FOREACH (wmEventHandler *, handler, &win->modalhandlers) {
       if (ELEM(handler->type, WM_HANDLER_TYPE_UI, WM_HANDLER_TYPE_OP)) {
@@ -4739,7 +4748,7 @@ static wmEvent *wm_event_add_mousemove(wmWindow *win, const wmEvent *event)
 
 static wmEvent *wm_event_add_trackpad(wmWindow *win, const wmEvent *event, int deltax, int deltay)
 {
-  /* Ignore in between trackpad events for performance, we only need high accuracy
+  /* Ignore in between track-pad events for performance, we only need high accuracy
    * for painting with mouse moves, for navigation using the accumulated value is ok. */
   wmEvent *event_last = win->event_queue.last;
   if (event_last && event_last->type == event->type) {
@@ -4830,7 +4839,7 @@ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void
       }
 
       /* Also add to other window if event is there, this makes overdraws disappear nicely. */
-      /* It remaps mousecoord to other window in event. */
+      /* It remaps mouse-coord to other window in event. */
       wmWindow *win_other = wm_event_cursor_other_windows(wm, win, &event);
       if (win_other) {
         wmEvent event_other = *win_other->eventstate;
@@ -4978,7 +4987,7 @@ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void
       event_state->type = event.type;
       event_state->flag = (event.flag & event_state_flag_mask);
 
-      /* Exclude arrow keys, esc, etc from text input. */
+      /* Exclude arrow keys, escape, etc from text input. */
       if (type == GHOST_kEventKeyUp) {
         event.ascii = '\0';
 
@@ -5007,7 +5016,6 @@ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void
         }
       }
 
-      /* Assigning both first and second is strange. - campbell */
       switch (event.type) {
         case EVT_LEFTSHIFTKEY:
         case EVT_RIGHTSHIFTKEY:
@@ -5066,7 +5074,7 @@ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void
           break;
         default:
           if (event.val == KM_PRESS && event.keymodifier == 0) {
-            /* Only set in eventstate, for next event. */
+            /* Only set in `eventstate`, for next event. */
             event_state->keymodifier = event.type;
           }
           else if (event.val == KM_RELEASE && event.keymodifier == event.type) {
@@ -5088,7 +5096,7 @@ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void
         event.keymodifier = 0;
       }
 
-      /* This case happens with an external numpad, and also when using 'dead keys'
+      /* This case happens with an external number-pad, and also when using 'dead keys'
        * (to compose complex latin characters e.g.), it's not really clear why.
        * Since it's impossible to map a key modifier to an unknown key,
        * it shouldn't harm to clear it. */
@@ -5272,7 +5280,7 @@ void WM_set_locked_interface(wmWindowManager *wm, bool lock)
    */
   wm->is_interface_locked = lock ? 1 : 0;
 
-  /* This will prevent drawing regions which uses non-threadsafe data.
+  /* This will prevent drawing regions which uses non-thread-safe data.
    * Currently it'll be just a 3D viewport.
    *
    * TODO(sergey): Make it different locked states, so different jobs
@@ -5354,7 +5362,7 @@ wmKeyMapItem *WM_event_match_keymap_item_from_handlers(
 /** \name Cursor Keymap Status
  *
  * Show cursor keys in the status bar.
- * This is done by detecting changes to the state - full keymap lookups are expensive
+ * This is done by detecting changes to the state - full key-map lookups are expensive
  * so only perform this on changing tools, space types, pressing different modifier keys... etc.
  * \{ */
 
@@ -5363,14 +5371,15 @@ struct CursorKeymapInfo_State {
   uint8_t modifier;
   short space_type;
   short region_type;
-  /* Never use, just compare memory for changes. */
+  /** Never use, just compare memory for changes. */
   bToolRef tref;
 };
 
 struct CursorKeymapInfo {
-  /* 0: mouse button index
-   * 1: event type (click/press, drag)
-   * 2: text.
+  /**
+   * 0: Mouse button index.
+   * 1: Event type (click/press, drag).
+   * 2: Text.
    */
   char text[3][2][128];
   wmEvent state_event;
@@ -5505,7 +5514,7 @@ void WM_window_cursor_keymap_status_refresh(bContext *C, wmWindow *win)
     }
   }
 
-  /* Changed context found, detect changes to keymap and refresh the status bar. */
+  /* Changed context found, detect changes to key-map and refresh the status bar. */
   const struct {
     int button_index;
     int type_index; /* 0: press or click, 1: drag. */