From 8b4f722fa343f954c6a8fe61aed075cd2d7438d5 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <git@henrik.io>
Date: Thu, 18 Aug 2022 16:15:29 +0200
Subject: [PATCH] docs(lib): update after! to reflect changes upstream

It used to be that after! suppressed macro expansion, but at some point
around 28.1, the elisp interpreter started recognizing the
compiler-macro hint in eval-after-load's definition; implicitly wrapping
quoted forms in a function. Therefore, we can no longer rely on
eval-after-load to hide macros from the byte-compiler. Instead, modules
will need to take care to wrap macro calls in `eval` or similar, on a
case-by-case basis.
---
 lisp/doom-lib.el | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/lisp/doom-lib.el b/lisp/doom-lib.el
index 03cd4485d..688d6d05b 100644
--- a/lisp/doom-lib.el
+++ b/lisp/doom-lib.el
@@ -496,27 +496,30 @@ The current file is the file from which `add-to-load-path!' is used."
 (defmacro after! (package &rest body)
   "Evaluate BODY after PACKAGE have loaded.
 
-PACKAGE is a symbol or list of them. These are package names, not modes,
-functions or variables. It can be:
+PACKAGE is a symbol (or list of them) referring to Emacs features (aka
+packages). PACKAGE may use :or/:any and :and/:all operators. The precise format
+is:
 
 - An unquoted package symbol (the name of a package)
     (after! helm BODY...)
-- An unquoted list of package symbols (i.e. BODY is evaluated once both magit
-  and git-gutter have loaded)
-    (after! (magit git-gutter) BODY...)
 - An unquoted, nested list of compound package lists, using any combination of
   :or/:any and :and/:all
     (after! (:or package-a package-b ...)  BODY...)
     (after! (:and package-a package-b ...) BODY...)
     (after! (:and package-a (:or package-b package-c) ...) BODY...)
-  Without :or/:any/:and/:all, :and/:all are implied.
+- An unquoted list of package symbols (i.e. BODY is evaluated once both magit
+  and git-gutter have loaded)
+    (after! (magit git-gutter) BODY...)
+  If :or/:any/:and/:all are omitted, :and/:all are implied.
 
-This is a wrapper around `eval-after-load' that:
+This emulates `eval-after-load' with a few key differences:
 
-1. Suppresses warnings for disabled packages at compile-time
-2. No-ops for package that are disabled by the user (via `package!')
-3. Supports compound package statements (see below)
-4. Prevents eager expansion pulling in autoloaded macros all at once"
+1. No-ops for package that are disabled by the user (via `package!') or not
+   installed yet.
+2. Supports compound package statements (see :or/:any and :and/:all above).
+
+Since the contents of these blocks will never by byte-compiled, avoid putting
+things you want byte-compiled in them! Like function/macro definitions."
   (declare (indent defun) (debug t))
   (if (symbolp package)
       (unless (memq package (bound-and-true-p doom-disabled-packages))
@@ -524,9 +527,6 @@ This is a wrapper around `eval-after-load' that:
                       (require package nil 'noerror))
                   #'progn
                 #'with-no-warnings)
-              ;; We intentionally avoid `with-eval-after-load' to prevent eager
-              ;; macro expansion from pulling (or failing to pull) in autoloaded
-              ;; macros/packages.
               `(eval-after-load ',package ',(macroexp-progn body))))
     (let ((p (car package)))
       (cond ((memq p '(:or :any))