[docs] fix and test docstrings

docs/make.jl

@@ -520,6 +520,13 @@ _validate_pages()
 #  Build the HTML docs
 # ==============================================================================
 
+Documenter.DocMeta.setdocmeta!(
+    JuMP,
+    :DocTestSetup,
+    :(using JuMP, JuMP.Containers);
+    recursive = true,
+)
+
 @time Documenter.makedocs(
     sitename = "JuMP",
     authors = "The JuMP core developers and contributors",
@@ -533,21 +540,8 @@ _validate_pages()
         sidebar_sitename = false,
     ),
     strict = true,
-    # ==========================================================================
-    # `modules = [JuMP]`, along with `checkdocs = :exports` causes Documenter to
-    # throw an error if exported functions with docstrings are not contained in
-    # the Documentation. However, problematically, we include some MOI docs,
-    # which forces us to include MOI in `modules`, despite the fact that we
-    # don't necessarily want to document every MOI method.
-    #
-    # This is should be fine for now, because MOI doesn't export anything.
-    # However, also problematically, some doctests in MOI are not checked and
-    # are failing. Until they are fixed, we can't enable these options.
-    #
-    # TODO(odow): uncomment when possible.
-    # modules = [JuMP, MOI],
-    # checkdocs = :exports,
-    # ==========================================================================
+    modules = [JuMP],
+    checkdocs = :exports,
     # Skip doctests if --fast provided.
     doctest = _FIX ? :fix : !_FAST,
     pages = vcat(_PAGES, "release_notes.md"),

src/Containers/DenseAxisArray.jl

@@ -203,9 +203,9 @@ match `size(data)` in the corresponding dimensions.
 ```jldoctest
 julia> array = Containers.DenseAxisArray([1 2; 3 4], [:a, :b], 2:3)
 2-dimensional DenseAxisArray{Int64,2,...} with index sets:
-    Dimension 1, Symbol[:a, :b]
+    Dimension 1, [:a, :b]
     Dimension 2, 2:3
-And data, a 2×2 Array{Int64,2}:
+And data, a 2×2 Matrix{Int64}:
  1  2
  3  4
 
@@ -242,9 +242,9 @@ julia> array = Containers.DenseAxisArray{Float64}(undef, [:a, :b], 1:2);
 
 julia> fill!(array, 1.0)
 2-dimensional DenseAxisArray{Float64,2,...} with index sets:
-    Dimension 1, Symbol[:a, :b]
+    Dimension 1, [:a, :b]
     Dimension 2, 1:2
-And data, a 2×2 Array{Float64,2}:
+And data, a 2×2 Matrix{Float64}:
  1.0  1.0
  1.0  1.0
 
@@ -256,9 +256,9 @@ julia> array[:a, 2]
 
 julia> array
 2-dimensional DenseAxisArray{Float64,2,...} with index sets:
-    Dimension 1, Symbol[:a, :b]
+    Dimension 1, [:a, :b]
     Dimension 2, 1:2
-And data, a 2×2 Array{Float64,2}:
+And data, a 2×2 Matrix{Float64}:
  1.0  5.0
  1.0  1.0
 ```

src/Containers/SparseAxisArray.jl

