Document limitations of operator overloading utils

docs/src/dev/adding_overloads.md

@@ -10,9 +10,14 @@ Having read our guide [*"How SparseConnectivityTracer works"*](@ref how-sct-work
 [`Dual`](@ref SparseConnectivityTracer.Dual)
 to improve the performance of your functions or to work around some of SCT's [limitations](@ref limitations).
 
+## Avoid hand-written overloads
+
 !!! warning "Don't overload manually"
-    We strongly discourage you from manually adding methods on our tracer types.
-    Instead, use the same mechanisms we use ourselves.
+    If you want to overload a `Function` that takes `Real` arguments, 
+    we strongly discourage you from manually adding methods to your function that use our internal tracer types.
+
+    Instead, use the same code generation mechanisms that we use.
+    This page of the documentation shows you how.
 
 !!! tip "Copy one of our package extensions"
     The easiest way to add overloads is to copy one of our [package extensions](https://github.com/adrhill/SparseConnectivityTracer.jl/tree/main/ext) and to modify it.

src/overloads/special_cases.jl

@@ -20,6 +20,8 @@ function Base.rand(
     rng::AbstractRNG, ::SamplerType{D}
 ) where {P,T<:AbstractTracer,D<:Dual{P,T}}
     p = rand(rng, P)
+    # This unfortunately can't just return the primal value.
+    # Random.jl will otherwise throw "TypeError: in typeassert, expected Dual{P,T}, got a value of type P". 
     t = myempty(T)
     return Dual(p, t)
 end