General edit of the docs

docs/make.jl

@@ -15,11 +15,9 @@ const _PDF = findfirst(isequal("--pdf"), ARGS) !== nothing || _IS_GITHUB_ACTIONS
 # ==============================================================================
 
 const _PAGES = [
-    "Introduction" => "index.md",
-    "Background" => [
+    "Introduction" => [
+        "index.md",
         "background/motivation.md",
-        "background/duality.md",
-        "background/naming_conventions.md",
     ],
     "Tutorials" => [
         "tutorials/example.md",
@@ -37,6 +35,10 @@ const _PAGES = [
         "manual/solutions.md",
         "manual/modification.md",
     ],
+    "Background" => [
+        "background/duality.md",
+        "background/naming_conventions.md",
+    ],
     "API Reference" => [
         "reference/standard_form.md",
         "reference/models.md",

docs/src/background/duality.md

@@ -53,11 +53,10 @@ and the dual is a minimization problem in standard conic form:
 \end{align}
 ```
 
-A linear inequality constraint ``a^T x + b \ge c`` should be interpreted as
-``a^T x + b - c \in \mathbb{R}_+``, and similarly ``a^T x + b \le c`` should be
-interpreted as ``a^T x + b - c \in \mathbb{R}_-``. Variable-wise constraints
-should be interpreted as affine constraints with the appropriate identity
-mapping in place of ``A_i``.
+A linear inequality constraint ``a^T x + b \ge c`` is equivalent to
+``a^T x + b - c \in \mathbb{R}_+``, and ``a^T x + b \le c`` is equivalent to
+``a^T x + b - c \in \mathbb{R}_-``. Variable-wise constraints are affine
+constraints with the appropriate identity mapping in place of ``A_i``.
 
 For the special case of minimization LPs, the MOI primal form can be stated as:
 ```math

docs/src/background/motivation.md

@@ -1,20 +1,24 @@
 # Motivation
 
-MOI has been designed to replace [MathProgBase](https://github.com/JuliaOpt/MathProgBase.jl),
-which was been used by modeling packages such as [JuMP](https://github.com/jump-dev/JuMP.jl)
-and [Convex.jl](https://github.com/jump-dev/Convex.jl).
+MathOptInterface (MOI) is a replacement for
+[MathProgBase](https://github.com/JuliaOpt/MathProgBase.jl),
+the first-generation abstraction layer for mathematical optimization previously
+used by
+[JuMP](https://github.com/jump-dev/JuMP.jl) and
+[Convex.jl](https://github.com/jump-dev/Convex.jl).
 
-This second-generation abstraction layer addresses a number of limitations of
-MathProgBase.
+To address a number of limitations of MathProgBase, MOI is designed to:
 
-MOI is designed to:
-- Be simple and extensible, unifying linear, quadratic, and conic optimization,
-  and seamlessly facilitate extensions to essentially arbitrary constraints and
-  functions (e.g., indicator constraints, complementarity constraints, and
-  piecewise-linear functions)
-- Be fast by allowing access to a solver's in-memory representation of a problem
-  without writing intermediate files (when possible) and by using multiple
-  dispatch and avoiding requiring containers of nonconcrete types
+- Be simple and extensible
+  * unifying linear, quadratic, and conic optimization,
+  * seamlessly facilitating extensions to essentially arbitrary constraints and
+    functions (e.g., indicator constraints, complementarity constraints, and
+    piecewise-linear functions)
+- Be fast
+   * by allowing access to a solver's in-memory representation of a problem
+     without writing intermediate files (when possible)
+   * by using multiple dispatch and avoiding requiring containers of nonconcrete
+     types
 - Allow a solver to return multiple results (e.g., a pool of solutions)
 - Allow a solver to return extra arbitrary information via attributes (e.g.,
   variable- and constraint-wise membership in an irreducible inconsistent subset

docs/src/index.md

@@ -1,5 +1,7 @@
 # Introduction
 
+Welcome to the documentation for MathOptInterface.
+
 !!! note
     This documentation is also available in PDF format:
     [MathOptInterface.pdf](MathOptInterface.pdf).
@@ -24,14 +26,14 @@ solver-specific APIs.
 Having a high-level overview of how this documentation is structured will help
 you know where to look for certain things.
 
-* The **Background** section contains articles on the motivation and theory
-  behind MathOptInterface. Look here if you want to understand _why_, rather
-  than _how_.
 * The **Tutorials** section contains articles on how to use and implement the
   MathOptInteraface API. Look here if you want to write a model in MOI, or write
   an interface to a new solver.
 * The **Manual** contains short code-snippets that explain how to use the MOI
   API. Look here for more details on particular areas of MOI.
+* The **Background** section contains articles on the theory
+  behind MathOptInterface. Look here if you want to understand _why_, rather
+  than _how_.
 * The **API Reference** contains a complete list of functions and types that
   comprise the MOI API. Look here is you want to know how to use (or implement)
   a particular function.

docs/src/manual/constraints.md

@@ -18,8 +18,8 @@ julia> c = MOI.add_constraint(model, MOI.VectorOfVariables(x), MOI.Nonnegatives(
 MathOptInterface.ConstraintIndex{MathOptInterface.VectorOfVariables, MathOptInterface.Nonnegatives}(1)
 ```
 
-[`add_constraint`](@ref) returns a [`ConstraintIndex`](@ref) type, which should
-be used to refer to the added constraint in other calls.
+[`add_constraint`](@ref) returns a [`ConstraintIndex`](@ref) type, which is used
+to refer to the added constraint in other calls.
 
 Check if a [`ConstraintIndex`](@ref) is valid using [`is_valid`](@ref).
 
@@ -114,13 +114,13 @@ nonpositive) real numbers.
 
 By convention, solvers are not expected to support nonzero constant terms in the
 [`ScalarAffineFunction`](@ref)s the first four rows above, because they are
-redundant with the parameters of the sets. For example, ``2x + 1 \le 2`` should
-be encoded as ``2x \le 1``.
+redundant with the parameters of the sets. For example, encode ``2x + 1 \le 2``
+as ``2x \le 1``.
 
 Constraints with [`VariableIndex`](@ref) in [`LessThan`](@ref), [`GreaterThan`](@ref),
 [`EqualTo`](@ref), or [`Interval`](@ref) sets have a natural interpretation as
 variable bounds. As such, it is typically not natural to impose multiple lower-
-or upper-bounds on the same variable, and the solver interfaces should throw
+or upper-bounds on the same variable, and the solver interfaces will throw
 respectively [`LowerBoundAlreadySet`](@ref) or [`UpperBoundAlreadySet`](@ref).
 
 Moreover, adding two [`VariableIndex`](@ref) constraints on the same variable

docs/src/manual/models.md

@@ -11,7 +11,7 @@ DocTestFilters = [r"MathOptInterface|MOI"]
 
 The most significant part of MOI is the definition of the **model API** that is
 used to specify an instance of an optimization problem (e.g., by adding
-variables and constraints). Objects that implement the model API should inherit
+variables and constraints). Objects that implement the model API must inherit
 from the [`ModelLike`](@ref) abstract type.
 
 Notably missing from the model API is the method to solve an optimization

docs/src/manual/solutions.md

@@ -38,7 +38,7 @@ else
 end
 ```
 
-After checking the [`TerminationStatus`](@ref), one should typically check
+After checking the [`TerminationStatus`](@ref), check
 [`ResultCount`](@ref). This attribute returns the number of results that the
 solver has available to return. *A result is defined as a primal-dual pair,
 but either the primal or the dual may be missing from the result.* While the

docs/src/manual/variables.md

@@ -17,8 +17,8 @@ Use [`add_variable`](@ref) to add a single variable.
 julia> x = MOI.add_variable(model)
 MathOptInterface.VariableIndex(1)
 ```
-[`add_variable`](@ref) returns a [`VariableIndex`](@ref) type, which should be
-used to refer to the added variable in other calls.
+[`add_variable`](@ref) returns a [`VariableIndex`](@ref) type, which is used to
+refer to the added variable in other calls.
 
 Check if a [`VariableIndex`](@ref) is valid using [`is_valid`](@ref).
 ```jldoctest variables

docs/src/reference/errors.md

@@ -11,19 +11,19 @@ DocTestFilters = [r"MathOptInterface|MOI"]
 
 When an MOI call fails on a model, precise errors should be thrown when possible
 instead of simply calling `error` with a message. The docstrings for the
-respective methods describe the errors that the implementation should thrown in
+respective methods describe the errors that the implementation should throw in
 certain situations. This error-reporting system allows code to distinguish
 between internal errors (that should be shown to the user) and unsupported
 operations which may have automatic workarounds.
 
-When an invalid index is used in an MOI call, an [`InvalidIndex`](@ref) should
-be thrown:
+When an invalid index is used in an MOI call, an [`InvalidIndex`](@ref) is
+thrown:
 ```@docs
 InvalidIndex
 ```
 
-When an invalid result index is used to retrieve an attribute, a 
-[`ResultIndexBoundsError`](@ref) should be thrown: 
+When an invalid result index is used to retrieve an attribute, a
+[`ResultIndexBoundsError`](@ref) is thrown:
 ```@docs
 ResultIndexBoundsError
 check_result_index_bounds

docs/src/reference/standard_form.md

@@ -99,16 +99,21 @@ Complements
 ## Matrix sets
 
 Matrix sets are vectorized in order to be subtypes of
-[`AbstractVectorSet`](@ref). For sets of symmetric matrices, storing both the
-`(i, j)` and `(j, i)` elements is redundant so there exists the
+[`AbstractVectorSet`](@ref).
+
+For sets of symmetric matrices, storing both the
+`(i, j)` and `(j, i)` elements is redundant. Use the
 [`AbstractSymmetricMatrixSetTriangle`](@ref) set to represent only the
-vectorization of the upper triangular part of the matrix. When the matrix
-of expressions constrained to be in the set is not symmetric and hence
-the `(i, j)` and `(j, i)` elements should be constrained to be symmetric,
-the [`AbstractSymmetricMatrixSetSquare`](@ref) set can be used. The
-[`Bridges.Constraint.SquareBridge`](@ref) can transform a set from the square
-form to the [`triangular_form`](@ref) by adding appropriate constraints if
-the `(i, j)` and `(j, i)` expressions are different.
+vectorization of the upper triangular part of the matrix.
+
+When the matrix of expressions constrained to be in the set is not symmetric,
+and hence additional constraints are needed to force the equality of the
+`(i, j)` and `(j, i)` elements, use the
+[`AbstractSymmetricMatrixSetSquare`](@ref) set.
+
+The [`Bridges.Constraint.SquareBridge`](@ref) can transform a set from the
+square form to the [`triangular_form`](@ref) by adding appropriate constraints
+if the `(i, j)` and `(j, i)` expressions are different.
 
 ```@docs
 AbstractSymmetricMatrixSetTriangle

docs/src/submodules/Bridges/implementation.md

@@ -9,24 +9,25 @@ DocTestFilters = [r"MathOptInterface|MOI"]
 
 # Bridge interface
 
-A bridge should implement the following functions to be usable by a bridge optimizer:
+To be usable by a bridge optimizer, a bridge must implement the following
+functions:
 ```@docs
 Bridges.added_constrained_variable_types
 Bridges.added_constraint_types
 ```
-Additionally, variable bridges should implement:
+Additionally, variable bridges must implement:
 ```@docs
 Bridges.Variable.supports_constrained_variable
 Bridges.Variable.concrete_bridge_type
 Bridges.Variable.bridge_constrained_variable
 ```
-constraint bridges should implement:
+constraint bridges must implement:
 ```@docs
 supports_constraint(::Type{<:Bridges.Constraint.AbstractBridge}, ::Type{<:AbstractFunction}, ::Type{<:AbstractSet})
 Bridges.Constraint.concrete_bridge_type
 Bridges.Constraint.bridge_constraint
 ```
-and objective bridges should implement:
+and objective bridges must implement:
 ```@docs
 Bridges.set_objective_function_type
 Bridges.Objective.concrete_bridge_type
@@ -36,7 +37,7 @@ Bridges.Objective.bridge_objective
 When querying the [`NumberOfVariables`](@ref), [`NumberOfConstraints`](@ref)
 [`ListOfVariableIndices`](@ref), and [`ListOfConstraintIndices`](@ref), the
 variables and constraints created by the bridges in the underlying model are
-hidden by the bridge optimizer. For this purpose, the bridge should provide
+hidden by the bridge optimizer. For this purpose, the bridge must provide
 access to the variables and constraints it has created by implementing the
 following methods of [`get`](@ref):
 ```@docs

docs/src/submodules/FileFormats/overview.md

@@ -160,7 +160,7 @@ filename.
 
 In some cases `src` may contain constraints that are not supported by the file
 format (e.g., the CBF format supports integer variables but not binary). If so,
-you should copy `src` to a bridged model using [`Bridges.full_bridge_optimizer`](@ref):
+copy `src` to a bridged model using [`Bridges.full_bridge_optimizer`](@ref):
 ```julia
 src = MOI.Utilities.Model{Float64}()
 x = MOI.add_variable(model)
@@ -170,9 +170,10 @@ bridged = MOI.Bridges.full_bridge_optimizer(dest, Float64)
 MOI.copy_to(bridged, src)
 MOI.write_to_file(dest, "my_model.cbf")
 ```
-You should also note that even after bridging, it may still not be possible to
-write the model to file because of unsupported constraints (e.g., PSD variables
-in the LP file format).
+!!! note
+    Even after bridging, it may still not be possible to write the model to file
+    because of unsupported constraints (e.g., PSD variables in the LP file
+    format).
 
 ## Read and write to `io`
 

docs/src/submodules/Test/overview.md

@@ -200,9 +200,7 @@ machine).
 **Step 3**
 
 Since the double-optimize error involves solving an optimization problem,
-add a new test to [src/Test/UnitTests/solve.jl](https://github.com/jump-dev/MathOptInterface.jl/blob/master/src/Test/UnitTests/solve.jl).
-
-The test should be something like
+add a new test to [src/Test/UnitTests/solve.jl](https://github.com/jump-dev/MathOptInterface.jl/blob/master/src/Test/UnitTests/solve.jl):
 ```julia
 """
     test_unit_optimize!_twice(model::MOI.ModelLike, config::Config)

docs/src/submodules/Utilities/overview.md

@@ -53,7 +53,7 @@ defined outside of MOI (but still known at compile time), we provide the
 
 The `@model` macro takes a name (for a new type, which must not exist yet),
 eight tuples specifying the types of constraints that are supported, and then a
-`Bool` indicating the type should be a subtype of `MOI.AbstractOptimizer` (if
+`Bool` indicating the type is a subtype of `MOI.AbstractOptimizer` (if
 `true`) or `MOI.ModelLike` (if `false`).
 
 The eight tuples are in the following order:
@@ -66,7 +66,7 @@ The eight tuples are in the following order:
  7. Un-typed vector functions, e.g., [`VectorOfVariables`](@ref)
  8. Typed vector functions, e.g., [`VectorAffineFunction`](@ref)
 
-The tuples can contain more than one element. Typed-sets should be speficied
+The tuples can contain more than one element. Typed-sets must be specified
 without their type parameter, i.e., `MOI.LessThan`, not `MOI.LessThan{Float64}`.
 
 Here is an example: