add an example to update! (#83)

* add an example to update!

* StaticArrays example

Co-authored-by: Michael Abbott <32575566+mcabbott@users.noreply.github.com>

Author: CarloLucibello

src/Optimisers.jl

@@ -129,7 +129,34 @@ The initial tree of states comes from [`setup`](@ref).
 
 This is used in exactly the same manner as [`update`](@ref), but because it may mutate
 arrays within the old model (and the old state), it will be faster for models of ordinary
-`Array`s or `CuArray`s. However, you should not rely on the old model being fully updated.
+`Array`s or `CuArray`s. However, you should not rely on the old model being fully updated
+but rather use the returned model.
+
+# Example
+
+```jldoctest
+julia> using StaticArrays, Zygote, Optimisers
+
+julia> m = (x = [1f0, 2f0], y = SA[4f0, 5f0]);  # partly mutable model
+
+julia> t = Optimisers.setup(Momentum(1/30, 0.9), m);
+
+julia> g = gradient(m -> sum(abs2.(m.x .+ m.y)), m)[1]
+(x = Float32[10.0, 14.0], y = Float32[10.0, 14.0])
+
+julia> t2, m2 = Optimisers.update!(t, m, g);
+
+julia> m2  # after update or update!, this is the new model
+(x = Float32[0.6666666, 1.5333333], y = Float32[3.6666667, 4.5333333])
+
+julia> m2.x === m.x  # update! has re-used this array, for efficiency
+true
+
+julia> m  # original should be discarded, may be mutated but no guarantee
+(x = Float32[0.6666666, 1.5333333], y = Float32[4.0, 5.0])
+
+julia> t  # original state should likewise be discarded
+(x = Leaf(Momentum{Float64}(0.0333333, 0.9), Float32[0.333333, 0.466667]), y = Leaf(Momentum{Float64}(0.0333333, 0.9), Float32[0.0, 0.0]))
 """
 update!