adding documentation

1 files changed, 38 insertions, 36 deletions

diff --git a/modules/dirvish-config.el b/modules/dirvish-config.el
index 96448d68..7f45b6e8 100644
--- a/modules/dirvish-config.el
+++ b/modules/dirvish-config.el
@@ -1,5 +1,5 @@
 ;;; dirvish-config.el --- Configuration for the Dired and Dirvish File Managers -*- lexical-binding: t; -*-
-;; author Craig Jennings <c@cjennings.net>
+;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
 
@@ -16,8 +16,8 @@
   :bind
   (:map dired-mode-map
         ([remap dired-summary] . which-key-show-major-mode)
-        ("E" . wdired-change-to-wdired-mode)           ;; edit names/properties in buffer
-        ("e" . cj/dired-ediff-files))                       ;; ediff files
+        ("E" . wdired-change-to-wdired-mode)           ;; edit names and properties in buffer
+        ("e" . cj/dired-ediff-files))                  ;; ediff files
   :custom
   (dired-use-ls-dired nil)                             ;; non GNU FreeBSD doesn't support a "--dired" switch
   :config
@@ -25,7 +25,7 @@
   (setq dired-dwim-target t)
   (setq dired-clean-up-buffers-too t)                  ;; offer to kill buffers associated deleted files and dirs
   (setq dired-clean-confirm-killing-deleted-buffers t) ;; don't ask; just kill buffers associated with deleted files
-  ;; (setq dired-kill-when-opening-new-dired-buffer t)    ;; stop littering buffers while navigating a directory tree
+  (setq dired-kill-when-opening-new-dired-buffer t)    ;; don't litter by leaving buffers when navigating directories
   (setq dired-recursive-copies (quote always))         ;; “always” means no asking
   (setq dired-recursive-deletes (quote top)))          ;; “top” means ask once
 
@@ -34,7 +34,7 @@
 ;; ------------------------------ Dired Open With ------------------------------
 
 (defun cj/dired-open-with (command)
-  "Open the dired file at point with a user-specified COMMAND.
+  "Open the Dired file at point with a user-specified COMMAND.
 This function is meant to be called interactively. It prompts for the command to
 open the file with if called without a parameter. The command runs
 asynchronously and its output is saved in a buffer, but the buffer is not
@@ -48,7 +48,7 @@ automatically displayed."
 ;; copies the full path of the file at point to the clipboard
 
 (defun cj/dired-copy-path-as-kill ()
-  "Copy the full path of file at point in dired to the clipboard."
+  "Copy the full path of file at point in Dired to the clipboard."
   (interactive)
   (let ((filename (dired-get-file-for-visit)))
     (if (and filename (file-exists-p filename))
@@ -58,9 +58,11 @@ automatically displayed."
       (message "No file at point."))))
 
 ;; ------------------------ Dired Convert Image To Jpeg ------------------------
-;; converts the image at point to a jpeg
+;; converts the image at point to a jpeg by typing "C" within dirvish
 
 (defun cj/dired-convert-image-to-jpeg ()
+  "Convert an image to JPEG via ImageMagick on the file at point.
+Alert if the file is already a JPEG; notify the user when converstion is done."
   (interactive)
   (let* ((original-file (dired-get-file-for-visit))
          (file-extension (file-name-extension original-file))
@@ -75,7 +77,7 @@ automatically displayed."
                        "'png' 'bmp' 'gif' 'tif' 'tiff' 'svg' 'webp'")))))
 
 ;; ------------------------ Dired Mark All Visible Files -----------------------
