From 6b2a74094e184a78a8d07e36f0060b009254deb0 Mon Sep 17 00:00:00 2001
From: Ellis Kenyo <me@elken.dev>
Date: Thu, 14 Sep 2023 16:44:43 +0100
Subject: [PATCH] docs(format): clarify how to update macro in private config

---
 modules/editor/format/README.org           | 9 +++++++++
 modules/editor/format/autoload/settings.el | 6 +++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/modules/editor/format/README.org b/modules/editor/format/README.org
index bb38e23a7..9869d6541 100644
--- a/modules/editor/format/README.org
+++ b/modules/editor/format/README.org
@@ -68,6 +68,15 @@ provide a simple macro that looks like the below:
 (set-formatter! 'unique-name '("command" "line" "here") :modes '(name-of-major-mode))
 #+end_src
 
+If you're trying to override a formatter that has previously been defined by
+Doom, you will need to ensure that the call in your config is contained within
+an =after!= form, eg below to override Clojure's with =zprint=:
+
+#+begin_src emacs-lisp
+(after! clojure-mode
+  (set-formatter! 'zprint '("zprint" "-") :modes '(clojure-mode)))
+#+end_src
+
 There are a few bonus symbols that apheleia uses (for example =npx= will be
 replaced by a correct path to npx) which are all documented in the link above.
 
diff --git a/modules/editor/format/autoload/settings.el b/modules/editor/format/autoload/settings.el
index f52a41e12..d7f116bc7 100644
--- a/modules/editor/format/autoload/settings.el
+++ b/modules/editor/format/autoload/settings.el
@@ -4,7 +4,7 @@
 (cl-defun set-formatter! (name args &key modes)
   "Define (or modify) a formatter named NAME.
 
-Supported keywords: :modes :filter
+Supported keywords: :modes
 
 NAME is a symbol that identifies this formatter.
 
@@ -20,6 +20,10 @@ nested list.
     string and ARG is both a predicate and argument for STRING. If ARG is nil,
     STRING will be omitted from the vector.
 
+If you're trying to override this, ensure that you wrap the call in `after!' and
+whichever package sets the initial formatter. See the ':editor format' README
+for more.
+
 For more information on how to structure the list to be
 compatible, see `apheleia--run-formatter-function'.