SemOptimizer: reattach docstrings to ctor

Instead of engine-specific subtype as it might be not available
in the user session.

Author: Alexey Stukalov

ext/SEMNLOptExt/NLopt.jl

@@ -4,6 +4,19 @@
 
 const NLoptConstraint = Pair{Any, Number}
 
+struct SemOptimizerNLopt <: SemOptimizer{:NLopt}
+    algorithm::Symbol
+    local_algorithm::Union{Symbol, Nothing}
+    options::Dict{Symbol, Any}
+    local_options::Dict{Symbol, Any}
+    equality_constraints::Vector{NLoptConstraint}
+    inequality_constraints::Vector{NLoptConstraint}
+end
+
+############################################################################################
+### Constructor
+############################################################################################
+
 """
 Connects to `NLopt.jl` as the optimization backend.
 Only usable if `NLopt.jl` is loaded in the current Julia session!
@@ -74,19 +87,6 @@ see [Constrained optimization](@ref) in our online documentation.
 
 Subtype of `SemOptimizer`.
 """
-struct SemOptimizerNLopt <: SemOptimizer{:NLopt}
-    algorithm::Symbol
-    local_algorithm::Union{Symbol, Nothing}
-    options::Dict{Symbol, Any}
-    local_options::Dict{Symbol, Any}
-    equality_constraints::Vector{NLoptConstraint}
-    inequality_constraints::Vector{NLoptConstraint}
-end
-
-############################################################################################
-### Constructor
-############################################################################################
-
 function SemOptimizerNLopt(;
     algorithm = :LD_LBFGS,
     local_algorithm = nothing,
@@ -115,6 +115,15 @@ function SemOptimizerNLopt(;
     )
 end
 
+"""
+    SemOptimizer(args...; engine = :NLopt, kwargs...)
+
+Creates SEM optimizer using [*NLopt.jl*](https://github.com/JuliaOpt/NLopt.jl).
+
+# Extended help
+
+See [`SemOptimizerNLopt`](@ref) for a full reference.
+"""
 SEM.SemOptimizer(::Val{:NLopt}, args...; kwargs...) = SemOptimizerNLopt(args...; kwargs...)
 
 ############################################################################################

src/optimizer/Empty.jl

@@ -1,20 +1,19 @@
 ############################################################################################
 ### Types
 ############################################################################################
-"""
-Empty placeholder for models that don't need
-an optimizer part.
-
-# Constructor
 
-    SemOptimizerEmpty()
-"""
+# dummy SEM optimizer
 struct SemOptimizerEmpty <: SemOptimizer{:Empty} end
 
 ############################################################################################
 ### Constructor
 ############################################################################################
 
+"""
+    SemOptimizer(engine = :Empty)
+
+Constructs a dummy optimizer for models that don't need it.
+"""
 SemOptimizer(::Val{:Empty}) = SemOptimizerEmpty()
 
 ############################################################################################

src/optimizer/abstract.jl

@@ -1,6 +1,24 @@
 engine(::Type{<:SemOptimizer{E}}) where {E} = E
 engine(optimizer::SemOptimizer) = engine(typeof(optimizer))
 
+"""
+    SemOptimizer(args...; engine::Symbol = :Optim, kwargs...)
+
+Constructs [`SemOptimizer`](@ref) for the specified optimization `engine`.
+
+A wrapper function that passes `args...` and `kwargs...` to the
+engine-specific optimizer constructor.
+
+Uses `:Optim` as the default engine.
+Throws an error if the specified `engine` is not supported.
+Call [`optimizer_engines`](@ref) for the list of supported engines.
+
+For the information about using the engine `:EngineName`, use
+```julia
+?SemOptimizer(Val(:EngineName))
+```
+
+"""
 SemOptimizer(args...; engine::Symbol = :Optim, kwargs...) =
     SemOptimizer{engine}(args...; kwargs...)
 

src/optimizer/optim.jl

@@ -3,25 +3,29 @@
 ############################################################################################
 ### Types and Constructor
 ############################################################################################
-"""
-    SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
-
-Connects to `Optim.jl` as the optimization backend.
 
-# Constructor
+# SemOptimizer for the Optim.jl
+mutable struct SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
+    algorithm::A
+    options::B
+end
 
-    SemOptimizerOptim(;
+"""
+    SemOptimizer(;
+        engine = :Optim,
         algorithm = LBFGS(),
         options = Optim.Options(;f_reltol = 1e-10, x_abstol = 1.5e-8),
         kwargs...)
 
+Creates SEM optimizer using [*Optim.jl*](https://julianlsolvers.github.io/Optim.jl/stable/).
+
 # Arguments
-- `algorithm`: optimization algorithm from `Optim.jl`
+- `algorithm`: optimization algorithm from *Optim.jl*
 - `options::Optim.Options`: options for the optimization algorithm
 
 # Usage
-All algorithms and options from the Optim.jl library are available, for more information see
-the Optim.jl online documentation.
+All algorithms and options from the *Optim.jl* package are available, for more information see
+the *Optim.jl* online documentation.
 
 # Examples
 ```julia
@@ -53,22 +57,20 @@ for the variance parameters (the diagonal of the *S* matrix).
 ## Interfaces
 - `algorithm(::SemOptimizerOptim)`
 - `options(::SemOptimizerOptim)`
-
-## Implementation
-
-Subtype of `SemOptimizer`.
 """
-mutable struct SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
-    algorithm::A
-    options::B
-end
-
 SemOptimizerOptim(;
     algorithm = LBFGS(),
     options = Optim.Options(; f_reltol = 1e-10, x_abstol = 1.5e-8),
     kwargs...,
 ) = SemOptimizerOptim(algorithm, options)
 
+"""
+    SemOptimizer(args...; engine = :Optim, kwargs...)
+
+Creates SEM optimizer using [*Optim.jl*](https://julianlsolvers.github.io/Optim.jl/stable/).
+
+See [`SemOptimizerOptim`](@ref) for the full reference.
+"""
 SemOptimizer(::Val{:Optim}, args...; kwargs...) = SemOptimizerOptim(args...; kwargs...)
 
 ############################################################################################