From fd93e705b4ca6dcde6f29e1e865ee50d1482d150 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Tue, 21 Feb 2017 03:45:24 -0500
Subject: [PATCH] General cleanup, refactor and documentation

---
 core/autoload/system.el                           | 11 +++++++----
 core/core-popups.el                               |  3 +--
 modules/completion/ivy/config.el                  | 10 ++++++++++
 modules/feature/workspaces/autoload/workspaces.el |  3 +++
 4 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/core/autoload/system.el b/core/autoload/system.el
index 462c04691..f46ef3324 100644
--- a/core/autoload/system.el
+++ b/core/autoload/system.el
@@ -19,15 +19,18 @@
 
 ;;;###autoload
 (defun doom-sh (&rest args)
-  "Runs a shell command and prints any output to the DOOM buffer.")
+  "Runs a shell command and prints any output to the DOOM buffer."
+  (error "doom-sh not implemented yet"))
 
 ;;;###autoload
-(defun doom-async-sh (&rest args))
+(defun doom-async-sh (&rest args)
+  "Like `doom-sh', but runs command asynchronously."
+  (error "doom-async-sh not implemented yet"))
 
 ;;;###autoload
 (defun doom-sudo (&rest args)
-  "Runs a shell command as admin, prompting for a password. Prints any output to
-the DOOM buffer.")
+  "Like `doom-sh', but runs as root (prompts for password)."
+  (error "doom-sudo not implemented yet"))
 
 ;;;###autoload
 (defun doom-fetch (fetcher location dest)
diff --git a/core/core-popups.el b/core/core-popups.el
index b3102d594..c4b395f44 100644
--- a/core/core-popups.el
+++ b/core/core-popups.el
@@ -68,7 +68,6 @@
           ("*Shell Command Output*" :size 20  :noselect t :autokill t)
           ("*Occur*"                :size 25  :noselect t :autokill t)
           (compilation-mode         :size 15  :noselect t :noesc t :autokill t)
-          (ivy-occur-grep-mode      :size 25  :noesc t)
           (eww-mode                 :size 30)
           (comint-mode              :noesc t)
           (tabulated-list-mode      :noesc t)))
@@ -83,7 +82,7 @@
 
 (defun doom*shackle-always-align (plist)
   "Ensure popups are always aligned and selected by default. Eliminates the need
-for the obvious :align t on every rule."
+for :align t on every rule."
   (when plist
     (unless (plist-member plist :align)
       (plist-put plist :align t))
diff --git a/modules/completion/ivy/config.el b/modules/completion/ivy/config.el
index 524c28a8e..d3173ba83 100644
--- a/modules/completion/ivy/config.el
+++ b/modules/completion/ivy/config.el
@@ -1,5 +1,14 @@
 ;;; completion/ivy/packages.el
 
+;; Ivy is my completion backend of choice. With counsel's help, I get:
+;;
+;; + Project-wide search with `counsel-ag' (or `+ivy:ag-search')
+;; + Project-wide replace if you press <backtab> in the ag occur buffer.
+;; + An Atom/Sublime-Text Command-T implementation with `counsel-find-file' and
+;;   `counsel-projectile-find-file'.
+;; + Ido-like completion for a slew of functions, like `counsel-M-x' and
+;;   `counsel-imenu'.
+
 ;; TODO Make this a setting
 (defmacro @def-counsel-action (name &rest forms)
   `(defun ,(intern (format "+ivy/counsel-%s" (symbol-name name))) ()
@@ -68,6 +77,7 @@
 
   (require 'counsel-projectile)
 
+  ;; FIXME Messy workaround, refactor this
   (@def-counsel-action ag-open-in-other-window
     (lambda (x)
       (when (string-match "\\`\\(.*?\\):\\([0-9]+\\):\\(.*\\)\\'" x)
diff --git a/modules/feature/workspaces/autoload/workspaces.el b/modules/feature/workspaces/autoload/workspaces.el
index 44218b436..05f3a893a 100644
--- a/modules/feature/workspaces/autoload/workspaces.el
+++ b/modules/feature/workspaces/autoload/workspaces.el
@@ -363,14 +363,17 @@ the workspace and move to the next."
 
 ;;;###autoload
 (defun +workspace-message (message &optional type)
+  "Show an 'elegant' message in the echo area next to a listing of workspaces."
   (message "%s" (+workspace--message-body message type)))
 
 ;;;###autoload
 (defun +workspace-error (message &optional noerror)
+  "Show an 'elegant' error in the echo area next to a listing of workspaces."
   (funcall (if noerror 'message 'error) "%s" (+workspace--message-body message 'error)))
 
 ;;;###autoload
 (defun +workspace/display ()
+  "Display a list of workspaces (like tabs) in the echo area."
   (interactive)
   (message "%s" (+workspace--tabline)))