[docs] improvements to the docstrings (#156)

docs/src/api.md

@@ -33,7 +33,7 @@ add_predictor
 
 ## `build_predictor`
 ```@docs
-build_predictor
+build_predictor(predictor::AbstractPredictor; kwargs...)
 ```
 
 ## `Affine`

src/MathOptAI.jl

@@ -20,6 +20,7 @@ An abstract type representing different types of prediction models.
 All subtypes must implement:
 
  * [`add_predictor`](@ref)
+ * [`build_predictor`](@ref)
 """
 abstract type AbstractPredictor end
 

src/predictors/Affine.jl

@@ -10,9 +10,9 @@
         b::Vector{T} = zeros(T, size(A, 1)),
     ) where {T} <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that represents the affine relationship:
+An [`AbstractPredictor`](@ref) that represents the relationship:
 ```math
-f(x) = A x + b
+y = A x + b
 ```
 
 ## Example

src/predictors/GrayBox.jl

@@ -11,8 +11,11 @@
         has_hessian::Bool = false,
     ) <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that represents the function ``f(x)`` as a
-user-defined nonlinear operator.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = f(x)
+```
+as a user-defined nonlinear operator.
 
 ## Arguments
 
@@ -56,7 +59,8 @@ GrayBox
   ├ op_##330(x[1], x[2]) - moai_GrayBox[1] = 0
   └ op_##331(x[1], x[2]) - moai_GrayBox[2] = 0
 
-julia> y, formulation = MathOptAI.add_predictor(model, MathOptAI.ReducedSpace(f), x);
+julia> y, formulation =
+           MathOptAI.add_predictor(model, MathOptAI.ReducedSpace(f), x);
 
 julia> y
 2-element Vector{NonlinearExpr}:

src/predictors/Pipeline.jl

@@ -7,11 +7,11 @@
 """
     Pipeline(layers::Vector{AbstractPredictor}) <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that represents a pipeline (composition) of
-nested layers:
+An [`AbstractPredictor`](@ref) that represents the relationship:
 ```math
-f(x) = (l_1 \\cdots (l_N(x))
+y = (l_1 \\circ \\ldots \\circ l_N)(x)
 ```
+where \$l_i\$ are a list of other [`AbstractPredictor`](@ref)s.
 
 ## Example
 

src/predictors/Quantile.jl

@@ -5,7 +5,7 @@
 # in the LICENSE.md file.
 
 """
-    Quantile(distribution, quantiles::Vector{Float64})
+    Quantile{D}(distribution::D, quantiles::Vector{Float64}) where {D}
 
 An [`AbstractPredictor`](@ref) that represents the `quantiles` of `distribution`.
 
@@ -29,6 +29,15 @@ julia> y
 2-element Vector{VariableRef}:
  moai_quantile[1]
  moai_quantile[2]
+
+julia> formulation
+Quantile(_, [0.1, 0.9])
+├ variables [2]
+│ ├ moai_quantile[1]
+│ └ moai_quantile[2]
+└ constraints [2]
+  ├ moai_quantile[1] - op_quantile_0.1(x) = 0
+  └ moai_quantile[2] - op_quantile_0.9(x) = 0
 ```
 """
 struct Quantile{D} <: AbstractPredictor

src/predictors/ReLU.jl

@@ -7,8 +7,11 @@
 """
     ReLU() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the ReLU constraint
-\$y = \\max\\{0, x\\}\$ as a non-smooth nonlinear constraint.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\max\\{0, x\\}
+```
+as a non-smooth nonlinear constraint.
 
 ## Example
 
@@ -76,8 +79,20 @@ end
 """
     ReLUBigM(M::Float64) <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the ReLU constraint
-\$y = \\max\\{0, x\\}\$ via a big-M MIP reformulation.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\max\\{0, x\\}
+```
+via the big-M MIP reformulation:
+```math
+\\begin{aligned}
+y \\ge 0            \\\\
+y \\ge x            \\\\
+y \\le M z          \\\\
+y \\le x + M(1 - z) \\\\
+z \\in\\{0, 1\\}
+\\end{aligned}
+```
 
 ## Example
 
@@ -154,12 +169,15 @@ end
 """
     ReLUSOS1() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the ReLU constraint
-\$y = \\max\\{0, x\\}\$ by the reformulation:
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\max\\{0, x\\}
+```
+by the reformulation:
 ```math
 \\begin{aligned}
-x = y - z \\\\
-[y, z] \\in SOS1 \\\\
+x = y - z           \\\\
+[y, z] \\in SOS1    \\\\
 y, z \\ge 0
 \\end{aligned}
 ```
@@ -228,12 +246,15 @@ end
 """
     ReLUQuadratic() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the ReLU constraint
-\$y = \\max\\{0, x\\}\$ by the reformulation:
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\max\\{0, x\\}
+```
+by the reformulation:
 ```math
 \\begin{aligned}
 x = y - z \\\\
-y \\times z = 0 \\\\
+y \\cdot z = 0 \\\\
 y, z \\ge 0
 \\end{aligned}
 ```

src/predictors/Scale.jl

@@ -10,9 +10,9 @@
         bias::Vector{T},
     ) where {T} <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that represents the affine relationship:
+An [`AbstractPredictor`](@ref) that represents the relationship:
 ```math
-f(x) = Diag(scale)x + bias
+y = Diag(scale)x + bias
 ```
 
 ## Example

src/predictors/Sigmoid.jl

@@ -7,8 +7,11 @@
 """
     Sigmoid() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the Sigmoid constraint
-\$y = \\frac{1}{1 + e^{-x}}\$ as a smooth nonlinear constraint.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\frac{1}{1 + e^{-x}}
+```
+as a smooth nonlinear constraint.
 
 ## Example
 

src/predictors/SoftMax.jl

@@ -7,8 +7,11 @@
 """
     SoftMax() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the SoftMax constraint
-\$y_i = \\frac{e^{x_i}}{\\sum_j e^{x_j}}\$ as a smooth nonlinear constraint.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\frac{e^{x}}{||e^{x}||_1}
+```
+as a smooth nonlinear constraint.
 
 ## Example
 

src/predictors/SoftPlus.jl

@@ -7,8 +7,11 @@
 """
     SoftPlus(; beta = 1.0) <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the SoftPlus constraint
-\$y = \\frac{1}{\\beta} \\log(1 + e^{\\beta x})\$ as a smooth nonlinear constraint.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\frac{1}{\\beta} \\log(1 + e^{\\beta x})
+```
+as a smooth nonlinear constraint.
 
 ## Example
 

src/predictors/Tanh.jl

@@ -7,8 +7,11 @@
 """
     Tanh() <: AbstractPredictor
 
-An [`AbstractPredictor`](@ref) that implements the Tanh constraint
-\$y = \\tanh(x)\$ as a smooth nonlinear constraint.
+An [`AbstractPredictor`](@ref) that represents the relationship:
+```math
+y = \\tanh(x)
+```
+as a smooth nonlinear constraint.
 
 ## Example