From bd04b68b0b81e7ca5dfa4bce920666a850ee6089 Mon Sep 17 00:00:00 2001
From: odow <o.dowson@gmail.com>
Date: Mon, 1 Apr 2024 10:40:31 +1300
Subject: [PATCH] Improve docstrings of backend and optimizer_index

---
 src/JuMP.jl                | 36 ++++++++++++++++++++++++++++++--
 src/optimizer_interface.jl | 42 ++++++++++++++++++++++++++++++--------
 2 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/src/JuMP.jl b/src/JuMP.jl
index dde8cc748aa..68434896da9 100644
--- a/src/JuMP.jl
+++ b/src/JuMP.jl
@@ -393,8 +393,12 @@ model depends on which operating mode JuMP is in (see [`mode`](@ref)).
  * If JuMP is in `MANUAL` or `AUTOMATIC` mode, the backend is a
    `MOI.Utilities.CachingOptimizer`.
 
-**This function should only be used by advanced users looking to access
-low-level MathOptInterface or solver-specific functionality.**
+Use [`index`](@ref) to get the index of a variable or constraint in the backend
+model.
+
+!!! warning
+    This function should only be used by advanced users looking to access
+    low-level MathOptInterface or solver-specific functionality.
 
 ## Notes
 
@@ -405,6 +409,25 @@ the innermost optimizer, see [`unsafe_backend`](@ref). Alternatively, use
 [`direct_model`](@ref) to create a JuMP model in `DIRECT` mode.
 
 See also: [`unsafe_backend`](@ref).
+
+## Example
+
+```jldoctest
+julia> import HiGHS
+
+julia> model = direct_model(HiGHS.Optimizer());
+
+julia> set_silent(model)
+
+julia> @variable(model, x >= 0)
+x
+
+julia> highs = backend(model)
+A HiGHS model with 1 columns and 0 rows.
+
+julia> index(x)
+MOI.VariableIndex(1)
+```
 """
 backend(model::GenericModel) = model.moi_backend
 
@@ -419,6 +442,9 @@ We strongly suggest you use the alternative suggested below.**
 
 See also: [`backend`](@ref).
 
+To obtain the index of a variable or constraint in the unsafe backend, use
+[`optimizer_index`](@ref).
+
 ## Unsafe behavior
 
 This function is unsafe for two main reasons.
@@ -482,6 +508,9 @@ julia> MOI.Utilities.attach_optimizer(model)
 
 julia> highs = unsafe_backend(model)
 A HiGHS model with 1 columns and 0 rows.
+
+julia> optimizer_index(x)
+MOI.VariableIndex(1)
 ```
 
 Use:
@@ -498,6 +527,9 @@ x
 
 julia> highs = backend(model)  # No need to call `attach_optimizer`.
 A HiGHS model with 1 columns and 0 rows.
+
+julia> index(x)
+MOI.VariableIndex(1)
 ```
 """
 unsafe_backend(model::GenericModel) = unsafe_backend(backend(model))
diff --git a/src/optimizer_interface.jl b/src/optimizer_interface.jl
index aa42f18186b..c7554397427 100644
--- a/src/optimizer_interface.jl
+++ b/src/optimizer_interface.jl
@@ -1130,19 +1130,45 @@ end
     optimizer_index(x::GenericVariableRef)::MOI.VariableIndex
     optimizer_index(x::ConstraintRef{<:GenericModel})::MOI.ConstraintIndex
 
-Return the index that corresponds to `x` in the optimizer model.
+Return the variable or constraint index that corresponds to `x` in the
+associated model `unsafe_backend(owner_model(x))`.
 
-Throws [`NoOptimizer`](@ref) if no optimizer is set, and throws an
-`ErrorException` if the optimizer is set but is not attached.
+This function should be used with [`unsafe_backend`](@ref).
+
+As a safer alternative, use [`backend`](@ref) and [`index`](@ref). See the
+docstrings of [`backend`](@ref) and [`unsafe_backend`](@ref) for more details.
+
+## Throws
+
+ * Throws [`NoOptimizer`](@ref) if no optimizer is set.
+ * Throws an `ErrorException` if the optimizer is set but is not attached.
+ * Throws an `ErrorException` if the index is bridged.
+
+## Example
+
+```jldoctest
+julia> import HiGHS
+
+julia> model = Model(HiGHS.Optimizer);
+
+julia> set_silent(model)
+
+julia> @variable(model, x >= 0)
+x
+
+julia> MOI.Utilities.attach_optimizer(model)
+
+julia> highs = unsafe_backend(model)
+A HiGHS model with 1 columns and 0 rows.
+
+julia> optimizer_index(x)
+MOI.VariableIndex(1)
+```
 """
 function optimizer_index(
     x::Union{GenericVariableRef,ConstraintRef{<:GenericModel}},
 )
-    model = owner_model(x)
-    if mode(model) == DIRECT
-        return index(x)
-    end
-    return _moi_optimizer_index(backend(model), index(x))
+    return _moi_optimizer_index(backend(owner_model(x)), index(x))
 end
 
 """