docs more consistent

Author: oxinabox

docs/src/rule_author/superpowers/mutation_support.md

@@ -1,6 +1,6 @@
 # Mutation Support
 
-ChainRulesCore.jl offers experimental support for mutation, targetting use in forward mode AD.
+ChainRulesCore.jl offers experimental support for mutation, targeting use in forward mode AD.
 (Mutation support in reverse mode AD is more complicated and will likely require more changes to the interface)
 
 !!! warning "Experimental"
@@ -17,18 +17,23 @@ It is required to be a structural tangent, having one tangent for each field of
 Technically, not all `mutable struct`s need to use `MutableTangent` to represent their tangents.
 Just like not all `struct`s need to use `Tangent`s.
 Common examples away from this are natural tangent types like for arrays.
-However, if one is setting up to use a custom tangent type for this it is surficiently off the beated path that we can not provide much guidance.
+However, if one is setting up to use a custom tangent type for this it is sufficiently off the beaten path that we can not provide much guidance.
 
 ## `zero_tangent`
 
 The [`zero_tangent`](@ref) function functions to give you a zero (i.e. additive identity) for any primal value.
 The [`ZeroTangent`](@ref) type also does this.
-The difference is that [`zero_tangent`](@ref) is (where possible) a full structural tangent mirroring the structure of the primal.
+The difference is that [`zero_tangent`](@ref) is in general full structural tangent mirroring the structure of the primal.
+To be technical the promise of [`zero_tangent`](@ref) is that it will be a value that supports mutation.
+However, in practice[^1] this is achieved through in a structural tangent
 For mutation support this is important, since it means that there is mutable memory available in the tangent to be mutated when the primal changes.
 To support this you thus need to make sure your zeros are created in various places with [`zero_tangent`](@ref) rather than []`ZeroTangent`](@ref).
 
-It is also useful for reasons of type stability, since it is always a structural tangent.
-For this reason AD system implementors might chose to use this to create the tangent for all literal values they encounter, mutable or not.
+
+
+It is also useful for reasons of type stability, since it forces a consistent type (generally a structural tangent) for any given primal type.
+For this reason AD system implementors might chose to use this to create the tangent for all literal values they encounter, mutable or not,
+and to process the output of `frule`s to convert [`ZeroTangent`](@ref) into corresponding [`zero_tangent`](@ref)s.
 
 ## Writing a frule for a mutating function
 It is relatively straight forward to write a frule for a mutating function.
@@ -41,7 +46,7 @@ There are a few key points to follow:
 ### Example
 For example, consider the primal function with:
 1. takes two `Ref`s
-2. doubles the first one inplace
+2. doubles the first one in place
 3. overwrites the second one's value with the literal 5.0
 4. returns the first one
 
@@ -70,4 +75,8 @@ function ChainRulesCore.frule((ȧ, ḃ), ::typeof(foo!), a::Base.RefValue, b::B
 end
 ```
 
-Then assuming the AD system does its part to makes sure you are indeed given mutable values to mutate (i.e. those `@assert`ions are true) then all is well and this rule will make mutation correct.
+Then assuming the AD system does its part to makes sure you are indeed given mutable values to mutate (i.e. those `@assert`ions are true) then all is well and this rule will make mutation correct.
+
+[^1]:
+    Further, it is hard to achieve this promise of allowing mutation to be supported without returning a structural tangent.
+    Except in the special case of where the struct is not mutable and has no nested fields that are mutable.

src/tangent_types/abstract_zero.jl

@@ -100,7 +100,8 @@ For mutable composites types this is a structural [`MutableTangent`](@ref)
 For `Array`s, it is applied recursively for each element.
 For other types, in particular immutable types, we do not make promises beyond that it will be `iszero`
 and suitable for accumulating against.
-In general though, it is more likely to produce a structural tangent.
+For types without a tangent space (e.g. singleton structs) this returns `NoTangent()`.
+In general, it is more likely to produce a structural tangent.
 
 !!! warning Exprimental
     `zero_tangent`is an experimental feature, and is part of the mutation support featureset.