Improve various docstrings by converting to jldoctest (#2579)

Author: odow

src/Benchmarks/Benchmarks.jl

@@ -22,15 +22,16 @@ arguments, and returns a new instance of the optimizer you wish to benchmark.
 
 Use `exclude` to exclude a subset of benchmarks.
 
-### Examples
+## Example
 
 ```julia
-suite() do
-    GLPK.Optimizer()
-end
-suite(exclude = [r"delete"]) do
-    Gurobi.Optimizer(OutputFlag=0)
-end
+julia> MOI.Benchmarks.suite() do
+           return GLPK.Optimizer()
+       end
+
+julia> MOI.Benchmarks.suite(; exclude = [r"delete"]) do
+           return Gurobi.Optimizer()
+       end
 ```
 """
 function suite(new_model::Function; exclude::Vector{Regex} = Regex[])
@@ -49,11 +50,21 @@ Run all benchmarks in `suite` and save to files called `name` in `directory`.
 
 Extra `kwargs` are based to `BenchmarkTools.run`.
 
-### Examples
+## Example
 
 ```julia
-my_suite = suite(() -> GLPK.Optimizer())
-create_baseline(my_suite, "glpk_master"; directory = "/tmp", verbose = true)
+julia> import MathOptInterface as MOI
+
+julia> import GLPK
+
+julia> my_suite = MOI.Benchmarks.suite(() -> GLPK.Optimizer());
+
+julia> MOI.Benchmarks.create_baseline(
+           my_suite,
+           "glpk_master";
+           directory = "/tmp",
+           verbose = true,
+       )
 ```
 """
 function create_baseline(
@@ -86,13 +97,21 @@ A report summarizing the comparison is written to `report_filename` in
 
 Extra `kwargs` are based to `BenchmarkTools.run`.
 
-### Examples
+## Example
 
 ```julia
-my_suite = suite(() -> GLPK.Optimizer())
-compare_against_baseline(
-    my_suite, "glpk_master"; directory = "/tmp", verbose = true
-)
+julia> import MathOptInterface as MOI
+
+julia> import GLPK
+
+julia> my_suite = MOI.Benchmarks.suite(() -> GLPK.Optimizer());
+
+julia> MOI.Benchmarks.compare_against_baseline(
+           my_suite,
+           "glpk_master";
+           directory = "/tmp",
+           verbose = true,
+       )
 ```
 """
 function compare_against_baseline(

src/Bridges/Bridges.jl

@@ -90,7 +90,7 @@ are not added. Therefore, you are recommended to use
 `model = MOI.instantiate(Package.Optimizer)`. See
 [`MOI.instantiate`](@ref).
 
-## Examples
+## Example
 
 ### An optimizer using a non-default bridge in `MOI.Bridges`
 

src/Bridges/Variable/bridge.jl

@@ -71,13 +71,15 @@ Return the concrete type of the bridge supporting variables in `S` constraints.
 This function can only be called if `MOI.supports_constrained_variable(BT, S)`
 is `true`.
 
-## Examples
+## Example
 
 As a variable in [`MOI.GreaterThan`](@ref) is bridged into
 variables in [`MOI.Nonnegatives`](@ref) by the
 [`VectorizeBridge`](@ref):
 
-```jldoctest; setup=:(import MathOptInterface as MOI)
+```jldoctest
+julia> import MathOptInterface as MOI
+
 julia> MOI.Bridges.Variable.concrete_bridge_type(
            MOI.Bridges.Variable.VectorizeBridge{Float64},
            MOI.GreaterThan{Float64},

src/Nonlinear/evaluator.jl

@@ -13,20 +13,46 @@ end
 
 Return the 1-indexed value of the constraint index `c` in `evaluator`.
 
-## Examples
-
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-c1 = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
-c2 = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
-evaluator = Evaluator(model)
-MOI.initialize(evaluator, Symbol[])
-ordinal_index(evaluator, c2)  # Returns 2
-delete(model, c1)
-evaluator = Evaluator(model)
-MOI.initialize(evaluator, Symbol[])
-ordinal_index(model, c2)  # Returns 1
+## Example
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model()
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 0 constraints
+
+julia> x = MOI.VariableIndex(1)
+MOI.VariableIndex(1)
+
+julia> c1 = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
+MathOptInterface.Nonlinear.ConstraintIndex(1)
+
+julia> c2 = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
+MathOptInterface.Nonlinear.ConstraintIndex(2)
+
+julia> evaluator = MOI.Nonlinear.Evaluator(model)
+Nonlinear.Evaluator with available features:
+  * :ExprGraph
+
+julia> MOI.initialize(evaluator, Symbol[])
+
+julia> MOI.Nonlinear.ordinal_index(evaluator, c2)  # Returns 2
+2
+
+julia> MOI.Nonlinear.delete(model, c1)
+
+julia> evaluator = MOI.Nonlinear.Evaluator(model)
+Nonlinear.Evaluator with available features:
+  * :ExprGraph
+
+julia> MOI.initialize(evaluator, Symbol[])
+
+julia> MOI.Nonlinear.ordinal_index(evaluator, c2)  # Returns 1
+1
 ```
 """
 function ordinal_index(evaluator::Evaluator, c::ConstraintIndex)

src/Nonlinear/model.jl

@@ -49,14 +49,26 @@ function of `model`.
 
 To remove the objective, pass `nothing`.
 
-## Examples
-
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-set_objective(model, :(\$x^2 + 1))
-set_objective(model, x)
-set_objective(model, nothing)
+## Example
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model()
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 0 constraints
+
+julia> x = MOI.VariableIndex(1)
+MOI.VariableIndex(1)
+
+julia> MOI.Nonlinear.set_objective(model, :(\$x^2 + 1))
+
+julia> MOI.Nonlinear.set_objective(model, x)
+
+julia> MOI.Nonlinear.set_objective(model, nothing)
 ```
 """
 function set_objective(model::Model, obj)
@@ -77,13 +89,19 @@ Parse `expr` into a [`Expression`](@ref) and add to `model`. Returns an
 
 `expr` must be a type that is supported by [`parse_expression`](@ref).
 
-## Examples
+## Example
 
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-ex = add_expression(model, :(\$x^2 + 1))
-set_objective(model, :(sqrt(\$ex)))
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model();
+
+julia> x = MOI.VariableIndex(1);
+
+julia> ex = MOI.Nonlinear.add_expression(model, :(\$x^2 + 1))
+MathOptInterface.Nonlinear.ExpressionIndex(1)
+
+julia> MOI.Nonlinear.set_objective(model, :(sqrt(\$ex)))
 ```
 """
 function add_expression(model::Model, expr)
@@ -111,12 +129,17 @@ Parse `func` and `set` into a [`Constraint`](@ref) and add to `model`. Returns a
 [`ConstraintIndex`](@ref) that can be used to delete the constraint or query
 solution information.
 
-## Examples
+## Example
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model();
 
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-c = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
+julia> x = MOI.VariableIndex(1);
+
+julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
+MathOptInterface.Nonlinear.ConstraintIndex(1)
 ```
 """
 function add_constraint(
@@ -141,13 +164,39 @@ end
 
 Delete the constraint index `c` from `model`.
 
-## Examples
+## Example
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model()
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 0 constraints
+
+julia> x = MOI.VariableIndex(1)
+MOI.VariableIndex(1)
+
+julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
+MathOptInterface.Nonlinear.ConstraintIndex(1)
+
+julia> model
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 1 constraint
 
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-c = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
-delete(model, c)
+julia> MOI.Nonlinear.delete(model, c)
+
+julia> model
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 0 constraints
 ```
 """
 function delete(model::Model, c::ConstraintIndex)
@@ -170,13 +219,26 @@ Add a new parameter to `model` with the default value `value`. Returns a
 [`ParameterIndex`](@ref) that can be interpolated into other input expressions
 and used to modify the value of the parameter.
 
-## Examples
+## Example
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> model = MOI.Nonlinear.Model()
+A Nonlinear.Model with:
+ 0 objectives
+ 0 parameters
+ 0 expressions
+ 0 constraints
+
+julia> x = MOI.VariableIndex(1)
+MOI.VariableIndex(1)
+
+julia> p = MOI.Nonlinear.add_parameter(model, 1.2)
+MathOptInterface.Nonlinear.ParameterIndex(1)
 
-```julia
-model = Model()
-x = MOI.VariableIndex(1)
-p = add_parameter(model, 1.2)
-c = add_constraint(model, :(\$x^2 - \$p), MOI.LessThan(0.0))
+julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2 - \$p), MOI.LessThan(0.0))
+MathOptInterface.Nonlinear.ConstraintIndex(1)
 ```
 """
 function add_parameter(model::Model, value::Float64)

src/Test/Test.jl

@@ -77,21 +77,24 @@ Return an object that is used to configure various tests.
      - `MOI.VariableName` to skip setting variable names
      - `MOI.ConstraintName` to skip setting constraint names
 
-## Examples
+## Example
 
 For a nonlinear solver that finds local optima and does not support finding
 dual variables or constraint names:
-```julia
-Config(
-    Float64;
-    optimal_status = MOI.LOCALLY_SOLVED,
-    exclude = Any[
-        MOI.ConstraintDual,
-        MOI.VariableName,
-        MOI.ConstraintName,
-        MOI.delete,
-    ],
-)
+
+```jldoctest
+julia> import MathOptInterface as MOI
+
+julia> config = MOI.Test.Config(
+           Float64;
+           optimal_status = MOI.LOCALLY_SOLVED,
+           exclude = Any[
+               MOI.ConstraintDual,
+               MOI.VariableName,
+               MOI.ConstraintName,
+               MOI.delete,
+           ],
+       );
 ```
 """
 function Config(
@@ -306,7 +309,7 @@ Check that the condition `x` is `true`. Otherwise, throw an [`RequirementUnmet`]
 error to indicate that the model does not support something required by the test
 function.
 
-## Examples
+## Example
 
 ```julia
 @requires MOI.supports(model, MOI.Silent())