Add function signature in documentation

[mtanneau]

The current documentation of user-facing functions, e.g., Krylov.cg, Krylov.minres, etc., does not include these functions' signature.

It makes it hard for newbies like me to know how exactly to call a function, without going through the source code.

Here is an example of what I had in mind, for Krylov.cg:

---

cg(A, b; kwargs...)

The conjugate gradient method to solve the symmetric linear system Ax=b.

The method does not abort if A is not definite.

A preconditioner M may be provided in the form of a linear operator and is
assumed to be symmetric and positive definite.
M also indicates the weighted norm in which residuals are measured.

Arguments

• A: Left-hand side
• b::AbstractVector: Right-hand side

Key-word arguments

• M: user-provided preconditioner
• atol: absolute tolerance
• rtol: relative tolerance
• itmax::Int: maximum number of iterations
  ...

---

Even just the signature would be useful.

[dpo]

I'm quite excited about https://juliadocs.github.io/DocStringExtensions.jl/stable/#DocStringExtensions.SIGNATURES

[amontoison]

DocStringExtensions.jl works quite well when the functions are not parametrized but in our case the solvers depend on T, the floating-point system. The signature only appears in the docstring for some random methods when I tested it. Another drawback of the signature generated by DocStringExtensions is that the output arguments are not given.

Signatures of our Krylov solvers are not updated often, I updated the docstrings with #208.

[dpo]

I think we should iterate with the DocstringsExtensions.jl authors to see if it's possible to get the result we want. It's a general principle that doesn't only apply to Krylov.jl.

I'm not worried about the output parameters. We usually describe those in a section of the docstring and that's sufficient.

[amontoison]

@mtanneau, does #238 solve your problem?

[mtanneau]

@amontoison yes :) Thanks.