make it easier to find out what ⊢is and how to type it (#216)

* make it easier to find out what ⊢is and how to type it

* more edits

* try

* try again

* apparently referring to unicode operators is really difficult

* a bit more editing of docstrings

Author: st--

docs/src/index.md

@@ -134,14 +134,14 @@ test_frule(foo ⊢ Tangent{Foo}(;a=rand()), rand())
 
 ## Specifying Tangents
 [`test_frule`](@ref) and [`test_rrule`](@ref) allow you to specify the tangents used for testing.
-This is done by passing in `x ⊢ Δx`, where `x` is the primal and `Δx` is the tangent, in the place of the primal inputs.
-If this is not done the tangent will be automatically generated via `FiniteDifferences.rand_tangent`.
+By default, tangents will be automatically generated via `FiniteDifferences.rand_tangent`.
+To explicitly specify a tangent, pass in `x ⊢ Δx`, where `x` is the primal and `Δx` is the tangent, in the place of the primal inputs.
+(You can enter [`⊢`](@ref) via `\vdash` + tab in the Julia REPL and supporting editors.)
 A special case of this is that if you specify it as `x ⊢ NoTangent()` then finite differencing will not be used on that input.
 Similarly, by setting the `output_tangent` keyword argument, you can specify the tangent for the primal output.
 
 This can be useful when the default provided `FiniteDifferences.rand_tangent` doesn't produce the desired tangent for your type.
-For example the default tangent for an `Int` is `NoTangent()`.
-Which is correct e.g. when the `Int` represents a discrete integer like in indexing.
+For example, the default tangent for an `Int` is `NoTangent()`, which is correct e.g. when the `Int` represents a discrete integer like in indexing.
 But if you are testing something where the `Int` is actually a special case of a real number, then you would want to specify the tangent as a `Float64`.
 
 Care must be taken when manually specifying tangents.
@@ -273,4 +273,4 @@ Test.DefaultTestSet("test_rrule: abs on Float64", Any[], 5, false, false)
 ```
 
 This behavior can also be overridden globally by setting the environment variable `CHAINRULES_TEST_INFERRED` before ChainRulesTestUtils is loaded or by changing `ChainRulesTestUtils.TEST_INFERRED[]` from inside Julia.
-ChainRulesTestUtils can detect whether a test is run as part of [PkgEval](https://github.com/JuliaCI/PkgEval.jl)and in this case disables inference tests automatically. Packages can use [`@maybe_inferred`](@ref) to get the same behavior for other inference tests.
+ChainRulesTestUtils can detect whether a test is run as part of [PkgEval](https://github.com/JuliaCI/PkgEval.jl) and in this case disables inference tests automatically. Packages can use [`@maybe_inferred`](@ref) to get the same behavior for other inference tests.

src/testers.jl

@@ -5,12 +5,14 @@ Given a function `f` with scalar input and scalar output, perform finite differe
 at input point `z` to confirm that there are correct `frule` and `rrule`s provided.
 
 # Arguments
-- `f`: Function for which the `frule` and `rrule` should be tested.
-- `z`: input at which to evaluate `f` (should generally be set to an arbitary point in the domain).
+- `f`: function for which the `frule` and `rrule` should be tested.
+- `z`: input at which to evaluate `f` (should generally be set to an arbitrary point in the domain).
 
-`fkwargs` are passed to `f` as keyword arguments.
-If `check_inferred=true`, then the type-stability of the `frule` and `rrule` are checked.
-All remaining keyword arguments are passed to `isapprox`.
+# Keyword Arguments
+- `fdm`: the finite differencing method to use.
+- `fkwargs` are passed to `f` as keyword arguments.
+- If `check_inferred=true`, then the inferrability (type-stability) of the `frule` and `rrule` are checked.
+- All remaining keyword arguments are passed to `isapprox`.
 """
 function test_scalar(f, z; rtol=1e-9, atol=1e-9, fdm=_fdm, fkwargs=NamedTuple(), check_inferred=true, kwargs...)
     # To simplify some of the calls we make later lets group the kwargs for reuse
@@ -71,19 +73,20 @@ end
 
 # Arguments
 - `config`: defaults to `ChainRulesTestUtils.ADviaRuleConfig`.
-- `f`: Function for which the `frule` should be tested. Can also provide `f ⊢ ḟ`.
-- `args` either the primal args `x`, or primals and their tangents: `x ⊢ ẋ`
-   - `x`: input at which to evaluate `f` (should generally be set to an arbitary point in the domain).
-   - `ẋ`: differential w.r.t. `x`, will be generated automatically if not provided
+- `f`: function for which the `frule` should be tested. Its tangent can be provided using `f ⊢ ḟ`.
+  (You can enter `⊢` via `\\vdash` + tab in the Julia REPL and supporting editors.)
+- `args...`: either the primal args `x`, or primals and their tangents: `x ⊢ ẋ`
+   - `x`: input at which to evaluate `f` (should generally be set to an arbitrary point in the domain).
+   - `ẋ`: differential w.r.t. `x`; will be generated automatically if not provided.
    Non-differentiable arguments, such as indices, should have `ẋ` set as `NoTangent()`.
 
 # Keyword Arguments
-   - `output_tangent` tangent to test accumulation of derivatives against
-     should be a differential for the output of `f`. Is set automatically if not provided.
+   - `output_tangent`: tangent against which to test accumulation of derivatives.
+     Should be a differential for the output of `f`. Is set automatically if not provided.
    - `fdm::FiniteDifferenceMethod`: the finite differencing method to use.
-   - `frule_f=frule`: Function with an `frule`-like API that is tested (defaults to
+   - `frule_f=frule`: function with an `frule`-like API that is tested (defaults to
      `frule`). Used for testing gradients from AD systems.
-   - If `check_inferred=true`, then the inferrability of the `frule` is checked,
+   - If `check_inferred=true`, then the inferrability (type-stability) of the `frule` is checked,
      as long as `f` is itself inferrable.
    - `fkwargs` are passed to `f` as keyword arguments.
    - All remaining keyword arguments are passed to `isapprox`.
@@ -144,21 +147,22 @@ end
 
 # Arguments
 - `config`: defaults to `ChainRulesTestUtils.ADviaRuleConfig`.
-- `f`: Function to which rule should be applied. Can also provide `f ⊢ f̄`.
-- `args` either the primal args `x`, or primals and their tangents: `x ⊢ x̄`
-    - `x`: input at which to evaluate `f` (should generally be set to an arbitary point in the domain).
-    - `x̄`: currently accumulated cotangent, will be generated automatically if not provided
+- `f`: function for which the `rrule` should be tested. Its tangent can be provided using `f ⊢ f̄`.
+  (You can enter `⊢` via `\\vdash` + tab in the Julia REPL and supporting editors.)
+- `args...`: either the primal args `x`, or primals and their tangents: `x ⊢ x̄`
+    - `x`: input at which to evaluate `f` (should generally be set to an arbitrary point in the domain).
+    - `x̄`: currently accumulated cotangent; will be generated automatically if not provided.
     Non-differentiable arguments, such as indices, should have `x̄` set as `NoTangent()`.
 
 # Keyword Arguments
- - `output_tangent` the seed to propagate backward for testing (technically a cotangent).
+ - `output_tangent`: the seed to propagate backward for testing (technically a cotangent).
    should be a differential for the output of `f`. Is set automatically if not provided.
-- `check_thunked_output_tangent=true`: also checks that passing a thunked version of the 
+ - `check_thunked_output_tangent=true`: also checks that passing a thunked version of the 
     output tangent to the pullback returns the same result.
  - `fdm::FiniteDifferenceMethod`: the finite differencing method to use.
- - `rrule_f=rrule`: Function with an `rrule`-like API that is tested (defaults to `rrule`).
+ - `rrule_f=rrule`: function with an `rrule`-like API that is tested (defaults to `rrule`).
    Used for testing gradients from AD systems.
- - If `check_inferred=true`, then the inferrability of the `rrule` is checked
+ - If `check_inferred=true`, then the inferrability (type-stability) of the `rrule` is checked
    — if `f` is itself inferrable — along with the inferrability of the pullback it returns.
  - `fkwargs` are passed to `f` as keyword arguments.
  - All remaining keyword arguments are passed to `isapprox`.