Minor refactors; revise docstrings+comments

core/core-keybinds.el

@@ -2,7 +2,8 @@
 
 ;; A centralized keybinds system, integrated with `which-key' to preview
 ;; available keybindings. All built into one powerful macro: `map!'. If evil is
-;; never loaded, then evil bindings set with `map!' will be ignored.
+;; never loaded, then evil bindings set with `map!' are ignored (i.e. omitted
+;; entirely for performance reasons).
 
 (defvar doom-leader-key "SPC"
   "The leader prefix key for Evil users.
@@ -33,6 +34,22 @@ This needs to be changed from $DOOMDIR/init.el.")
 
 
 ;;
+;;; Universal, non-nuclear escape
+
+;; `keyboard-quit' is too much of a nuclear option. I wanted an ESC/C-g to
+;; do-what-I-mean. It serves four purposes (in order):
+;;
+;; 1. Quit active states; e.g. highlights, searches, snippets, iedit,
+;;    multiple-cursors, recording macros, etc.
+;; 2. Close popup windows remotely (if it is allowed to)
+;; 3. Refresh buffer indicators, like git-gutter and flycheck
+;; 4. Or fall back to `keyboard-quit'
+;;
+;; And it should do these things incrementally, rather than all at once. And it
+;; shouldn't interfere with recording macros or the minibuffer. This may require
+;; you press ESC/C-g two or three times on some occasions to reach
+;; `keyboard-quit', but this is much more intuitive.
+
 (defvar doom-escape-hook nil
   "A hook run after C-g is pressed (or ESC in normal mode, for evil users). Both
 trigger `doom/escape'.
@@ -88,12 +105,12 @@ If any hook returns non-nil, all hooks after it are ignored.")
 
 ;; We use a prefix commands instead of general's :prefix/:non-normal-prefix
 ;; properties because general is incredibly slow binding keys en mass with them
-;; in conjunction with :states. This effectively doubled Doom's startup time.
+;; in conjunction with :states -- an effective doubling of Doom's startup time!
 (define-prefix-command 'doom/leader 'doom-leader-map)
 (define-key doom-leader-map [override-state] 'all)
 
 ;; Bind `doom-leader-key' and `doom-leader-alt-key' as late as possible to give
-;; the user more changes to modify them.
+;; the user a chance to modify them.
 (defun doom|init-leader-keys ()
   "Bind `doom-leader-key' and `doom-leader-alt-key'."
   (let ((map general-override-mode-map))
@@ -111,15 +128,15 @@ If any hook returns non-nil, all hooks after it are ignored.")
                 "\\)")))
 (add-hook 'doom-after-init-modules-hook #'doom|init-leader-keys)
 
-;; ...However, this approach (along with :wk-full-keys in `define-leader-key!')
+;; However, the prefix command approach (along with :wk-full-keys in
-;; means that which-key is only informed of the key sequence *after*
+;; `define-leader-key!') means that which-key is only informed of the key
-;; `doom-leader-key'/`doom-leader-alt-key'. e.g. binding to `SPC f s' will
+;; sequence minus `doom-leader-key'/`doom-leader-alt-key'. e.g. binding to `SPC
-;; create a which-key label for any key that ends in 'f s'.
+;; f s' creates a wildcard label for any key that ends in 'f s'.
 ;;
-;; TO get around that, we forcibly inject `doom-leader-key' and
+;; So we forcibly inject `doom-leader-key' and `doom-leader-alt-key' into the
-;; `doom-leader-alt-key' into the which-key key replacement regexp for keybinds
+;; which-key key replacement regexp for keybinds created on `doom-leader-map'.
-;; created on `doom-leader-map'. This is a dirty hack, but I'd rather this than
+;; This is a dirty hack, but I'd rather this than general being responsible for
-;; general being responsible for 50% of Doom's startup time.
+;; 50% of Doom's startup time.
 (defun doom*general-extended-def-:which-key (_state keymap key edef kargs)
   (with-eval-after-load 'which-key
     (let* ((wk (general--getf2 edef :which-key :wk))
@@ -194,6 +211,8 @@ If any hook returns non-nil, all hooks after it are ignored.")
 
 
 ;;
+;;; `map!' macro
+
 (defvar doom-evil-state-alist
   '((?n . normal)
     (?v . visual)

core/core-modules.el

@@ -211,34 +211,13 @@ non-nil, return paths of possible modules, activated or otherwise."
       use-package-minimum-reported-time (if doom-debug-mode 0 0.1)
       use-package-expand-minimally (not noninteractive))
 
-;; Adds two new keywords to `use-package' (and consequently, `def-package!'),
+;; Adds two new keywords to `use-package' (and consequently, `def-package!') to
-;; they are:
+;; expand its lazy-loading capabilities. They are:
 ;;
 ;; :after-call SYMBOL|LIST
-;;   Takes a symbol or list of symbols representing functions or hook variables.
-;;   The first time any of these functions or hooks are executed, the package is
-;;   loaded. e.g.
-;;
-;;   (def-package! projectile
-;;     :after-call (pre-command-hook after-find-file dired-before-readin-hook)
-;;     ...)
-;;
 ;; :defer-incrementally SYMBOL|LIST|t
-;;   Takes a symbol or list of symbols representing packages that will be loaded
-;;   incrementally at startup before this one. This is helpful for large
-;;   packages like magit or org, which load a lot of dependencies on first load.
-;;   This lets you load them piece-meal, one at a time, during idle periods, so
-;;   that when you finally do need the package, it'll loads much quicker. e.g.
 ;;
-;;   (def-package! magit
+;; Check out `def-package!'s documentation for more about these two.
-;;     ;; You do not need to include magit in this list!
-;;     :defer-incrementally (dash f s with-editor git-commit package)
-;;     ...)
-;;
-;;   (def-package! x
-;;     ;; This is equivalent to :defer-incrementally (x)
-;;     :defer-incrementally t
-;;     ...)
 (defvar doom--deferred-packages-alist '(t))
 (after! use-package-core
   ;; :ensure and :pin don't work well with Doom, so we forcibly remove them.
@@ -356,8 +335,35 @@ to least)."
 
 (defvar doom-disabled-packages)
 (defmacro def-package! (name &rest plist)
-  "This is a thin wrapper around `use-package'. It is ignored if the NAME
+  "This is a thin wrapper around `use-package'.
-package is disabled."
+
+It is ignored if the NAME package is disabled.
+
+Supports two special properties over `use-package':
+
+:after-call SYMBOL|LIST
+  Takes a symbol or list of symbols representing functions or hook variables.
+  The first time any of these functions or hooks are executed, the package is
+  loaded. e.g.
+
+  (def-package! projectile
+    :after-call (pre-command-hook after-find-file dired-before-readin-hook)
+    ...)
+
+:defer-incrementally SYMBOL|LIST|t
+  Takes a symbol or list of symbols representing packages that will be loaded
+  incrementally at startup before this one. This is helpful for large packages
+  like magit or org, which load a lot of dependencies on first load. This lets
+  you load them piece-meal during idle periods, so that when you finally do need
+  the package, it'll load quicker. e.g.
+
+  NAME is implicitly added if this property is present and non-nil. No need to
+  specify it. A value of `t' implies NAME, e.g.
+
+  (def-package! x
+    ;; This is equivalent to :defer-incrementally (x)
+    :defer-incrementally t
+    ...)"
   (unless (or (memq name doom-disabled-packages)
               ;; At compile-time, use-package will forcibly load its package to
               ;; prevent compile-time errors. However, Doom users can

modules/config/default/+evil-bindings.el

@@ -495,11 +495,10 @@
       :desc "Toggle last popup"     "~"    #'+popup/toggle
       :desc "Find file"             "."    #'find-file
 
+      :desc "Switch buffer"         ","    #'switch-to-buffer
       (:when (featurep! :feature workspaces)
         :desc "Switch workspace buffer" "," #'persp-switch-to-buffer
         :desc "Switch buffer"           "<" #'switch-to-buffer)
-      (:unless (featurep! :feature workspaces)
-        :desc "Switch buffer"           "," #'switch-to-buffer)
 
       :desc "Resume last search"    "'"
       (cond ((featurep! :completion ivy)   #'ivy-resume)