nit: revise and reformat comments

early-init.el

@@ -106,9 +106,9 @@
    ;;   this early -- I remove `.so' from `load-suffixes' and pass the
    ;;   `must-suffix' arg to `load'. See the docs of `load' for details.
    (if (let ((load-suffixes '(".elc" ".el")))
-         ;; I avoid `load's NOERROR argument because other, legitimate errors
+         ;; I avoid `load's NOERROR argument because it suppresses other,
-         ;; (like permission or IO errors) should not be suppressed or
+         ;; legitimate errors (like permission or IO errors), which gets
-         ;; interpreted as "this is not a Doom config".
+         ;; incorrectly interpreted as "this is not a Doom config".
          (condition-case _
              ;; Load the heart of Doom Emacs.
              (load (expand-file-name "lisp/doom" user-emacs-directory)

lisp/doom-keybinds.el

@@ -46,12 +46,12 @@ and Emacs states, and for non-evil users.")
 
 ;; HACK: Emacs cannot distinguish between C-i from TAB. This is largely a
 ;;   byproduct of its history in the terminal, which can't distinguish them
-;;   either, however, when GUIs came about Emacs greated separate input events
+;;   either, however, when GUIs came about Emacs created separate input events
 ;;   for more contentious keys like TAB and RET. Therefore [return] != RET,
 ;;   [tab] != TAB, and [backspace] != DEL.
 ;;
-;;   In the same vein, this keybind adds a [C-i] event, so users can bind to it.
+;;   In the same vein, this keybind adds a [C-i] event, so users can bind to it
-;;   Otherwise, it falls back to regular C-i keybinds.
+;;   independently of TAB. Otherwise, it falls back to keys bound to C-i.
 (define-key key-translation-map [?\C-i]
   (cmd! (if (let ((keys (this-single-command-raw-keys)))
               (and keys

lisp/doom-lib.el

@@ -303,9 +303,9 @@ TRIGGER-HOOK is a list of quoted hooks and/or sharp-quoted functions."
    (error "file!: cannot deduce the current file path")))
 
 (defmacro dir! ()
-  "Return the directory of the file this macro was called."
+  "Return the directory of the file in which this macro was called."
-   (let (file-name-handler-alist)
+  (let (file-name-handler-alist)
-     (file-name-directory (macroexpand '(file!)))))
+    (file-name-directory (macroexpand '(file!)))))
 
 ;; REVIEW Should I deprecate this? The macro's name is so long...
 (defalias 'letenv! 'with-environment-variables)
@@ -883,16 +883,16 @@ testing advice (when combined with `rotate-text').
        (dolist (target (cdr targets))
          (advice-remove target #',symbol)))))
 
+
+;;
+;;; Backports
+
 (defmacro defbackport! (type symbol &rest body)
   "Backport a function/macro/alias from later versions of Emacs."
   (declare (indent defun) (doc-string 4))
   (unless (fboundp (doom-unquote symbol))
     `(,type ,symbol ,@body)))
 
-
-;;
-;;; Backports
-
 ;; `format-spec' wasn't autoloaded until 28.1
 (defbackport! autoload 'format-spec "format-spec")
 

lisp/doom-start.el

@@ -100,13 +100,15 @@
 
 ;;; Disable UI elements early
 ;; PERF,UI: Doom strives to be keyboard-centric, so I consider these UI elements
-;;   clutter. Initializing them also costs a morsel of startup time. Whats more,
+;;   clutter. Initializing them also costs a morsel of startup time. What's
-;;   the menu bar exposes functionality that Doom doesn't endorse. Perhaps one
+;;   more, the menu bar exposes functionality that Doom doesn't endorse. Perhaps
-;;   day Doom will support these, but today is not that day.
+;;   one day Doom will support these, but today is not that day. By disabling
-;;
+;;   them early, we save Emacs some time.
+
 ;; HACK: I intentionally avoid calling `menu-bar-mode', `tool-bar-mode', and
-;;   `scroll-bar-mode' because they do extra work to manipulate frame variables
+;;   `scroll-bar-mode' because their manipulation of frame parameters can
-;;   that isn't necessary this early in the startup process.
+;;   trigger/queue a superfluous (and expensive, depending on the window system)
+;;   frame redraw at startup.
 (push '(menu-bar-lines . 0)   default-frame-alist)
 (push '(tool-bar-lines . 0)   default-frame-alist)
 (push '(vertical-scroll-bars) default-frame-alist)
@@ -119,7 +121,7 @@
 ;;   non-application window -- which means it doesn't automatically capture
 ;;   focus when it is started, among other things, so enable the menu-bar for
 ;;   GUI frames, but keep it disabled in terminal frames because there it
-;;   activates an ugly, in-frame menu bar.
+;;   unavoidably activates an ugly, in-frame menu bar.
 (eval-when! doom--system-macos-p
   (add-hook! '(window-setup-hook after-make-frame-functions)
     (defun doom-restore-menu-bar-in-gui-frames-h (&optional frame)
@@ -136,7 +138,7 @@
 ;; a step too opinionated.
 (setq default-input-method nil)
 ;; ...And the clipboard on Windows could be in a wider encoding (UTF-16), so
-;; leave Emacs to its own devices.
+;; leave Emacs to its own devices there.
 (eval-when! (not doom--system-windows-p)
   (setq selection-coding-system 'utf-8))
 
@@ -180,7 +182,7 @@
 (defvar doom-incremental-packages '(t)
   "A list of packages to load incrementally after startup. Any large packages
 here may cause noticeable pauses, so it's recommended you break them up into
-sub-packages. For example, `org' is comprised of many packages, and can be
+sub-packages. For example, `org' is comprised of many packages, and might be
 broken up into:
 
   (doom-load-packages-incrementally
@@ -192,7 +194,7 @@ broken up into:
 This is already done by the lang/org module, however.
 
 If you want to disable incremental loading altogether, either remove
-`doom-load-packages-incrementally-h' from `emacs-startup-hook' or set
+`doom-load-packages-incrementally-h' from `doom-after-init-hook' or set
 `doom-incremental-first-idle-timer' to nil. Incremental loading does not occur
 in daemon sessions (they are loaded immediately at startup).")
 
@@ -201,7 +203,7 @@ in daemon sessions (they are loaded immediately at startup).")
 
 Set this to nil to disable incremental loading at startup.
 Set this to 0 to load all incrementally deferred packages immediately at
-`emacs-startup-hook'.")
+`doom-after-init-hook'.")
 
 (defvar doom-incremental-idle-timer 0.75
   "How long (in idle seconds) in between incrementally loading packages.")

lisp/doom.el

@@ -59,9 +59,13 @@
 ;;     - On first switched-to buffer: `doom-first-buffer-hook'
 ;;     - On first opened file:        `doom-first-file-hook'
 ;;
-;; This is Doom's heart, where I define all its major constants and variables,
+;; This file is Doom's heart, where I define all its major constants and
-;; set only its sanest global defaults, employ its hackiest (and least
+;; variables, set only its sanest global defaults, employ its hackiest (and
-;; offensive) optimizations, and load the minimum for all Doom sessions.
+;; least offensive) optimizations, and load the minimum needed for all Doom
+;; sessions, interactive or otherwise.
+;;
+;; See doom-start.el for initialization intended solely for interactive
+;; sessions, and doom-cli.el for non-interactive sessions.
 ;;
 ;;; Code:
 
@@ -110,7 +114,8 @@
 ;;; 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.
+;; include information about the external system environment. Module-specific
+;; features are kept elsewhere, however.
 (defconst doom-features
   (pcase system-type
     ('darwin                           '(macos bsd))
@@ -410,8 +415,9 @@ users).")
 
     ;; PERF: Shave seconds off startup time by starting the scratch buffer in
     ;;   `fundamental-mode', rather than, say, `org-mode' or `text-mode', which
-    ;;   pull in a ton of packages. `doom/open-scratch-buffer' provides a better
+    ;;   pull in a ton of packages. This buffer is created whether or not we're
-    ;;   scratch buffer anyway.
+    ;;   in an interactive session. Plus, `doom/open-scratch-buffer' provides a
+    ;;   better scratch buffer, so keep the initial one blank.
     (setq initial-major-mode 'fundamental-mode
           initial-scratch-message nil)