nit: comment revision & reformatting

lisp/doom-start.el

@@ -64,11 +64,12 @@
 ;; usage, however!
 (setq inhibit-compacting-font-caches t)
 
-;; PGTK builds only: this timeout adds latency to frame operations, like
-;; `make-frame-invisible', which are frequently called without a guard because
-;; it's inexpensive in non-PGTK builds. Lowering the timeout from the default
-;; 0.1 should make childframes and packages that manipulate them (like `lsp-ui',
-;; `company-box', and `posframe') feel much snappier. See emacs-lsp/lsp-ui#613.
+;; PGTK builds only: there's a timeout that adds latency to frame operations,
+;; like `make-frame-invisible', which Emacs frequently calls without a guard
+;; because it's inexpensive in non-PGTK builds. Lowering the timeout from the
+;; default 0.1 should make childframes and packages that manipulate them (like
+;; `lsp-ui', `company-box', and `posframe') feel much snappier. See
+;; emacs-lsp/lsp-ui#613.
 (eval-when! (boundp 'pgtk-wait-for-event-timeout)
   (setq pgtk-wait-for-event-timeout 0.001))
 
@@ -90,8 +91,8 @@
 ;; The GC introduces annoying pauses and stuttering into our Emacs experience,
 ;; so we use `gcmh' to stave off the GC while we're using Emacs, and provoke it
 ;; when it's idle. However, if the idle delay is too long, we run the risk of
-;; runaway memory usage in busy sessions. If it's too low, then we may as well
-;; not be using gcmh at all.
+;; runaway memory usage in busy sessions. And if it's too low, then we may as
+;; well not be using gcmh at all.
 (setq gcmh-idle-delay 'auto  ; default is 15s
       gcmh-auto-idle-delay-factor 10
       gcmh-high-cons-threshold (* 16 1024 1024))  ; 16mb
@@ -124,11 +125,10 @@
 ;;   disabling Emacs' menu-bar also makes MacOS treat Emacs GUI frames like
 ;;   non-application windows (e.g. it won't capture focus on activation, among
 ;;   other things), so the menu-bar should be preserved there.
