General refactor for readability

+ Removes redundant/unhelpful comments
+ Renames functions, hooks and variables to be self-documenting
+ Use add-to-list to ensure idempotency (and is more performant)

modules/feature/workspaces/config.el

@@ -13,8 +13,7 @@
 ;; NOTE persp-mode requires `workgroups' for file persistence in Emacs 24.4.
 
 (defvar +workspaces-main "main"
-  "The name of the primary and initial workspace, which cannot be deleted or
-renamed.")
+  "The name of the primary and initial workspace, which cannot be deleted.")
 
 (defvar +workspaces-switch-project-function #'doom-project-find-file
   "The function to run after `projectile-switch-project' or
@@ -27,7 +26,7 @@ new project directory.")
 stored in `persp-save-dir'.")
 
 ;; If emacs is passed --restore, restore the last session on startup. This is
-;; particularly useful for the `+workspace/restart-emacs-then-restore' command.
+;; used by the `+workspace/restart-emacs-then-restore' command.
 (defun +workspaces-restore-last-session (&rest _)
   (add-hook 'emacs-startup-hook #'+workspace/load-session :append))
 (add-to-list 'command-switch-alist (cons "--restore" #'+workspaces-restore-last-session))
@@ -51,7 +50,7 @@ stored in `persp-save-dir'.")
       (+workspaces|init-frame (selected-frame))))
 
   (defun +workspaces|init-frame (frame)
-    "Make sure a main workspace exists and is switched to, if FRAME isn't in any
+    "Ensure a main workspace exists and is switched to, if FRAME isn't in any
 workspace. Also ensures that the *Warnings* buffer will be visible in main.
 
 Uses `+workspaces-main' to determine the name of the main workspace."
@@ -60,10 +59,10 @@ Uses `+workspaces-main' to determine the name of the main workspace."
     (unless noninteractive
       (let (persp-before-switch-functions persp-activated-functions)
         (with-selected-frame frame
-          ;; The default perspective persp-mode makes (defined by
-          ;; `persp-nil-name') is special and doesn't actually represent a real
-          ;; persp object, so buffers can't really be assigned to it, among
-          ;; other quirks. We create a *real* main workspace to fill this role.
+          ;; The default perspective persp-mode creates (`persp-nil-name') is
+          ;; special and doesn't represent a real persp object, so buffers can't
+          ;; really be assigned to it, among other quirks. We create a *real*
+          ;; main workspace to fill this role.
           (unless (persp-get-by-name +workspaces-main)
             (persp-add-new +workspaces-main))
           ;; Switch to it if we aren't auto-loading the last session
@@ -73,9 +72,8 @@ Uses `+workspaces-main' to determine the name of the main workspace."
             ;; We want to know where we are in every new daemon frame
             (when (daemonp)
               (run-at-time 0.1 nil #'+workspace/display))
-            ;; The warnings buffer gets swallowed by creating
-            ;; `+workspaces-main', so we display it manually, if it exists (fix
-            ;; #319).
+            ;; Fix #319: the warnings buffer gets swallowed by creating
+            ;; `+workspaces-main', so we display it manually, if it exists.
             (when-let* ((warnings (get-buffer "*Warnings*")))
               (save-excursion
                 (display-buffer-in-side-window
@@ -93,21 +91,22 @@ Uses `+workspaces-main' to determine the name of the main workspace."
         persp-auto-resume-time -1 ; Don't auto-load on startup
         persp-auto-save-opt (if noninteractive 0 1)) ; auto-save on kill
 
+  (advice-add #'persp-asave-on-exit :around #'+workspaces*autosave-real-buffers)
+
+  (add-hook 'doom-cleanup-hook #'+workspaces|cleanup-unassociated-buffers)
+
   ;; Ensure buffers we've opened/switched to are auto-added to the current
   ;; perspective
   (setq persp-add-buffer-on-find-file t
         persp-add-buffer-on-after-change-major-mode t)
   (add-hook 'persp-add-buffer-on-after-change-major-mode-filter-functions #'doom-unreal-buffer-p)
 
-  ;; bootstrap
   (defun +workspaces|init-persp-mode ()
     (cond (persp-mode
-           ;; Ensure `persp-kill-buffer-query-function' is last in
-           ;; kill-buffer-query-functions
+           ;; `persp-kill-buffer-query-function' must be last
            (remove-hook 'kill-buffer-query-functions 'persp-kill-buffer-query-function)
            (add-hook 'kill-buffer-query-functions 'persp-kill-buffer-query-function t)
-           ;; Remap `buffer-list' to current workspace's buffers in
-           ;; `doom-buffer-list'
+           ;; Restrict buffer list to workspace
            (advice-add #'doom-buffer-list :override #'+workspace-buffer-list))
           ((advice-remove #'doom-buffer-list #'+workspace-buffer-list))))
   (add-hook 'persp-mode-hook #'+workspaces|init-persp-mode)
@@ -120,22 +119,16 @@ Uses `+workspaces-main' to determine the name of the main workspace."
                          'auto-create)))
   (add-hook 'persp-after-load-state-functions #'+workspaces|leave-nil-perspective)
 
-  ;; Modify `delete-window' to close the workspace if used on the last window
+  ;; Delete the current workspace if closing the last open window
   (define-key! persp-mode-map
-    [remap restart-emacs] #'+workspace/restart-emacs-then-restore
     [remap delete-window] #'+workspace/close-window-or-workspace
     [remap evil-delete-window] #'+workspace/close-window-or-workspace)
-  ;; only auto-save when real buffers are present
-  (advice-add #'persp-asave-on-exit :around #'+workspaces*autosave-real-buffers)
-  ;; On `doom/cleanup-session', delete buffers associated with no perspectives
-  (add-hook 'doom-cleanup-hook #'+workspaces|cleanup-unassociated-buffers)
 
   ;; per-frame workspaces
   (setq persp-init-frame-behaviour t
         persp-init-new-frame-behaviour-override nil
         persp-interactive-init-frame-behaviour-override #'+workspaces|associate-frame
         persp-emacsclient-init-frame-behaviour-override #'+workspaces|associate-frame)
-  ;; delete frame associated with workspace, if it exists
   (add-hook 'delete-frame-functions #'+workspaces|delete-associated-workspace)
 
   ;; per-project workspaces, but reuse current workspace if empty
@@ -163,8 +156,8 @@ Uses `+workspaces-main' to determine the name of the main workspace."
 
   (add-hook 'projectile-after-switch-project-hook #'+workspaces|switch-to-project)
 
-  ;; In some scenarios, persp-mode throws error an error when Emacs tries to
-  ;; die, preventing its death.
+  ;; In some scenarios, persp-mode throws error when Emacs tries to die,
+  ;; preventing its death and trapping us in Emacs.
   (defun +workspaces*ignore-errors-on-kill-emacs (orig-fn)
     (ignore-errors (funcall orig-fn)))
   (advice-add #'persp-kill-emacs-h :around #'+workspaces*ignore-errors-on-kill-emacs)