cleanup, add docstrings

Author: vroide

cider-util.el

@@ -516,29 +516,39 @@ Any other value is just returned."
     x))
 
 
-;;; Files
+;;; Files & Directories
 (defun cider--ensure-executable (file)
+  "Try to make FILE executable if it isn't already.
+Returns FILE on success, nil on failure."
   (with-demoted-errors "Error while trying to make file executable:\n %s"
     (when (or (file-executable-p file)
               (and (set-file-modes file "u+x")
                    (file-executable-p file)))
       file)))
 
-(defconst cider--temp-name-prefix ".cider__")
+(defconst cider--temp-name-prefix ".cider__"
+  "Prefix for marking temporary files created by cider.")
 
 (defun cider--make-temp-name (file)
+  "Generate a randomized name from FILEs basename.
+Tag it with `cider--temp-name-prefix'"
   (make-temp-name
    (concat cider--temp-name-prefix (file-name-nondirectory file) "__")))
 
 (defun cider--make-nearby-temp-copy (file)
+  "Create a copy of FILE in the default local or remote tempdir.
+Falls back to `clojure-project-dir' or `default-directory'.
+The copy is marked with `cider--temp-name-prefix'."
   (let* ((default-directory (or (clojure-project-dir) default-directory))
-         ;; Note: (temporary-file-directory) uses `default-directory' as fallback.
          (new-file (file-name-concat (temporary-file-directory)
                                      (cider--make-temp-name file))))
     (copy-file file new-file :exists-ok nil nil :keep-permissions)
     new-file))
 
-(defun cider--inject-self-delete (bash-script)
+(defun cider--inject-self-delete (bash-file)
+  "Make BASH-FILE delete itself on exit.
+Injects the self-delete script after the first line, assuming it is a
+shebang."
   (let (;; Don't create any temporary files.
         (remote-file-name-inhibit-locks t)
         (remote-file-name-inhibit-auto-save-visited t)
@@ -547,7 +557,7 @@ Any other value is just returned."
         ;; Disable version-control check
         (vc-handled-backends nil))
     (with-temp-buffer
-      (insert-file-contents bash-script)
+      (insert-file-contents bash-file)
       ;; inject after the first line, assuming it is the shebang
       (goto-char (point-min))
       (skip-chars-forward "^\n")
@@ -558,9 +568,9 @@ Any other value is just returned."
                  echo \"cider: Cleaned up temporary script after use.\"
                  exit $ARG
                ' EXIT"
-               (file-local-name bash-script)))
-      (write-file bash-script))
-    bash-script))
+               (file-local-name bash-file)))
+      (write-file bash-file))
+    bash-file))
 
 
 ;;; Help mode

cider.el

@@ -434,8 +434,8 @@ Returns the local path to the script or nil."
   "Get or create an executable enrich-classpath script for PROJECT-TYPE.
 If `default-directory' is remote, create a copy at
 '<remote-tempdir>/.cider__<script-name>__<random>' that deletes itself after
-use.  The search for <remote-tempdir> is handled by tramp and falls back to
-`default-directory'.  Returns nil if anything goes wrong."
+use.  The search for '<remote-tempdir>' is handled by tramp and falls back to
+`clojure-project-dir' or `default-directory'.  Returns nil if anything goes wrong."
   (when-let* ((cider-dir (file-name-directory (locate-library "cider.el" t)))
               (name (map-elt cider--enrich-classpath-script-names project-type))
               (location (concat cider-dir name))
@@ -2143,8 +2143,9 @@ M-2 \\[cider-jack-in-universal]."
 
 
 (defun cider--resolve-command (command)
-  "Find COMMAND in exec-path and shell-quote it.
-Return nil if not found."
+  "Test if COMMAND exists, is executable and shell-quote it.
+Return nil otherwise.  When `default-directory' is remote, the check is
+performed by tramp."
   (when-let* ((command (or (executable-find command :remote)
                            (executable-find (concat command ".bat")))))
     (shell-quote-argument command)))