From 5e0a9754524f75a5d686748e9449ab1c94956547 Mon Sep 17 00:00:00 2001
From: Oscar Dowson <odow@users.noreply.github.com>
Date: Mon, 10 Jun 2024 09:40:24 +1200
Subject: [PATCH] [docs] add warning about Y <= X, Set() syntax (#3769)

---
 docs/src/manual/constraints.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/docs/src/manual/constraints.md b/docs/src/manual/constraints.md
index 4eb08ee188e..8665f886cba 100644
--- a/docs/src/manual/constraints.md
+++ b/docs/src/manual/constraints.md
@@ -1238,8 +1238,9 @@ julia> @constraint(model, x in MOI.ExponentialCone())
 ## Set inequality syntax
 
 For modeling convenience, the syntax `@constraint(model, x >= y, Set())` is
-short-hand for `@constraint(model, x - y in Set())`. Therefore, the following
-calls are equivalent:
+short-hand for `@constraint(model, x - y in Set())`. 
+
+Therefore, the following calls are equivalent:
 ```jldoctest set_inequality
 julia> model = Model();
 
@@ -1250,9 +1251,6 @@ julia> y = [0.5, 0.75];
 julia> @constraint(model, x >= y, MOI.Nonnegatives(2))
 [x[1] - 0.5, x[2] - 0.75] ∈ MathOptInterface.Nonnegatives(2)
 
-julia> @constraint(model, y <= x, MOI.Nonnegatives(2))
-[x[1] - 0.5, x[2] - 0.75] ∈ MathOptInterface.Nonnegatives(2)
-
 julia> @constraint(model, x - y in MOI.Nonnegatives(2))
 [x[1] - 0.5, x[2] - 0.75] ∈ MathOptInterface.Nonnegatives(2)
 ```
@@ -1270,6 +1268,11 @@ julia> @constraint(model, x .- 1 >= 0, MOI.Nonnegatives(2))
 [x[1] - 1, x[2] - 1] ∈ MathOptInterface.Nonnegatives(2)
 ```
 
+!!! warning
+    The syntax `@constraint(model, y <= x, Set())` is supported, but it is not
+    recommended because the value of the primal and dual solutions associated
+    with the constraint may be the negative of what you expect.
+
 ## Second-order cone constraints
 
 A [`SecondOrderCone`](@ref) constrains the variables `t` and `x` to the set:
@@ -1440,6 +1443,11 @@ julia> @constraint(model, X >= Y, PSDCone())
  X[2,1] - 2  X[2,2] - 1] ∈ PSDCone()
 ```
 
+!!! warning
+    The syntax `@constraint(model, Y <= X, PSDCone())` is supported, but it is
+    not recommended because the value of the primal and dual solutions associated
+    with the constraint may be the negative of what you expect.
+
 ### Symmetry
 
 Solvers supporting PSD constraints usually expect to be given a matrix that