core: revise & clarify comments

core/core-editor.el

@@ -189,13 +189,18 @@ possible."
         ;; Only prompts for confirmation when buffer is unsaved.
         revert-without-query (list "."))
 
-  ;; Instead of `auto-revert-mode' or `global-auto-revert-mode', we lazily auto
+  ;; `auto-revert-mode' and `global-auto-revert-mode' would, normally, abuse the
-  ;; revert; when we save a file or switch buffers/windows (or focus on Emacs).
+  ;; heck out of inotify handles _or_ aggresively poll your buffer list every X
+  ;; seconds. Too many inotify handles can grind Emacs to a halt if you preform
+  ;; expensive or batch processes on files outside of Emacs (e.g. their mtime
+  ;; changes), and polling your buffer list is terribly inefficient as your
+  ;; buffer list grows into the tens or hundreds.
   ;;
-  ;; Autorevert normally abuses the heck out of inotify handles which can grind
+  ;; So Doom uses a different strategy: we lazily auto revert buffers when the
-  ;; Emacs to a halt if you do expensive IO (outside of Emacs) on the files you
+  ;; user a) saves a file, b) switches to a buffer (or its window), or c) you
-  ;; have open (like compression). The only alternative is aggressive polling,
+  ;; focus Emacs (after using another program). This way, Emacs only ever has to
-  ;; which is unreliable and expensive with a lot of buffers open.
+  ;; operate on, at minimum, a single buffer and, at maximum, X buffers, where X
+  ;; is the number of open windows (which is rarely, if ever, over 10).
   (defun doom-auto-revert-buffer-h ()
     "Auto revert current buffer, if necessary."
     (unless (or auto-revert-mode (active-minibuffer-window))
@@ -221,9 +226,15 @@ possible."
         (file-truename file)
       file))
   (setq recentf-filename-handlers
-        '(substring-no-properties    ; strip out lingering text properties
+        '(;; Text properties inflate the size of recentf's files, and there is
-          doom--recent-file-truename ; resolve symlinks of local files
+          ;; no purpose in persisting them, so we strip them out.
-          abbreviate-file-name)      ; replace $HOME with ~
+          substring-no-properties
+          ;; Resolve symlinks of local files. Otherwise we get duplicate
+          ;; entries opening symlinks.
+          doom--recent-file-truename
+          ;; Replace $HOME with ~, which is more portable, and reduces how much
+          ;; horizontal space the recentf listing uses to list recent files.
+          abbreviate-file-name)
         recentf-save-file (concat doom-cache-dir "recentf")
         recentf-auto-cleanup 'never
         recentf-max-menu-items 0

core/core.el

@@ -323,8 +323,9 @@ config.el instead."
 (setq ffap-machine-p-known 'reject)
 
 ;; Font compacting can be terribly expensive, especially for rendering icon
-;; fonts on Windows. Whether it has a notable affect on Linux and Mac hasn't
+;; fonts on Windows. Whether disabling it has a notable affect on Linux and Mac
-;; been determined, but we inhibit it there anyway.
+;; hasn't been determined, but we inhibit it there anyway. This increases memory
+;; usage, however!
 (setq inhibit-compacting-font-caches t)
 
 ;; Performance on Windows is considerably worse than elsewhere. We'll need
@@ -346,8 +347,10 @@ config.el instead."
       gcmh-verbose doom-debug-p)
 
 ;; HACK `tty-run-terminal-initialization' is *tremendously* slow for some
-;;      reason. Disabling it completely could have many side-effects, so we
+;;      reason; inexplicably doubling startup time for terminal Emacs. Keeping
-;;      defer it until later, at which time it (somehow) runs very quickly.
+;;      it disabled will have nasty side-effects, so we simply delay it until
+;;      later in the startup process and, for some reason, it runs much faster
+;;      when it does.
 (unless (daemonp)
   (advice-add #'tty-run-terminal-initialization :override #'ignore)
   (add-hook! 'window-setup-hook