Improve text of showerror for NotAllowedError

Author: odow

src/error.jl

@@ -51,19 +51,38 @@ form).
 function operation_name end
 
 function Base.showerror(io::IO, err::NotAllowedError)
-    print(io, typeof(err), ": ", operation_name(err), " cannot be performed")
+    println(io, typeof(err), ":\n")
+    println(io, "## Cause\n")
+    print(io, operation_name(err), " cannot be performed")
     m = message(err)
-    if Base.isempty(m)
-        print(io, ".")
-    else
-        print(io, ": ", m)
+    if !isempty(m)
+        println(io, " because:\n\n", m)
     end
-    return print(
+    println(io)
+    print(
         io,
-        " You may want to use a `CachingOptimizer` in `AUTOMATIC` mode",
-        " or you may need to call `reset_optimizer` before doing this",
-        " operation if the `CachingOptimizer` is in `MANUAL` mode.",
+        """
+        ## Fixing this error
+
+        An `MOI.NotAllowedError` error occurs when you have tried to do something that
+        is not implemented by the solver.
+
+        The most common way to fix this error is to wrap the optimizer in a
+        `MOI.Utilities.CachingOptimizer`.
+
+        For example, if you are using `JuMP.Model` or `JuMP.set_optimizer`, do:
+        ```julia
+        model = JuMP.Model(optimizer; with_cache_type = Float64)
+        model = JuMP.GenericModel{T}(optimizer; with_cache_type = T)
+        JuMP.set_optimizer(model, optimizer; with_cache_type = Float64)
+        ```
+        Similarly, if you are using `MOI.instantiate`, do:
+        ```julia
+        model = MOI.instantiate(optimizer; with_cache_type = Float64)
+        ```
+        """,
     )
+    return
 end
 
 """

test/General/errors.jl

@@ -139,23 +139,19 @@ function test_errors_DeleteNotAllowed()
     try
         MOI.delete(model, vi)
     catch err
-        @test sprint(showerror, err) ==
-              "$(MOI.DeleteNotAllowed{typeof(vi)}): Deleting the index $vi " *
-              "cannot be performed. You may want to use a `CachingOptimizer` " *
-              "in `AUTOMATIC` mode or you may need to call `reset_optimizer` " *
-              "before doing this operation if the `CachingOptimizer` is in " *
-              "`MANUAL` mode."
+        contents = sprint(showerror, err)
+        @test occursin("$(MOI.DeleteNotAllowed{typeof(vi)})", contents)
+        @test occursin("Deleting the index $vi ", contents)
+        @test occursin("## Fixing this error", contents)
     end
     @test_throws MOI.DeleteNotAllowed{typeof(ci)} MOI.delete(model, ci)
     try
         MOI.delete(model, ci)
     catch err
-        @test sprint(showerror, err) ==
-              "$(MOI.DeleteNotAllowed{typeof(ci)}): Deleting the index $ci " *
-              "cannot be performed. You may want to use a `CachingOptimizer` " *
-              "in `AUTOMATIC` mode or you may need to call `reset_optimizer` " *
-              "before doing this operation if the `CachingOptimizer` is in " *
-              "`MANUAL` mode."
+        contents = sprint(showerror, err)
+        @test occursin("$(MOI.DeleteNotAllowed{typeof(ci)})", contents)
+        @test occursin("Deleting the index $ci ", contents)
+        @test occursin("## Fixing this error", contents)
     end
     return
 end
@@ -244,14 +240,11 @@ function test_errors_ModifyNotAllowed_constraint()
     change = MOI.ScalarConstantChange(1.0)
     err = MOI.ModifyConstraintNotAllowed(ci, change)
     @test_throws err MOI.modify(model, ci, change)
-    @test sprint(showerror, err) ==
-          "$(MOI.ModifyConstraintNotAllowed{MOI.VariableIndex,MOI.EqualTo{Float64},MOI.ScalarConstantChange{Float64}}):" *
-          " Modifying the constraints $(MOI.ConstraintIndex{MOI.VariableIndex,MOI.EqualTo{Float64}}(1))" *
-          " with MathOptInterface.ScalarConstantChange{Float64}(1.0) cannot" *
-          " be performed. You may want to use a `CachingOptimizer` in" *
-          " `AUTOMATIC` mode or you may need to call `reset_optimizer`" *
-          " before doing this operation if the `CachingOptimizer` is in" *
-          " `MANUAL` mode."
+    contents = sprint(showerror, err)
+    @test occursin("$(typeof(err)):" contents)
+    @test occursin("Modifying the constraints $ci", contents)
+    @test occursin("## Fixing this error", contents)
+    return
 end
 
 function test_errors_ModifyNotAllowed_objective()
@@ -260,13 +253,11 @@ function test_errors_ModifyNotAllowed_objective()
     attr = MOI.ObjectiveFunction{MOI.VariableIndex}()
     err = MOI.ModifyObjectiveNotAllowed(change)
     @test_throws err MOI.modify(model, attr, change)
-    @test sprint(showerror, err) ==
-          "$(MOI.ModifyObjectiveNotAllowed{MOI.ScalarConstantChange{Float64}}):" *
-          " Modifying the objective function with $(MOI.ScalarConstantChange{Float64}(1.0))" *
-          " cannot be performed. You may want to use a `CachingOptimizer`" *
-          " in `AUTOMATIC` mode or you may need to call `reset_optimizer`" *
-          " before doing this operation if the `CachingOptimizer` is in" *
-          " `MANUAL` mode."
+    contents = sprint(showerror, err)
+    @test occursin("$(typeof(err)):" contents)
+    @test occursin("Modifying the objective function with $change", contents)
+    @test occursin("## Fixing this error", contents)
+    return
 end
 
 function test_errors_show_SetAttributeNotAllowed()
@@ -352,11 +343,10 @@ function test_get_fallback_error()
         MOI.get(model, MOI.SolveTimeSec()),
     )
     err = MOI.GetAttributeNotAllowed(MOI.SolveTimeSec(), "")
-    @test sprint(showerror, err) ==
-          "$(typeof(err)): Getting attribute $(MOI.SolveTimeSec()) cannot be " *
-          "performed. You may want to use a `CachingOptimizer` in " *
-          "`AUTOMATIC` mode or you may need to call `reset_optimizer` before " *
-          "doing this operation if the `CachingOptimizer` is in `MANUAL` mode."
+    contents = sprint(showerror, err)
+    @test occursin("$(typeof(err)):", contents)
+    @test occursin("Getting attribute $(MOI.SolveTimeSec())", contents)
+    @test occursin("## Fixing this error", contents)
     return
 end