Merge pull request #197 from vpuri3/docs

minor fixes

Author: ChrisRackauckas

src/func.jl

@@ -1,6 +1,6 @@
 #
 """
-Matrix free operators (given by a function)
+Matrix free operator given by a function
 
 $(FIELDS)
 """
@@ -115,45 +115,36 @@ is assumed to be of the same type and share as the input.
 
 # Keyword Arguments
 
-Keyword arguments are used to pass in the adjoint operator, `op_adjoint`,
-the inverse operator, `op_inverse`, and the adjoint-inverse operator
-`adjoint_inverse`. All are assumed to have the same calling signature and
+Keyword arguments are used to pass in the adjoint evaluation function,
+`op_adjoint`, the inverse function, `op_inverse`, and the adjoint-inverse
+function `adjoint_inverse`. All are assumed to have the same calling signature and
 below traits.
 
 ## Traits
 Keyword arguments are used to set operator traits, which are assumed to be
 uniform across `op`, `op_adjoint`, `op_inverse`, `op_adjoint_inverse`.
 
+* `p` - Prototype of parameter struct passed to the operator during evaluation, i.e. `L(u, p, t)`. `p` is set to `nothing` if no value is provided.
+* `t` - Protype of scalar time variable passed to the operator during evaluation. `t` is set to `zero(T)` if no value is provided.
+* `accepted_kwargs` - `Tuple` of `Symbol`s corresponding to the keyword arguments accepted by `op*`, and `update_coefficients[!]`. For example, if `op` accepts kwarg `scale`, as in `op(u, p, t; scale)`, then `accepted_kwargs = (:scale,)`.
+
+* `T` - `eltype` of the operator. If no value is provided, the constructor inferrs the value from types of `input`, and `output`
 * `isinplace` - `true` if the operator can be used is a mutating way with in-place allocations. This trait is inferred if no value is provided.
 * `outofplace` - `true` if the operator can be used is a non-mutating way with in-place allocations. This trait is inferred if no value is provided.
-* `isconstant` - `true` if the operator is constant, and doesn't need to be updated via `update_coefficients[!]` during operator evaluation.
 * `has_mul5` - `true` if the operator provides a five-argument `mul!` via the signature `op(v, u, p, t, α, β; <accepted_kwargs>)`. This trait is inferred if no value is provided.
-* `cache` - Pregenerated cache arrays for in-place evaluations. Expected to be of type and shape `(similar(input), similar(output),)`. The constructor generates cache if no values are provided. Cache generation by the constructor can be disabled by setting the kwarg `ifcache = false`.
-* `T` - `eltype` of the operator. If no value is provided, the constructor inferrs the value from types of `input`, and `output`
-* `p` - Prototype of parameter struct passed to the operator during evaluation, i.e. `L(u, p, t)`. `p` is set to `nothing` if no value is provided.
-* `t` - Protype of scalar time variable passed to the operator during evaluation. `t` is set to `zero(T)` if no value is provided.
-* `ifcache` - Allocate cache arrays in constructor. Defaults to `true`. Cache can be generated afterwards by calling `cache_operator(L, input, output)`
+* `isconstant` - `true` if the operator is constant, and doesn't need to be updated via `update_coefficients[!]` during operator evaluation.
 * `islinear` - `true` if the operator is linear. Defaults to `false`.
+* `ifcache` - Allocate cache arrays in constructor. Defaults to `true`. Cache can be generated afterwards by calling `cache_operator(L, input, output)`
+* `cache` - Pregenerated cache arrays for in-place evaluations. Expected to be of type and shape `(similar(input), similar(output),)`. The constructor generates cache if no values are provided. Cache generation by the constructor can be disabled by setting the kwarg `ifcache = false`.
 * `opnorm` - The norm of `op`. Can be a `Number`, or function `opnorm(p::Integer)`. Defaults to `nothing`.
 * `issymmetric` - `true` if the operator is linear and symmetric. Defaults to `false`.
 * `ishermitian` - `true` if the operator is linear and hermitian. Defaults to `false`.
 * `isposdef` - `true` if the operator is linear and positive-definite. Defaults to `false`.
-
-Cache arrays can optionally be passed in via the
-kwarg `cache`, and
-disabled by passing the kwarg `cach`
 """
 function FunctionOperator(op,
                           input::AbstractVecOrMat,
                           output::AbstractVecOrMat = input;
 
-                          isinplace::Union{Nothing,Bool}=nothing,
-                          outofplace::Union{Nothing,Bool}=nothing,
-                          isconstant::Bool = false,
-                          has_mul5::Union{Nothing,Bool}=nothing,
-                          cache::Union{Nothing, NTuple{2}}=nothing,
-                          T::Union{Type{<:Number},Nothing}=nothing,
-
                           op_adjoint=nothing,
                           op_inverse=nothing,
                           op_adjoint_inverse=nothing,
@@ -162,11 +153,18 @@ function FunctionOperator(op,
                           t::Union{Number,Nothing}=nothing,
                           accepted_kwargs::NTuple{N,Symbol} = (),
 
-                          ifcache::Bool = true,
-
                           # traits
+                          T::Union{Type{<:Number},Nothing}=nothing,
+                          isinplace::Union{Nothing,Bool}=nothing,
+                          outofplace::Union{Nothing,Bool}=nothing,
+                          has_mul5::Union{Nothing,Bool}=nothing,
+                          isconstant::Bool = false,
                           islinear::Bool = false,
 
+                          ifcache::Bool = true,
+                          cache::Union{Nothing, NTuple{2}}=nothing,
+
+                          # LinearAlgebra traits
                           opnorm = nothing,
                           issymmetric::Bool = false,
                           ishermitian::Bool = false,

src/matrix.jl

@@ -28,6 +28,7 @@ adjoints, transposes.
 
 # Example
 
+Out-of-place update and usage
 ```
 u = rand(4)
 p = rand(4, 4)
@@ -43,6 +44,7 @@ L = cache_operator(M, u)
 v = L(u, p, t; scale = 1.0)
 ```
 
+In-place update and usage
 ```
 v = zero(4)
 u = rand(4)