From e0d3d8b1a785ec291f0a41da3f12cad51d80eb6b Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Mon, 19 Jun 2023 18:31:14 -0400
Subject: [PATCH] better words

---
 src/compiler/interface.jl | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/compiler/interface.jl b/src/compiler/interface.jl
index 43e47c6c3..c09d6db31 100644
--- a/src/compiler/interface.jl
+++ b/src/compiler/interface.jl
@@ -119,13 +119,15 @@ julia> ∇ == gradient(/, 1, 2)
 true
 ```
 
-If `f` returns a Tuple or NamedTuple, then it calculates
-`gradient(first∘f, args...)` but returns the whole `f(args...)`:
+Allows you to capture auxillary outputs, in addition to the scalar
+used by `gradient`. To do this, `f` must return a Tuple or NamedTuple.
+Then it calculates `grad = gradient(first∘f, args...)
+but returns the whole `val = f(args...)`:
 
 ```jldoctest; setup=:(using Zygote)
 julia> withgradient([1,2,4]) do x
           z = 1 ./ x
-          sum(z), z
+          sum(z), z  # here z is an auxillary output
        end
 (val = (1.75, [1.0, 0.5, 0.25]), grad = ([-1.0, -0.25, -0.0625],))