nit: comment revision and formatting

For clarity, to enforce conventions, and explain the unexplained.

lisp/doom-editor.el

@@ -1,4 +1,6 @@
-;;; doom-editor.el -*- lexical-binding: t; -*-
+;;; doom-editor.el --- defaults for text editing in Doom -*- lexical-binding: t; -*-
+;;; Commentary:
+;;; Code:
 
 (defvar doom-detect-indentation-excluded-modes
   '(fundamental-mode pascal-mode so-long-mode doom-docs-org-mode)

lisp/doom-keybinds.el

@@ -1,4 +1,4 @@
-;;; doom-keybinds.el -*- lexical-binding: t; -*-
+;;; doom-keybinds.el --- defaults for Doom's keybinds -*- lexical-binding: t; -*-
 ;;; Commentary:
 ;;
 ;; A centralized keybinds system, integrated with `which-key' to preview

lisp/doom-modules.el

@@ -104,7 +104,6 @@ before the user's private module.")
 
 This closure takes two arguments: a cons cell containing (CATEGORY . MODULE)
 symbols, and that module's plist."
-  (declare (pure t) (side-effect-free t))
   (lambda (module plist)
     (let ((doom--current-module module)
           (doom--current-flags (cdr (get (car module) (cdr module))))

lisp/doom-projects.el

@@ -1,4 +1,6 @@
-;;; doom-projects.el -*- lexical-binding: t; -*-
+;;; doom-projects.el --- defaults for project management in Doom -*- lexical-binding: t; -*-
+;;; Commentary:
+;;; Code:
 
 (defvar doom-projectile-cache-limit 10000
   "If any project cache surpasses this many files it is purged when quitting

lisp/doom-start.el

@@ -25,18 +25,18 @@
 ;;; Reasonable defaults for interactive sessions
 
 ;;; Runtime optimizations
-;; A second, case-insensitive pass over `auto-mode-alist' is time wasted.
+;; PERF: A second, case-insensitive pass over `auto-mode-alist' is time wasted.
 (setq auto-mode-case-fold nil)
 
-;; Disable bidirectional text scanning for a modest performance boost. I've set
-;; this to `nil' in the past, but the `bidi-display-reordering's docs say that
-;; is an undefined state and suggest this to be just as good:
+;; PERF: Disable bidirectional text scanning for a modest performance boost.
+;;   I've set this to `nil' in the past, but the `bidi-display-reordering's docs
+;;   say that is an undefined state and suggest this to be just as good:
 (setq-default bidi-display-reordering 'left-to-right
               bidi-paragraph-direction 'left-to-right)
 
-;; Disabling the BPA makes redisplay faster, but might produce incorrect display
-;; reordering of bidirectional text with embedded parentheses and other bracket
-;; characters whose 'paired-bracket' Unicode property is non-nil.
+;; PERF: Disabling BPA makes redisplay faster, but might produce incorrect
+;;   reordering of bidirectional text with embedded parentheses (and other
+;;   bracket characters whose 'paired-bracket' Unicode property is non-nil).
 (setq bidi-inhibit-bpa t)  ; Emacs 27+ only
 
 ;; Reduce rendering/line scan work for Emacs by not rendering cursors or regions
@@ -300,6 +300,10 @@ If RETURN-P, return the message as a string instead of displaying it."
                      (float-time (time-subtract (current-time) before-init-time))))))
 
 
+;;
+;;; Let 'er rip!
+
+;;; Load loaddefs
 ;; Doom caches a lot of information in `doom-autoloads-file'. Module and package
 ;; autoloads, autodefs like `set-company-backend!', and variables like
 ;; `doom-modules', `doom-disabled-packages', `load-path', `auto-mode-alist', and
@@ -321,6 +325,10 @@ If RETURN-P, return the message as a string instead of displaying it."
              (list "Doom is in an incomplete state"
                    "run 'doom sync' on the command line to repair it")))))
 
