More Elisp linting

In order for this to scale, I need to solve two things:
1. Ad-hoc ignore fill-column rules for URLs and other exceptions.
2. Run Elisp flychecker without evaluating my Elisp code and firing its
   side-effects.

19 files changed, 62 insertions, 67 deletions

diff --git a/emacs/.emacs.d/wpc/alist.el b/emacs/.emacs.d/wpc/alist.el
index f9d2be71fb8e..52493c6c03a7 100644
--- a/emacs/.emacs.d/wpc/alist.el
+++ b/emacs/.emacs.d/wpc/alist.el
@@ -199,8 +199,10 @@ Mutative variant of `alist-delete'."
 
 ;; TODO: Should I support `alist-find-key' and `alist-find-value' variants?
 (defun alist-find (p xs)
-  "Apply a predicate fn, P, to each key and value in XS and return the key of
-  the first element that returns t."
+  "Find an element in XS.
+
+Apply a predicate fn, P, to each key and value in XS and return the key of the
+first element that returns t."
   (let ((result (list-find (lambda (x) (funcall p (car x) (cdr x))) xs)))
     (if result
         (car result)
diff --git a/emacs/.emacs.d/wpc/buffer.el b/emacs/.emacs.d/wpc/buffer.el
index de0c2ad66bcd..8494bfa8fb74 100644
--- a/emacs/.emacs.d/wpc/buffer.el
+++ b/emacs/.emacs.d/wpc/buffer.el
@@ -18,7 +18,7 @@
 ;; buffers":
 ;; 1. Toggling previous: <SPC><SPC>
 ;; 2. Using `ivy-read': <SPC>b
-;; TODO: These obscure evil KBDs. Maybe a hydra definition would be best?
+;; TODO: These obscure evil KBDs.  Maybe a hydra definition would be best?
 ;; 3. Cycling (forwards/backwards): C-f, C-b
 
 ;;; Code:
@@ -117,7 +117,7 @@ Return a reference to that buffer."
 ;; encapsulates all of this behavior.
 
 (defun buffer-cycle (cycle-fn)
-  "Cycle forwards or backwards through `buffer-source-code-buffers'."
+  "Using CYCLE-FN, move through `buffer-source-code-buffers'."
   (let ((last-called (source-code-cycle-last-called
                       buffer-source-code-cycle-state))
         (cycle (source-code-cycle-cycle
diff --git a/emacs/.emacs.d/wpc/constants.el b/emacs/.emacs.d/wpc/constants.el
index f57e10b63911..ae21a089cc05 100644
--- a/emacs/.emacs.d/wpc/constants.el
+++ b/emacs/.emacs.d/wpc/constants.el
@@ -1,4 +1,4 @@
-;;; constants.el --- Constants for organizing my Emacs -*- lexical-binding: t -*-
+;;; constants.el --- Constants for organizing my Elisp -*- lexical-binding: t -*-
 
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
@@ -26,7 +26,7 @@
 
 (defconst constants-ci?
   (maybe-some? (getenv "CI"))
-  "True when Emacs is running in CI.")
+  "Encoded as t when Emacs is running in CI.")
 
 (defconst constants-briefcase
   (getenv "BRIEFCASE")
diff --git a/emacs/.emacs.d/wpc/cycle.el b/emacs/.emacs.d/wpc/cycle.el
index cdf502fbdbb2..6b1181b4edd3 100644
--- a/emacs/.emacs.d/wpc/cycle.el
+++ b/emacs/.emacs.d/wpc/cycle.el
@@ -1,9 +1,9 @@
-;;; cycle.el --- Simple module for working with cycles. -*- lexical-binding: t -*-
+;;; cycle.el --- Simple module for working with cycles -*- lexical-binding: t -*-
 
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "24.3"))
 
 ;;; Commentary:
 ;; Something like this may already exist, but I'm having trouble finding it, and
@@ -56,7 +56,7 @@
   "Return the list representation of a cycle, XS."
   (cycle-xs xs))
 
-(defun next-index<- (lo hi x)
+(defun cycle--next-index<- (lo hi x)
   "Return the next index in a cycle when moving downwards.
 - `LO' is the lower bound.
 - `HI' is the upper bound.
@@ -65,7 +65,7 @@
       (- hi 1)
     (- x 1)))
 
-(defun next-index-> (lo hi x)
+(defun cycle--next-index-> (lo hi x)
   "Return the next index in a cycle when moving upwards.
 - `LO' is the lower bound.
 - `HI' is the upper bound.
@@ -97,7 +97,7 @@ underlying struct."
 (defun cycle-next (xs)
   "Return the next value in `XS' and update `current-index'."
   (let* ((current-index (cycle-current-index xs))
-         (next-index (next-index-> 0 (cycle-count xs) current-index)))
+         (next-index (cycle--next-index-> 0 (cycle-count xs) current-index)))
     (struct-set! cycle previous-index current-index xs)
     (struct-set! cycle current-index next-index xs)
     (nth next-index (cycle-xs xs))))
@@ -105,7 +105,7 @@ underlying struct."
 (defun cycle-prev (xs)
   "Return the previous value in `XS' and update `current-index'."
   (let* ((current-index (cycle-current-index xs))
-         (next-index (next-index<- 0 (cycle-count xs) current-index)))
+         (next-index (cycle--next-index<- 0 (cycle-count xs) current-index)))
     (struct-set! cycle previous-index current-index xs)
     (struct-set! cycle current-index next-index xs)
     (nth next-index (cycle-xs xs))))
@@ -136,7 +136,7 @@ underlying struct."
       (error "No element in cycle matches predicate"))))
 
 (defun cycle-focus-item (x xs)
-  "Focus ITEM in cycle XS.
+  "Focus item, X, in cycle XS.
 ITEM is the first item in XS that t for `equal'."
   (cycle-focus (lambda (y) (equal x y)) xs))
 
diff --git a/emacs/.emacs.d/wpc/device.el b/emacs/.emacs.d/wpc/device.el
index 0d551fae266a..5d2f2606d7b3 100644
--- a/emacs/.emacs.d/wpc/device.el
+++ b/emacs/.emacs.d/wpc/device.el
@@ -3,13 +3,17 @@
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "25.1"))
 
 ;;; Commentary:
 ;; Functions for querying device information.
 
 ;;; Code:
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Dependencies
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
 (require 'dash)
 (require 'alist)
 
diff --git a/emacs/.emacs.d/wpc/functions.el b/emacs/.emacs.d/wpc/functions.el
index 6eabec49f2e0..c0b873aaff14 100644
--- a/emacs/.emacs.d/wpc/functions.el
+++ b/emacs/.emacs.d/wpc/functions.el
@@ -13,17 +13,19 @@
 
 ;;; Code:
 (defun functions-evil-window-vsplit-right ()
+  "Split the window vertically and focus the right half."
   (interactive)
   (evil-window-vsplit)
   (windmove-right))
 
 (defun functions-evil-window-split-down ()
+  "Split the window horizontal and focus the bottom half."
   (interactive)
   (evil-window-split)
   (windmove-down))
 
 (defun functions-create-snippet ()
-  "Creates a window split and then opens the Yasnippet editor."
+  "Create a window split and then opens the Yasnippet editor."
   (interactive)
   (evil-window-vsplit)
   (call-interactively #'yas-new-snippet))
diff --git a/emacs/.emacs.d/wpc/irc.el b/emacs/.emacs.d/wpc/irc.el
index 7247e818c5e0..46a0fa73af60 100644
--- a/emacs/.emacs.d/wpc/irc.el
+++ b/emacs/.emacs.d/wpc/irc.el
@@ -3,7 +3,7 @@
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "25.1"))
 
 ;;; Commentary:
 ;; Need to decide which client I will use for IRC.
@@ -60,14 +60,14 @@
                              irc-server->channels)))))
 
 (defun irc-channel->server (server->channels channel)
-  "Resolve an IRC server from a given CHANNEL."
+  "Using SERVER->CHANNELS, resolve an IRC server from a given CHANNEL."
   (let ((result (alist-find (lambda (k v) (cycle-contains? channel v))
                             server->channels)))
     (prelude-assert (maybe-some? result))
     result))
 
 (defun irc-channel->cycle (server->channels channel)
-  "Resolve an IRC's channels cycle from a given CHANNEL."
+  "Using SERVER->CHANNELS, resolve an IRC's channels cycle from CHANNEL."
   (alist-get (irc-channel->server server->channels channel)
              server->channels))
 
@@ -98,7 +98,7 @@
 ;; TODO: Support function or KBD for switching to an ERC buffer.
 
 (defun irc-kill-all-erc-processes ()
-  "Kills all ERC buffers and processes."
+  "Kill all ERC buffers and processes."
   (interactive)
   (->> (erc-buffer-list)
        (-map #'kill-buffer)))
diff --git a/emacs/.emacs.d/wpc/ivy-clipmenu.el b/emacs/.emacs.d/wpc/ivy-clipmenu.el
index 17679514e4d1..9f5b7ca8a0f1 100644
--- a/emacs/.emacs.d/wpc/ivy-clipmenu.el
+++ b/emacs/.emacs.d/wpc/ivy-clipmenu.el
@@ -83,7 +83,7 @@ This value defaults to 25.")
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (defun ivy-clipmenu-parse-content (x)
-  "Parse the label from the entry in clipmenu's line-cache."
+  "Parse the label from the entry, X, in clipmenu's line-cache."
   (->> (s-split " " x)
        (-drop 1)
        (s-join " ")))
diff --git a/emacs/.emacs.d/wpc/ivy-helpers.el b/emacs/.emacs.d/wpc/ivy-helpers.el
index 068598082975..8b53c62fd643 100644
--- a/emacs/.emacs.d/wpc/ivy-helpers.el
+++ b/emacs/.emacs.d/wpc/ivy-helpers.el
@@ -40,8 +40,7 @@ with the key and value from KV."
        (message "%s process finished." process)))))
 
 (defun ivy-helpers-list-external-commands ()
-  "Creates a list of all external commands available on $PATH while filtering
-NixOS wrappers."
+  "Create a list of all external commands available on $PATH."
   (cl-loop
    for dir in (split-string (getenv "PATH") path-separator)
    when (and (file-exists-p dir) (file-accessible-directory-p dir))
@@ -56,8 +55,7 @@ NixOS wrappers."
    finally return (sort completions 'string-lessp)))
 
 (defun ivy-helpers-run-external-command ()
-  "Prompts the user with a list of all installed applications and
-lets them select one to launch."
+  "Prompts the user with a list of all installed applications to launch."
   (interactive)
   (let ((external-commands-list (ivy-helpers-list-external-commands)))
     (ivy-read "Command:" external-commands-list
diff --git a/emacs/.emacs.d/wpc/kbd.el b/emacs/.emacs.d/wpc/kbd.el
index 08e16df90150..d3a4224e432d 100644
--- a/emacs/.emacs.d/wpc/kbd.el
+++ b/emacs/.emacs.d/wpc/kbd.el
@@ -3,7 +3,7 @@
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "25.1"))
 
 ;;; Commentary:
 ;; In order to stay organized, I'm attempting to dedicate KBD prefixes to
diff --git a/emacs/.emacs.d/wpc/keybindings.el b/emacs/.emacs.d/wpc/keybindings.el
index 89e39348f56d..07067a9cdf12 100644
--- a/emacs/.emacs.d/wpc/keybindings.el
+++ b/emacs/.emacs.d/wpc/keybindings.el
@@ -8,7 +8,7 @@
 ;;; Commentary:
 ;; Attempting to centralize my keybindings to simplify my configuration.
 ;;
-;; I have some expectations about my keybindings. Here are some of those
+;; I have some expectations about my keybindings.  Here are some of those
 ;; defined:
 ;; - In insert mode:
 ;;   - C-a: beginning-of-line
@@ -123,8 +123,8 @@
   `(exwm-input-set-key (kbd ,c) ,fn))
 
 (keybindings-exwm "C-M-v" #'ivy-clipmenu-copy)
-(keybindings-exwm "<XF86MonBrightnessUp>" #'screen-brightness/increase)
-(keybindings-exwm "<XF86MonBrightnessDown>" #'screen-brightness/decrease)
+(keybindings-exwm "<XF86MonBrightnessUp>" #'screen-brightness-increase)
+(keybindings-exwm "<XF86MonBrightnessDown>" #'screen-brightness-decrease)
 (keybindings-exwm "<XF86AudioMute>" #'pulse-audio/toggle-mute)
 (keybindings-exwm "<XF86AudioLowerVolume>" #'pulse-audio/decrease-volume)
 (keybindings-exwm "<XF86AudioRaiseVolume>" #'pulse-audio/increase-volume)
diff --git a/emacs/.emacs.d/wpc/keyboard.el b/emacs/.emacs.d/wpc/keyboard.el
index f8d37280c880..ebef794bd5f2 100644
--- a/emacs/.emacs.d/wpc/keyboard.el
+++ b/emacs/.emacs.d/wpc/keyboard.el
@@ -71,10 +71,10 @@
   (interactive)
   ;; TODO: Ensure these work once the tokenizing in prelude-start-process works
   ;; as expected.
-  (start-process "keyboard-swap-caps-lock-and-escape" nil "/usr/bin/xmodmap" "-e"
-                 "remove Lock = Caps_Lock")
-  (start-process "keyboard-swap-caps-lock-and-escape" nil "/usr/bin/xmodmap" "-e"
-                 "keysym Caps_Lock = Escape"))
+  (start-process "keyboard-swap-caps-lock-and-escape"
+                 nil "/usr/bin/xmodmap" "-e" "remove Lock = Caps_Lock")
+  (start-process "keyboard-swap-caps-lock-and-escape"
+                 nil "/usr/bin/xmodmap" "-e" "keysym Caps_Lock = Escape"))
 
 (defun keyboard-inc-repeat-rate ()
   "Increment `keyboard-repeat-rate'."
diff --git a/emacs/.emacs.d/wpc/laptop-battery.el b/emacs/.emacs.d/wpc/laptop-battery.el
index 26ded42c7b0a..7347b5ab5b30 100644
--- a/emacs/.emacs.d/wpc/laptop-battery.el
+++ b/emacs/.emacs.d/wpc/laptop-battery.el
@@ -3,7 +3,7 @@
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "25.1"))
 
 ;;; Commentary:
 ;; Some wrappers to obtain battery information.
diff --git a/emacs/.emacs.d/wpc/modeline.el b/emacs/.emacs.d/wpc/modeline.el
index cca336c733aa..6852bb284bc5 100644
--- a/emacs/.emacs.d/wpc/modeline.el
+++ b/emacs/.emacs.d/wpc/modeline.el
@@ -8,18 +8,21 @@
 ;;; Commentary:
 ;; Because I use EXWM, I treat my Emacs mode-line like my system bar: I need to
 ;; quickly check the system time, and I expect it to be at the bottom-right of
-;; my Emacs frame. I used doom-modeline for awhile, which is an impressive
+;; my Emacs frame.  I used doom-modeline for awhile, which is an impressive
 ;; package, but it conditionally colorizes on the modeline for the active
-;; buffer. So if my bottom-right window is inactive, I cannot see the time.
+;; buffer.  So if my bottom-right window is inactive, I cannot see the time.
 ;;
 ;; My friend, @tazjin, has a modeline setup that I think is more compatible with
 ;; EXWM, so I'm going to base my setup off of his.
 
+;;; Code:
+
 (use-package telephone-line)
 
 (defun modeline-bottom-right-window? ()
-  "Determines whether the last (i.e. bottom-right) window of the
-  active frame is showing the buffer in which this function is
+  "Determines whether the last (i.e.
+bottom-right) window of the
+active frame is showing the buffer in which this function is
   executed."
   (let* ((frame (selected-frame))
          (right-windows (window-at-side-list frame 'right))
@@ -28,9 +31,7 @@
     (eq (current-buffer) (window-buffer last-window))))
 
 (defun modeline-maybe-render-time ()
-  "Renders the mode-line-misc-info string for display in the
-  mode-line if the currently active window is the last one in the
-  frame.
+  "Conditionally renders the `mode-line-misc-info' string.
 
   The idea is to not display information like the current time,
   load, battery levels on all buffers."
@@ -47,7 +48,8 @@
       (format "[%s]" exwm-workspace-current-index)))
   ;; Define a highlight font for ~ important ~ information in the last
   ;; window.
-  (defface special-highlight '((t (:foreground "white" :background "#5f627f"))) "")
+  (defface special-highlight
+    '((t (:foreground "white" :background "#5f627f"))) "")
   (add-to-list 'telephone-line-faces
                '(highlight . (special-highlight . special-highlight)))
   (setq telephone-line-lhs
@@ -61,7 +63,6 @@
         telephone-line-primary-right-separator 'telephone-line-tan-right
         telephone-line-secondary-left-separator 'telephone-line-tan-hollow-left
         telephone-line-secondary-right-separator 'telephone-line-tan-hollow-right)
-
   (telephone-line-mode 1))
 
 (provide 'modeline)
diff --git a/emacs/.emacs.d/wpc/number.el b/emacs/.emacs.d/wpc/number.el
index 9d576797f1c9..c8ed665b3098 100644
--- a/emacs/.emacs.d/wpc/number.el
+++ b/emacs/.emacs.d/wpc/number.el
@@ -108,21 +108,6 @@ While this function is undeniably trivial, I have unintentionally done (- 1 x)
   "Add one to `X'."
   (+ x 1))
 
-;; TODO: Does this belong in a math module?  Is math too vague?  Or is number
-;; too vague?
-;; TODO: Resolve the circular dependency that this introduces with series.el,
-;; and then re-enable this function and its tests below.
-;; (defun number-factorial (x)
-;;   "Return factorial of `X'."
-;;   (cond
-;;    ((number-negative? x) (error "Will not take factorial of negative numbers"))
-;;    ((= 0 x) 1)
-;;    ;; NOTE: Using `series/range' introduces a circular dependency because:
-;;    ;; series -> number -> series.  Conceptually, however, this should be
-;;    ;; perfectly acceptable.
-;;    (t (->> (series/range 1 x)
-;;            (list-reduce 1 #'*)))))
-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Tests
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
diff --git a/emacs/.emacs.d/wpc/scope.el b/emacs/.emacs.d/wpc/scope.el
index a64abe40dc45..c97a59b88bd6 100644
--- a/emacs/.emacs.d/wpc/scope.el
+++ b/emacs/.emacs.d/wpc/scope.el
@@ -3,7 +3,7 @@
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
 ;; URL: https://git.wpcarro.dev/wpcarro/briefcase
-;; Package-Requires: ((emacs "24"))
+;; Package-Requires: ((emacs "25.1"))
 
 ;;; Commentary:
 ;; Exposing an API for working with a scope data structure in a non-mutative
diff --git a/emacs/.emacs.d/wpc/screen-brightness.el b/emacs/.emacs.d/wpc/screen-brightness.el
index be2a68e62c9f..30973607bb03 100644
--- a/emacs/.emacs.d/wpc/screen-brightness.el
+++ b/emacs/.emacs.d/wpc/screen-brightness.el
@@ -1,6 +1,9 @@
 ;;; screen-brightness.el --- Control laptop screen brightness -*- lexical-binding: t -*-
 
 ;; Author: William Carroll <wpcarro@gmail.com>
+;; Version: 0.0.1
+;; URL: https://git.wpcarro.dev/wpcarro/briefcase
+;; Package-Requires: ((emacs "24"))
 
 ;;; Commentary:
 ;; Mainly just Elisp wrappers around `xbacklight`.
@@ -19,27 +22,27 @@
 ;; Constants
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-(defconst screen-brightness/step-size 15
+(defconst screen-brightness-step-size 15
   "The size of the increment or decrement step for the screen's brightness.")
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Library
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-(defun screen-brightness/increase ()
+(defun screen-brightness-increase ()
   "Increase the screen brightness."
   (interactive)
   (prelude-start-process
-   :name "screen-brightness/increase"
-   :command (string-format "xbacklight -inc %s" screen-brightness/step-size))
+   :name "screen-brightness-increase"
+   :command (string-format "xbacklight -inc %s" screen-brightness-step-size))
   (message "[screen-brightness.el] Increased screen brightness."))
 
-(defun screen-brightness/decrease ()
+(defun screen-brightness-decrease ()
   "Decrease the screen brightness."
   (interactive)
   (prelude-start-process
-   :name "screen-brightness/decrease"
-   :command (string-format "xbacklight -dec %s" screen-brightness/step-size))
+   :name "screen-brightness-decrease"
+   :command (string-format "xbacklight -dec %s" screen-brightness-step-size))
   (message "[screen-brightness.el] Decreased screen brightness."))
 
 (provide 'screen-brightness)
diff --git a/emacs/.emacs.d/wpc/string.el b/emacs/.emacs.d/wpc/string.el
index 9d18029690f5..9a43f1664501 100644
--- a/emacs/.emacs.d/wpc/string.el
+++ b/emacs/.emacs.d/wpc/string.el
@@ -1,4 +1,4 @@
-;; string.el --- Library for working with strings -*- lexical-binding: t -*-
+;;; string.el --- Library for working with strings -*- lexical-binding: t -*-
 
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1
diff --git a/emacs/.emacs.d/wpc/symbol.el b/emacs/.emacs.d/wpc/symbol.el
index fac182090a73..39450caff59e 100644
--- a/emacs/.emacs.d/wpc/symbol.el
+++ b/emacs/.emacs.d/wpc/symbol.el
@@ -1,4 +1,4 @@
-;; symbol.el --- Library for working with symbols. -*- lexical-binding: t -*-
+;;; symbol.el --- Library for working with symbols -*- lexical-binding: t -*-
 
 ;; Author: William Carroll <wpcarro@gmail.com>
 ;; Version: 0.0.1