nit: revise and reformat code comments

bin/doom

@@ -160,7 +160,7 @@
                                             (shell-quote-argument (match-string 2 env)))))
                   (format "PATH=\"%s%s$PATH\" \\\n" (concat doom-emacs-dir "bin/") path-separator)
                   "_postscript $@\n"))
-        (set-file-modes script #o600)t
+        (set-file-modes script #o600)
         ;; Error code 128 is special: it means run the post-script after this
         ;; session ends.
         128))))))

core/core-editor.el

@@ -456,6 +456,9 @@ files, so this replace calls to `pp' with the much faster `prin1'."
   ;; Creates a jump point before killing a buffer. This allows you to undo
   ;; killing a buffer easily (only works with file buffers though; it's not
   ;; possible to resurrect special buffers).
+  ;;
+  ;; I'm not advising `kill-buffer' because I only want this to affect
+  ;; interactively killed buffers.
   (advice-add #'kill-current-buffer :around #'doom-set-jump-a)
 
   ;; Create a jump point before jumping with imenu.

modules/completion/vertico/config.el

@@ -34,7 +34,7 @@ overrides `completion-styles' during company completion sessions.")
   :config
   (defun +vertico-orderless-dispatch (pattern _index _total)
     (cond
-     ;; Ensure that $ works with Consult commands, which add disambiguation suffixes
+     ;; Ensure $ works with Consult commands, which add disambiguation suffixes
      ((string-suffix-p "$" pattern)
       `(orderless-regexp . ,(concat (substring pattern 0 -1) "[\x100000-\x10FFFD]*$")))
      ;; Ignore single !
@@ -52,11 +52,12 @@ overrides `completion-styles' during company completion sessions.")
      ((string-suffix-p "~" pattern) `(orderless-flex . ,(substring pattern 0 -1)))))
   (setq completion-styles '(orderless)
         completion-category-defaults nil
-        ;; note that despite override in the name orderless can still be used in find-file etc.
+        ;; note that despite override in the name orderless can still be used in
+        ;; find-file etc.
         completion-category-overrides '((file (styles . (orderless partial-completion))))
         orderless-style-dispatchers '(+vertico-orderless-dispatch)
         orderless-component-separator "[ &]")
-  ;; otherwise find-file gets different highlighting than other commands
+  ;; ...otherwise find-file gets different highlighting than other commands
   (set-face-attribute 'completions-first-difference nil :inherit nil))
 
 

modules/lang/plantuml/config.el

@@ -21,8 +21,8 @@
 
 
 (after! ob-plantuml
-  ;; HACK We force ob-plantuml to use `plantuml-mode''s building mechanism,
-  ;; which is more sophisticated.
+  ;; HACK Force ob-plantuml to use `plantuml-mode''s building mechanism, which
+  ;;      is more sophisticated.
   (advice-add #'org-babel-execute:plantuml
               :override #'+plantuml-org-babel-execute:plantuml-a)
   (add-to-list 'org-babel-default-header-args:plantuml

modules/ui/workspaces/config.el

@@ -59,8 +59,11 @@ stored in `persp-save-dir'.")
         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-a)
 
+  ;;;; Create main workspace
+  ;; The default perspective persp-mode creates is special and doesn't represent
+  ;; a real persp object, so buffers can't really be assigned to it, among other
+  ;; quirks, so I replace it with a "main" perspective.
   (add-hook! '(persp-mode-hook persp-after-load-state-functions)
     (defun +workspaces-ensure-no-nil-workspaces-h (&rest _)
       (when persp-mode
@@ -76,9 +79,7 @@ stored in `persp-save-dir'.")
       "Ensure a main workspace exists."
       (when persp-mode
         (let (persp-before-switch-functions)
-          ;; The default perspective persp-mode creates is special and doesn't
-          ;; represent a real persp object, so buffers can't really be assigned
-          ;; to it, among other quirks, so we get rid of it...
+          ;; Try our best to hide the nil perspective.
           (when (equal (car persp-names-cache) persp-nil-name)
             (pop persp-names-cache))
           ;; ...and create a *real* main workspace to fill this role.
@@ -216,6 +217,9 @@ stored in `persp-save-dir'.")
       (setcar helm-source-projectile-projects-actions
               '("Switch to Project" . +workspaces-switch-to-project-h))))
 
+  ;; Don't bother auto-saving the session if no real buffers are open.
+  (advice-add #'persp-asave-on-exit :around #'+workspaces-autosave-real-buffers-a)
+
   ;; Fix #1973: visual selection surviving workspace changes
   (add-hook 'persp-before-deactivate-functions #'deactivate-mark)
 
@@ -225,7 +229,7 @@ stored in `persp-save-dir'.")
       (defun +workspaces-delete-all-posframes-h (&rest _)
         (posframe-delete-all))))
 
-
+  ;; Don't try to persist dead/remote buffers. They cause errors.
   (add-hook! 'persp-filter-save-buffers-functions
     (defun +workspaces-dead-buffer-p (buf)
       ;; Fix #1525: Ignore dead buffers in PERSP's buffer list
@@ -239,16 +243,15 @@ stored in `persp-save-dir'.")
   ;; excluded from the buffer list.
   (add-hook 'bookmark-after-jump-hook #'+workspaces-add-current-buffer-h)
 
-  ;;
-  ;; eshell
+  ;;; eshell
   (persp-def-buffer-save/load
    :mode 'eshell-mode :tag-symbol 'def-eshell-buffer
    :save-vars '(major-mode default-directory))
   ;; compile
   (persp-def-buffer-save/load
    :mode 'compilation-mode :tag-symbol 'def-compilation-buffer
-   :save-vars
-   '(major-mode default-directory compilation-directory compilation-environment compilation-arguments))
+   :save-vars '(major-mode default-directory compilation-directory
+                compilation-environment compilation-arguments))
   ;; Restore indirect buffers
   (defvar +workspaces--indirect-buffers-to-restore nil)
   (persp-def-buffer-save/load