From 0aaabf1904aebcd6940fc15cc19015c6853317f8 Mon Sep 17 00:00:00 2001
From: Eric Callahan <arksine.code@gmail.com>
Date: Tue, 6 Feb 2024 11:19:03 -0500
Subject: [PATCH] docs: update BED_MESH_OFFSET description

Add the ZFADE parameter to the documentation.

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
---
 docs/Bed_Mesh.md | 14 +++++++++++---
 docs/G-Codes.md  | 10 ++++++----
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/docs/Bed_Mesh.md b/docs/Bed_Mesh.md
index ada3de29d249..9ee8df507e77 100644
--- a/docs/Bed_Mesh.md
+++ b/docs/Bed_Mesh.md
@@ -542,11 +542,19 @@ This gcode may be used to clear the internal mesh state.
 
 ### Apply X/Y offsets
 
-`BED_MESH_OFFSET [X=<value>] [Y=<value>]`
+`BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value>]`
 
 This is useful for printers with multiple independent extruders, as an offset
 is necessary to produce correct Z adjustment after a tool change.  Offsets
 should be specified relative to the primary extruder.  That is, a positive
 X offset should be specified if the secondary extruder is mounted to the
-right of the primary extruder, and a positive Y offset should be specified
-if the secondary extruder is mounted "behind" the primary extruder.
+right of the primary extruder, a positive Y offset should be specified
+if the secondary extruder is mounted "behind" the primary extruder, and
+a positive ZFADE offset should be specified if the secondary extruder's
+nozzle is above the primary extruder's.
+
+Note that a ZFADE offset does *NOT* directly apply additional adjustment.  It
+is intended to compensate for a `gcode offset` when [mesh fade](#mesh-fade)
+is enabled.  For example, if a secondary extruder is higher than the primary
+and needs a negative gcode offset, ie: `SET_GCODE_OFFSET Z=-.2`, it can be
+accounted for in `bed_mesh` with `BED_MESH_OFFSET ZFADE=.2`.
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index 92cb76606afb..3e32ba3f7cd9 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -184,10 +184,12 @@ SAVE_CONFIG gcode must be run to make the changes to persistent memory
 permanent.
 
 #### BED_MESH_OFFSET
-`BED_MESH_OFFSET [X=<value>] [Y=<value>]`: Applies X and/or Y offsets
-to the mesh lookup. This is useful for printers with independent
-extruders, as an offset is necessary to produce correct Z adjustment
-after a tool change.
+`BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value]`: Applies X, Y,
+and/or ZFADE offsets to the mesh lookup. This is useful for printers with
+independent extruders, as an offset is necessary to produce correct Z
+adjustment after a tool change.  Note that a ZFADE offset does not apply
+additional z-adjustment directly, it is used to correct the `fade`
+calculation when a `gcode offset` has been applied to the Z axis.
 
 ### [bed_screws]