document gradient ownership

Project.toml

@@ -1,7 +1,7 @@
 name = "LogDensityProblems"
 uuid = "6fdf6af0-433a-55f7-b3ed-c6c6e0b8df7c"
 authors = ["Tamas K. Papp <tkpapp@gmail.com>"]
-version = "0.10.5"
+version = "0.10.6"
 
 [deps]
 ArgCheck = "dce04be8-c92d-5529-be00-80e4d2c0e197"

docs/Project.toml

@@ -7,4 +7,4 @@ UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [compat]
-Documenter = "~0.26"
+Documenter = "~0.27"

docs/src/index.md

@@ -162,6 +162,10 @@ function LogDensityProblems.logdensity_and_gradient(problem::NormalPosterior, x)
 end
 ```
 
+!!! note
+    If the gradient is a mutable vector (eg `Vector`), it should not be reused for another purpose. Practically, each call to [`LogDensityProblems.logdensity_and_gradient`](@ref) should allocate a new one, or use immutables like
+    `StaticArrays.SVector` for small dimensions.
+
 # Various utilities
 
 You may find these utilities useful for debugging and optimization.

src/LogDensityProblems.jl

@@ -116,8 +116,12 @@ Return two values:
 
 - the log density as real number, which equivalent to `logdensity(ℓ, x)`
 
-- *if* the log density is finite, the gradient, a vector of real numbers, otherwise this
-   value is arbitrary and should be ignored.
+- *if* the log density is finite, the gradient, an `::AbstractVector` of real numbers,
+   otherwise this value is arbitrary and should be ignored.
+
+!!! note
+    Caller may assume ownership of results, ie that the gradient vector will not be
+    overwritten or reused for a different purpose.
 
 The first argument (the log density) can be shifted by a constant, see the note for
 [`logdensity`](@ref).
@@ -198,7 +202,11 @@ Wrap `P` using automatic differentiation to obtain a gradient.
 `kind` is usually a `Val` type with a symbol that refers to a package, for example
 ```julia
 ADgradient(Val(:ForwardDiff), P)
+ADgradient(Val(:ReverseDiff), P)
+ADgradient(Val(:Zygote), P)
 ```
+Some methods may be loaded only conditionally after the relevant package is loaded (eg
+`using Zygote`).
 
 The symbol can also be used directly as eg
 
@@ -208,10 +216,7 @@ ADgradient(:ForwardDiff, P)
 
 and should mostly be equivalent if the compiler manages to fold the constant.
 
-`parent` can be used to retrieve the original argument.
-
-See `methods(ADgradient)`. Note that **some methods are defined conditionally on the
-relevant package being loaded.**
+The function `parent` can be used to retrieve the original argument.
 """
 ADgradient(kind::Symbol, P; kwargs...) = ADgradient(Val{kind}(), P; kwargs...)