-;;
 (when doom--system-macos-p
-  ;; NOTE: The correct way to disable this hack is to toggle `menu-bar-mode' (or
-  ;;   put it on a hook). Don't try to undo the hack below, as it may change
-  ;;   without warning, but will always respect `menu-bar-mode'.
+  ;; NOTE: Don't try to undo the hack below, as it may change without warning.
+  ;;   Instead, toggle `menu-bar-mode' (or put it on a hook) as normal. This
+  ;;   hack will always try to respect the state of `menu-bar-mode'.
   (setcdr (assq 'menu-bar-lines default-frame-alist) 'tty)
   (add-hook! 'after-make-frame-functions
     (defun doom--init-menu-bar-on-macos-h (&optional frame)
@@ -357,8 +357,8 @@ If RETURN-P, return the message as a string instead of displaying it."
 ;;      and ~/_emacs) -- and spare us the IO of searching for them, and allows
 ;;      savvy hackers to use $EMACSDIR as their $DOOMDIR, if they wanted.
 ;;   3. Cut down on unnecessary logic in Emacs' bootstrapper.
-;;   4. Offer a more user-friendly error state/screen, especially for errors
-;;      emitted from Doom's core or the user's config.
+;;   4. TODO Offer a more user-friendly error state/screen, especially for
+;;      errors emitted from Doom's core or the user's config.
 (define-advice startup--load-user-init-file (:override (&rest _) init-doom 100)
   (let ((debug-on-error-from-init-file nil)
         (debug-on-error-should-be-set nil)

lisp/doom.el

@@ -148,8 +148,9 @@
     (push 'harfbuzz features))
 
 ;; The `native-compile' feature exists whether or not it is functional (e.g.
-;; libgcc is available or not). This seems silly, so pretend it doesn't exist if
-;; it isn't functional.
+;; 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
+;; pretend it doesn't exist if that's the case.
 (if (featurep 'native-compile)
     (if (not (native-comp-available-p))
         (delq 'native-compile features)))
@@ -393,10 +394,10 @@ users).")
 
   (unless noninteractive
     ;; PERF: Resizing the Emacs frame (to accommodate fonts that are smaller or
-    ;;   larger than the system font) appears to impact startup time
+    ;;   larger than the default system font) can impact startup time
     ;;   dramatically. The larger the delta, the greater the delay. Even trivial
-    ;;   deltas can yield up to a ~1000ms loss, depending on font size and
-    ;;   `window-system'. PGTK seems least affected and NS/MAC the most.
+    ;;   deltas can yield up to a ~1000ms loss, depending also on
+    ;;   `window-system' (PGTK builds seem least affected and NS/MAC the most).
     (setq frame-inhibit-implied-resize t)
 
     ;; PERF: A fair bit of startup time goes into initializing the splash and
@@ -432,14 +433,14 @@ users).")
                                 (selected-frame) nil t))))
 
     ;; PERF: `load-suffixes' and `load-file-rep-suffixes' are consulted on each
-    ;;   `require' and `load'. Doom won't load any modules this early, so omit
-    ;;   .so for a tiny startup boost. Is later restored in doom-start.
+    ;;   `require' and `load'. Doom won't load any modules this early, so I omit
+    ;;   *.so for a tiny startup boost. Is later restored in `doom-start'.
     (put 'load-suffixes 'initial-value (default-toplevel-value 'load-suffixes))
     (put 'load-file-rep-suffixes 'initial-value (default-toplevel-value 'load-file-rep-suffixes))
     (set-default-toplevel-value 'load-suffixes '(".elc" ".el"))
     (set-default-toplevel-value 'load-file-rep-suffixes '(""))
-    ;; COMPAT: Undo any problematic startup optimizations; from this point, I
-    ;;   make no assumptions about what might be loaded in userland.
+    ;; COMPAT: Undo any problematic startup optimizations eventually, to prevent
+    ;;   incompatibilities with anything loaded in userland.
     (add-hook! 'doom-before-init-hook
       (defun doom--reset-load-suffixes-h ()
         (setq load-suffixes (get 'load-suffixes 'initial-value)
@@ -458,10 +459,10 @@ users).")
         (setq custom-dont-initialize nil)))
 
     ;; PERF: The mode-line procs a couple dozen times during startup, before the
-    ;;   user can even see the first mode-line. This is normally fast, but we
-    ;;   can't predict what the user (or packages) will put into the mode-line.
-    ;;   Also, mode-line packages have a bad habit of throwing performance to
-    ;;   the wind, so best we just disable the mode-line until we can see one.
+    ;;   user even sees the first mode-line. This is normally fast, but we can't
+    ;;   predict what the user (or packages) will put into the mode-line. Also,
+    ;;   mode-line packages have a bad habit of throwing performance to the
+    ;;   wind, so best we just disable the mode-line until we can see one.
     (put 'mode-line-format 'initial-value (default-toplevel-value 'mode-line-format))
     (setq-default mode-line-format nil)
     (dolist (buf (buffer-list))

modules/completion/corfu/config.el

@@ -28,8 +28,10 @@ TAB/S-TAB.")
   "If non-nil, prefer navigating org tables over cycling candidates with
 TAB/S-TAB.")
 
+
 ;;
 ;;; Packages
+
 (use-package! corfu
   :hook (doom-first-input . global-corfu-mode)
   :init

modules/editor/format/autoload/lsp.el

@@ -2,7 +2,6 @@
 ;;;###if (modulep! :tools lsp)
 
 (defvar +format-lsp--last nil)
-
 ;;;###autoload
 (define-minor-mode +format-with-lsp-mode
   "Toggles `lsp-mode'/`eglot' integration with `apheleia-mode' in this buffer.

modules/emacs/dired/config.el

@@ -1,8 +1,12 @@
-;;; tools/dired/config.el -*- lexical-binding: t; -*-
+;;; emacs/dired/config.el -*- lexical-binding: t; -*-
 
 (defvar +dired-dirvish-icon-provider 'nerd-icons
   "Icon provider to use for dirvish when the module is enabled.")
 
+
+;;
+;;; Packages
+
 (use-package! dired
   :commands dired-jump
   :init

modules/lang/beancount/config.el

@@ -18,7 +18,7 @@
   ;; HACK: The intro message changed in newer versions of Fava, plus, the output
   ;;   could contain ANSI codes, causing the `beancount-fava' command to not
   ;;   open the server in the browser after the server has started.
-  ;; REVIEW: PR this uptsream!
+  ;; REVIEW: PR this upstream!
   (defadvice! +beancount--open-in-browser-after-starting-fix-a (_process output)
     :override #'beancount--fava-filter
     (save-match-data

modules/lang/clojure/config.el

@@ -10,6 +10,7 @@
 (defvar +clojure-load-clj-refactor-with-lsp nil
   "Whether or not to include clj-refactor along with clojure-lsp.")
 
+
 ;;
 ;;; Packages
 

modules/lang/go/config.el

@@ -69,6 +69,7 @@
   (set-company-backend! 'go-mode 'company-go)
   (setq company-go-show-annotation t))
 
+
 (use-package! flycheck-golangci-lint
   :when (and (modulep! :checkers syntax)
              (not (modulep! :checkers syntax +flymake)))

modules/lang/haskell/config.el

@@ -6,7 +6,7 @@
 
 
 ;;
-;;; Common packages
+;;; Packages
 
 (after! haskell-mode
   (setq haskell-process-suggest-remove-import-lines t  ; warnings for redundant imports etc

modules/os/macos/config.el

@@ -18,7 +18,9 @@
 ;; Visit files opened outside of Emacs in existing frame, not a new one
 (setq ns-pop-up-frames nil)
 
-;; sane trackpad/mouse scroll settings
+;; Sane trackpad/mouse scroll settings. Also disables smooth scrolling because
+;; it's disturbingly clunky and slow without something like
+;; jdtsmith/ultra-scroll-mac.
 (setq mac-redisplay-dont-reset-vscroll t
       mac-mouse-wheel-smooth-scroll nil)
 

modules/ui/popup/autoload/settings.el

@@ -163,6 +163,7 @@ used.
 \(fn PREDICATE &key IGNORE ACTIONS SIDE SIZE WIDTH HEIGHT SLOT VSLOT TTL QUIT SELECT MODELINE AUTOSAVE PARAMETERS)"
   (declare (indent defun))
   (push (+popup-make-rule predicate plist) +popup--display-buffer-alist)
+  ;; TODO: Don't overwrite user entries in `display-buffer-alist'
   (when (bound-and-true-p +popup-mode)
     (setq display-buffer-alist +popup--display-buffer-alist))
   +popup--display-buffer-alist)