[docs] some more vale fixes (#2404)

Author: odow

.vale.ini

@@ -8,15 +8,30 @@ BasedOnStyles = Vale, Google
 
 # TODO(odow): fix all of these
 Google.Ellipses = OFF
-Google.Exclamation = OFF
 Google.FirstPerson = OFF
 Google.OptionalPlurals = OFF
 Google.Units = OFF
 Vale.Spelling = OFF
+Google.Quotes = OFF
 
 [*.md]
 BasedOnStyles = Vale, Google
 
 [*]
-TokenIgnores = (\$.+?\$), \]\(@(ref|id).+?\)
-Google.Quotes = OFF
+TokenIgnores = (\$+.+?\$+)|(\]\(@(ref|id).+?\))
+
+# TODO(odow): investigate
+
+[docs/src/submodules/Bridges/implementation.md]
+Vale.Spelling = OFF
+
+[docs/src/submodules/Utilities/overview.md]
+Vale.Spelling = OFF
+
+[src/FileFormats/NL/README.md]
+Google.FirstPerson = NO
+
+# Okay to ignore
+
+[LICENSE.md]
+Google.Quotes = NO

docs/styles/config/vocabularies/JuMP/accept.txt

@@ -1,5 +1,8 @@
 % Julia-related vocab
 api|API
+[Aa]rgs
+attr
+kwargs
 arXiv
 backports
 blogposts
@@ -14,10 +17,14 @@ getters
 [Jj]ulia
 linkcheck
 nonlinearly
+nonzeros
 [Pp]recompil(ation|(e(?d)))
+Stacktrace
 subexpression(?s)
 sublicense
+supertype
 textualist
+untyped
 
 % JuMP-related vocab
 [Cc]anonicaliz(e|ation|ing)
@@ -29,10 +36,15 @@ Presolve
 [Ss]emidefinite
 unboundedness
 [Un]nivariate
+unary
 
 % Other
+Alizadeh
+Arkadi
+Cholesky
 Codecov
 Clp
+Goldfarb
 Gurobi
 GZip
 Holy
@@ -41,3 +53,4 @@ MOI
 PATHSolver
 preprint
 Lubin
+Nemirovski

src/Bridges/Constraint/bridges/geomean.jl

@@ -61,7 +61,7 @@ struct GeoMeanBridge{T,F,G,H} <: AbstractBridge
     xij::Vector{MOI.VariableIndex}
     t_upper_bound_constraint::MOI.ConstraintIndex{F,MOI.LessThan{T}}
     rsoc_constraints::Vector{MOI.ConstraintIndex{G,MOI.RotatedSecondOrderCone}}
