More docs on generation

Author: oxinabox

docs/src/autodiff/operator_overloading.md

@@ -11,11 +11,44 @@ A signature type tuple always has the form:
 first positional argument.
 One can dispatch on the signature type to make rules with argument types your AD does not support not call `eval`;
 or more simply you can just use conditions for this.
-The hook is automatically triggered whenever a package is loaded.
+For example if your AD only supports `AbstractMatrix{Float64}` and `Float64` inputs you might write:
+```julia
+const ACCEPT_TYPE = Union{Float64, AbstractMatrix{Float64}} 
+function define_overload(sig::Type{<:Tuple{F, Vararg{ACCEPT_TYPE}}) where F
+    @eval quote
+        # ...
+    end
+end
+define_overload(::Any) = nothing  # don't do anything for any other signature
+
+on_new_rule(frule, define_overload)
+```
+
+or you might write:
+```julia
+const ACCEPT_TYPES = (Float64, AbstractMatrix{Float64})
+function define_overload(sig) where F
+    sig = Base.unwrap_unionall(sig)  # not really handling most UnionAll,
+    opT, argTs = Iterators.peel(sig.parameters)
+    all(any(acceptT<: argT for acceptT in ACCEPT_TYPES) for argT in argTs) || return
+    @eval quote
+        # ...
+    end
+end
+
+on_new_rule(frule, define_overload)
+```
 
-`refresh_rules`(@ref) is used to manually trigger the hook function on any new rules.
+The generation of overloaded code is the responsibility of the AD implementor.
+Packages like [ExprTools.jl](https://github.com/invenia/ExprTools.jl) can be helpful for this.
+Its generally fairly simple, though can become complex if you need to handle complicated type-constraints.
+Examples are shown below.
+
+The hook is automatically triggered whenever a package is loaded.
+It can also be triggers manually using `refresh_rules`(@ref).
 This is useful for example if new rules are define in the REPL, or if a package defining rules is modified.
 (Revise.jl will not automatically trigger).
+When the rules are refreshed (automatically or manually), the hooks are only triggered on new/modified rules; not ones that have already had the hooks triggered on.
 
 `clear_new_rule_hooks!`(@ref) clears all registered hooks.
 It is useful to undo [`on_new_rule`] hook registration if you are iteratively developing your overload generation function.

test/demos/forwarddiffzero.jl

@@ -28,7 +28,7 @@ Base.to_power_type(x::Dual) = x
 
 
 function define_dual_overload(sig)
-    sig = Base.unwrap_unionall(sig)
+    sig = Base.unwrap_unionall(sig)  # Not really handling most UnionAlls
     opT, argTs = Iterators.peel(sig.parameters)
     fieldcount(opT) == 0 || return  # not handling functors 
     all(Float64 <: argT for argT in argTs) || return  # only handling purely Float64 ops.

test/demos/reversediffzero.jl

@@ -57,7 +57,7 @@ Base.to_power_type(x::Tracked) = x
 
 "What to do when a new rrule is declared"
 function define_tracked_overload(sig)
-    sig = Base.unwrap_unionall(sig)
+    sig = Base.unwrap_unionall(sig)  # not really handling most UnionAll
     opT, argTs = Iterators.peel(sig.parameters)
     fieldcount(opT) == 0 || return  # not handling functors 
     all(Float64 <: argT for argT in argTs) || return  # only handling purely Float64 ops.