nit: minor comment revision

early-init.el

@@ -27,26 +27,28 @@
 ;;; Code:
 
 (let (file-name-handler-alist)
-  ;; PERF: Garbage collection is a big contributor to startup times. This fends
+  ;; PERF: Garbage collection is a big contributor to startup times in both
-  ;;   it off, but will be reset later by `gcmh-mode'. Not resetting it later
+  ;;   interactive and CLI sessions, so I defer it.
-  ;;   causes stuttering/freezes.
+  (if noninteractive  ; in CLI sessions
-  (if noninteractive
+      ;; PERF: GC deferral is less important in the CLI, but still helps script
-      ;; PERF: Deferring the GC in non-interactive sessions isn't as important,
+      ;;   startup times. Just don't set it too high to avoid runaway memory
-      ;;   but still yields a notable benefit. Still, avoid setting it to high
+      ;;   usage in long-running elisp shell scripts.
-      ;;   here, as runaway memory usage is a real risk in longer sessions.
       (setq gc-cons-threshold 134217728  ; 128mb
             ;; Backported from 29 (see emacs-mirror/emacs@73a384a98698)
             gc-cons-percentage 1.0)
+    ;; PERF: Doom relies on `gcmh-mode' to reset this while the user is idle, so
+    ;;   I effectively disable GC during startup. DON'T COPY THIS BLINDLY! If
+    ;;   it's not reset later there will be stuttering, freezes, and crashes.
     (setq gc-cons-threshold most-positive-fixnum))
 
-  ;; PERF: Don't use precious startup time checking mtime on elisp bytecode.
+  ;; PERF: Don't use precious startup time to check mtimes on elisp bytecode.
-  ;;   Ensuring correctness is 'doom sync's job, not the interactive session's.
+  ;;   Ensuring correctness is 'doom sync's job. Although stale byte-code will
-  ;;   Still, stale byte-code will cause *heavy* losses in startup efficiency,
+  ;;   heavily impact startup times, performance is unimportant when Emacs is in
-  ;;   but performance is unimportant when Emacs is in an error state.
+  ;;   an error state.
   (setq load-prefer-newer noninteractive)
 
   ;; UX: Respect DEBUG envvar as an alternative to --debug-init, and to make
-  ;;   startup sufficiently verbose from this point on.
+  ;;   startup more verbose sooner.
   (when (getenv-internal "DEBUG")
     (setq init-file-debug t
           debug-on-error t))
@@ -76,10 +78,10 @@
             (setq user-emacs-directory (expand-file-name init-dir))))
       ;; FIX: Discard the switch to prevent "invalid option" errors later.
       (push (cons "--profile" (lambda (_) (pop argv))) command-switch-alist)
