nit(cli): revise comments wrt site-run-file loading

bin/doom

@@ -62,17 +62,14 @@
 ;;   Put together, plus a strategically placed exit call, the shell will read
 ;;   one part of this file and ignore the rest, while the elisp interpreter will
 ;;   do the opposite.
-;; - I intentionally avoid loading site files, so lisp/doom-cli.el can load them
+;; - I intentionally suppress loading site files (must be done with '-q
-;;   by hand later. There, I can suppress and deal with unhelpful warnings (e.g.
+;;   --no-site-file' NOT '-Q', as the latter omits the site-lisp dir from
-;;   "package cl is deprecated"), "Loading X...DONE" spam, and any other
+;;   `load-path' too), so lisp/doom-cli.el can load them manually later (early
-;;   disasterous side-effects.
+;;   in lisp/doom-cli.el). Look there for an explanation why I do this.
-;;
-;;   But be careful not to use -Q! It implies --no-site-lisp, which omits the
-;;   site-lisp directory from `load-path'.
 ;; - POSIX-compliancy is paramount: there's no guarantee what /bin/sh will be
 ;;   symlinked to in the esoteric OSes/distros Emacs users use.
-;; - The user may have a noexec flag set on /tmp, so pass the exit script to
+;; - The user may have mounted /tmp with a noexec flag, so pass the exit script
-;;   /bin/sh rather than executing them directly.
+;;   to /bin/sh rather than executing them directly.
 
 ;; In CLI sessions, prefer correctness over performance.
 (setq load-prefer-newer t)

lisp/doom-cli.el

@@ -23,12 +23,12 @@
               doom-cache-dir
               doom-state-dir))
 
-  ;; HACK: bin/doom invokes Emacs with --no-site-lisp so that site files can be
+  ;; HACK: bin/doom suppresses loading of site files so they can be loaded
-  ;;   loaded manually, here, where I can suppress any output it produces, and
+  ;;   manually, here. Why? To suppress the otherwise unavoidable output they
-  ;;   they almost always produce some. This output pollutes the output of doom
+  ;;   commonly produce (like deprecation notices, file-loaded messages, and
-  ;;   scripts with potentially confusing -- but always unimportant --
+  ;;   linter warnings). This output pollutes the output of doom's CLI (or
-  ;;   information to the user, like deprecation notices, file-loaded messages,
+  ;;   scripts derived from it) with potentially confusing or alarming -- but
-  ;;   and linter warnings. With this, that output is suppressed.
+  ;;   always unimportant -- information to the user.
   (quiet!
    (require 'cl nil t)    ; "Package cl is deprecated"
    (unless site-run-file  ; unset in doom.el

lisp/doom.el

@@ -502,10 +502,10 @@ users).")
 
     ;; PERF,UX: site-lisp files are often obnoxiously noisy (emitting output
     ;;   that isn't useful to end-users, like load messages, deprecation
-    ;;   notices, and linter warnings. Displaying these in the minibuffer causes
+    ;;   notices, and linter warnings). Displaying these in the minibuffer
-    ;;   unnecessary redraws at startup which can impact startup time
+    ;;   causes unnecessary redraws at startup which can impact startup time
-    ;;   drastically and cause flashes of white. It also pollutes the logs. By
+    ;;   drastically and cause flashes of white. It also pollutes the logs. I
-    ;;   suppressing it here, I load it myself, later, in a more controlled way
+    ;;   suppress it here and load it myself, later, in a more controlled way
     ;;   (see `startup--load-user-init-file@undo-hacks').
     (put 'site-run-file 'initial-value site-run-file)
     (setq site-run-file nil)