adding basic docstrings for solvers

Author: tlienart

src/fit/solvers.jl

@@ -16,25 +16,69 @@ abstract type Solver end
 
 # ===================== analytical.jl
 
+"""
+$SIGNATURES
+
+Analytical solver (Cholesky). If the `iterative` parameter is set to `true`
+then a CG solver is used. The CG solver is matrix-free and should be preferred
+in "large scale" cases (when the hat matrix `X'X` is "big").
+
+## Parameters
+
+* `iterative` (Bool): whether to use CG (iterative) or not
+* `max_inner` (Int): in the iterative mode, how many inner iterations to do.
+"""
 @with_kw struct Analytical <: Solver
     iterative::Bool = false
     max_inner::Int  = 200
 end
-
 CG() = Analytical(; iterative=true)
 
 # ===================== newton.jl
 
+"""
+$SIGNATURES
+
+Newton solver. This is a full Hessian solver and should be avoided for
+"large scale" cases.
+"""
 struct Newton <: Solver end
 
+"""
+$SIGNATURES
+
+Newton CG solver. This is the same as the Newton solver except that instead
+of solving systems of the form `H\\b` where `H` is the full Hessian, it uses
+a matrix-free conjugate gradient approach to solving that system. This should
+generally be preferred for larger scale cases.
+"""
 struct NewtonCG <: Solver end
 
+"""
+$SIGNATURES
+
+LBFGS quasi-Newton solver. See [the wikipedia entry](https://en.wikipedia.org/wiki/Limited-memory_BFGS).
+"""
 struct LBFGS <: Solver end
 
 # struct BFGS <: Solver end
 
 # ===================== pgrad.jl
 
+"""
+$SIGNATURES
+
+Proximal Gradient solver for non-smooth objective functions.
+
+## Parameters
+
+* `accel` (Bool): whether to use Nesterov-style acceleration
+* `max_iter` (Int): number of overall iterations
+* `tol` (Float64): tolerance for the relative change θ ie `norm(θ-θ_)/norm(θ)`
+* `max_inner`: number of inner steps when searching for a stepsize in the
+               backtracking step
+* `beta`: rate of shrinkage in the backtracking step (between 0 and 1)
+"""
 @with_kw struct ProxGrad <: Solver
     accel::Bool    = false # use Nesterov style acceleration (see also FISTA)
     max_iter::Int  = 1000  # max number of overall iterations
@@ -48,6 +92,21 @@ ISTA(; kwa...)  = ProxGrad(;accel = false, kwa...)
 
 # ===================== iwls.jl
 
+"""
+$SIGNATURES
+
+Iteratively Reweighted Least Square with Conjugate Gradient. This is the
+standard (expensive) IWLS but with more efficient solves to avoid full matrix
+computations.
+
+## Parameters
+
+* `max_iter` (Int): number of max iterations (outer)
+* `max_inner` (Int): number of iterations for the CG solves
+* `tol` (Float64): tolerance for the relative change θ ie `norm(θ-θ_)/norm(θ)`
+* `damping` (Float64): how much to trust iterates (1=full trust)
+* `threshold` (Float64): threshold for the residuals
+"""
 @with_kw struct IWLSCG <: Solver
     max_iter::Int      = 100
     max_inner::Int     = 200

src/mlj/regressors.jl

@@ -2,6 +2,19 @@
    LINEAR REGRESSOR (OLS)
    ====================== =#
 
+"""
+$SIGNATURES
+
+Standard linear regression model.
+
+## Parameters
+
+* `fit_intercept` (Bool): whether to fit the intercept or not.
+* `solver`: type of solver to use (if `nothing` the default is used). The
+            solver is Cholesky by default but can be Conjugate-Gradient as
+            well. See `?Analytical` for more information.
+
+"""
 @with_kw_noshow mutable struct LinearRegressor <: MMI.Deterministic
     fit_intercept::Bool    = true
     solver::Option{Solver} = nothing