docs(upload): revise & clarify

Flesh out usage section and flesh out comments in config.el.

modules/tools/upload/config.el

@@ -1,17 +1,5 @@
 ;;; tools/upload/config.el -*- lexical-binding: t; -*-
 
-;; Uses `ssh-deploy' to map a local folder to a remote one. Set
-;; `ssh-deploy-root-remote' and `ssh-deploy-root-local' in a .dir-locals.el file
-;; to establish this mapping.
-;;
-;; Example:
-;;   ((nil . ((ssh-deploy-root-local . "/local/path/to/project")
-;;            (ssh-deploy-root-remote . "/ssh:user@server:/remote/project/")
-;;            (ssh-deploy-on-explicit-save . 1))))
-;;
-;; Note: `ssh-deploy-root-local' is optional, and will resort to
-;; `doom-project-root' if unspecified.
-
 (use-package! ssh-deploy
   :commands (ssh-deploy-upload-handler
              ssh-deploy-upload-handler-forced
@@ -19,11 +7,12 @@
              ssh-deploy-browse-remote-handler
              ssh-deploy-remote-changes-handler)
   :init
-  (setq ssh-deploy-revision-folder (concat doom-cache-dir "ssh-revisions/")
+  (setq ssh-deploy-revision-folder (file-name-concat doom-cache-dir "ssh-revisions/")
         ssh-deploy-on-explicit-save 1
         ssh-deploy-automatically-detect-remote-changes nil)
 
-  ;; Make these safe as file-local variables
+  ;; Forward-declare these as safe file/dir-local variables in case files set
+  ;; them before ssh-deploy is loaded.
   (dolist (sym '((ssh-deploy-root-local . stringp)
                  (ssh-deploy-root-remote . stringp)
                  (ssh-deploy-script . functionp)
@@ -33,7 +22,8 @@
                  (ssh-deploy-exclude-list . listp)))
     (put (car sym) 'safe-local-variable (cdr sym)))
 
-  ;; Maybe auto-upload on save
+  ;; Respect `ssh-deploy-on-explicit-save' if `ssh-deploy-root-remote' has
+  ;; changed since the buffer was opened.
   (add-hook! 'after-save-hook
     (defun +upload-init-after-save-h ()
       (when (and (bound-and-true-p ssh-deploy-root-remote)