-    # Ihe case that `d > 2`, this is `Nothing` because the new variables are
+    # In the case that `d > 2`, this is `Nothing` because the new variables are
     # non-negative due to the RotatedSecondOrderCone constraint.
     x_nonnegative_constraint::Union{
         Nothing,

src/Bridges/Constraint/bridges/indicator_sos.jl

@@ -52,7 +52,7 @@ function bridge_constraint(
     sos_index = MOI.add_constraint(
         model,
         MOI.VectorOfVariables([slack, z]),
-        MOI.SOS1{T}([0.4, 0.6]),  # This weight vector is arbitrary!
+        MOI.SOS1{T}([0.4, 0.6]),  # This weight vector is arbitrary
     )
     new_f = MOI.Utilities.operate(+, T, f_scalars[2], slack)
     affine_index = MOI.add_constraint(model, new_f, s.set)

src/Bridges/Constraint/bridges/quad_to_soc.jl

@@ -346,7 +346,7 @@ end
 # where Q = U^T * U$, we have `x = U * z` and `s = -a^T z - b` hence, we have
 #                       = -u * (z^T Q z/2 + a^T z + b)
 # So the dual of the quadratic constraint is `-u`, so that the contribution
-# to the lagrangian function of both the quadratic and RotatedSOC formulation
+# to the Lagrangian function of both the quadratic and RotatedSOC formulation
 # is exactly the same.
 function MOI.get(
     model::MOI.ModelLike,

src/Bridges/Constraint/bridges/set_dot_scaling.jl

@@ -93,7 +93,7 @@ end
 # scalar product for the scaled PSD cone is `<x, y>_2 = x'y` but the scalar
 # product for the PSD cone additionally scales the offdiagonal entries by `2`
 # hence by `D^2` so `<x, y>_1 = x'D^2y`.
-# So `<Dx, y>_2 = <x, D^(-1)y>_1` hence the adjoint of `D` is its inverse!
+# So `<Dx, y>_2 = <x, D^(-1)y>_1` hence the adjoint of `D` is its inverse.
 function MOI.Bridges.adjoint_map_function(
     ::Type{<:SetDotScalingBridge{T,S}},
     func,

src/Bridges/Constraint/bridges/slack.jl

@@ -141,7 +141,7 @@ function MOI.set(
     # As the slack appears `+slack` in `slack_in_set` and `-slack` in equality,
     # giving `value` to both will cancel it out in the Lagrangian.
     # Giving `value` to `bridge.equality` will put the function in the
-    # lagrangian as expected.
+    # Lagrangian as expected.
     MOI.set(model, attr, bridge.slack_in_set, value)
     MOI.set(model, attr, bridge.equality, value)
     return

src/Bridges/Variable/bridges/rsoc_to_psd.jl

@@ -14,7 +14,7 @@
    ``Y = \\left[\\begin{array}{c c}t & x^\\top \\\\ x & 2u \\mathbf{I}\\end{array}\\right].``
 
 Additional bounds are added to ensure the off-diagonals of the ``2uI`` submatrix
-are `0`, and linear constraints are added to ennsure the diagonal of ``2uI``
+are `0`, and linear constraints are added to ensure the diagonal of ``2uI``
 takes the same values.
 
 As a special case, if ``|x|| = 0``, then `RSOCtoPSDBridge` reformulates into
@@ -36,7 +36,7 @@ As a special case, if ``|x|| = 0``, then `RSOCtoPSDBridge` reformulates into
    * [`MOI.VectorOfVariables`](@ref) in
    [`MOI.PositiveSemidefiniteConeTriangle`](@ref) otherwise
  * The constraint node [`MOI.VariableIndex`](@ref) in [`MOI.EqualTo`](@ref)
- * The constrant node [`MOI.ScalarAffineFunction`](@ref) in [`MOI.EqualTo`](@ref)
+ * The constant node [`MOI.ScalarAffineFunction`](@ref) in [`MOI.EqualTo`](@ref)
 """
 struct RSOCtoPSDBridge{T} <: AbstractBridge
     variables::Vector{MOI.VariableIndex}

src/Bridges/Variable/bridges/vectorize.jl

@@ -124,7 +124,7 @@ function MOI.set(
     bridge::VectorizeBridge,
     ::MOI.Utilities.ScalarLinearSet,
 )
-    # This would require modifing any constraint which uses the bridged
+    # This would require modifying any constraint which uses the bridged
     # variable.
     return throw(
         MOI.SetAttributeNotAllowed(

src/Bridges/bridge.jl

@@ -274,7 +274,7 @@ needs_final_touch(::AbstractBridge) = false
     final_touch(bridge::AbstractBridge, model::MOI.ModelLike)::Nothing
 
 A function that is called immediately prior to [`MOI.optimize!`](@ref) to allow
-bridges to modify their reformulations with repsect to other variables and
+bridges to modify their reformulations with respect to other variables and
 constraints in `model`.
 
 For example, if the correctness of `bridge` depends on the bounds of a variable

src/Bridges/bridge_optimizer.jl

@@ -2205,7 +2205,7 @@ function bridged_function(bridge::AbstractBridgeOptimizer, value)
     end
     # We assume that the type of `value` is not altered. This restricts
     # variable bridges to only return `ScalarAffineFunction` but otherwise,
-    # the peformance would be bad.
+    # the performance would be bad.
     return MOI.Utilities.substitute_variables(
         vi -> bridged_variable_function(bridge, vi),
         value,
@@ -2383,9 +2383,9 @@ function unbridged_constraint_function(
     # Otherwise, first unbridge the function:
     f = unbridged_function(b, func)::typeof(func)
     # But now we have to deal with an issue. Something like x in [1, ∞) might
-    # get bridged into y in R₊, with x => y + 1, so if the orginal constraint is
+    # get bridged into y in R₊, with x => y + 1, so if the original constraint is
     # 2x >= 1, the bridged function is 2y >= -1. Unbridging this with y = x - 1
-    # gives 2x - 2, but we only care about 2x! Where did the -2 come from? It
+    # gives 2x - 2, but we only care about 2x. Where did the -2 come from? It
     # was moved into the set. This gets handled separately, so for
     # ConstraintFunction it is sufficient to drop any non-zero constant terms.
     #

src/FileFormats/CBF/write.jl

@@ -84,7 +84,7 @@ function _add_function(
     f::MOI.VectorOfVariables,
     ::Type{<:Union{MOI.ExponentialCone,MOI.DualExponentialCone}},
 )
-    # The Exponential cone in MOI and CBF are reversed!
+    # The Exponential cone in MOI and CBF are reversed
     for v in reverse(f.variables)
         data.num_rows += 1
         push!(data.acoord, (data.num_rows, v.value, 1.0))
@@ -97,7 +97,7 @@ function _add_function(
     f::MOI.VectorAffineFunction,
     ::Type{<:Union{MOI.ExponentialCone,MOI.DualExponentialCone}},
 )
-    # The Exponential cone in MOI and CBF are reversed!
+    # The Exponential cone in MOI and CBF are reversed
     for term in f.terms
         t = term.scalar_term
         row = data.num_rows + 4 - term.output_index

src/FileFormats/LP/LP.jl

@@ -401,7 +401,7 @@ end
 
 # ==============================================================================
 #
-#   Base.read!
+#   `Base.read!`
 #
 # ==============================================================================
 
@@ -541,7 +541,7 @@ function _get_term(token_types, token_values, offset)
         error("Invalid line")
     end
     if offset > length(token_types) || token_types[offset] == _TOKEN_SIGN
-        return coef, offset  # It's a standalone constant!
+        return coef, offset  # It's a standalone constant
     end
     if token_types[offset] == _TOKEN_QUADRATIC_OPEN
         return _get_term(token_types, token_values, offset + 1)
@@ -588,7 +588,7 @@ function _parse_function(
         else
             @assert token_type == _TOKEN_VARIABLE
             x = _get_variable_from_name(model, cache, token::String)
-            # A cheat for type-stability. Store `Float64` of the variable index!
+            # A cheat for type-stability. Store `Float64` of the variable index
             token_values[i] = Float64(x.value)
         end
     end

src/FileFormats/MOF/mof.schema.json

@@ -1133,7 +1133,7 @@
                     }
                 }
             }, {
-                "description": "The set `{(c, y, x) in Z^{1+1+d}}`, such that `c` is strictly greater than the number of occurances of `y` in `x` and `dimension = 1 + 1 + d`.",
+                "description": "The set `{(c, y, x) in Z^{1+1+d}}`, such that `c` is strictly greater than the number of occurences of `y` in `x` and `dimension = 1 + 1 + d`.",
                 "examples": ["{\"type\": \"CountGreaterThan\", \"dimension\": 3}"],
                 "required": ["dimension"],
                 "properties": {

src/FileFormats/MPS/MPS.jl

@@ -489,7 +489,7 @@ function write_columns(io::IO, model::Model, flip_obj, ordered_names, names)
             int_open = false
         end
         if length(coefficients[variable]) == 0
-            # Every variable must appear in the COLUMNS section! Add a 0
+            # Every variable must appear in the COLUMNS section. Add a 0
             # objective coefficient instead.
             println(io, Card(f2 = variable, f3 = "OBJ", f4 = "0"))
         end
@@ -906,7 +906,7 @@ end
 
 # ==============================================================================
 #
-#   Base.read!
+#   `Base.read!`
 #
 # Here is a template for an MPS file, reproduced from
 # http://lpsolve.sourceforge.net/5.5/mps-format.htm.
@@ -1024,7 +1024,7 @@ end
     HEADER_INDICATORS,
 )
 
-# `Headers(s)` gets called _alot_ (on every line), so we try very hard to be
+# `Headers` gets called _alot_ (on every line), so we try very hard to be
 # efficient.
 function Headers(s::AbstractString)
     N = length(s)
@@ -1687,7 +1687,7 @@ function parse_qmatrix_line(data, items)
         error("Malformed QMATRIX line: $(join(items, " "))")
     end
     if data.name_to_col[items[1]] <= data.name_to_col[items[2]]
-        # Off-diagonals have duplicate entries! We don't need to store both
+        # Off-diagonals have duplicate entries. We don't need to store both
         # triangles.
         push!(data.quad_obj, (items[1], items[2], parse(Float64, items[3])))
     end
@@ -1703,7 +1703,7 @@ function parse_qcmatrix_line(data, items)
         error("Malformed QCMATRIX line: $(join(items, " "))")
     end
     if data.name_to_col[items[1]] <= data.name_to_col[items[2]]
-        # Off-diagonals have duplicate entries! We don't need to store both
+        # Off-diagonals have duplicate entries. We don't need to store both
         # triangles.
         push!(
             data.qc_matrix[data.current_qc_matrix],

src/FileFormats/NL/NL.jl

@@ -296,7 +296,7 @@ function MOI.copy_to(dest::Model, model::MOI.ModelLike)
     end
     # Correct bounds of binary variables. Mainly because AMPL doesn't have the
     # concept of binary nonlinear variables, but it does have binary linear
-    # variables! How annoying.
+    # variables. How annoying.
     for (_, v) in dest.x
         if v.type == _BINARY
             v.lower = max(0.0, v.lower)

src/FileFormats/NL/NLExpr.jl

@@ -384,7 +384,7 @@ function _process_expr!(expr::_NLExpr, arg::MOI.VariableIndex)
     return push!(expr.nonlinear_terms, arg)
 end
 
-# TODO(odow): these process_expr! functions use recursion. For large models,
+# TODO(odow): these functions use recursion. For large models,
 # this may exceed the stack. At some point, we may have to rewrite this to not
 # use recursion.
 function _process_expr!(expr::_NLExpr, arg::Expr)
@@ -443,7 +443,7 @@ function _process_expr!(expr::_NLExpr, args::Vector{Any})
     if op == :+
         if N == 1  # +x, so we can just drop the op and process the args.
             return _process_expr!(expr, args[2])
-        elseif N > 2  # nary-addition!
+        elseif N > 2  # nary-addition
             op = :sum
         end
     elseif op == :- && N == 1
@@ -458,7 +458,7 @@ function _process_expr!(expr::_NLExpr, args::Vector{Any})
             N = length(args) - 1
         end
     elseif op == :* && N == 1
-        # Unary multiplication! We can drop the op and process the args.
+        # unary multiplication: we can drop the op and process the args.
         return _process_expr!(expr, args[2])
     end
     # Now convert the Julia expression into an _NLExpr.

src/FileFormats/SDPA/SDPA.jl

@@ -280,7 +280,7 @@ end
 
 # ==============================================================================
 #
-#   Base.read!
+#   `Base.read!`
 #
 # ==============================================================================
 

src/FileFormats/utils.jl

@@ -88,7 +88,7 @@ function create_unique_constraint_names(
                 replacements,
             )
             if new_name in added_names
-                # We found a duplicate name! We could just append a string like
+                # We found a duplicate name. We could just append a string like
                 # "_", but we're going to be clever and loop through the
                 # integers to name them appropriately. Thus, if we have three
                 # constraints named c, we'll end up with variables named c, c_1,
@@ -145,7 +145,7 @@ function create_unique_variable_names(
             replacements,
         )
         if new_name in added_names
-            # We found a duplicate name! We could just append a string like "_",
+            # We found a duplicate name. We could just append a string like "_",
             # but we're going to be clever and loop through the integers to name
             # them appropriately. Thus, if we have three variables named x,
             # we'll end up with variables named x, x_1, and x_2.

src/Nonlinear/ReverseAD/forward_over_reverse.jl

@@ -232,7 +232,7 @@ function _forward_eval_ϵ(
                 @inbounds partial = ex.partials_storage[ix]
                 @inbounds storage_val = storage_ϵ[ix]
                 # TODO: This "if" statement can take 8% of the hessian
-                # evaluation time! Find a more efficient way.
+                # evaluation time. Find a more efficient way.
                 if !isfinite(partial) && storage_val == zero_ϵ
                     continue
                 end

src/Nonlinear/ReverseAD/graph_tools.jl

@@ -10,7 +10,7 @@
         moi_index_to_consecutive_index::Dict{MOI.VariableIndex,Int},
     )
 
-Return a new `Vector{Nonlinear.Node}` where all occurances of
+Return a new `Vector{Nonlinear.Node}` where all occurences of
 `NODE_MOI_VARIABLE` are replaced by `NODE_VARIABLE` that is 1-indexed and
 ordered.
 """
@@ -356,7 +356,7 @@ end
             Vector{Vector{Int}}(undef, length(subexpressions)),
     )
 
-Return a topologically sorted list of the integer subexpresssion indices that
+Return a topologically sorted list of the integer subexpression indices that
 need to be computed to evaluate `subexpressions[s]` for all `s in starts`.
 
 `starts` should be ordered, and not contain duplicates.
@@ -369,14 +369,14 @@ If calling `_topological_sort` a single time, you may omit the
 `subexpression_dependency_graph` argument.
 
 However, if calling `_topological_sort` multiple times on the _same_ vector of
-subexpresssions, you should create `subexpression_dependency_graph` once (either
+subexpressions, you should create `subexpression_dependency_graph` once (either
 as the uninitialized vector, or by explicitly computing the full
 `subexpression_dependency_graph`), and pass it in.
 
 ## Notes
 
 * It is important to not use recursion here, because expressions may have
-  arbitrary levels of nesting!
+  arbitrary levels of nesting.
 * This function assumes `subexpressions` is acyclic.
 """
 function _topological_sort(
@@ -441,7 +441,7 @@ Returns two things:
    subexpression-indices that need to be evaluated to compute
    `main_expressions[i]`.
 
-**Warning:** This doesn't handle cyclic expressions! But this should be fine
+**Warning:** This doesn't handle cyclic expressions. But this should be fine
 because we can't compute them in JuMP anyway.
 """
 function _order_subexpressions(