added documentation for categories

[matbesancon]

JuMP @variable can be odd for newcomers because there seems to be bindings that don't exist:

@variable(m, x[1:10], Bin)

JuMP.Bin # not found
?JuMP.Bin # not found either

This allows having a short docstring for these categories

[matbesancon]

These haven't been exported, so users still need the fully qualified JuMP.PSD to find them

[codecov]

Codecov Report

Merging #2028 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff           @@
##           master   #2028   +/-   ##
======================================
  Coverage    91.5%   91.5%           
======================================
  Files          33      33           
  Lines        4215    4215           
======================================
  Hits         3857    3857           
  Misses        358     358

Impacted Files	Coverage Δ
src/sets.jl	83.33% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0565f26...cdd1f5d. Read the comment docs.

[codecov]

Codecov Report

Merging #2028 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff           @@
##           master   #2028   +/-   ##
======================================
  Coverage    91.5%   91.5%           
======================================
  Files          33      33           
  Lines        4215    4215           
======================================
  Hits         3857    3857           
  Misses        358     358

Impacted Files	Coverage Δ
src/sets.jl	83.33% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0565f26...cdd1f5d. Read the comment docs.

[odow]

I didn't know you could declare variables like this!

But, maybe we should make it a type? Because it still has this:

julia> JuMP.Bin
ERROR: UndefVarError: Bin not defined

We also don't really want to declare an Int JuMP-local variable. It would get exported and might cause all sorts of issues.

[matbesancon]

It's a bizarre trickery, it's documented, but not an identifier. You get it in REPL auto-completion, but raises UndefVar

[matbesancon]

We can make them types indeed

[mlubin]

I agree that the use of Bin and Int can be a bit confusing in the macros, but we cannot export Int in any case because of the conflict with the name in Base.

These haven't been exported, so users still need the fully qualified JuMP.PSD to find them

All symbols without preceding underscores are exported from JuMP:
https://github.com/JuliaOpt/JuMP.jl/blob/0565f26eb5aca10c92516143f8a40280257b49b9/src/JuMP.jl#L757-L758

I've thought about @variable(model, x, :Bin) and @variable(model, x, :Int). Which is more confusing for new users, Julia symbol syntax with a colon or seemingly referring to undefined bindings like Bin?

[matbesancon]

Which is more confusing for new users, Julia symbol syntax with a colon or seemingly referring to undefined bindings like Bin?

I would say symbols are less confusing, they can experiment with them in the REPL, get typeof(:Int) and then check the documentation for Symbol.

The fact that Int is among the categories is even more confusing in the current state, because users might think the last argument passed is a type

[blegat]

PSD should be replaced by PSDCone(). In fact, we should allow any MOI.AbstractVectorSet and then reshape just like with @constraint. We could do the same for Int and Bin. We expect MOI.ZeroOne() and JuMP.Bin() just redirects to it

[matbesancon]

So what should do here?

[odow]

The problem with :Int is that there is a distinction between JuMP provided types like :Int and :Bin, and extension types (like SDDP.State).

[matbesancon]

This may be personal but I find it less of a problem than Bin because you know there is "something" (an identifier) which is Int, while you need to understand how macro operate to get that Bin doesn't exist

[matbesancon]

bump here?

[odow]

I think we're going to punt on this until we come up with a better solution. Exporting a symbol for Bin is weird because we don't for Int. And we won't be changing the syntax before JuMP 1.0. So maybe just close?

[odow]

Closing until we come up with a better solution in the future.