-      ;; Running 'doom sync' or 'doom profile sync' (re)generates a light
+      ;; Running 'doom sync' or 'doom profile sync --all' (re)generates a light
-      ;; profile loader in $EMACSDIR/profiles/load.el (or $DOOMPROFILELOADFILE),
+      ;; profile loader in $XDG_DATA_HOME/doom/profiles.X.el (or
-      ;; after reading `doom-profile-load-path'. This loader requires
+      ;; $DOOMPROFILELOADFILE), after reading `doom-profile-load-path'. This
-      ;; `$DOOMPROFILE' be set to function.
+      ;; loader requires `$DOOMPROFILE' be set to function.
       (setenv "DOOMPROFILE" profile)
       (or (load (let ((windows? (memq system-type '(ms-dos windows-nt cygwin))))
                   (expand-file-name
@@ -133,9 +135,10 @@
           ;;   fit guess. It's better than Emacs' 80kb default.
           (setq gc-cons-threshold (* 16 1024 1024))
           nil))
-      ;; In non-interactive sessions, leave to the consumer to call
+      ;; Sets up Doom (particularly `doom-profile') for the session ahead. This
-      ;; `doom-initialize' at the best time, otherwise we need to initialize
+      ;; loads the profile's init file, if it's available. In interactive
-      ;; ASAP for the Emacs session ahead.
+      ;; session, a missing profile is an error state, in a non-interactive one,
+      ;; it's not (and left to the consumer to deal with).
       (doom-initialize (not noninteractive))
     ;; If we're here, the user wants to load another config/profile (that may or
     ;; may not be a Doom config).

lisp/doom.el

@@ -70,13 +70,14 @@
 ;;
 ;;; Code:
 
-;; For `when-let*' and `if-let*' on versions of Emacs before they were autoloaded.
+;; For the `when-let*' and `if-let*' macros on older versions of Emacs, before
+;; they were autoloaded.
 (eval-when-compile (require 'subr-x))
 
-(eval-and-compile  ; Check version at both compile and runtime.
+(eval-and-compile
-  ;; Doom's minimum supported version of Emacs is 27.1. Its my goal to support
+  ;; Doom core supports Emacs 27.1 and newer. However, keep in mind that modules
-  ;; one major version below the stable release, for about a year or until
+  ;; may have different requirements (e.g. the official module library requires
-  ;; stable is ubiquitous (or at least easily accessible) across Linux distros.
+  ;; 29.x or newer).
   (when (< emacs-major-version 27)
     (user-error
      (concat
@@ -116,8 +117,7 @@
 ;;; Custom features & global constants
 ;; Doom has its own features that its modules, CLI, and user extensions can
 ;; announce, and don't belong in `features', so they are stored here, which can
-;; include information about the external system environment. Module-specific
+;; include information about the external system environment.
-;; features are kept elsewhere, however.
 (defconst doom-system
   (pcase system-type
     ('darwin                           '(macos bsd))
@@ -133,8 +133,7 @@
 (defconst doom--system-linux-p   (eq 'linux   (car doom-system)))
 
 ;; `system-type' is esoteric, so I create a pseudo feature as a stable and
-;; consistent alternative, and all while using the same `featurep' interface
+;; consistent alternative, for use with `featurep'.
-;; we're already familiar with.
 (push :system features)
 (put :system 'subfeatures doom-system)
 
@@ -151,13 +150,13 @@
 
 ;; The `native-compile' feature exists whether or not it is functional (e.g.
 ;; libgcc is available or not). This seems silly, as some packages will blindly
-;; use the native-comp API if it's present, whether or not it's functional. so
+;; use the native-comp API if it's present but non-functional, so let's pretend
-;; pretend it doesn't exist if that's the case.
+;; it doesn't exist if that's the case.
 (if (featurep 'native-compile)
     (if (not (native-comp-available-p))
         (delq 'native-compile features)))
 
-;; DEPRECATED remove in v3
+;; DEPRECATED: Remove in v3
 (with-no-warnings
   (defconst IS-MAC      doom--system-macos-p)
   (defconst IS-LINUX    doom--system-linux-p)
@@ -181,10 +180,10 @@
   (define-obsolete-variable-alias 'doom-etc-dir 'doom-data-dir "3.0.0"))
 
 ;; HACK: Silence obnoxious obsoletion warnings about (if|when)-let in >=31.
-;;   These warnings are unhelpful to end-users, and so, so many packages use
+;;   These warnings are unhelpful to end-users, and many packages use these
-;;   these macros so rather than hopelessly pester them, I'll silence them. Not
+;;   macros, so I silence these warnings to spare users the unactionable spam.
-;;   to mention, Emacs doesn't respect `warning-suppress-types' when it comes to
+;;   Not to mention, Emacs doesn't respect `warning-suppress-types' when it
-;;   obsoletion warnings.
+;;   comes to obsoletion warnings.
 (put 'if-let 'byte-obsolete-info nil)
 (put 'when-let 'byte-obsolete-info nil)
 
@@ -559,7 +558,7 @@ uses a straight or package.el command directly).")
 (when noninteractive
   ;; Don't generate superfluous files when writing temp buffers.
   (setq make-backup-files nil)
-  ;; Stop user config from interfering with package management.
+  ;; Stop user config from interfering with elisp shell scripts.
   (setq enable-dir-local-variables nil)
   ;; Reduce ambiguity, embrace specificity, enjoy predictability.
   (setq case-fold-search nil)
@@ -571,8 +570,7 @@ uses a straight or package.el command directly).")
 ;;   ones) abuse it to build paths for storage/cache files (instead of correctly
 ;;   using `locate-user-emacs-file'). This change ensures that said data files
 ;;   are never saved to the root of your emacs directory *and* saves us the
-;;   trouble of setting a million directory/file variables. But it may throw off
+;;   trouble of setting a million directory/file variables.
-;;   anyone (or any package) that uses it to search for your Emacs initfiles.
 (setq user-emacs-directory doom-profile-cache-dir)
 
 ;; ...However, this may surprise packages (and users) that read
@@ -602,7 +600,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to
 (when (boundp 'native-comp-eln-load-path)
   ;; Don't store eln files in ~/.emacs.d/eln-cache (where they can easily be
   ;; deleted by 'doom upgrade').
-  ;; REVIEW Use `startup-redirect-eln-cache' when 28 support is dropped
+  ;; REVIEW: Advise `startup-redirect-eln-cache' when 28 support is dropped.
   (add-to-list 'native-comp-eln-load-path (expand-file-name "eln/" doom-profile-cache-dir))
 
   ;; UX: Suppress compiler warnings and don't inundate users with their popups.
@@ -610,7 +608,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to
   (setq native-comp-async-report-warnings-errors init-file-debug
         native-comp-warning-on-missing-source init-file-debug)
 
-  ;; HACK: native-comp-deferred-compilation-deny-list is replaced in later
+  ;; HACK: `native-comp-deferred-compilation-deny-list' is replaced in later
   ;;   versions of Emacs 29, and with no deprecation warning. I alias them to
   ;;   ensure backwards compatibility for packages downstream that may have not
   ;;   caught up yet. I avoid marking it obsolete because obsolete warnings are
@@ -631,8 +629,8 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to
 
   (define-advice comp-run-async-workers (:around (fn &rest args) dont-litter-tmpdir)
     "Normally, native-comp writes a ton to /tmp. This advice forces it to write
-to `doom-cache-dir'/comp/ instead, so that Doom can safely clean it up as part
+to `doom-profile-cache-dir' instead, so it can be safely cleaned up as part of
-of 'doom sync' or 'doom gc'."
+'doom sync' or 'doom gc'."
     (let ((temporary-file-directory (expand-file-name "comp/" doom-profile-cache-dir)))
       (make-directory temporary-file-directory t)
       (apply fn args)))
@@ -642,7 +640,7 @@ of 'doom sync' or 'doom gc'."
     ;;   to comp-run. See emacsmirror/emacs@e6a955d24268. Doom forces straight
     ;;   to consult this variable when building packages.
     (require 'comp-run nil t)
-    ;; HACK Disable native-compilation for some troublesome packages
+    ;; HACK: Disable native-compilation for some troublesome packages
     (mapc (doom-partial #'add-to-list 'native-comp-deferred-compilation-deny-list)
           (list "/seq-tests\\.el\\'"
                 "/emacs-jupyter.*\\.el\\'"
@@ -851,12 +849,13 @@ appropriately against `noninteractive' or the `cli' context."
         (require 'doom-cli)
         (add-hook 'doom-cli-initialize-hook #'doom-finalize)))
 
-    ;; HACK: We suppress loading of site files so they can be loaded manually,
+    ;; HACK: I suppress loading of site files here to load them manually later.
-    ;;   here. Why? To suppress the otherwise unavoidable output they commonly
+    ;;   Why? To suppress the otherwise unavoidable output they commonly produce
-    ;;   produce (like deprecation notices, file-loaded messages, and linter
+    ;;   (like deprecation notices, file-loaded messages, and linter warnings).
-    ;;   warnings). This output pollutes the output of doom's CLI (or scripts
+    ;;   This output pollutes Emacs' log and the output of doom's CLI (or
-    ;;   derived from it) with potentially confusing or alarming -- but always
+    ;;   scripts derived from it) with potentially confusing or alarming -- but
-    ;;   unimportant -- information to the user.
+    ;;   always unimportant and rarely actionable -- information to the user. To
+    ;;   see that output, turn on debug mode!
     (let ((site-loader
            (lambda ()
              (quiet!!
@@ -885,8 +884,8 @@ appropriately against `noninteractive' or the `cli' context."
     ;; HACK: Ensure OS checks are as fast as possible (given their ubiquity).
     (setq features (cons :system (delq :system features)))
 
-    ;; Remember these variables' initial values, so we can safely reset them
+    ;; Remember these variables' initial values, so they can be safely reset
-    ;; at a later time, or consult them without fear of contamination.
+    ;; later (e.g. by `doom/reload'), or compared against for change heuristics.
     (dolist (var '(exec-path load-path process-environment))
       (put var 'initial-value (default-toplevel-value var)))