-;; convenience function to mark all visible files in dired
+;; convenience function to mark all visible files by typing "M" in dirvish
 
 (defun cj/dired-mark-all-visible-files ()
   "Mark all visible files for deletion in Dired mode."
@@ -102,28 +104,28 @@ automatically displayed."
   :custom
   (dirvish-quick-access-entries
    `(("h"  "~/"                                   "home")
-	 ("cx" ,code-dir                              "code directory")
-	 ("dl" ,dl-dir                                "downloads")
-	 ("dr" ,(concat sync-dir "/drill/")           "drill files")
-	 ("dt" ,(concat dl-dir "/torrents/complete/") "torrents")
-	 ("dx" "~/documents/"                         "documents")
-	 ("mb" "/media/backup/"                       "backup directory")
-	 ("mx" "~/music/"                             "music")
-	 ("pd" "~/projects/documents/"                "project documents")
-	 ("pl" "~/projects/elibrary/"                 "project elibrary")
-	 ("pf" "~/projects/finances/"                 "project finances")
-	 ("pj" "~/projects/jr-estate/"                "project jr-estate")
-	 ("ps" ,(concat pix-dir "/screenshots/")      "pictures screenshots")
-	 ("pw" ,(concat pix-dir "/wallpaper/")        "pictures wallpaper")
-	 ("px" ,pix-dir                               "pictures directory")
-	 ("rcj" "/sshx:cjennings@cjennings.net:~"     "remote cjennings.net")
-	 ("sx" ,sync-dir                              "sync directory")
-	 ("sv" "~/sync/videos/"                       "sync/videos directory")
-	 ("tg" ,(concat sync-dir "/text.games")       "text games")
-	 ("vr" ,video-recordings-dir                  "video recordings directory")
-	 ("vx" ,videos-dir                            "videos")
-	 ("rsb" "/sshx:cjennings@wolf.usbx.me:/home/cjennings/" "remote seedbox")
-	 )) ;; end dirvish-quick-access-entries
+     ("cx" ,code-dir                              "code directory")
+     ("dl" ,dl-dir                                "downloads")
+     ("dr" ,(concat sync-dir "/drill/")           "drill files")
+     ("dt" ,(concat dl-dir "/torrents/complete/") "torrents")
+     ("dx" "~/documents/"                         "documents")
+     ("mb" "/media/backup/"                       "backup directory")
+     ("mx" "~/music/"                             "music")
+     ("pd" "~/projects/documents/"                "project documents")
+     ("pl" "~/projects/elibrary/"                 "project elibrary")
+     ("pf" "~/projects/finances/"                 "project finances")
+     ("pj" "~/projects/jr-estate/"                "project jr-estate")
+     ("ps" ,(concat pix-dir "/screenshots/")      "pictures screenshots")
+     ("pw" ,(concat pix-dir "/wallpaper/")        "pictures wallpaper")
+     ("px" ,pix-dir                               "pictures directory")
+     ("rcj" "/sshx:cjennings@cjennings.net:~"     "remote cjennings.net")
+     ("sx" ,sync-dir                              "sync directory")
+     ("sv" "~/sync/videos/"                       "sync/videos directory")
+     ("tg" ,(concat sync-dir "/text.games")       "text games")
+     ("vr" ,video-recordings-dir                  "video recordings directory")
+     ("vx" ,videos-dir                            "videos")
+     ("rsb" "/sshx:cjennings@wolf.usbx.me:/home/cjennings/" "remote seedbox")
+     )) ;; end dirvish-quick-access-entries
   ;; (dirvish-attributes '(file-size))
   (dirvish-attributes '(nerd-icons file-size))
   (dirvish-preview-dispatchers '(image gif video audio epub pdf archive))
@@ -141,8 +143,8 @@ automatically displayed."
    ("g"       . dirvish-quick-access)
    ("G"       . revert-buffer)
    ("bg"      . (lambda () (interactive)  ; set background image
-				  (shell-command (concat "nitrogen --save --set-zoom-fill "
-										 (dired-file-name-at-point) " >>/dev/null 2>&1" ))))
+                  (shell-command (concat "nitrogen --save --set-zoom-fill "
+                                         (dired-file-name-at-point) " >>/dev/null 2>&1" ))))
    ("Z"       . (lambda () (interactive) (cj/dired-open-with "zathura")))
    ("L"       . (lambda () (interactive) (cj/dired-open-with "libreoffice")))
    ("o"       . (lambda () (interactive) (cj/dired-open-with "xdg-open")))
@@ -180,7 +182,7 @@ automatically displayed."
 (use-package dired-rsync
   :after dired
   :bind (:map dired-mode-map
-			  ("r" . dired-rsync)))
+              ("r" . dired-rsync)))
 
 ;; ---------------------------- Dired Hide Dotfiles ----------------------------
 
@@ -212,7 +214,7 @@ automatically displayed."
   (setq dired-sidebar-pop-to-sidebar-on-toggle-open 'nil))         ; don't jump to sidebar when it's toggled on
 
 ;; ----------------------------- Dired Ediff Files -----------------------------
-;; mark two files within dired, then ediff them within Emacs
+;; mark two files within dirvish, then ediff them by typing "e" (see above keybinding)
 
 (defun cj/dired-ediff-files ()
   "Ediff two selected files within Dired."
@@ -232,8 +234,8 @@ automatically displayed."
           (add-hook 'ediff-after-quit-hook-internal
                     (lambda ()
                       (setq ediff-after-quit-hook-internal nil)
-					  (set-window-configuration wnd))))
-	  (error "No more than 2 files should be marked"))))
+                      (set-window-configuration wnd))))
+      (error "No more than 2 files should be marked"))))
 
 (provide 'dirvish-config)
 ;;; dirvish-config.el ends here