+;;; Load envvar file
+;; 'doom env' generates an envvar file. This is a snapshot of your shell
+;; environment, which Doom loads here. This is helpful in scenarios where Emacs
+;; is launched from an environment detached from the user's shell environment.
 (when (and (or (display-graphic-p)
                (daemonp))
            doom-env-file)
@@ -336,7 +344,8 @@ If RETURN-P, return the message as a string instead of displaying it."
 (doom-run-hook-on 'doom-first-file-hook   '(find-file-hook dired-initial-position-hook))
 (doom-run-hook-on 'doom-first-input-hook  '(pre-command-hook))
 
-;; There's a chance the user will later use package.el or straight in this
+;;; Setup autoloads for major core libraries
+;; UX: There's a chance the user will later use package.el or straight in this
 ;;   interactive session. If they do, make sure they're properly initialized
 ;;   when they do.
 (autoload 'doom-initialize-packages "doom-packages")

lisp/doom-ui.el

@@ -1,4 +1,6 @@
-;;; doom-ui.el -*- lexical-binding: t; -*-
+;;; doom-ui.el --- defaults for Doom's aesthetics -*- lexical-binding: t; -*-
+;;; Commentary:
+;;; Code;
 
 ;;
 ;;; Variables
@@ -253,13 +255,14 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 ;; when resizing too many windows at once or rapidly.
 (setq window-resize-pixelwise nil)
 
-;; Disable tool, menu, and scrollbars. Doom is designed to be keyboard-centric,
-;; so these are just clutter (the scrollbar also impacts performance). Whats
-;; more, the menu bar exposes functionality that Doom doesn't endorse.
+;; 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,
+;;   the menu bar exposes functionality that Doom doesn't endorse. Perhaps one
+;;   day Doom will support these, but today is not that day.
 ;;
-;; I am intentionally not calling `menu-bar-mode', `tool-bar-mode', and
-;; `scroll-bar-mode' because they do extra and unnecessary work that can be more
-;; concisely and efficiently expressed with these six lines:
+;; HACK: I intentionally avoid calling `menu-bar-mode', `tool-bar-mode', and
+;;   `scroll-bar-mode' because they do extra work to manipulate frame variables
+;;   that isn't necessary this early in the startup process.
 (push '(menu-bar-lines . 0)   default-frame-alist)
 (push '(tool-bar-lines . 0)   default-frame-alist)
 (push '(vertical-scroll-bars) default-frame-alist)
@@ -268,9 +271,11 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 (setq menu-bar-mode nil
       tool-bar-mode nil
       scroll-bar-mode nil)
+;; Note, that disabling `menu-bar-mode' can cause issues on MacOS. See the
+;; :os macos module for a fix.
 
-;; The native border "consumes" a pixel of the fringe on righter-most splits,
-;; `window-divider' does not. Available since Emacs 25.1.
+;; FIX: The native border "consumes" a pixel of the fringe on righter-most
+;;   splits, `window-divider' does not. Available since Emacs 25.1.
 (setq window-divider-default-places t
       window-divider-default-bottom-width 1
       window-divider-default-right-width 1)
@@ -285,7 +290,7 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 (when IS-LINUX
   (setq x-gtk-use-system-tooltips nil))
 
- ;; Favor vertical splits over horizontal ones. Monitors are trending toward
+;; UX: Favor vertical splits over horizontal ones. Monitors are trending toward
 ;;   wide, rather than tall.
 (setq split-width-threshold 160
       split-height-threshold nil)
@@ -309,7 +314,7 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 ;; Typing yes/no is obnoxious when y/n will do
 (if (boundp 'use-short-answers)
     (setq use-short-answers t)
-  ;; DEPRECATED Remove when we drop 27.x support
+  ;; DEPRECATED: Remove when we drop 27.x support
   (advice-add #'yes-or-no-p :override #'y-or-n-p))
 
 ;; Try to keep the cursor out of the read-only portions of the minibuffer.

lisp/doom.el

@@ -344,7 +344,8 @@ users).")
 ;;   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 setting a million directory/file variables.
+;;   trouble of setting a million directory/file variables. But it may throw off
+;;   anyone (or any package) that uses it to search for your Emacs initfiles.
 (setq user-emacs-directory doom-cache-dir)
 
 ;; ...However, this may surprise packages (and users) that read
@@ -380,6 +381,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to
 ;;
 ;;; Reasonable, global defaults
 
+;;; Reduce unnecessary/unactionable warnings/logs
 ;; Disable warnings from the legacy advice API. They aren't actionable or
 ;; useful, and often come from third party packages.
 (setq ad-redefinition-action 'accept)
@@ -396,6 +398,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to
 (setq debug-on-error init-file-debug
       jka-compr-verbose init-file-debug)
 
+;;; Stricter security defaults
 ;; Emacs is essentially one huge security vulnerability, what with all the
 ;; dependencies it pulls in from all corners of the globe. Let's try to be a
 ;; *little* more discerning.

modules/os/macos/config.el

@@ -12,7 +12,7 @@
 ;;; Compatibilty fixes
 
 ;; Curse Lion and its sudden but inevitable fullscreen mode!
-;; NOTE Meaningless to railwaycat's emacs-mac build
+;; This is meaningless to railwaycat's emacs-mac build though.
 (setq ns-use-native-fullscreen nil)
 
 ;; Visit files opened outside of Emacs in existing frame, not a new one
@@ -29,7 +29,7 @@
      (require 'ns-auto-titlebar nil t)
      (ns-auto-titlebar-mode +1))
 
-;; HACK On MacOS, disabling the menu bar makes MacOS treat Emacs as a
+;; HACK: On MacOS, disabling the menu bar makes MacOS treat Emacs as a
 ;;   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