@@ -20,16 +20,16 @@ structure than `sa` even if `f(zero(T))` is not zero.
 
 ```jldoctest
 julia> dict = Dict((:a, 2) => 1.0, (:a, 3) => 2.0, (:b, 3) => 3.0)
-Dict{Tuple{Symbol,Int64},Float64} with 3 entries:
+Dict{Tuple{Symbol, Int64}, Float64} with 3 entries:
+  (:a, 3) => 2.0
   (:b, 3) => 3.0
   (:a, 2) => 1.0
-  (:a, 3) => 2.0
 
 julia> array = Containers.SparseAxisArray(dict)
-JuMP.Containers.SparseAxisArray{Float64,2,Tuple{Symbol,Int64}} with 3 entries:
-  [b, 3]  =  3.0
+SparseAxisArray{Float64, 2, Tuple{Symbol, Int64}} with 3 entries:
   [a, 2]  =  1.0
   [a, 3]  =  2.0
+  [b, 3]  =  3.0
 
 julia> array[:b, 3]
 3.0
@@ -44,6 +44,8 @@ function SparseAxisArray(d::Dict{K,T}) where {T,N,K<:NTuple{N,Any}}
     return SparseAxisArray(d, ntuple(n -> Symbol("#$n"), N))
 end
 
+SparseAxisArray(d::Dict, ::Nothing) = SparseAxisArray(d)
+
 Base.length(sa::SparseAxisArray) = length(sa.data)
 
 Base.IteratorSize(::Type{<:SparseAxisArray}) = Base.HasLength()

src/Containers/container.jl

@@ -36,7 +36,7 @@ not supporting index names.
 
 ```jldoctest
 julia> Containers.container((i, j) -> i + j, Containers.vectorized_product(Base.OneTo(3), Base.OneTo(3)))
-3×3 Array{Int64,2}:
+3×3 Matrix{Int64}:
  2  3  4
  3  4  5
  4  5  6
