[docs] clarify behavior of FEASIBILITY_SENSE in documentation (#3966)

Author: odow

docs/src/manual/objective.md

@@ -231,6 +231,30 @@ julia> @objective(model, Max, objective_function(model))
 2 x
 ```
 
+## Remove an objective
+
+To remove an objective function use [`set_objective_sense`](@ref) to set the
+sense to [`FEASIBILITY_SENSE`](@ref):
+
+```jldoctest
+julia> model = Model();
+
+julia> @variable(model, x);
+
+julia> @objective(model, Min, 2x);
+
+julia> objective_function(model)
+2 x
+
+julia> set_objective_sense(model, FEASIBILITY_SENSE)
+
+julia> objective_sense(model)
+FEASIBILITY_SENSE::OptimizationSense = 2
+
+julia> objective_function(model)
+0
+```
+
 ## Set a vector-valued objective
 
 Define a multi-objective optimization problem by passing a vector of objectives:

src/macros/@objective.jl

@@ -8,10 +8,24 @@
 
 Set the objective sense to `sense` and objective function to `func`.
 
-The objective sense can be either `Min`, `Max`, `MOI.MIN_SENSE`, `MOI.MAX_SENSE`
-or `MOI.FEASIBILITY_SENSE`. In order to set the sense programmatically, that is,
-when `sense` is a variable whose value is the sense, one of the three
-[`MOI.OptimizationSense`](@ref) values must be used.
+## `sense`
+
+The objective sense must be either be the literals `Min` or `Max`, or one of the
+three [`MOI.OptimizationSense`](@ref) enum values ([`MIN_SENSE`](@ref),
+[`MAX_SENSE`](@ref), or [`FEASIBILITY_SENSE`](@ref)).
+
+In order to set the sense programmatically, that is, when `sense` is a Julia
+variable whose value is the sense, you must use a [`MOI.OptimizationSense`](@ref).
+
+## FEASIBILITY_SENSE
+
+[`FEASIBILITY_SENSE`](@ref) implies that there is no objective function.
+Therefore, you should not set `sense` to [`FEASIBILITY_SENSE`](@ref) with a
+non-zero `func`.
+
+To reset the model to [`FEASIBILITY_SENSE`](@ref), do
+`@objective(model, FEASIBILITY_SENSE, 0)`, or use [`set_objective_sense`](@ref):
+`set_objective_sense(model, FEASIBILITY_SENSE)`.
 
 ## Example
 
@@ -50,6 +64,29 @@ MIN_SENSE::OptimizationSense = 0
 julia> @objective(model, sense, x^2 - 2x + 1)
 x² - 2 x + 1
 ```
+
+Remove an objective function:
+```jldoctest
+julia> model = Model();
+
+julia> @variable(model, x >= 0);
+
+julia> @objective(model, Min, 2x + 1)
+2 x + 1
+
+julia> print(model)
+Min 2 x + 1
+Subject to
+ x ≥ 0
+
+julia> @objective(model, FEASIBILITY_SENSE, 0)
+0
+
+julia> print(model)
+Feasibility
+Subject to
+ x ≥ 0
+```
 """
 macro objective(input_args...)
     error_fn = Containers.build_error_fn(:objective, input_args, __source__)

src/objective.jl

@@ -200,10 +200,12 @@ end
 
 Sets the objective sense of the model to the given sense.
 
-See [`set_objective_function`](@ref) to set the objective function.
+See also: [`@objective`](@ref), [`set_objective_function`](@ref), [`set_objective`](@ref)
 
-These are low-level functions; the recommended way to set the objective is with
-the [`@objective`](@ref) macro.
+## FEASIBILITY_SENSE
+
+Setting the objective sense to [`FEASIBILITY_SENSE`](@ref) will remove any
+existing objective.
 
 ## Example
 
@@ -220,7 +222,8 @@ MAX_SENSE::OptimizationSense = 1
 ```
 """
 function set_objective_sense(model::GenericModel, sense::MOI.OptimizationSense)
-    return MOI.set(model, MOI.ObjectiveSense(), sense)
+    MOI.set(model, MOI.ObjectiveSense(), sense)
+    return
 end
 
 """
@@ -229,12 +232,9 @@ end
     set_objective_function(model::GenericModel, func::Real)
     set_objective_function(model::GenericModel, func::Vector{<:AbstractJuMPScalar})
 
-Sets the objective function of the model to the given function.
-
-See [`set_objective_sense`](@ref) to set the objective sense.
+Set the objective function of `model` to the given function `func`.
 
-These are low-level functions; the recommended way to set the objective is with
-the [`@objective`](@ref) macro.
+See also: [`@objective`](@ref), [`set_objective_function`](@ref), [`set_objective`](@ref)
 
 ## Example
 
@@ -277,14 +277,16 @@ end
 
 function set_objective_function(model::GenericModel, func::AbstractJuMPScalar)
     check_belongs_to_model(func, model)
-    return set_objective_function(model, moi_function(func))
+    set_objective_function(model, moi_function(func))
+    return
 end
 
 function set_objective_function(model::GenericModel{T}, func::Real) where {T}
-    return set_objective_function(
+    set_objective_function(
         model,
         MOI.ScalarAffineFunction(MOI.ScalarAffineTerm{T}[], convert(T, func)),
     )
+    return
 end
 
 function set_objective_function(
@@ -294,7 +296,8 @@ function set_objective_function(
     for f in func
         check_belongs_to_model(f, model)
     end
-    return set_objective_function(model, moi_function(func))
+    set_objective_function(model, moi_function(func))
+    return
 end
 
 function set_objective_function(model::AbstractModel, func)
@@ -306,24 +309,41 @@ end
 
 The functional equivalent of the [`@objective`](@ref) macro.
 
-Sets the objective sense and objective function simultaneously, and is
-equivalent to calling [`set_objective_sense`](@ref) and
-[`set_objective_function`](@ref) separately.
+This function sets the objective sense and objective function simultaneously,
+and it is equivalent to calling [`set_objective_sense`](@ref) followed by
+[`set_objective_function`](@ref).
+
+This is a low-level function; the recommended way to set the objective function
+and sense is with the [`@objective`](@ref) macro.
+
+## FEASIBILITY_SENSE
+
+You should not set `sense` to [`FEASIBILITY_SENSE`](@ref) because
+[`FEASIBILITY_SENSE`](@ref) implies that there is no objective function.
+
+Instead of `set_objective(model, FEASIBILITY_SENSE, f)`, do
+`set_objective_sense(model, FEASIBILITY_SENSE)`.
 
 ## Example
 
 ```jldoctest
 julia> model = Model();
 
-julia> @variable(model, x)
-x
+julia> @variable(model, x);
 
 julia> set_objective(model, MIN_SENSE, x)
+
+julia> objective_sense(model)
+MIN_SENSE::OptimizationSense = 0
+
+julia> objective_function(model)
+x
 ```
 """
 function set_objective(model::AbstractModel, sense::MOI.OptimizationSense, func)
     set_objective_sense(model, sense)
-    return set_objective_function(model, func)
+    set_objective_function(model, func)
+    return
 end
 
 """