General cleanup/doc comment update

core/core-defuns.el

@@ -339,7 +339,7 @@ while emacs was open!"
       (list -load-path -custom-theme-load-path))))
 
 (defun doom-reload-autoloads ()
-  "Regenerate autoloads for DOOM emacs."
+  "Regenerate and reload autoloads.el."
   (interactive)
   (let ((generated-autoload-file (concat doom-core-dir "/autoloads.el")))
     (when (file-exists-p generated-autoload-file)
@@ -354,7 +354,9 @@ while emacs was open!"
     (message "Done!")))
 
 (defun doom-byte-compile (&optional minimal)
-  "Byte compile the core and library .el files in ~/.emacs.d"
+  "Byte compile the core and library .el files in ~/.emacs.d. If MINIMAL is nil,
+only byte compile a few important files. If t, compile all files too. If 'basic,
+only compile defun libraries."
   (interactive)
   (mapc (lambda (f) (byte-compile-file (concat doom-emacs-dir "/" f) t))
         '("init.el" "core/core.el" "core/core-defuns.el" "core/core-ui.el"

core/core-os-osx.el

@@ -16,7 +16,8 @@
       ;; Don't open files from the workspace in a new frame
       ns-pop-up-frames nil)
 
-;; fix emacs PATH on OSX (GUI only)
+;; On OSX, in GUI Emacs, `exec-path' isn't populated properly (it should match
+;; $PATH in my shell). `exe-path-from-shell' fixes this.
 (when window-system
   (setenv "SHELL" "/usr/local/bin/zsh")
   ;; `exec-path-from-shell' is slow, so bring out the cache
@@ -69,7 +70,7 @@
 
 
 ;;
-;; OS-integration
+;; OS-specific functions
 ;;
 
 (defun doom-open-with (&optional app-name path)
@@ -109,7 +110,11 @@
   (doom:send-to-tmux (format "cd %s" (shell-quote-argument default-directory)))
   (doom-switch-to-iterm))
 
-;; Open with external programs
+
+;;
+;; Plugins
+;;
+
 (use-package openwith
   :config
   (openwith-mode t)

core/core-popup.el

@@ -2,9 +2,9 @@
 
 ;; I use a slew of hackery to get Emacs to treat 'pop-ups' consistently. It goes
 ;; through great lengths to tame helm, flycheck, help buffers--*even* the beast
-;; that is org-mode.
+;; that is org-mode, with the help of `display-buffer-alist' and shackle.
 ;;
-;; Be warned, an update could break any of this.
+;; Be warned, an update could break this.
 
 (use-package shackle
   :config
@@ -34,13 +34,13 @@
           ("*vc-change-log*"   :align below :size 15  :select t)
           (vc-annotate-mode    :same t)))
 
-  ;; Emacs 25.1+ already shows the completion window at the bottom of the
+  ;; Emacs 25.1+ properly shows the completion window at the bottom of the
   ;; current frame.
-  (unless (and (>= emacs-major-version 25) (= emacs-minor-version 1))
+  (unless (version< emacs-version "25.1")
     (push '("*Completions*"     :align below :size 30  :noselect t) shackle-rules))
 
-  ;; :noesc    = Can't be closed with a single ESC
+  ;; :noesc  = Can't be closed with a single ESC
-  ;; :nokill   = Won't be killed when closed (only buried)
+  ;; :nokill = Won't be killed when closed (only buried)
   (defvar doom-popup-rules
     '(("^\\*doom\\(:scratch\\)?\\*$" :noesc :nokill)
       ("^\\*doom.*\\*$"       :noesc :nokill)
@@ -52,9 +52,9 @@
       (esup-mode              :noesc)
       (tabulated-list-mode    :noesc)))
 
-  ;; There is no shackle-popup hook, so I hacked one in
+  ;; There is no shackle-popup hook, so I hack one in
   (advice-add 'shackle-display-buffer :around 'doom*popup-init)
-  ;; Don't mess with popups
+  ;; Tell these functions not to mess with popups
   (advice-add 'balance-windows        :around 'doom*save-popup)
   (advice-add 'doom/evil-window-move  :around 'doom*save-popup))
 

core/core-project.el

@@ -91,7 +91,8 @@
 
   ;; Don't cache ignored files!
   (defun doom*projectile-cache-current-file (orig-fun &rest args)
-    (unless (--any (f-descendant-of? buffer-file-name it) (projectile-ignored-directories))
+    (unless (--any (f-descendant-of? buffer-file-name it)
+                   (projectile-ignored-directories))
       (apply orig-fun args)))
   (advice-add 'projectile-cache-current-file :around 'doom*projectile-cache-current-file)
 

core/core-ui.el

@@ -79,7 +79,7 @@
 (with-current-buffer "*Messages*" (doom-hide-mode-line-mode +1))
 
 ;; Eldoc is enabled globally on Emacs 25. No thank you, I'll do it myself.
-(when (and (> emacs-major-version 24) (featurep 'eldoc))
+(when (bound-and-true-p global-eldoc-mode)
   (global-eldoc-mode -1))
 
 ;; TODO/FIXME/NOTE highlighting in comments

core/defuns/defuns-popups.el

@@ -101,6 +101,8 @@ the display (unless DONT-REDRAW is non-nil)."
   (let ((orig-win (selected-window)))
     (mapc (lambda (w) (doom/popup-close w dont-kill t))
           (--filter (and (doom/popup-p it) (not (eq it orig-win))) (window-list))))
+  ;; Earlier versions of Emacs were more prone to graphical artifacts, so redraw
+  ;; the frame in them.
   (when (< emacs-major-version 25)
     (unless dont-redraw (redraw-frame))))
 
@@ -122,7 +124,7 @@ the display (unless DONT-REDRAW is non-nil)."
 
 ;;;###autoload
 (defun doom*popup-init (orig-fn &rest args)
-  "Enable `doom-popup-mode' in every popup window and returns the window."
+  "Enables `doom-popup-mode' in every popup window and returns the window."
   (let ((window (apply orig-fn args)))
     (with-selected-window window
       (doom-popup-mode +1))
@@ -139,7 +141,8 @@ the display (unless DONT-REDRAW is non-nil)."
 
 ;;;###autoload
 (define-minor-mode doom-popup-mode
-  "Pop ups"
+  "Minor mode for pop-up windows. Enables local keymaps and sets state
+variables."
   :global nil
   :init-value nil
   :keymap doom-popup-mode-map