doc: Update comments

users/crumb/programs/emacs/modules/syd-evil.el

@@ -26,7 +26,7 @@
         ;; to do highlighting them all.
         evil-ex-interactive-search-highlight 'selected-window
         ;; It's infuriating that innocuous "beginning of line" or "end of line"
-        ;; errors will abort macros, so suppress them:
+        ;; errors will abort macros, so we suppress them:
         evil-kbd-macro-suppress-motion-error t
         evil-undo-system (cond ((featurep 'undo-tree) 'undo-tree)
                                ((featurep 'undo-fu) 'undo-fu)))
@@ -35,20 +35,19 @@
         evil-want-integration t)
 
   :config
-  ;; 'M-:' starts off in insert mode, yet initialises with the normal mode
+  ;; 'M-:' starts off in insert mode, yet the normal mode cursor lingers until a
-  ;; cursor.  Quick fix!  }:P
+  ;; refresh is forced.  Quick fix!  }:P
-  (add-hook 'minibuffer-setup-hook
+  (add-hook 'minibuffer-setup-hook #'evil-refresh-cursor)
-            #'evil-refresh-cursor)
 
-  ;; Unbind 'C-k'.  Normally, it inserts digraphs; I have a compose key.  It
+  ;; Unbind 'C-k'.  Normally, it inserts digraphs; I have a compose key, and
-  ;; often gets in the way of buffers with navigation, e.g. scrolling through
+  ;; it's strictly less useful than Emacs' native input methods.  It often gets
-  ;; shell/REPL history, navigating Vertico completions, etc.
+  ;; in the way of buffers with navigation, e.g. scrolling through shell/REPL
+  ;; history, navigating Vertico completions, etc.
   (keymap-set evil-insert-state-map "C-k" nil)
 
   ;; In imitation of Vim's :mes[sages] command, define an Evil analogue to show
   ;; the echo area.
-  (evil-ex-define-cmd "mes[sages]"
+  (evil-ex-define-cmd "mes[sages]" #'view-echo-area-messages)
-                      #'view-echo-area-messages)
 
   (evil-mode 1))
 
@@ -80,8 +79,7 @@
     ;; We handle loading evil-collection ourselves
     (defvar evil-collection--supported-modes nil)
     ;; This has to be defined here since evil-collection doesn't autoload its own.
-    ;; It must be updated whenever evil-collection updates theirs. Here's an easy
+    ;; It must be updated whenever evil-collection updates theirs.
-    ;; way to update it:
     (defvar evil-collection-mode-list
       `(2048-game ag alchemist anaconda-mode apropos arc-mode atomic-chrome
         auto-package-update beginend bluetooth bm bookmark

users/crumb/programs/emacs/modules/syd-keybinds.el

@@ -42,8 +42,7 @@ are active.")
   ;; Ideally, *nothing* takes precedence over Leader — it's an incredibly
   ;; important key!
   ;; https://github.com/noctuid/evil-guide?tab=readme-ov-file#undoprevent-overridingintercept-maps
-  ;; Really, we do this because Doom does.  I'm honestly not entirely sure what
+  ;; See `evil-make-overriding-map'.
-  ;; it does.  I can't find anything useful online.
   (define-key syd-leader-map [override-state] 'all)
   ;; Finally, we shall bind the damned keys. }:)
   (let ((map general-override-mode-map))
@@ -60,8 +59,8 @@ all hooks after it are ignored.")
 ;;
 ;;; Universal, non-nuclear escape
 
-;; `keyboard-quit' is too much of a nuclear option. I wanted an ESC/C-g to
+;; `keyboard-quit' is too much of a nuclear option. I want ESC/C-g to
-;; do-what-I-mean. It serves four purposes (in order):
+;; do-what-I-mean.  It serves four purposes (in order):
 ;;
 ;; 1. Quit active states; e.g. highlights, searches, snippets, iedit,
 ;;    multiple-cursors, recording macros, etc.
@@ -70,8 +69,8 @@ all hooks after it are ignored.")
 ;; 4. Or fall back to `keyboard-quit'
 ;;
 ;; And it should do these things incrementally, rather than all at once. And it
-;; shouldn't interfere with recording macros or the minibuffer. This may require
+;; shouldn't interfere with recording macros or the minibuffer.  This may
-;; you press ESC/C-g two or three times on some occasions to reach
+;; require you press ESC/C-g two or three times on some occasions to reach
 ;; `keyboard-quit', but this is much more intuitive.
 
 (defun syd/escape (&optional interactive)