From b734e12c6184f1c960989360d01c41dda88c379c Mon Sep 17 00:00:00 2001
From: Oscar Dowson <odow@users.noreply.github.com>
Date: Fri, 31 Jan 2025 10:13:05 +1300
Subject: [PATCH] [docs] update docstring of is_solved_and_feasible (#3932)

---
 src/optimizer_interface.jl | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/src/optimizer_interface.jl b/src/optimizer_interface.jl
index 18fc1816b23..ab5e8723e71 100644
--- a/src/optimizer_interface.jl
+++ b/src/optimizer_interface.jl
@@ -813,7 +813,6 @@ end
     )
 
 Return `true` if:
-
  * the [`termination_status`](@ref) is one of:
    * [`OPTIMAL`](@ref) (the solver found a global optimum)
    * [`LOCALLY_SOLVED`](@ref) (the solver found a local optimum, which may also
@@ -823,24 +822,36 @@ Return `true` if:
 This function is conservative, in that it returns `false` for situations like
 the solver terminating with a feasible solution due to a time limit.
 
+If this function returns `false`, use [`termination_status`](@ref),
+[`result_count`](@ref), [`primal_status`](@ref) and [`dual_status`](@ref) to
+understand what solutions are available (if any).
+
 See also: [`assert_is_solved_and_feasible`](@ref).
 
 ## Keyword arguments
 
+### `allow_local`
+
 If `allow_local = false`, then this function returns `true` only if the
 [`termination_status`](@ref) is [`OPTIMAL`](@ref).
 
+### `allow_almost`
+
 If `allow_almost = true`, then the [`termination_status`](@ref) may additionally
 be [`ALMOST_OPTIMAL`](@ref) or [`ALMOST_LOCALLY_SOLVED`](@ref) (if `allow_local`),
 and the [`primal_status`](@ref) and [`dual_status`](@ref) may additionally be
 [`NEARLY_FEASIBLE_POINT`](@ref).
 
-If `dual`, additionally use [`dual_status`](@ref) to check that a dual feasible
-point is available.
+### `dual`
 
-If this function returns `false`, use [`termination_status`](@ref),
-[`result_count`](@ref), [`primal_status`](@ref) and [`dual_status`](@ref) to
-understand what solutions are available (if any).
+If `dual`, additionally check that an optimal dual solution is available via
+[`dual_status`](@ref). The `allow_` keywords control both the primal and dual
+solutions.
+
+### `result`
+
+The index of the result to query. This value is passed to the `result` keyword
+arguments of [`primal_status`](@ref) and [`dual_status`](@ref).
 
 ## Example
 
@@ -851,6 +862,14 @@ julia> model = Model(Ipopt.Optimizer);
 
 julia> is_solved_and_feasible(model)
 false
+
+julia> is_solved_and_feasible(
+           model;
+           allow_almost = true,
+           dual = true,
+           result = 2,
+       )
+false
 ```
 """
 function is_solved_and_feasible(