Update/improve documentation for core defuns

core/autoload/packages.el

@@ -70,23 +70,31 @@ the packages relevant to that backend."
 
 ;;;###autoload
 (defun doom-get-outdated-packages ()
-  "Return a list of packages that are out of date. Each element is a sublist,
+  "Return a list of lists representing packages that are out of date. Each
-containing (list package-symbol current-version-string new-version-string). Can
+element is a sublist, containing (PACKAGE-SYMBOL OLD-VERSION-LIST
-be fed to `doom/packages-update'."
+NEW-VERSION-LIST).
-  (-non-nil (--map (doom-package-outdated-p (car it)) (doom-get-packages))))
+
+Used by `doom/packages-update'."
+  (-non-nil (--map (doom-package-outdated-p (car it))
+                   (doom-get-packages))))
 
 ;;;###autoload
 (defun doom-get-orphaned-packages ()
-  "Return a list of packages that are no longer needed or depended on. Can be
+  "Return a list of symbols representing packages that are no longer needed or
-fed to `doom/packages-delete'."
+depended on.
+
+Used by `doom/packages-autoremove'."
   (doom-read-packages t)
   (let ((package-selected-packages (append (mapcar 'car doom-packages) doom-protected-packages)))
     (package--removable-packages)))
 
 ;;;###autoload
 (defun doom-get-packages-to-install ()
-  "Return a list of packages that aren't installed, but need to be. Used by
+  "Return a list of packages that aren't installed, but need to be. Each element
-`doom/packages-install'."
+is a list whose CAR is the package symbol, and whose CDR is a plist taken from
+that package's `@package' declaration.
+
+Used by `doom/packages-install'."
   (--remove (assq (car it) package-alist) (doom-get-packages)))
 
 (defun doom--scrape-sexps (sym file)

core/core-packages.el

@@ -14,14 +14,15 @@
 ;; 3. Stability: I don't want to worry that each time I use my package
 ;;    manager something might inexplicably go wrong. This was the case with
 ;;    Cask, which I used previously. package.el and quelpa appear to be much
-;;    more stable.
+;;    faster and more stable.
 ;; 4. No external dependencies (e.g. Cask) for plugin management.
 ;;
-;; Note: it should be safe to use *most* package.el functions directly, but for
+;; Note: it should be safe to use *most* package.el functions directly, though I
-;; complete certainty I recommend the DOOM variants: `doom/install-package',
+;; wouldn't recommend you use `package-autoremove'. For complete certainty, I've provided safer DOOM vaiants:
-;; `doom/delete-package' and `doom/update-packages'. As well as:
+;; `doom/install-package', `doom/delete-package' and `doom/update-packages'.
-;; `doom/packages-install', `doom/packages-update', and
+;;
-;; `doom/packages-autoremove'.
+;; As well as: `doom/packages-install', `doom/packages-update', and
+;; `doom/packages-autoremove', which are called from the Makefile.
 ;;
 ;; See core/autoload/packages.el for more functions.
 
@@ -122,11 +123,11 @@ avoided to speed up startup."
     (unless (file-exists-p doom-cache-dir)
       (make-directory doom-cache-dir t))
 
+    ;; Ensure core packages are installed
     (unless (and (file-exists-p doom-packages-dir)
                  (require 'use-package nil t)
                  (require 'quelpa nil t))
       (package-refresh-contents)
-      ;; Ensure core packages are installed
       (condition-case ex
           (mapc (lambda (pkg)
                   (package-install pkg)

core/core-popups.el

@@ -1,15 +1,13 @@
 ;;; core-popups.el --- taming sudden yet inevitable windows
 
 ;; I'd like certain buffers--like help windows, prompts or
-;; informational/terminal/temporary buffers--to have less presence among my work
+;; informational/terminal/temporary buffers--to have less presence over my work
-;; buffers (typically, source code buffers). I'd also like them to be easy to
+;; buffers (e.g. source code buffers). I'd also like them to be easy to both
-;; both dispose of quickly and invoke from anywhere. It will also hide the
+;; dispose of quickly and invoke from anywhere. Also, hide the mode-line in
-;; mode-line in popups using `doom-hide-modeline-mode'
+;; popups with `doom-hide-modeline-mode'
 ;;
-;; I use `shackle' to make this as consistent as possible, which lets you
+;; I use `shackle' to make this as consistent as possible, which allows you
-;; specify rules on how to treat certain buffers. I go through great lengths to
+;; to specify rules on how to treat certain buffers.
-;; tame helm, flycheck, help buffers--*even* the beast that is org-mode, with
-;; the help of `display-buffer-alist' and `shackle'.
 ;;
 ;; Be warned, there is a lot of hackery voodoo here that could break with an
 ;; emacs update, or an update to any of the packages it tries to tame (like helm

core/core.el

@@ -2,14 +2,15 @@
 
 ;;; Naming conventions:
 ;;
-;;   doom-...   A public variable or function (non-interactive use)
+;;   doom-...   public variables or functions (non-interactive)
-;;   doom--...  A private variable, function (non-interactive use) or macro
+;;   doom--...  private anything (non-interactive), not safe for direct use
-;;   doom/...   An interactive function
+;;   doom/...   an interactive function
-;;   doom:...   An evil operator, motion or command
+;;   doom:...   an evil operator, motion or command
-;;   doom|...   A hook
+;;   doom|...   hook function
-;;   doom*...   An advising function
+;;   doom*...   advising functions
-;;   ...!       Macro, shortcut alias or defsubst
+;;   doom!...   interaction commands exclusively for installing external dependencies
-;;   @...       A generator macro for keybinds
+;;   @...       a macro, public shortcut alias or a generator macro for keybinds
+;;   %...       functions used for in-snippet logic
 ;;   +...       Any of the above, but part of a module, e.g. +emacs-lisp|init-hook
 ;;
 ;; Autoloaded functions are in core/autoload/*.el and modules/*/*/autoload.el or