improve docs

Author: oxinabox

docs/src/opting_out_of_rules.md

@@ -1,4 +1,4 @@
-# Opting out of rules
+# [Opting out of rules](@id opt_out)
 
 It is common to define rules fairly generically.
 Often matching (or exceeding) how generic the matching original primal method is.
@@ -53,6 +53,12 @@ Similar can be done  `@opt_out frule`.
 It can also be done passing in a [`RuleConfig`](@ref config).
 
 
+!!! warning "If the general rule uses a config, the opt-out must also"
+    Following the same principles as for [rules with config](@ref config), a rule with a `RuleConfig` argument will take precedence over one without, including if that one is a opt-out rule.
+    But if the general rule does not use a config, then the opt-out rule *can* use a config.
+    This allows, for example, you to use opt-out to avoid a particular AD system using a opt-out rule that takes that particular AD's config.
+    
+
 ## How to support this (for AD implementers)
 
 We provide two ways to know that a rule has been opted out of.

src/rule_definition_tools.jl

@@ -428,6 +428,8 @@ This will generate an [`rrule`](@ref) that returns `nothing`,
 and will also add a similar entry to [`ChainRulesCore.no_rrule`](@ref).
 
 Similar applies for [`frule`](@ref) and [`ChainRulesCore.no_frule`](@ref)
+
+For more information see the [documentation on opting out of rules](@ref opt_out).
 """
 macro opt_out(expr)
     no_rule_target = _no_rule_target_rewrite!(deepcopy(expr))

src/rules.jl

@@ -146,20 +146,26 @@ end
 const NO_RRULE_DOC = """
     no_rrule
 
-This is an implementation detail for opting out of [`rrule`](@ref).
+This is an piece of infastructure supporting opting out of [`rrule`](@ref).
 It follows the signature for `rrule` exactly.
-We use it as a way to store a collection of type-tuples in its method-table.
-If something has this defined, it means that it must having a must also have a `rrule`,
-that returns `nothing`.
+A collection of type-tuples is stored in its method-table.
+If something has this defined, it means that it must having a must also have a `rrule`, 
+defined that returns `nothing`.
+
+!!! warning "do not overload no_rrule directly
+    It is fine and intended to query the method table of `no_rrule`.
+    It is not safe to add to that directly, as corresponding changes also need to be made to
+    `rrule`.
+    The [`@opt_out`](@ref) macro does both these things, and so should almost always be used
+    rather than defining a method of `no_rrule` directly.
 
 ### Mechanics
-note: when the text below says methods `==` or `<:` it actually means:
+note: when the text below says methods `==` it actually means:
 `parameters(m.sig)[2:end]` (i.e. the signature type tuple) rather than the method object `m` itself.
 
 To decide if should opt-out using this mechanism.
- - find the most specific method of `rrule`
- - find the most specific method of `no_rrule`
- - if the method of `no_rrule` `<:` the method of `rrule`, then should opt-out
+ - find the most specific method of `rrule` and `no_rule` e.g with `Base.which`
+  - if the method of `no_rrule` `==` the method of `rrule`, then should opt-out
 
 To just ignore the fact that rules can be opted-out from, and that some rules thus return
 `nothing`, then filter the list of methods of `rrule` to remove those that are `==` to ones
@@ -171,6 +177,8 @@ rule without config.
 On the other-hand if your AD can work with `rrule`s that return `nothing`, then it is
 simpler to just use that mechanism for opting out; and you don't need to worry about this
 at all.
+
+For more information see the [documentation on opting out of rules](@ref opt_out)
 """
 
 """