General comment and autoload tag update + clean up

core/core-editor.el

@@ -9,10 +9,12 @@
  ;; Formatting
  delete-trailing-lines nil
  fill-column 80
+ ;; Spaces, not tabs
  indent-tabs-mode nil
  require-final-newline t
  tab-always-indent t
  tab-width 4
+ ;; Wrapping
  truncate-lines t
  truncate-partial-width-windows 50
  visual-fill-column-center-text nil

core/core-ui.el

@@ -52,7 +52,7 @@
   (tool-bar-mode   -1)  ; no toolbar
   ;; full filename in frame title
   (setq frame-title-format '(buffer-file-name "%f" ("%b")))
-  ;; set font
+  ;; Set theme and font
   (with-demoted-errors "FONT ERROR: %s"
     (set-frame-font doom-default-font t)
     ;; Fallback to `doom-unicode-font' for Unicode characters

core/core-workgroups.el

@@ -79,5 +79,10 @@ these workgroups won't be auto-renamed.")
     (workgroups-mode +1)
     (wg-create-workgroup wg-first-wg-name)))
 
+(unless window-system
+  (defalias 'wg-workgroup-associated-buffers 'ignore)
+  (defalias 'wg-current-workgroup 'ignore)
+  (defalias 'wg-save-session 'ignore))
+
 (provide 'core-workgroups)
 ;;; core-workgroups.el ends here

core/defuns/defuns-buffers.el

@@ -3,8 +3,8 @@
 ;;;###autoload (autoload 'doom:narrow "defuns-buffers" nil t)
 (evil-define-operator doom:narrow (&optional beg end bang)
   "Restrict editing in this buffer to the current region, indirectly. With BANG,
-clone the buffer and hard-narrow the selection. Otherwise use fancy-narrow. If
-mark isn't active, then widen the buffer (if narrowed).
+clone the buffer and hard-narrow the selection. If mark isn't active, then widen
+the buffer (if narrowed).
 
 Inspired from http://demonastery.org/2013/04/emacs-evil-narrow-region/"
   (interactive "<r><!>")
@@ -19,14 +19,14 @@ Inspired from http://demonastery.org/2013/04/emacs-evil-narrow-region/"
 
 ;;;###autoload
 (defun doom/set-read-only-region (begin end)
-  "See http://stackoverflow.com/questions/7410125"
+  "Mark a region as read-only (http://stackoverflow.com/questions/7410125)"
   (let ((modified (buffer-modified-p)))
     (add-text-properties begin end '(read-only t))
     (set-buffer-modified-p modified)))
 
 ;;;###autoload
 (defun doom/set-region-writeable (begin end)
-  "See http://stackoverflow.com/questions/7410125"
+  "Undoes `doom/set-read-only-region' (http://stackoverflow.com/questions/7410125)"
   (let ((modified (buffer-modified-p))
         (inhibit-read-only t))
     (remove-text-properties begin end '(read-only t))
@@ -35,17 +35,12 @@ Inspired from http://demonastery.org/2013/04/emacs-evil-narrow-region/"
 
 ;; Buffer Life and Death ;;;;;;;;;;;;;;;
 
-(unless window-system
-  (defalias 'wg-workgroup-associated-buffers 'ignore)
-  (defalias 'wg-current-workgroup 'ignore)
-  (defalias 'wg-save-session 'ignore))
-
 ;;;###autoload
 (defun doom/get-buffers (&optional all-p)
-  "Get all buffers in the current workgroup.
+  "Get all buffers in the current project, in the current workgroup.
 
-    If PROJECT-P is non-nil, get all buffers in current workgroup
-    If both are non-nil, get all project buffers across all workgroups"
+    If ALL-P is non-nil, get all buffers across all projects in current
+workgroup."
   (let ((buffers (if (wg-current-workgroup t)
                      (doom/get-buffers-in-workgroup)
                    (buffer-list)))
@@ -59,48 +54,64 @@ Inspired from http://demonastery.org/2013/04/emacs-evil-narrow-region/"
 
 ;;;###autoload
 (defun doom/get-buffers-in-workgroup ()
-  (let ((assoc-bufs (wg-workgroup-associated-buffers nil)))
-    (--filter (memq it assoc-bufs) (buffer-list))))
+  "Get a list of buffers in current workgroup. Returns nil if workgroups2 isn't
+loaded."
+  (when (featurep 'workgroups2)
+    (let ((assoc-bufs (wg-workgroup-associated-buffers nil)))
+      (--filter (memq it assoc-bufs) (buffer-list)))))
 
 ;;;###autoload
 (defun doom/get-buffer-names (&optional buffer-list)
+  "Get a list of names of buffers in the current workgroup, OR return the names
+of the buffers in BUFFER-LIST."
   (mapcar #'buffer-name (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/get-visible-windows (&optional window-list)
-  "Get a list of the visible windows in the current frame (that aren't popups)."
+  "Get a list of the visible windows in the current frame (that aren't popups),
+OR return only the visible windows in WINDOW-LIST."
   (-remove #'doom/popup-p (or window-list (window-list))))
 
 ;;;###autoload
 (defun doom/get-visible-buffers (&optional buffer-list)
-  "Get a list of unburied buffers in the current project and workgroup."
+  "Get a list of unburied buffers in the current project and workgroup, OR
+return only the unburied buffers in BUFFER-LIST (a list of BUFFER-OR-NAMEs)."
   (-filter #'get-buffer-window (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/get-buried-buffers (&optional buffer-list)
-  "Get a list of buried buffers in the current project and workgroup."
+  "Get a list of buried buffers in the current project and workgroup, OR return
+only the buried buffers in BUFFER-LIST (a list of BUFFER-OR-NAMEs)."
   (-remove 'get-buffer-window (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/get-matching-buffers (pattern &optional buffer-list)
-  "Get a list of buffers that match the pattern"
+  "Get a list of all buffers (in the current workgroup OR in BUFFER-LIST) that
+match the regex PATTERN."
   (--filter (string-match-p pattern (buffer-name it))
             (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/get-buffers-in-modes (modes &optional buffer-list)
-  "Get a list of buffers whose major-mode is one of MODES"
+  "Get a list of all buffers (in the current workgroup OR in BUFFER-LIST) whose
+`major-mode' is one of MODES."
   (--filter (memq (buffer-local-value 'major-mode it) modes)
             (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/get-real-buffers (&optional buffer-list)
+  "Get a list of all buffers (in the current workgroup OR in BUFFER-LIST) that
+`doom/real-buffer-p' returns non-nil for."
   (-filter #'doom/real-buffer-p (or buffer-list (doom/get-buffers))))
 
 ;;;###autoload
 (defun doom/kill-real-buffer (&optional arg)
-  "Kill buffer (but only bury scratch buffer), then switch to a real buffer. Only buries
-the buffer if it is being displayed in another window."
+  "Kill buffer then switch to a real buffer. Only buries the buffer if it is
+being displayed in another window.
+
+NOTE: only buries scratch buffer.
+
+See `doom/real-buffer-p' for what 'real' means."
   (interactive (list t))
   (cond ((eq (current-buffer) doom-buffer)
          (doom-mode-init t))
@@ -124,7 +135,8 @@ the buffer if it is being displayed in another window."
 
 ;;;###autoload
 (defun doom/kill-unreal-buffers ()
-  "Kill all buried, unreal buffers in current frame. See `doom-unreal-buffers'"
+  "Kill all buried buffers in current frame that match any of the rules in
+`doom-unreal-buffers'."
   (interactive)
   (let ((kill-list (-remove 'doom/real-buffer-p
                             (doom/get-buried-buffers (buffer-list)))))
@@ -134,7 +146,7 @@ the buffer if it is being displayed in another window."
 
 ;;;###autoload
 (defun doom/kill-process-buffers ()
-  "Kill all buffers that represent running processes and aren't visible."
+  "Kill all buried buffers that represent running processes."
   (interactive)
   (let ((buffer-list (buffer-list))
         (killed-processes 0))
@@ -152,11 +164,13 @@ the buffer if it is being displayed in another window."
     (message "Cleaned up %s processes" killed-processes)))
 
 ;;;###autoload
-(defun doom/kill-matching-buffers (regexp &optional buffer-list)
+(defun doom/kill-matching-buffers (pattern &optional buffer-list)
+  "Kill all buffers (in current workgroup OR in BUFFER-LIST) that match the
+regex PATTERN."
   (interactive)
   (let ((i 0))
     (mapc (lambda (b)
-            (when (string-match-p regexp (buffer-name b))
+            (when (string-match-p pattern (buffer-name b))
               (kill-buffer b)
               (setq i (1+ i))))
           (if buffer-list buffer-list (doom/get-buffers)))
@@ -164,8 +178,8 @@ the buffer if it is being displayed in another window."
 
 ;;;###autoload
 (defun doom/cycle-real-buffers (&optional n)
-  "Switch to the previous buffer and avoid special buffers. If there's nothing
-left, create a scratch buffer."
+  "Switch to the previous buffer, skipping over special buffers. If there's
+nothing left, create a scratch buffer."
   (let* ((start-buffer (current-buffer))
          (move-func (if (> n 0) 'switch-to-next-buffer 'switch-to-prev-buffer))
          (max 25)
@@ -194,8 +208,9 @@ left, create a scratch buffer."
 
 ;;;###autoload
 (defun doom/real-buffer-p (&optional buffer)
-  "Returns whether BUFFER a 'real' buffer or not. Real means it isn't a popup,
-temporary, scratch or special buffer."
+  "Returns whether BUFFER a 'real' buffer or not. Real means: a) it isn't a
+popup (or temporary) window and b) it isn't a special buffer (e.g. scratch or
+*messages* buffer)."
   (setq buffer (or (and (bufferp buffer) buffer)
                    (and (stringp buffer) (get-buffer buffer))
                    (current-buffer)))
@@ -206,16 +221,17 @@ temporary, scratch or special buffer."
                    (--any? (string-match-p it (buffer-name buffer))
                            (-filter 'stringp doom-unreal-buffers))))))))
 
-;; Inspired by spacemacs <https://github.com/syl20bnr/spacemacs/blob/master/spacemacs/funcs.el>
 ;;;###autoload
 (defun doom/next-real-buffer ()
-  "Switch to the next buffer and avoid special buffers."
+  "Switch to the next real buffer, skipping special buffers. See
+`doom/real-buffer-p'."
   (interactive)
   (doom/cycle-real-buffers +1))
 
 ;;;###autoload
 (defun doom/previous-real-buffer ()
-  "Switch to the previous buffer and avoid special buffers."
+  "Switch to the previous real buffer, skipping special buffers. See
+`doom/real-buffer-p'."
   (interactive)
   (doom/cycle-real-buffers -1))
 
@@ -247,22 +263,23 @@ temporary, scratch or special buffer."
 
 ;;;###autoload (autoload 'doom:kill-buried-buffers "defuns-buffers" nil t)
 (evil-define-command doom:kill-buried-buffers (&optional bang)
-  "Kill buried project buffers (in workgroup) and report how many it found. BANG = get all
-buffers regardless of project."
+  "Kill buried project buffers in current workgroup and report how many it
+found. If BANG, then include buffers that aren't part of the current project."
   (interactive "<!>")
   (doom--kill-buffers (doom/get-buried-buffers (doom/get-buffers (not bang)))))
 
 ;;;###autoload (autoload 'doom:kill-buried-buffers "defuns-buffers" nil t)
 (evil-define-command doom:kill-matching-buffers (&optional bang pattern)
-  "Kill project buffers matching regex pattern PATTERN. If BANG, then extend search to
-buffers regardless of project."
+  "Kill project buffers in current workgroup that match regex PATTERN. If BANG,
+then include buffers that aren't part of the current project."
   :repeat nil
   (interactive "<!><a>")
   (doom-kill-buffers (doom/get-matching-buffers pattern (doom/get-buffers (not bang)))))
 
 ;;;###autoload (autoload 'doom:scratch-buffer "defuns-buffers" nil t)
 (evil-define-operator doom:scratch-buffer (&optional beg end bang)
-  "Send a selection to the scratch buffer. If BANG, don't use a popup."
+  "Send a region to and pop up the scratch buffer. If BANG, don't use a popup
+(use the current window)."
   :move-point nil
   :type inclusive
   (interactive "<r><!>")
@@ -282,14 +299,14 @@ buffers regardless of project."
 
 ;;;###autoload (autoload 'doom:cd "defuns-buffers" nil t)
 (evil-define-command doom:cd (dir)
-  "Ex-command alias for `cd'"
+  "Change the `default-directory' to DIR (alias for `cd')"
   :repeat nil
   (interactive "<f>")
   (cd (if (zerop (length dir)) "~" dir)))
 
 ;;;###autoload
-(defun doom/kill-all-buffers-do-not-remember ()
-  "Kill all buffers so that workgroups2 will wipe its current session."
+(defun doom/kill-workgroup-and-quit ()
+  "Wipe the current workgroup session and save the blank slate."
   (interactive)
   (let (confirm-kill-emacs)
     (mapc 'kill-buffer (doom/get-buffers t))

core/defuns/defuns-company.el

@@ -2,12 +2,14 @@
 
 ;;;###autoload
 (defun doom/company-evil-complete-next (&optional arg)
+  "dabbrev wrapper for `evil-complete-next'"
   (call-interactively 'company-dabbrev)
   (if (eq company-candidates-length 1)
       (company-complete)))
 
 ;;;###autoload
 (defun doom/company-evil-complete-previous (&optional arg)
+  "dabbrev wrapper for `evil-complete-previous'"
   (let ((company-selection-wrap-around t))
     (call-interactively 'company-dabbrev)
     (if (eq company-candidates-length 1)
@@ -37,6 +39,8 @@
 
 ;;;###autoload
 (defun doom/company-whole-lines (command &optional arg &rest ignored)
+  "`company-mode' completion backend that completes whole-lines, akin to vim's
+C-x C-l."
   (interactive (list 'interactive))
   (let ((lines (doom--company-whole-lines)))
     (cl-case command
@@ -52,7 +56,7 @@
 
 ;;;###autoload
 (defun doom/company-complete ()
-  "Bring up the completion popup. If there is only one result, auto-complete it."
+  "Bring up the completion popup. If only one result, complete it."
   (interactive)
   (require 'company)
   (when (and (bound-and-true-p company-mode)

core/defuns/defuns-editor.el

@@ -46,6 +46,7 @@
 
 ;;;###autoload
 (defun doom/reselect-paste ()
+  "Go back into visual mode and reselect the last pasted region."
   (interactive)
   (evil-goto-mark ?\[)
   (evil-visual-state)

core/defuns/defuns-embrace.el

@@ -12,7 +12,7 @@
 
 ;;;###autoload
 (defun doom/embrace-escaped ()
-  "Escaped surround characters."
+  "Backslash-escaped surround character support for embrace."
   (let ((char (read-char "\\")))
     (if (eq char 27)
         (cons "" "")
@@ -23,11 +23,12 @@
 
 ;;;###autoload
 (defun doom/embrace-latex ()
-  "LaTeX commands"
+  "LaTeX command support for embrace."
   (cons (format "\\%s{" (read-string "\\")) "}"))
 
 ;;;###autoload
 (defun doom/embrace-elisp-fn ()
+  "Elisp function support for embrace."
   (cons (format "(%s " (or (read-string "(") "")) ")"))
 
 (provide 'defuns-embrace)

core/defuns/defuns-evil.el

@@ -1,16 +1,16 @@
 ;;; defuns-evil.el
 
-;;;###autoload (autoload 'doom:evil-open-folds "defuns-evil" nil t)
+;;;###autoload (autoload 'doom/evil-open-folds "defuns-evil" nil t)
 (evil-define-command doom/evil-open-folds (count)
-  "Instead of `evil-open-folds'. Accepts COUNT for dictating fold level."
+  "Instead of `evil-open-folds'; accepts COUNT for dictating fold level."
   (interactive "P")
   (unless (bound-and-true-p hs-minor-mode)
     (hs-minor-mode 1))
   (if count (hs-hide-level count) (evil-open-folds)))
 
-;;;###autoload (autoload 'doom:evil-open-folds "defuns-evil" nil t)
+;;;###autoload (autoload 'doom/evil-open-folds "defuns-evil" nil t)
 (evil-define-command doom/evil-close-folds (count)
-  "Instead of `evil-close-folds'. Accepts COUNT for dictating fold level."
+  "Instead of `evil-close-folds'; accepts COUNT for dictating fold level."
   (interactive "P")
   (unless (bound-and-true-p hs-minor-mode)
     (hs-minor-mode 1))
@@ -18,14 +18,14 @@
 
 ;;;###autoload (autoload 'doom/multi-next-line "defuns-evil" nil t)
 (evil-define-motion doom/multi-next-line (count)
-  "Move down 6 lines"
+  "Move down 6 lines."
   :type line
   (let ((line-move-visual visual-line-mode))
     (evil-line-move (* 6 (or count 1)))))
 
 ;;;###autoload (autoload 'doom/multi-previous-line "defuns-evil" nil t)
 (evil-define-motion doom/multi-previous-line (count)
-  "Move up 6 lines"
+  "Move up 6 lines."
   :type line
   (let ((line-move-visual visual-line-mode))
     (evil-line-move (- (* 6 (or count 1))))))

core/defuns/defuns-file.el

@@ -2,7 +2,7 @@
 
 ;;;###autoload (autoload 'doom:file-delete "defuns-file" nil t)
 (evil-define-command doom:file-delete (&optional bang filename)
-  "Delete current buffer's file. If bang, then kill the buffer afterwards as well."
+  "Delete current buffer's file. If BANG, kill buffer afterwards."
   :repeat nil
   (interactive "<!><f>")
   (let ((filename (file-truename (or filename (buffer-file-name)))))
@@ -41,7 +41,7 @@ provided."
 ;;;###autoload (autoload 'doom:file-move "defuns-file" nil t)
 (evil-define-command doom:file-move (path)
   "Move current buffer's file to PATH. Replaces %, # and other variables (see
-  `evil-ex-replace-special-filenames')"
+`evil-ex-replace-special-filenames')"
   :repeat nil
   (interactive "<f>")
   (let* ((old-path (buffer-file-name))