From 451c16b8eed755c875b4894c7c605f0bcbffb405 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Sun, 23 Dec 2018 00:25:51 -0500
Subject: [PATCH] Revise :after-call & :defer-incrementally comments

Now implicitly adds the current package to :defer-incrementally's list
of packages.
---
 core/core-editor.el           |  4 ++--
 core/core-modules.el          | 34 +++++++++++++++++++++++++++-------
 modules/tools/magit/config.el |  2 +-
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/core/core-editor.el b/core/core-editor.el
index 859013d97..5a1c339ef 100644
--- a/core/core-editor.el
+++ b/core/core-editor.el
@@ -97,7 +97,7 @@ fundamental-mode) for performance sake."
 
 (def-package! savehist
   ;; persist variables across sessions
-  :defer-incrementally (custom savehist)
+  :defer-incrementally (custom)
   :after-call post-command-hook
   :config
   (setq savehist-file (concat doom-cache-dir "savehist")
@@ -129,7 +129,7 @@ savehist file."
 
 (def-package! recentf
   ;; Keep track of recently opened files
-  :defer-incrementally (easymenu tree-widget timer recentf)
+  :defer-incrementally (easymenu tree-widget timer)
   :after-call after-find-file
   :commands recentf-open-files
   :config
diff --git a/core/core-modules.el b/core/core-modules.el
index bee39dd97..97e886ecb 100644
--- a/core/core-modules.el
+++ b/core/core-modules.el
@@ -191,14 +191,34 @@ non-nil, return paths of possible modules, activated or otherwise."
       use-package-minimum-reported-time (if doom-debug-mode 0 0.1)
       use-package-expand-minimally (not noninteractive))
 
-;; Adds the :after-call custom keyword to `use-package' (and consequently,
-;; `def-package!'). :after-call takes a symbol or list of symbols. These symbols
-;; can be functions or hook variables.
+;; Adds two new keywords to `use-package' (and consequently, `def-package!'),
+;; they are:
 ;;
-;;   (use-package X :after-call find-file-hook)
+;; :after-call SYMBOL|LIST
+;;   Takes a symbol or list of symbols representing functions or hook variables.
+;;   The first time any of these functions or hooks are executed, the package is
+;;   loaded. e.g.
 ;;
-;; This will load X on the first invokation of `find-file-hook' (then it will
-;; remove itself from the hook/function).
+;;   (def-package! projectile
+;;     :after-call (pre-command-hook after-find-file dired-before-readin-hook)
+;;     ...)
+;;
+;; :defer-incrementally SYMBOL|LIST|t
+;;   Takes a symbol or list of symbols representing packages that will be loaded
+;;   incrementally at startup before this one. This is helpful for large
+;;   packages like magit or org, which load a lot of dependencies on first load.
+;;   This lets you load them piece-meal, one at a time, during idle periods, so
+;;   that when you finally do need the package, it'll loads much quicker. e.g.
+;;
+;;   (def-package! magit
+;;     ;; You do not need to include magit in this list!
+;;     :defer-incrementally (dash f s with-editor git-commit package)
+;;     ...)
+;;
+;;   (def-package! x
+;;     ;; This is equivalent to :defer-incrementally (x)
+;;     :defer-incrementally t
+;;     ...)
 (defvar doom--deferred-packages-alist '(t))
 (after! use-package-core
   (add-to-list 'use-package-deferring-keywords :defer-incrementally nil #'eq)
@@ -215,7 +235,7 @@ non-nil, return paths of possible modules, activated or otherwise."
      `((doom-load-packages-incrementally
         ',(if (equal targets '(t))
               (list name)
-            targets)))
+            (append targets (list name)))))
      (use-package-process-keywords name rest state)))
 
   (defalias 'use-package-normalize/:after-call 'use-package-normalize-symlist)
diff --git a/modules/tools/magit/config.el b/modules/tools/magit/config.el
index 928680797..97af76ff2 100644
--- a/modules/tools/magit/config.el
+++ b/modules/tools/magit/config.el
@@ -15,7 +15,7 @@ what features are available.")
 
 (def-package! magit
   :commands magit-file-delete
-  :defer-incrementally (dash f s with-editor git-commit package magit)
+  :defer-incrementally (dash f s with-editor git-commit package)
   :init
   (setq magit-auto-revert-mode nil)  ; we already use `global-auto-revert-mode'
   :config