From c6063de4399411e45a06e8ac14249b323419ae6c Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Mon, 11 Mar 2024 00:47:13 -0400 Subject: [PATCH] nit: revise and reformat comments --- early-init.el | 6 +++--- lisp/doom-keybinds.el | 6 +++--- lisp/doom-lib.el | 14 +++++++------- lisp/doom-start.el | 24 +++++++++++++----------- lisp/doom.el | 18 ++++++++++++------ 5 files changed, 38 insertions(+), 30 deletions(-) diff --git a/early-init.el b/early-init.el index 922972c02..bc6032b42 100644 --- a/early-init.el +++ b/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 - ;; (like permission or IO errors) should not be suppressed or - ;; interpreted as "this is not a Doom config". + ;; I avoid `load's NOERROR argument because it suppresses other, + ;; legitimate errors (like permission or IO errors), which gets + ;; 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) diff --git a/lisp/doom-keybinds.el b/lisp/doom-keybinds.el index f6ff2a99a..210432fc5 100644 --- a/lisp/doom-keybinds.el +++ b/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. -;; Otherwise, it falls back to regular C-i keybinds. +;; In the same vein, this keybind adds a [C-i] event, so users can bind to it +;; 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 diff --git a/lisp/doom-lib.el b/lisp/doom-lib.el index c33edede1..9f996d3e7 100644 --- a/lisp/doom-lib.el +++ b/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." - (let (file-name-handler-alist) - (file-name-directory (macroexpand '(file!))))) + "Return the directory of the file in which this macro was called." + (let (file-name-handler-alist) + (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") diff --git a/lisp/doom-start.el b/lisp/doom-start.el index e52624bcf..2c25a3421 100644 --- a/lisp/doom-start.el +++ b/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, -;; the menu bar exposes functionality that Doom doesn't endorse. Perhaps one -;; day Doom will support these, but today is not that day. -;; +;; clutter. Initializing them also costs a morsel of startup time. What's +;; more, the menu bar exposes functionality that Doom doesn't endorse. Perhaps +;; 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 -;; that isn't necessary this early in the startup process. +;; `scroll-bar-mode' because their manipulation of frame parameters can +;; 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.") diff --git a/lisp/doom.el b/lisp/doom.el index 5f9835224..65924d1ec 100644 --- a/lisp/doom.el +++ b/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, -;; set only its sanest global defaults, employ its hackiest (and least -;; offensive) optimizations, and load the minimum for all Doom sessions. +;; This file is Doom's heart, where I define all its major constants and +;; variables, set only its sanest global defaults, employ its hackiest (and +;; 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 - ;; scratch buffer anyway. + ;; pull in a ton of packages. This buffer is created whether or not we're + ;; 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)