diff --git a/core/autoload/packages.el b/core/autoload/packages.el index d33b64160..252994b9a 100644 --- a/core/autoload/packages.el +++ b/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, -containing (list package-symbol current-version-string new-version-string). Can -be fed to `doom/packages-update'." - (-non-nil (--map (doom-package-outdated-p (car it)) (doom-get-packages)))) + "Return a list of lists representing packages that are out of date. Each +element is a sublist, containing (PACKAGE-SYMBOL OLD-VERSION-LIST +NEW-VERSION-LIST). + +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 -fed to `doom/packages-delete'." + "Return a list of symbols representing packages that are no longer needed or +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 -`doom/packages-install'." + "Return a list of packages that aren't installed, but need to be. Each element +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) diff --git a/core/core-packages.el b/core/core-packages.el index fab97425b..9128b548f 100644 --- a/core/core-packages.el +++ b/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 -;; complete certainty I recommend the DOOM variants: `doom/install-package', -;; `doom/delete-package' and `doom/update-packages'. As well as: -;; `doom/packages-install', `doom/packages-update', and -;; `doom/packages-autoremove'. +;; Note: it should be safe to use *most* package.el functions directly, though I +;; wouldn't recommend you use `package-autoremove'. For complete certainty, I've provided safer DOOM vaiants: +;; `doom/install-package', `doom/delete-package' and `doom/update-packages'. +;; +;; 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) diff --git a/core/core-popups.el b/core/core-popups.el index e8c87d04d..dab998ea7 100644 --- a/core/core-popups.el +++ b/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 -;; buffers (typically, source code buffers). I'd also like them to be easy to -;; both dispose of quickly and invoke from anywhere. It will also hide the -;; mode-line in popups using `doom-hide-modeline-mode' +;; informational/terminal/temporary buffers--to have less presence over my work +;; buffers (e.g. source code buffers). I'd also like them to be easy to both +;; dispose of quickly and invoke from anywhere. Also, hide the mode-line in +;; popups with `doom-hide-modeline-mode' ;; -;; I use `shackle' to make this as consistent as possible, which lets you -;; specify rules on how to treat certain buffers. I go through great lengths to -;; tame helm, flycheck, help buffers--*even* the beast that is org-mode, with -;; the help of `display-buffer-alist' and `shackle'. +;; I use `shackle' to make this as consistent as possible, which allows you +;; to specify rules on how to treat certain buffers. ;; ;; 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 diff --git a/core/core.el b/core/core.el index 6dcb6ac82..6120fed19 100644 --- a/core/core.el +++ b/core/core.el @@ -2,14 +2,15 @@ ;;; Naming conventions: ;; -;; doom-... A public variable or function (non-interactive use) -;; doom--... A private variable, function (non-interactive use) or macro -;; doom/... An interactive function -;; doom:... An evil operator, motion or command -;; doom|... A hook -;; doom*... An advising function -;; ...! Macro, shortcut alias or defsubst -;; @... A generator macro for keybinds +;; doom-... public variables or functions (non-interactive) +;; doom--... private anything (non-interactive), not safe for direct use +;; doom/... an interactive function +;; doom:... an evil operator, motion or command +;; doom|... hook function +;; doom*... advising functions +;; doom!... interaction commands exclusively for installing external dependencies +;; @... 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