[docs] Add Google style guide for Vale and fix errors and warnings (#2110)

Author: odow

docs/.vale.ini

@@ -1,10 +1,10 @@
 StylesPath = styles
-MinAlertLevel = suggestion
+MinAlertLevel = warning
 
 Vocab = JuMP-Vocab
 
 [*.md]
-BasedOnStyles = Vale
+BasedOnStyles = Vale, Google
 
 # Skip \\token and \token LaTeX commands
 TokenIgnores = \\\\[a-z]+, \\[a-z]+, [a-zA-Z]+_[_a-zA-Z]+

docs/src/background/infeasibility_certificates.md

@@ -70,7 +70,7 @@ A problem is unbounded if and only if:
 
 A feasible primal solution—if one exists—can be obtained by setting
 [`ObjectiveSense`](@ref) to `FEASIBILITY_SENSE` before optimizing. Therefore,
-most solvers terminate after they prove the dual is infeasible via a certificate
+most solvers stop after they prove the dual is infeasible via a certificate
 of dual infeasibility, but _before_ they have found a feasible primal solution.
 This is also the reason that MathOptInterface defines the `DUAL_INFEASIBLE`
 status instead of `UNBOUNDED`.
@@ -138,9 +138,9 @@ If the solver has found a certificate of primal infeasibility:
 
 ### Infeasibility certificates of variable bounds
 
-Many linear solvers (e.g., Gurobi) do not provide explicit access to the primal
-infeasibility certificate of a variable bound. However, given a set of linear
-constraints:
+Many linear solvers (for example, Gurobi) do not provide explicit access to the
+primal infeasibility certificate of a variable bound. However, given a set of
+linear constraints:
 ```math
 \begin{align}
 l_A \le A x \le u_A \\

docs/src/background/motivation.md

@@ -12,17 +12,17 @@ To address a number of limitations of MathProgBase, MOI is designed to:
 - 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)
+    functions (for example, 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 non-concrete
-     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
-  for infeasibility analysis)
+   * by using multiple dispatch and avoiding requiring containers of
+     non-concrete types
+- Allow a solver to return multiple results (for example, a pool of solutions)
+- Allow a solver to return extra arbitrary information via attributes (for
+  example, variable- and constraint-wise membership in an irreducible
+  inconsistent subset for infeasibility analysis)
 - Provide a greatly expanded set of status codes explaining what happened during
   the optimization procedure
 - Enable a solver to more precisely specify which problem classes it supports

docs/src/background/naming_conventions.md

@@ -17,16 +17,16 @@ Sets encode the structure of constraints. Their names should follow the
 following conventions:
 
 * Abstract types in the set hierarchy should begin with `Abstract` and end in
-  `Set`, e.g., [`AbstractScalarSet`](@ref), [`AbstractVectorSet`](@ref).
-* Vector-valued conic sets should end with `Cone`, e.g.,
+  `Set`, for example, [`AbstractScalarSet`](@ref), [`AbstractVectorSet`](@ref).
+* Vector-valued conic sets should end with `Cone`, for example,
   [`NormInfinityCone`](@ref), [`SecondOrderCone`](@ref).
 * Vector-valued Cartesian products should be plural and not end in `Cone`,
-  e.g., [`Nonnegatives`](@ref), not `NonnegativeCone`.
+  for example, [`Nonnegatives`](@ref), not `NonnegativeCone`.
 * Matrix-valued conic sets should provide two representations: `ConeSquare` and
-  `ConeTriangle`, e.g., [`RootDetConeTriangle`](@ref) and
+  `ConeTriangle`, for example, [`RootDetConeTriangle`](@ref) and
   [`RootDetConeSquare`](@ref). See [Matrix cones](@ref) for more details.
-* Scalar sets should be singular, not plural, e.g., [`Integer`](@ref), not
-  `Integers`.
+* Scalar sets should be singular, not plural, for example, [`Integer`](@ref),
+  not `Integers`.
 * As much as possible, the names should follow established conventions in the
   domain where this set is used: for instance, convex sets should have names
   close to those of [CVX](http://web.cvxr.com/cvx/doc/), and

docs/src/changelog.md

@@ -416,7 +416,7 @@ removed, similar to how Julia 1.0 was Julia 0.7 with deprecations removed.
 ### Troubleshooting problems when updating
 
 If you experience problems when updating, you are likely using previously
-deprecated functionality. (By default, Julia does not warn when you use
+deprecated features. (By default, Julia does not warn when you use
 deprecated features.)
 
 To find the deprecated features you are using, start Julia with `--depwarn=yes`:
@@ -1115,7 +1115,7 @@ This release contains backports from the ongoing development of the v0.10 releas
 ## v0.8.0 (December 18, 2018)
 
 - Rename all enum values to follow the JuMP naming guidelines for constants,
-  e.g., `Optimal` becomes `OPTIMAL`, and `DualInfeasible` becomes
+  for example, `Optimal` becomes `OPTIMAL`, and `DualInfeasible` becomes
   `DUAL_INFEASIBLE`.
 - Rename CachingOptimizer methods for style compliance.
 - Add an `MOI.TerminationStatusCode` called `ALMOST_DUAL_INFEASIBLE`.
@@ -1204,10 +1204,10 @@ This release contains backports from the ongoing development of the v0.10 releas
 - Add test for empty rows in vector linear constraint.
 - Rework errors: `CannotError` has been renamed `NotAllowedError` and
   the distinction between `UnsupportedError` and `NotAllowedError` is now
-  about whether the element is not supported (i.e. it cannot be copied a
+  about whether the element is not supported (for example, it cannot be copied a
   model containing this element) or the operation is not allowed (either
   because it is not implemented, because it cannot be performed in the current
-  state of the model, because it cannot be performed for a specific index, ...)
+  state of the model, or because it cannot be performed for a specific index)
 - `canget` is removed. `NoSolution` is added as a result status to indicate
   that the solver does not have either a primal or dual solution available
   (See #479).

docs/src/manual/constraints.md

@@ -112,9 +112,9 @@ nonpositive) real numbers.
 | ``Ax + b = 0``                | `VectorAffineFunction`       | `Zeros`        |
 
 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, encode ``2x + 1 \le 2``
-as ``2x \le 1``.
+[`ScalarAffineFunction`](@ref)s the first four rows of the preceding table
+because they are 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
@@ -195,7 +195,7 @@ Variable bounds are handled in a similar fashion:
  - `@variable(m, x >= 1)` becomes `VariableIndex`-in-`GreaterThan`
 
 One notable difference is that a variable with an upper and lower bound is
-translated into two constraints, rather than an interval. i.e.:
+translated into two constraints, rather than an interval, that is:
 
  - `@variable(m, 0 <= x <= 1)` becomes `VariableIndex`-in-`LessThan` *and*
     `VariableIndex`-in-`GreaterThan`.

docs/src/manual/models.md

@@ -9,16 +9,16 @@ DocTestFilters = [r"MathOptInterface|MOI"]
 # Models
 
 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
+used to specify an instance of an optimization problem (for example, by adding
 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
-problem. `ModelLike` objects may store an instance (e.g., in memory or backed by
-a file format) without being linked to a particular solver. In addition to the
-model API, MOI defines [`AbstractOptimizer`](@ref) and provides methods to solve
-the model and interact with solutions. See the [Solutions](@ref manual_solutions)
-section for more details.
+problem. `ModelLike` objects may store an instance (for example, in memory or
+backed by a file format) without being linked to a particular solver. In
+addition to the model API, MOI defines [`AbstractOptimizer`](@ref) and provides
+methods to solve the model and interact with solutions. See the
+[Solutions](@ref manual_solutions) section for more details.
 
 !!! info
     Throughout the rest of the manual, `model` is used as a generic `ModelLike`,

docs/src/manual/modification.md

@@ -57,7 +57,7 @@ constraint (for example, from [`LessThan`](@ref) to [`GreaterThan`](@ref)). For
 these cases, MathOptInterface provides the [`transform`](@ref) method.
 
 The [`transform`](@ref) function returns a new constraint index, and the old
-constraint index (i.e., `c`) is no longer valid.
+constraint index (that is, `c`) is no longer valid.
 
 ```jldoctest transform_set; setup=:(model = MOI.Utilities.Model{Float64}(); x = MOI.add_variable(model))
 julia> c = MOI.add_constraint(
@@ -129,10 +129,8 @@ julia> MOI.get(model, MOI.ConstraintFunction(), c) ≈ new_f
 true
 ```
 
-!!! tip
-    [`ScalarConstantChange`](@ref) can also be used to modify the objective
-    function by passing an instance of [`ObjectiveFunction`](@ref) instead of
-    the constraint index `c` as we saw above.
+[`ScalarConstantChange`](@ref) can also be used to modify the objective
+function by passing an instance of [`ObjectiveFunction`](@ref):
 
 ```jldoctest scalar_constant_change
 julia> MOI.set(
@@ -207,10 +205,8 @@ julia> MOI.get(model, MOI.ConstraintFunction(), c) ≈ new_f
 true
 ```
 
-!!! tip
-    [`ScalarCoefficientChange`](@ref) can also be used to modify the objective
-    function by passing an instance of [`ObjectiveFunction`](@ref) instead of
-    the constraint index `c` as we saw above.
+[`ScalarCoefficientChange`](@ref) can also be used to modify the objective
+function by passing an instance of [`ObjectiveFunction`](@ref).
 
 ## Modify affine coefficients in a vector function
 

docs/src/manual/solutions.md

@@ -19,7 +19,7 @@ MOI.optimize!(optimizer)
 
 ## Why did the solver stop?
 
-The optimization procedure may terminate for a number of reasons. The
+The optimization procedure may stop for a number of reasons. The
 [`TerminationStatus`](@ref) attribute of the optimizer returns a
 [`TerminationStatusCode`](@ref) object which explains why the solver stopped.
 

docs/src/manual/standard_form.md

@@ -34,8 +34,8 @@ The function types implemented in MathOptInterface.jl are:
 
 | Function         | Description |
 | :--------------- | :---------- |
-| [`VariableIndex`](@ref) | ``x_j``, i.e., projection onto a single coordinate defined by a variable index ``j``. |
-| [`VectorOfVariables`](@ref) | The projection onto multiple coordinates (i.e., extracting a sub-vector). |
+| [`VariableIndex`](@ref) | ``x_j``, the projection onto a single coordinate defined by a variable index ``j``. |
+| [`VectorOfVariables`](@ref) | The projection onto multiple coordinates (that is, extracting a sub-vector). |
 | [`ScalarAffineFunction`](@ref) | ``a^T x + b``, where ``a`` is a vector and ``b`` scalar. |
 | [`VectorAffineFunction`](@ref) | ``A x + b``, where ``A`` is a matrix and ``b`` is a vector. |
 | [`ScalarQuadraticFunction`](@ref) | ``\frac{1}{2} x^T Q x + a^T x + b``, where ``Q`` is a symmetric matrix, ``a`` is a vector, and ``b`` is a constant. |