Add docstrings for StrongWolfe (#159)

Author: timholy

src/strongwolfe.jl

@@ -20,14 +20,35 @@ use `MoreThuente`, `HagerZhang` or `BackTracking`.
     ρ::T = 2.0
 end
 
+"""
+    (ls::StrongWolfe)(df, x::AbstractArray, p::AbstractArray, alpha0::Real, x_new, ϕ_0, dϕ_0) -> alpha, ϕalpha
+
+Given a differentiable function `df` (in the sense of `NLSolversBase.OnceDifferentiable` or
+`NLSolversBase.TwiceDifferentiable`), a multidimensional starting point `x` and step `p`,
+and a guess `alpha0` for the step length, find an `alpha` satisfying the strong Wolfe conditions.
+
+See the one-dimensional method for additional details.
+"""
 function (ls::StrongWolfe)(df, x::AbstractArray{T},
                            p::AbstractArray{T}, α::Real, x_new::AbstractArray{T},
                            ϕ_0, dϕ_0) where T
     ϕ, dϕ, ϕdϕ = make_ϕ_dϕ_ϕdϕ(df, x_new, x, p)
     ls(ϕ, dϕ, ϕdϕ, α, ϕ_0, dϕ_0)
 end
+
+"""
+    (ls::StrongWolfe)(ϕ, dϕ, ϕdϕ, alpha0, ϕ_0, dϕ_0) -> alpha, ϕalpha
+
+Given `ϕ(alpha::Real)`, its derivative `dϕ`, a combined-evaluation function
+`ϕdϕ(alpha) -> (ϕ(alpha), dϕ(alpha))`, and an initial guess `alpha0`,
+identify a value of `alpha > 0` satisfying the strong Wolfe conditions.
+
+`ϕ_0` and `dϕ_0` are the value and derivative, respectively, of `ϕ` at `alpha = 0.`
+
+Both `alpha` and `ϕ(alpha)` are returned.
+"""
 function (ls::StrongWolfe)(ϕ, dϕ, ϕdϕ,
-                           alpha0::T, ϕ_0, dϕ_0) where T
+                           alpha0::T, ϕ_0, dϕ_0) where T<:Real
     @unpack c_1, c_2, ρ = ls
 
     zeroT = convert(T, 0)