docs: clarify tape recording in ReverseDiff docstring (#92)

Author: gdalle

Project.toml

@@ -1,7 +1,7 @@
 name = "ADTypes"
 uuid = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
 authors = ["Vaibhav Dixit <[email protected]>, Guillaume Dalle and contributors"]
-version = "1.9.0"
+version = "1.9.1"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

src/dense.jl

@@ -298,7 +298,24 @@ Defined by [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
 # Fields
 
-  - `compile::Union{Val, Bool}`: whether to [compile the tape](https://juliadiff.org/ReverseDiff.jl/api/#ReverseDiff.compile) prior to differentiation (the boolean version is also the type parameter)
+  - `compile::Union{Val, Bool}`: whether to allow pre-recording and reusing a tape (which speeds up the differentiation process).
+
+      + If `compile=false` or `compile=Val(false)`, a new tape must be recorded at every call to the differentiation operator.
+      + If `compile=true` or `compile=Val(true)`, a tape can be pre-recorded on an example input and then reused at every differentiation call.
+
+    The boolean version of this keyword argument is taken as the type parameter.
+
+!!! warning
+
+    Pre-recording a tape only captures the path taken by the differentiated function _when executed on the example input_.
+    If said function has value-dependent branching behavior, reusing pre-recorded tapes can lead to incorrect results.
+    In such situations, you should keep the default setting `compile=Val(false)`.
+    For more details, please refer to ReverseDiff's [`AbstractTape` API documentation](https://juliadiff.org/ReverseDiff.jl/dev/api/#The-AbstractTape-API).
+
+!!! info
+
+    Despite what its name may suggest, the `compile` setting does not prescribe whether or not the tape is compiled with [`ReverseDiff.compile`](https://juliadiff.org/ReverseDiff.jl/dev/api/#ReverseDiff.compile) after being recorded.
+    This is left as a private implementation detail.
 """
 struct AutoReverseDiff{C} <: AbstractADType
     compile::Bool  # this field is left for legacy reasons