[docs] better document various enums (#2699)

Author: odow

docs/src/reference/models.md

@@ -155,8 +155,12 @@ OTHER_RESULT_STATUS
 ```@docs
 compute_conflict!
 ConflictStatus
-ConstraintConflictStatus
 ConflictStatusCode
+COMPUTE_CONFLICT_NOT_CALLED
+NO_CONFLICT_EXISTS
+NO_CONFLICT_FOUND
+CONFLICT_FOUND
+ConstraintConflictStatus
 ConflictParticipationStatusCode
 NOT_IN_CONFLICT
 IN_CONFLICT

docs/src/reference/standard_form.md

@@ -98,6 +98,9 @@ NormNuclearCone
 SOS1
 SOS2
 Indicator
+ActivationCondition
+ACTIVATE_ON_ZERO
+ACTIVATE_ON_ONE
 Complements
 HyperRectangle
 Scaled

docs/src/submodules/FileFormats/reference.md

@@ -14,11 +14,19 @@ Functions to help read and write MOI models to/from various file formats. See
 ```@docs
 FileFormats.Model
 FileFormats.FileFormat
+FileFormats.FORMAT_AUTOMATIC
+FileFormats.FORMAT_CBF
 FileFormats.CBF.Model
+FileFormats.FORMAT_LP
 FileFormats.LP.Model
+FileFormats.FORMAT_MOF
 FileFormats.MOF.Model
+FileFormats.FORMAT_MPS
 FileFormats.MPS.Model
+FileFormats.FORMAT_NL
 FileFormats.NL.Model
+FileFormats.FORMAT_REW
+FileFormats.FORMAT_SDPA
 FileFormats.SDPA.Model
 ```
 

docs/src/submodules/Utilities/reference.md

@@ -53,11 +53,18 @@ Utilities.struct_of_constraint_code
 
 ```@docs
 Utilities.CachingOptimizer
+Utilities.CachingOptimizerState
+Utilities.NO_OPTIMIZER
+Utilities.EMPTY_OPTIMIZER
+Utilities.ATTACHED_OPTIMIZER
+Utilities.state
+Utilities.CachingOptimizerMode
+Utilities.AUTOMATIC
+Utilities.MANUAL
+Utilities.mode
 Utilities.attach_optimizer
 Utilities.reset_optimizer
 Utilities.drop_optimizer
-Utilities.state
-Utilities.mode
 ```
 
 ## Mock optimizer

src/FileFormats/FileFormats.jl

@@ -20,42 +20,72 @@ include("MPS/MPS.jl")
 include("NL/NL.jl")
 include("SDPA/SDPA.jl")
 
-"""
-    FileFormat
-
-List of accepted export formats.
-
-- `FORMAT_AUTOMATIC`: try to detect the file format based on the file name
-- `FORMAT_CBF`: the Conic Benchmark format
-- `FORMAT_LP`: the LP file format
-- `FORMAT_MOF`: the MathOptFormat file format
-- `FORMAT_MPS`: the MPS file format
-- `FORMAT_NL`: the AMPL .nl file format
-- `FORMAT_REW`: the .rew file format, which is MPS with generic names
-- `FORMAT_SDPA`: the SemiDefinite Programming Algorithm format
-"""
-@enum(
+MOI.@_documented_enum(
+    """
+        FileFormat
+
+    List of accepted export formats.
+    """,
     FileFormat,
+    """
+    Try to detect the file format based on the file name.
+    """,
     FORMAT_AUTOMATIC,
+    """
+    The Conic Benchmark format.
+
+    See [`FileFormats.CBF.Model`](@ref) for more details.
+    """,
     FORMAT_CBF,
+    """
+    The LP file format.
+
+    See [`FileFormats.LP.Model`](@ref) for more details.
+    """,
     FORMAT_LP,
+    """
+    The MathOptFormat file format.
+
+    See [`FileFormats.MOF.Model`](@ref) for more details.
+    """,
     FORMAT_MOF,
+    """
+    The MPS file format.
+
+    See [`FileFormats.MPS.Model`](@ref) for more details.
+    """,
     FORMAT_MPS,
+    """
+    The AMPL .nl file format.
+
+    See [`FileFormats.NL.Model`](@ref) for more details.
+    """,
     FORMAT_NL,
+    """
+    The .rew file format, which is equivalent to the MPS format
+    ([`FileFormats.FORMAT_MPS`](@ref)) with the `generic_names = true` keyword
+    argument set by default.
+
+    See [`FileFormats.MPS.Model`](@ref) for more details.
+    """,
     FORMAT_REW,
+    """
+    The SemiDefinite Programming Algorithm format.
+
+    See [`FileFormats.SDPA.Model`](@ref) for more details.
+    """,
     FORMAT_SDPA,
 )
 
 """
-    Model(
-        ;
+    Model(;
         format::FileFormat = FORMAT_AUTOMATIC,
         filename::Union{Nothing, String} = nothing,
         kwargs...
     )
 
-Return model corresponding to the `FileFormat` `format`, or, if
-`format == FORMAT_AUTOMATIC`, guess the format from `filename`.
+Return model corresponding to the [`FileFormats.FileFormat`](@ref) `format`, or,
+if `format == FORMAT_AUTOMATIC`, guess the format from `filename`.
 
 The `filename` argument is only needed if `format == FORMAT_AUTOMATIC`.
 

src/Utilities/cachingoptimizer.jl

@@ -12,8 +12,52 @@
 # function that uses `.optimizer`. For example:
 # `MOI.supports(model.optimizer, F, S)::Bool`.
 
-@enum CachingOptimizerState NO_OPTIMIZER EMPTY_OPTIMIZER ATTACHED_OPTIMIZER
-@enum CachingOptimizerMode MANUAL AUTOMATIC
+MOI.@_documented_enum(
+    """
+        CachingOptimizerState
+
+    A [`Utilities.CachingOptimizer`](@ref) may be in one of three possible
+    states.
+    """,
+    CachingOptimizerState,
+    "The CachingOptimizer does not have any optimizer.",
+    NO_OPTIMIZER,
+    """
+    The CachingOptimizer has an optimizer. The optimizer is empty and it is not
+    synchronized with the cached model.
+    """,
+    EMPTY_OPTIMIZER,
+    """
+    The CachingOptimizer has an optimizer, and it is synchronized with the
+    cached model.
+    """,
+    ATTACHED_OPTIMIZER,
+)
+MOI.@_documented_enum(
+    """
+        CachingOptimizerMode
+
+    A [`Utilities.CachingOptimizer`](@ref) has two modes of operation.
+    """,
+    CachingOptimizerMode,
+    """
+    The only methods that change the state of the `CachingOptimizer`
+    are [`Utilities.reset_optimizer`](@ref), [`Utilities.drop_optimizer`](@ref),
+    and [`Utilities.attach_optimizer`](@ref).
+
+    Attempting to perform an operation in the incorrect state results in an
+    error.
+    """,
+    MANUAL,
+    """
+    The [`Utilities.CachingOptimizer`](@ref) changes its state when necessary.
+    For example, [`MOI.optimize!`](@ref) will automatically call
+    [`Utilities.attach_optimizer`](@ref) (an optimizer must have been previously
+    set). Attempting to add a constraint or perform a modification not supported
+    by the optimizer results in a drop to the [`EMPTY_OPTIMIZER`](@ref) state.
+    """,
+    AUTOMATIC,
+)
 
 """
     CachingOptimizer
@@ -22,57 +66,52 @@
 links it with an optimizer. It supports incremental model construction and
 modification even when the optimizer doesn't.
 
-## Constructors
+## Mode
+
+A [`Utilities.CachingOptimizer`](@ref) has two modes of operation:
+[`Utilities.AUTOMATIC`](@ref) and [`Utilities.MANUAL`](@ref). See their
+docstrings for details.
+
+Use [`Utilities.mode`](@ref) to query the mode of a
+[`Utilities.CachingOptimizer`](@ref).
+
+## State
+
+A [`Utilities.CachingOptimizer`](@ref) may be in one of three possible states:
+[`NO_OPTIMIZER`](@ref), [`Utilities.EMPTY_OPTIMIZER`](@ref), and
+[`Utilities.ATTACHED_OPTIMIZER`](@ref). See their docstrings for details.
+
+Use [`Utilities.state`](@ref) to query the state of a
+[`Utilities.CachingOptimizer`](@ref).
+
+## Constructor with optimizer
 
 ```julia
     CachingOptimizer(cache::MOI.ModelLike, optimizer::AbstractOptimizer)
 ```
 
-Creates a `CachingOptimizer` in `AUTOMATIC` mode, with the optimizer
+Creates a `CachingOptimizer` in [`AUTOMATIC`](@ref) mode, with the optimizer
 `optimizer`.
 
 The type of the optimizer returned is
-`CachingOptimizer{typeof(optimizer), typeof(cache)}` so it does not support the
-function `reset_optimizer(::CachingOptimizer, new_optimizer)` if the type of
-`new_optimizer` is different from the type of `optimizer`.
+`CachingOptimizer{typeof(optimizer),typeof(cache)}` so it does not support the
+function [`Utilities.reset_optimizer(::CachingOptimizer, new_optimizer)`](@ref)
+if the type of `new_optimizer` is different from the type of `optimizer`.
+
+## Constructor without optimizer
 
 ```julia
     CachingOptimizer(cache::MOI.ModelLike, mode::CachingOptimizerMode)
 ```
 
-Creates a `CachingOptimizer` in the `NO_OPTIMIZER` state and mode `mode`.
+Creates a `CachingOptimizer` in the [`NO_OPTIMIZER`](@ref)
+[`Utilities.CachingOptimizerState`](@ref) and the
+[`Utilities.CachingOptimizerMode`](@ref) `mode`.
 
 The type of the optimizer returned is
 `CachingOptimizer{MOI.AbstractOptimizer,typeof(cache)}` so it _does_ support the
 function `reset_optimizer(::CachingOptimizer, new_optimizer)` if the type of
 `new_optimizer` is different from the type of `optimizer`.
-
-## About the type
-
-### States
-
-A `CachingOptimizer` may be in one of three possible states
-(`CachingOptimizerState`):
-
-* `NO_OPTIMIZER`: The CachingOptimizer does not have any optimizer.
-* `EMPTY_OPTIMIZER`: The CachingOptimizer has an empty optimizer.
-  The optimizer is not synchronized with the cached model.
-* `ATTACHED_OPTIMIZER`: The CachingOptimizer has an optimizer, and it is
-  synchronized with the cached model.
-
-### Modes
-
-A `CachingOptimizer` has two modes of operation (`CachingOptimizerMode`):
-
-* `MANUAL`: The only methods that change the state of the `CachingOptimizer`
-  are [`Utilities.reset_optimizer`](@ref), [`Utilities.drop_optimizer`](@ref),
-  and [`Utilities.attach_optimizer`](@ref).
-  Attempting to perform an operation in the incorrect state results in an error.
-* `AUTOMATIC`: The `CachingOptimizer` changes its state when necessary. For
-  example, `optimize!` will automatically call `attach_optimizer` (an
-  optimizer must have been previously set). Attempting to add a constraint or
-  perform a modification not supported by the optimizer results in a drop to
-  `EMPTY_OPTIMIZER` mode.
 """
 mutable struct CachingOptimizer{O,M<:MOI.ModelLike} <: MOI.AbstractOptimizer
     optimizer::Union{Nothing,O}
@@ -154,14 +193,18 @@ end
 """
     state(m::CachingOptimizer)::CachingOptimizerState
 
-Returns the state of the CachingOptimizer `m`. See [`Utilities.CachingOptimizer`](@ref).
+Returns the state of the CachingOptimizer `m`.
+
+See [`Utilities.CachingOptimizer`](@ref).
 """
 state(m::CachingOptimizer) = m.state
 
 """
     mode(m::CachingOptimizer)::CachingOptimizerMode
 
-Returns the operating mode of the CachingOptimizer `m`. See [`Utilities.CachingOptimizer`](@ref).
+Returns the operating mode of the CachingOptimizer `m`.
+
+See [`Utilities.CachingOptimizer`](@ref).
 """
 mode(m::CachingOptimizer) = m.mode
 

src/attributes.jl

@@ -1449,26 +1449,27 @@ struct ResultCount <: AbstractModelAttribute end
 
 attribute_value_type(::ResultCount) = Int
 
-"""
-    ConflictStatusCode
+@_documented_enum(
+    """
+        ConflictStatusCode
 
-An Enum of possible values for the `ConflictStatus` attribute. This attribute
-is meant to explain the reason why the conflict finder stopped executing in the
-most recent call to [`compute_conflict!`](@ref).
+    An Enum of possible values for the [`ConflictStatus`](@ref) attribute.
 
-Possible values are:
-* `COMPUTE_CONFLICT_NOT_CALLED`: the function [`compute_conflict!`](@ref) has
-  not yet been called
-* `NO_CONFLICT_EXISTS`: there is no conflict because the problem is feasible
-* `NO_CONFLICT_FOUND`: the solver could not find a conflict
-* `CONFLICT_FOUND`: at least one conflict could be found
-"""
-@enum ConflictStatusCode begin
-    COMPUTE_CONFLICT_NOT_CALLED
-    NO_CONFLICT_EXISTS
-    NO_CONFLICT_FOUND
-    CONFLICT_FOUND
-end
+    This attribute is meant to explain the reason why the conflict finder
+    stopped executing in the most recent call to [`compute_conflict!`](@ref).
+    """,
+    ConflictStatusCode,
+    """
+    The function [`compute_conflict!`](@ref) has not yet been called.
+    """,
+    COMPUTE_CONFLICT_NOT_CALLED,
+    "There is no conflict because the problem is feasible.",
+    NO_CONFLICT_EXISTS,
+    "The solver could not find a conflict.",
+    NO_CONFLICT_FOUND,
+    "The solver found a conflict.",
+    CONFLICT_FOUND,
+)
 
 """
     ConflictStatus()