Fix escaping in docstrings (#141)

Author: gdalle

docs/src/faq.md

@@ -12,29 +12,32 @@ To differentiate through an `ImplicitFunction`, the following backends are suppo
 
 By default, the conditions are differentiated using the same "outer" backend that is trying to differentiate the `ImplicitFunction`.
 However, this can be switched to any other "inner" backend compatible with [DifferentiationInterface.jl](https://github.com/gdalle/DifferentiationInterface.jl) (i.e. a subtype of `ADTypes.AbstractADType`).
-You can override the default with the `conditions_x_backend` and `conditions_y_backend` keyword arguments when constructing an `ImplicitFunction`.
 
 ## Input and output types
 
-### Arrays
+### Vectors
 
 Functions that eat or spit out arbitrary vectors are supported, as long as the forward mapping _and_ conditions return vectors of the same size.
 
 If you deal with small vectors (say, less than 100 elements), consider using [StaticArrays.jl](https://github.com/JuliaArrays/StaticArrays.jl) for increased performance.
 
+### Arrays
+
+Functions that eat or spit out matrices and higher-order tensors are not supported.
+You can use `vec` and `reshape` for the conversion to and from vectors.
+
 ### Scalars
 
 Functions that eat or spit out a single number are not supported.
 The forward mapping _and_ conditions need vectors: instead of returning `val` you should return `[val]` (a 1-element `Vector`).
 Or better yet, wrap it in a static vector: `SVector(val)`.
 
-### Sparse vectors
+### Sparse arrays
 
 !!! danger "Danger"
-    Sparse vectors are not supported and might give incorrect values or `NaN`s!
+    Sparse arrays are not supported out of the box and might yield incorrect values!
 
-With ForwardDiff.jl, differentiation of sparse vectors will often give wrong results due to [sparsity pattern cancellation](https://github.com/JuliaDiff/ForwardDiff.jl/issues/658).
-That is why we do not test behavior for sparse inputs.
+If your use case involves sparse arrays, it is best to differentiate with respect to the dense vector of values and only construct the sparse array inside of the `forward` and `conditions` functions.
 
 ## Number of inputs and outputs
 

src/implicit_function.jl

@@ -1,7 +1,7 @@
 """
     KrylovLinearSolver
 
-Callable object that can solve linear systems `As = b` and `AS = b` in the same way that `\`.
+Callable object that can solve linear systems `As = b` and `AS = b` in the same way as the built-in `\\`.
 Uses an iterative solver from [Krylov.jl](https://github.com/JuliaSmoothOptimizers/Krylov.jl) under the hood.
 
 # Note
@@ -81,7 +81,7 @@ The provided `linear_solver` objects needs to be callable, with two methods:
 - `(A, b::AbstractVector) -> s::AbstractVector` such that `A * s = b`
 - `(A, B::AbstractVector) -> S::AbstractMatrix` such that `A * S = B`
 
-It can be either a direct solver (like `\`) or an iterative one (like [`KrylovLinearSolver`](@ref)).
+It can be either a direct solver (like `\\`) or an iterative one (like [`KrylovLinearSolver`](@ref)).
 Typically, direct solvers work best with dense Jacobians (`lazy = false`) while iterative solvers work best with operators (`lazy = true`).
 
 # Condition backends
@@ -103,11 +103,7 @@ end
 """
     ImplicitFunction{lazy}(
         forward, conditions;
-        linear_solver=if lazy
-            KrylovLinearSolver()
-        else
-            \
-        end,
+        linear_solver=lazy ? KrylovLinearSolver() : \\,
         conditions_x_backend=nothing,
         conditions_x_backend=nothing,
     )
@@ -138,9 +134,7 @@ end
         conditions_x_backend=nothing,
     )
 
-Constructor for an [`ImplicitFunction`](@ref) which picks the `lazy` parameter automatically based on the `linear_solver`, using the following heuristic:
-
-    lazy = linear_solver != \
+Constructor for an [`ImplicitFunction`](@ref) which picks the `lazy` parameter automatically based on the `linear_solver`, using the following heuristic: `lazy = linear_solver != \\`.
 """
 function ImplicitFunction(
     forward,