@@ -45,7 +45,7 @@ julia> Containers.container((i, j) -> i + j, Containers.vectorized_product(1:3,
 2-dimensional DenseAxisArray{Int64,2,...} with index sets:
     Dimension 1, 1:3
     Dimension 2, 1:3
-And data, a 3×3 Array{Int64,2}:
+And data, a 3×3 Matrix{Int64}:
  2  3  4
  3  4  5
  4  5  6
@@ -54,17 +54,17 @@ julia> Containers.container((i, j) -> i + j, Containers.vectorized_product(2:3,
 2-dimensional DenseAxisArray{Int64,2,...} with index sets:
     Dimension 1, 2:3
     Dimension 2, Base.OneTo(3)
-And data, a 2×3 Array{Int64,2}:
+And data, a 2×3 Matrix{Int64}:
  3  4  5
  4  5  6
 
 julia> Containers.container((i, j) -> i + j, Containers.nested(() -> 1:3, i -> i:3, condition = (i, j) -> isodd(i) || isodd(j)))
-SparseAxisArray{Int64,2,Tuple{Int64,Int64}} with 5 entries:
+SparseAxisArray{Int64, 2, Tuple{Int64, Int64}} with 5 entries:
+  [1, 1]  =  2
   [1, 2]  =  3
+  [1, 3]  =  4
   [2, 3]  =  5
   [3, 3]  =  6
-  [1, 1]  =  2
-  [1, 3]  =  4
 ```
 """
 function container(f::Function, indices, D, names)

src/Containers/macro.jl

@@ -337,7 +337,7 @@ The type of container can be controlled by the `container` keyword.
 
 ```jldoctest
 julia> Containers.@container([i = 1:3, j = 1:3], i + j)
-3×3 Array{Int64,2}:
+3×3 Matrix{Int64}:
  2  3  4
  3  4  5
  4  5  6
@@ -351,7 +351,7 @@ julia> x
 2-dimensional DenseAxisArray{Int64,2,...} with index sets:
     Dimension 1, 1:3
     Dimension 2, 1:3
-And data, a 3×3 Array{Int64,2}:
+And data, a 3×3 Matrix{Int64}:
  2  3  4
  3  4  5
  4  5  6
@@ -360,18 +360,18 @@ julia> Containers.@container([i = 2:3, j = 1:3], i + j)
 2-dimensional DenseAxisArray{Int64,2,...} with index sets:
     Dimension 1, 2:3
     Dimension 2, Base.OneTo(3)
-And data, a 2×3 Array{Int64,2}:
+And data, a 2×3 Matrix{Int64}:
  3  4  5
  4  5  6
 
 julia> Containers.@container([i = 1:3, j = 1:3; i <= j], i + j)
-JuMP.Containers.SparseAxisArray{Int64,2,Tuple{Int64,Int64}} with 6 entries:
+SparseAxisArray{Int64, 2, Tuple{Int64, Int64}} with 6 entries:
+  [1, 1]  =  2
   [1, 2]  =  3
+  [1, 3]  =  4
+  [2, 2]  =  4
   [2, 3]  =  5
   [3, 3]  =  6
-  [2, 2]  =  4
-  [1, 1]  =  2
-  [1, 3]  =  4
 ```
 """
 macro container(args...)

src/JuMP.jl

@@ -255,6 +255,8 @@ Solver name: HiGHS
 ```
 is equivalent to:
 ```jldoctest
+julia> import HiGHS
+
 julia> model = direct_generic_model(Float64, HiGHS.Optimizer())
 A JuMP Model
 Feasibility problem with:
@@ -358,6 +360,8 @@ Solver name: HiGHS
 ```
 is equivalent to:
 ```jldoctest
+julia> import HiGHS
+
 julia> model = direct_model(HiGHS.Optimizer())
 A JuMP Model
 Feasibility problem with:
@@ -665,14 +669,14 @@ julia> remove_bridge(model, MOI.Bridges.Constraint.SOCtoNonConvexQuadBridge)
 julia> add_bridge(
            model,
            MOI.Bridges.Constraint.NumberConversionBridge;
-           coefficient_type = Complex{Float64}
+           coefficient_type = Complex{Float64},
        )
 
 julia> remove_bridge(
-        model,
-        MOI.Bridges.Constraint.NumberConversionBridge;
-        coefficient_type = Complex{Float64}
-    )
+           model,
+           MOI.Bridges.Constraint.NumberConversionBridge;
+           coefficient_type = Complex{Float64},
+       )
 ```
 """
 function remove_bridge(
@@ -869,14 +873,16 @@ julia> @variable(model, x)
 x
 
 julia> @variable(model, x)
-ERROR: An object of name x is already attached to this model. If
-this is intended, consider using the anonymous construction syntax,
-e.g., `x = @variable(model, [1:N], ...)` where the name of the object
-does not appear inside the macro.
-
-Alternatively, use `unregister(model, :x)` to first unregister the
-existing name from the model. Note that this will not delete the object;
-it will just remove the reference at `model[:x]`.
+ERROR: An object of name x is already attached to this model. If this
+    is intended, consider using the anonymous construction syntax, e.g.,
+    `x = @variable(model, [1:N], ...)` where the name of the object does
+    not appear inside the macro.
+
+    Alternatively, use `unregister(model, :x)` to first unregister
+    the existing name from the model. Note that this will not delete the
+    object; it will just remove the reference at `model[:x]`.
+
+Stacktrace:
 [...]
 
 julia> num_variables(model)
@@ -973,10 +979,9 @@ julia> set_optimize_hook(model, my_hook)
 my_hook (generic function with 1 method)
 
 julia> optimize!(model; test_arg = true)
-Base.Iterators.Pairs{Symbol, Bool, Tuple{Symbol}, NamedTuple{(:test_arg,), Tuple{Bool}}}(:test_arg => 1)
+Base.Pairs{Symbol, Bool, Tuple{Symbol}, NamedTuple{(:test_arg,), Tuple{Bool}}}(:test_arg => 1)
 Calling with `ignore_optimize_hook = true`
 ERROR: NoOptimizer()
-Stacktrace:
 [...]
 ```
 """
@@ -1012,9 +1017,9 @@ function _get_index_keyword_indexing_error()
         1-dimensional DenseAxisArray{VariableRef,1,...} with index sets:
             Dimension 1, Base.OneTo(3)
         And data, a 3-element Vector{VariableRef}:
-        x[1]
-        x[2]
-        x[3]
+         x[1]
+         x[2]
+         x[3]
 
         julia> x[i=2]
         x[2]