Skip to content

Commit d066d0d

Browse files
odowodow
authored
Improve various docstrings by converting to jldoctest (#2579)
1 parent 6a8fc30 commit d066d0d

File tree

17 files changed

+459
-194
lines changed

17 files changed

+459
-194
lines changed

‎src/Benchmarks/Benchmarks.jl

Lines changed: 34 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,16 @@ arguments, and returns a new instance of the optimizer you wish to benchmark.
2222
2323
Use `exclude` to exclude a subset of benchmarks.
2424
25-
### Examples
25+
## Example
2626
2727
```julia
28-
suite() do
29-
GLPK.Optimizer()
30-
end
31-
suite(exclude = [r"delete"]) do
32-
Gurobi.Optimizer(OutputFlag=0)
33-
end
28+
julia> MOI.Benchmarks.suite() do
29+
return GLPK.Optimizer()
30+
end
31+
32+
julia> MOI.Benchmarks.suite(; exclude = [r"delete"]) do
33+
return Gurobi.Optimizer()
34+
end
3435
```
3536
"""
3637
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`.
4950
5051
Extra `kwargs` are based to `BenchmarkTools.run`.
5152
52-
### Examples
53+
## Example
5354
5455
```julia
55-
my_suite = suite(() -> GLPK.Optimizer())
56-
create_baseline(my_suite, "glpk_master"; directory = "/tmp", verbose = true)
56+
julia> import MathOptInterface as MOI
57+
58+
julia> import GLPK
59+
60+
julia> my_suite = MOI.Benchmarks.suite(() -> GLPK.Optimizer());
61+
62+
julia> MOI.Benchmarks.create_baseline(
63+
my_suite,
64+
"glpk_master";
65+
directory = "/tmp",
66+
verbose = true,
67+
)
5768
```
5869
"""
5970
function create_baseline(
@@ -86,13 +97,21 @@ A report summarizing the comparison is written to `report_filename` in
8697
8798
Extra `kwargs` are based to `BenchmarkTools.run`.
8899
89-
### Examples
100+
## Example
90101
91102
```julia
92-
my_suite = suite(() -> GLPK.Optimizer())
93-
compare_against_baseline(
94-
my_suite, "glpk_master"; directory = "/tmp", verbose = true
95-
)
103+
julia> import MathOptInterface as MOI
104+
105+
julia> import GLPK
106+
107+
julia> my_suite = MOI.Benchmarks.suite(() -> GLPK.Optimizer());
108+
109+
julia> MOI.Benchmarks.compare_against_baseline(
110+
my_suite,
111+
"glpk_master";
112+
directory = "/tmp",
113+
verbose = true,
114+
)
96115
```
97116
"""
98117
function compare_against_baseline(

‎src/Bridges/Bridges.jl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ are not added. Therefore, you are recommended to use
9090
`model = MOI.instantiate(Package.Optimizer)`. See
9191
[`MOI.instantiate`](@ref).
9292
93-
## Examples
93+
## Example
9494
9595
### An optimizer using a non-default bridge in `MOI.Bridges`
9696

‎src/Bridges/Variable/bridge.jl

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,13 +71,15 @@ Return the concrete type of the bridge supporting variables in `S` constraints.
7171
This function can only be called if `MOI.supports_constrained_variable(BT, S)`
7272
is `true`.
7373
74-
## Examples
74+
## Example
7575
7676
As a variable in [`MOI.GreaterThan`](@ref) is bridged into
7777
variables in [`MOI.Nonnegatives`](@ref) by the
7878
[`VectorizeBridge`](@ref):
7979
80-
```jldoctest; setup=:(import MathOptInterface as MOI)
80+
```jldoctest
81+
julia> import MathOptInterface as MOI
82+
8183
julia> MOI.Bridges.Variable.concrete_bridge_type(
8284
MOI.Bridges.Variable.VectorizeBridge{Float64},
8385
MOI.GreaterThan{Float64},

‎src/Nonlinear/evaluator.jl

Lines changed: 40 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,46 @@ end
1313
1414
Return the 1-indexed value of the constraint index `c` in `evaluator`.
1515
16-
## Examples
17-
18-
```julia
19-
model = Model()
20-
x = MOI.VariableIndex(1)
21-
c1 = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
22-
c2 = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
23-
evaluator = Evaluator(model)
24-
MOI.initialize(evaluator, Symbol[])
25-
ordinal_index(evaluator, c2) # Returns 2
26-
delete(model, c1)
27-
evaluator = Evaluator(model)
28-
MOI.initialize(evaluator, Symbol[])
29-
ordinal_index(model, c2) # Returns 1
16+
## Example
17+
18+
```jldoctest
19+
julia> import MathOptInterface as MOI
20+
21+
julia> model = MOI.Nonlinear.Model()
22+
A Nonlinear.Model with:
23+
0 objectives
24+
0 parameters
25+
0 expressions
26+
0 constraints
27+
28+
julia> x = MOI.VariableIndex(1)
29+
MOI.VariableIndex(1)
30+
31+
julia> c1 = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
32+
MathOptInterface.Nonlinear.ConstraintIndex(1)
33+
34+
julia> c2 = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
35+
MathOptInterface.Nonlinear.ConstraintIndex(2)
36+
37+
julia> evaluator = MOI.Nonlinear.Evaluator(model)
38+
Nonlinear.Evaluator with available features:
39+
* :ExprGraph
40+
41+
julia> MOI.initialize(evaluator, Symbol[])
42+
43+
julia> MOI.Nonlinear.ordinal_index(evaluator, c2) # Returns 2
44+
2
45+
46+
julia> MOI.Nonlinear.delete(model, c1)
47+
48+
julia> evaluator = MOI.Nonlinear.Evaluator(model)
49+
Nonlinear.Evaluator with available features:
50+
* :ExprGraph
51+
52+
julia> MOI.initialize(evaluator, Symbol[])
53+
54+
julia> MOI.Nonlinear.ordinal_index(evaluator, c2) # Returns 1
55+
1
3056
```
3157
"""
3258
function ordinal_index(evaluator::Evaluator, c::ConstraintIndex)

‎src/Nonlinear/model.jl

Lines changed: 93 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,26 @@ function of `model`.
4949
5050
To remove the objective, pass `nothing`.
5151
52-
## Examples
53-
54-
```julia
55-
model = Model()
56-
x = MOI.VariableIndex(1)
57-
set_objective(model, :(\$x^2 + 1))
58-
set_objective(model, x)
59-
set_objective(model, nothing)
52+
## Example
53+
54+
```jldoctest
55+
julia> import MathOptInterface as MOI
56+
57+
julia> model = MOI.Nonlinear.Model()
58+
A Nonlinear.Model with:
59+
0 objectives
60+
0 parameters
61+
0 expressions
62+
0 constraints
63+
64+
julia> x = MOI.VariableIndex(1)
65+
MOI.VariableIndex(1)
66+
67+
julia> MOI.Nonlinear.set_objective(model, :(\$x^2 + 1))
68+
69+
julia> MOI.Nonlinear.set_objective(model, x)
70+
71+
julia> MOI.Nonlinear.set_objective(model, nothing)
6072
```
6173
"""
6274
function set_objective(model::Model, obj)
@@ -77,13 +89,19 @@ Parse `expr` into a [`Expression`](@ref) and add to `model`. Returns an
7789
7890
`expr` must be a type that is supported by [`parse_expression`](@ref).
7991
80-
## Examples
92+
## Example
8193
82-
```julia
83-
model = Model()
84-
x = MOI.VariableIndex(1)
85-
ex = add_expression(model, :(\$x^2 + 1))
86-
set_objective(model, :(sqrt(\$ex)))
94+
```jldoctest
95+
julia> import MathOptInterface as MOI
96+
97+
julia> model = MOI.Nonlinear.Model();
98+
99+
julia> x = MOI.VariableIndex(1);
100+
101+
julia> ex = MOI.Nonlinear.add_expression(model, :(\$x^2 + 1))
102+
MathOptInterface.Nonlinear.ExpressionIndex(1)
103+
104+
julia> MOI.Nonlinear.set_objective(model, :(sqrt(\$ex)))
87105
```
88106
"""
89107
function add_expression(model::Model, expr)
@@ -111,12 +129,17 @@ Parse `func` and `set` into a [`Constraint`](@ref) and add to `model`. Returns a
111129
[`ConstraintIndex`](@ref) that can be used to delete the constraint or query
112130
solution information.
113131
114-
## Examples
132+
## Example
133+
134+
```jldoctest
135+
julia> import MathOptInterface as MOI
136+
137+
julia> model = MOI.Nonlinear.Model();
115138
116-
```julia
117-
model = Model()
118-
x = MOI.VariableIndex(1)
119-
c = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
139+
julia> x = MOI.VariableIndex(1);
140+
141+
julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
142+
MathOptInterface.Nonlinear.ConstraintIndex(1)
120143
```
121144
"""
122145
function add_constraint(
@@ -141,13 +164,39 @@ end
141164
142165
Delete the constraint index `c` from `model`.
143166
144-
## Examples
167+
## Example
168+
169+
```jldoctest
170+
julia> import MathOptInterface as MOI
171+
172+
julia> model = MOI.Nonlinear.Model()
173+
A Nonlinear.Model with:
174+
0 objectives
175+
0 parameters
176+
0 expressions
177+
0 constraints
178+
179+
julia> x = MOI.VariableIndex(1)
180+
MOI.VariableIndex(1)
181+
182+
julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
183+
MathOptInterface.Nonlinear.ConstraintIndex(1)
184+
185+
julia> model
186+
A Nonlinear.Model with:
187+
0 objectives
188+
0 parameters
189+
0 expressions
190+
1 constraint
145191
146-
```julia
147-
model = Model()
148-
x = MOI.VariableIndex(1)
149-
c = add_constraint(model, :(\$x^2), MOI.LessThan(1.0))
150-
delete(model, c)
192+
julia> MOI.Nonlinear.delete(model, c)
193+
194+
julia> model
195+
A Nonlinear.Model with:
196+
0 objectives
197+
0 parameters
198+
0 expressions
199+
0 constraints
151200
```
152201
"""
153202
function delete(model::Model, c::ConstraintIndex)
@@ -170,13 +219,26 @@ Add a new parameter to `model` with the default value `value`. Returns a
170219
[`ParameterIndex`](@ref) that can be interpolated into other input expressions
171220
and used to modify the value of the parameter.
172221
173-
## Examples
222+
## Example
223+
224+
```jldoctest
225+
julia> import MathOptInterface as MOI
226+
227+
julia> model = MOI.Nonlinear.Model()
228+
A Nonlinear.Model with:
229+
0 objectives
230+
0 parameters
231+
0 expressions
232+
0 constraints
233+
234+
julia> x = MOI.VariableIndex(1)
235+
MOI.VariableIndex(1)
236+
237+
julia> p = MOI.Nonlinear.add_parameter(model, 1.2)
238+
MathOptInterface.Nonlinear.ParameterIndex(1)
174239
175-
```julia
176-
model = Model()
177-
x = MOI.VariableIndex(1)
178-
p = add_parameter(model, 1.2)
179-
c = add_constraint(model, :(\$x^2 - \$p), MOI.LessThan(0.0))
240+
julia> c = MOI.Nonlinear.add_constraint(model, :(\$x^2 - \$p), MOI.LessThan(0.0))
241+
MathOptInterface.Nonlinear.ConstraintIndex(1)
180242
```
181243
"""
182244
function add_parameter(model::Model, value::Float64)

‎src/Test/Test.jl

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -77,21 +77,24 @@ Return an object that is used to configure various tests.
7777
- `MOI.VariableName` to skip setting variable names
7878
- `MOI.ConstraintName` to skip setting constraint names
7979
80-
## Examples
80+
## Example
8181
8282
For a nonlinear solver that finds local optima and does not support finding
8383
dual variables or constraint names:
84-
```julia
85-
Config(
86-
Float64;
87-
optimal_status = MOI.LOCALLY_SOLVED,
88-
exclude = Any[
89-
MOI.ConstraintDual,
90-
MOI.VariableName,
91-
MOI.ConstraintName,
92-
MOI.delete,
93-
],
94-
)
84+
85+
```jldoctest
86+
julia> import MathOptInterface as MOI
87+
88+
julia> config = MOI.Test.Config(
89+
Float64;
90+
optimal_status = MOI.LOCALLY_SOLVED,
91+
exclude = Any[
92+
MOI.ConstraintDual,
93+
MOI.VariableName,
94+
MOI.ConstraintName,
95+
MOI.delete,
96+
],
97+
);
9598
```
9699
"""
97100
function Config(
@@ -306,7 +309,7 @@ Check that the condition `x` is `true`. Otherwise, throw an [`RequirementUnmet`]
306309
error to indicate that the model does not support something required by the test
307310
function.
308311
309-
## Examples
312+
## Example
310313
311314
```julia
312315
@requires MOI.supports(model, MOI.Silent())

0 commit comments

Comments
 (0)