Add documentation for enum instances (#2186)

Author: odow

docs/src/reference/callbacks.md

@@ -18,8 +18,11 @@ submit
 
 ```@docs
 CallbackNodeStatus
-CallbackNodeStatusCode
 CallbackVariablePrimal
+CallbackNodeStatusCode
+CALLBACK_NODE_STATUS_INTEGER
+CALLBACK_NODE_STATUS_FRACTIONAL
+CALLBACK_NODE_STATUS_UNKNOWN
 ```
 
 ## Lazy constraints
@@ -40,6 +43,9 @@ UserCut
 
 ```@docs
 HeuristicCallback
-HeuristicSolutionStatus
 HeuristicSolution
+HeuristicSolutionStatus
+HEURISTIC_SOLUTION_ACCEPTED
+HEURISTIC_SOLUTION_REJECTED
+HEURISTIC_SOLUTION_UNKNOWN
 ```

docs/src/reference/constraints.md

@@ -34,8 +34,13 @@ ConstraintDualStart
 ConstraintPrimal
 ConstraintDual
 ConstraintBasisStatus
-BasisStatusCode
 ConstraintFunction
 CanonicalConstraintFunction
 ConstraintSet
+BasisStatusCode
+BASIC
+NONBASIC
+NONBASIC_AT_LOWER
+NONBASIC_AT_UPPER
+SUPER_BASIC
 ```

docs/src/reference/models.md

@@ -41,6 +41,10 @@ Name
 ObjectiveFunction
 ObjectiveFunctionType
 ObjectiveSense
+OptimizationSense
+MIN_SENSE
+MAX_SENSE
+FEASIBILITY_SENSE
 NumberOfVariables
 ListOfVariableIndices
 ListOfConstraintTypesPresent
@@ -85,9 +89,33 @@ List of attributes useful for optimizers
 ```@docs
 TerminationStatus
 TerminationStatusCode
+OPTIMIZE_NOT_CALLED
+OPTIMAL
+INFEASIBLE
+DUAL_INFEASIBLE
+LOCALLY_SOLVED
+LOCALLY_INFEASIBLE
+INFEASIBLE_OR_UNBOUNDED
+ALMOST_OPTIMAL
+ALMOST_INFEASIBLE
+ALMOST_DUAL_INFEASIBLE
+ALMOST_LOCALLY_SOLVED
+ITERATION_LIMIT
+TIME_LIMIT
+NODE_LIMIT
+SOLUTION_LIMIT
+MEMORY_LIMIT
+OBJECTIVE_LIMIT
+NORM_LIMIT
+OTHER_LIMIT
+SLOW_PROGRESS
+NUMERICAL_ERROR
+INVALID_MODEL
+INVALID_OPTION
+INTERRUPTED
+OTHER_ERROR
 PrimalStatus
 DualStatus
-ResultStatusCode
 RawStatusString
 ResultCount
 ObjectiveValue
@@ -100,12 +128,31 @@ BarrierIterations
 NodeCount
 ```
 
+### ResultStatusCode
+
+```@docs
+ResultStatusCode
+NO_SOLUTION
+FEASIBLE_POINT
+NEARLY_FEASIBLE_POINT
+INFEASIBLE_POINT
+INFEASIBILITY_CERTIFICATE
+NEARLY_INFEASIBILITY_CERTIFICATE
+REDUCTION_CERTIFICATE
+NEARLY_REDUCTION_CERTIFICATE
+UNKNOWN_RESULT_STATUS
+OTHER_RESULT_STATUS
+```
+
 ### Conflict Status
 
 ```@docs
 compute_conflict!
 ConflictStatus
-ConflictStatusCode
 ConstraintConflictStatus
+ConflictStatusCode
 ConflictParticipationStatusCode
+NOT_IN_CONFLICT
+IN_CONFLICT
+MAYBE_IN_CONFLICT
 ```

src/MathOptInterface.jl

@@ -233,6 +233,90 @@ function copy_to(dest, src)
     )
 end
 
+"""
+    @_documented_enum(args...)
+
+A utility macro for writing `@enum`s with inline documentation strings.
+
+The even arguments are forwarded to the `@enum` macro, and the odd arguments are
+used as the docstring for the corresponding even argument.
+
+## Example
+
+```julia
+julia> MOI.@_documented_enum(
+           \"\"\"
+               MyDocumentedEnum
+
+           This is an example for the documentation.
+           \"\"\",
+           MyDocumentedEnum,
+           \"A country down-under\",
+           AUSTRALIA,
+           \"Another country down-under\",
+           NEW_ZEALAND,
+       )
+MyDocumentedEnum
+
+help?> MyDocumentedEnum
+search: MyDocumentedEnum
+
+  MyDocumentedEnum
+
+  This is an example for the documentation.
+
+  Values
+  ========
+
+  Possible values are:
+
+    •  AUSTRALIA: A country down-under
+
+    •  NEW_ZEALAND: Another country down-under
+
+help?> AUSTRALIA
+search: AUSTRALIA
+
+  AUSTRALIA::MyDocumentedEnum
+
+  An instance of the MyDocumentedEnum enum.
+
+  AUSTRALIA: A country down-under
+```
+"""
+macro _documented_enum(args...)
+    @assert iseven(length(args))
+    code = quote
+        $(Expr(:macrocall, Symbol("@enum"), __source__, args[2:2:end]...))
+    end
+    main_doc, enum = args[1], args[2]
+    main_doc *= "\n## Values\n\nPossible values are:\n\n"
+    for i in 3:2:length(args)
+        docstr, value = args[i], args[i+1]
+        doc = """
+            $value::$enum
+
+        An instance of the [`$enum`](@ref) enum.\n\n`$value`: $docstr
+        """
+        push!(
+            code.args,
+            Expr(:macrocall, Symbol("@doc"), __source__, doc, Meta.quot(value)),
+        )
+        main_doc *= " * [`$value`](@ref): $docstr\n"
+    end
+    push!(
+        code.args,
+        Expr(
+            :macrocall,
+            Symbol("@doc"),
+            __source__,
+            main_doc,
+            Meta.quot(args[2]),
+        ),
+    )
+    return esc(code)
+end
+
 include("error.jl")
 include("indextypes.jl")
 include("functions.jl")