[docs] Add missing docstrings (#2414)

* [docs] Add missing docstrings

* Add more docstrings

* Update aff_expr.jl

docs/src/reference/constraints.md

@@ -6,6 +6,7 @@ More information can be found in the [Constraints](@ref) section of the manual.
 @constraint
 @constraints
 @SDconstraint
+@SDconstraints
 
 name(::ConstraintRef{Model,<:JuMP._MOICON})
 set_name(::ConstraintRef{Model,<:JuMP._MOICON}, ::String)
@@ -47,8 +48,6 @@ index(::ConstraintRef)
 optimizer_index(::ConstraintRef{Model})
 
 constraint_object
-jump_function
-moi_function
 moi_set
 
 function_string

docs/src/reference/expressions.md

@@ -4,9 +4,26 @@ More information can be found in the [Expressions](@ref) section of the manual.
 
 ```@docs
 @expression
+@expressions
+
+GenericAffExpr
+AffExpr
+GenericQuadExpr
+QuadExpr
+UnorderedPair
+
 add_to_expression!
-drop_zeros!
 constant
+drop_zeros!
+isequal_canonical
 linear_terms
+map_coefficients
+map_coefficients_inplace!
 quad_terms
+variable_ref_type
+
+jump_function
+jump_function_type
+moi_function
+moi_function_type
 ```

docs/src/reference/models.md

@@ -45,4 +45,5 @@ copy_extension_data
 Base.copy(::AbstractModel)
 
 operator_warn
+error_if_direct_mode
 ```

docs/src/reference/nonlinear.md

@@ -5,7 +5,9 @@ manual.
 
 ```@docs
 @NLconstraint
+@NLconstraints
 @NLexpression
+@NLexpressions
 @NLobjective
 @NLparameter
 value(::JuMP.NonlinearParameter)

docs/src/reference/objectives.md

@@ -5,14 +5,14 @@ More information can be found in the [Objectives](@ref) section of the manual.
 ```@docs
 @objective
 
-objective_sense
-set_objective_sense
-
 objective_function
 objective_function_type
-set_objective_function
+objective_sense
 
+set_objective
 set_objective_coefficient
+set_objective_function
+set_objective_sense
 
 objective_function_string
 show_objective_function_summary

src/aff_expr.jl

@@ -76,19 +76,62 @@ end
 
 
 #############################################################################
-# GenericAffExpr
-# ∑ aᵢ xᵢ  +  c
+
+"""
+    mutable struct GenericAffExpr{CoefType,VarType} <: AbstractJuMPScalar
+        constant::CoefType
+        terms::OrderedDict{VarType,CoefType}
+    end
+
+An expression type representing an affine expression of the form:
+``\\sum a_i x_i + c``.
+
+## Fields
+
+ * `.constant`: the constant `c` in the expression.
+ * `.terms`: an `OrderedDict`, with keys of `VarType` and values of `CoefType`
+   describing the sparse vector `a`.
+"""
 mutable struct GenericAffExpr{CoefType,VarType} <: AbstractJuMPScalar
     constant::CoefType
     terms::OrderedDict{VarType,CoefType}
 end
 
+"""
+    variable_ref_type(::GenericAffExpr{C, V}) where {C, V}
+
+A helper function used internally by JuMP and some JuMP extensions. Returns the
+variable type `V` from a [`GenericAffExpr`](@ref)
+"""
 variable_ref_type(::GenericAffExpr{C, V}) where {C, V} = V
 
+"""
+    GenericAffExpr(constant::V, kv::AbstractArray{Pair{K,V}}) where {K,V}
+
+Create a [`GenericAffExpr`](@ref) by passing a constant and a vector of pairs.
+
+## Examples
+
+```jldoctest; setup=:(using JuMP; model = Model(); @variable(model, x))
+julia> GenericAffExpr(1.0, [x => 1.0])
+x + 1
+"""
 function GenericAffExpr(constant::V, kv::AbstractArray{Pair{K,V}}) where {K,V}
     return GenericAffExpr{V,K}(constant, _new_ordered_dict(K, V, kv))
 end
 
+"""
+    GenericAffExpr(constant::V, kv::Vararg{Pair{K,V},N}) where {K,V,N}
+
+Create a [`GenericAffExpr`](@Ref) by passing a constant and pairs of additional
+arguments.
+
+## Examples
+
+```jldoctest; setup=:(using JuMP; model = Model(); @variable(model, x))
+julia> GenericAffExpr(1.0, x => 1.0)
+x + 1
+"""
 function GenericAffExpr(constant::V, kv::Vararg{Pair{K,V},N}) where {K,V,N}
     return GenericAffExpr{V,K}(constant, _new_ordered_dict(K, V, kv...))
 end
@@ -131,6 +174,27 @@ function _affine_coefficient(f::GenericAffExpr{C, V}, variable::V) where {C, V}
     return get(f.terms, variable, zero(C))
 end
 
+"""
+    map_coefficients_inplace!(f::Function, a::GenericAffExpr)
+
+Apply `f` to the coefficients and constant term of an [`GenericAffExpr`](@ref)
+`a` and update them in-place.
+
+See also: [`map_coefficients`](@ref)
+
+## Example
+
+```jldoctest; setup=:(using JuMP; model = Model(); @variable(model, x))
+julia> a = GenericAffExpr(1.0, x => 1.0)
+x + 1
+
+julia> map_coefficients_inplace!(c -> 2 * c, a)
+2 x + 2
+
+julia> a
+2 x + 2
+```
+"""
 function map_coefficients_inplace!(f::Function, a::GenericAffExpr)
     # The iterator remains valid if existing elements are updated.
     for (coef, var) in linear_terms(a)
@@ -140,6 +204,27 @@ function map_coefficients_inplace!(f::Function, a::GenericAffExpr)
     return a
 end
 
+"""
+    map_coefficients(f::Function, a::GenericAffExpr)
+
+Apply `f` to the coefficients and constant term of an [`GenericAffExpr`](@ref)
+`a` and return a new expression.
+
+See also: [`map_coefficients_inplace!`](@ref)
+
+## Example
+
+```jldoctest; setup=:(using JuMP; model = Model(); @variable(model, x))
+julia> a = GenericAffExpr(1.0, x => 1.0)
+x + 1
+
+julia> map_coefficients(c -> 2 * c, a)
+2 x + 2
+
+julia> a
+x + 1
+```
+"""
 function map_coefficients(f::Function, a::GenericAffExpr)
     return map_coefficients_inplace!(f, copy(a))
 end
@@ -295,9 +380,19 @@ function SparseArrays.dropzeros(aff::GenericAffExpr)
     return result
 end
 
-# Check if two AffExprs are equal after dropping zeros and disregarding the
-# order. Mostly useful for testing.
-function isequal_canonical(aff::GenericAffExpr{C,V}, other::GenericAffExpr{C,V}) where {C,V}
+"""
+    isequal_canonical(
+        aff::GenericAffExpr{C,V},
+        other::GenericAffExpr{C,V}
+    ) where {C,V}
+
+Return `true` if `aff` is equal to `other` after dropping zeros and disregarding
+the order. Mainly useful for testing.
+"""
+function isequal_canonical(
+    aff::GenericAffExpr{C,V},
+    other::GenericAffExpr{C,V}
+) where {C,V}
     aff_nozeros = dropzeros(aff)
     other_nozeros = dropzeros(other)
     # Note: This depends on equality of OrderedDicts ignoring order.
@@ -312,7 +407,12 @@ function Base.convert(::Type{GenericAffExpr{T,V}}, v::_Constant) where {T,V}
     return GenericAffExpr{T,V}(convert(T, _constant_to_number(v)))
 end
 
-# Alias for (Float64, VariableRef), the specific GenericAffExpr used by JuMP
+"""
+    AffExpr
+
+Alias for `GenericAffExpr{Float64,VariableRef}`, the specific
+[`GenericAffExpr`](@ref) used by JuMP.
+"""
 const AffExpr = GenericAffExpr{Float64,VariableRef}
 
 # Check all coefficients are finite, i.e. not NaN, not Inf, not -Inf
@@ -358,12 +458,48 @@ function MOI.ScalarAffineFunction(a::AffExpr)
                                           for t in linear_terms(a)]
     return MOI.ScalarAffineFunction(terms, a.constant)
 end
+
+"""
+    moi_function(x)
+
+Given a JuMP object `x`, return the MathOptInterface equivalent.
+
+See also: [`jump_function`](@ref).
+"""
+function moi_function end
+
+"""
+    moi_function_type(::Type{T}) where {T}
+
+Given a JuMP object type `T`, return the MathOptInterface equivalent.
+
+See also: [`jump_function_type`](@ref).
+"""
+function moi_function_type end
+
+"""
+    jump_function(x)
+
+Given an MathOptInterface object `x`, return the JuMP equivalent.
+
+See also: [`moi_function`](@ref).
+"""
+function jump_function end
+
+"""
+    jump_function_type(::Type{T}) where {T}
+
+Given an MathOptInterface object type `T`, return the JuMP equivalent.
+
+See also: [`moi_function_type`](@ref).
+"""
+function jump_function_type end
+
 moi_function(a::GenericAffExpr) = MOI.ScalarAffineFunction(a)
 function moi_function_type(::Type{<:GenericAffExpr{T}}) where T
     return MOI.ScalarAffineFunction{T}
 end
 
-
 function AffExpr(m::Model, f::MOI.ScalarAffineFunction)
     aff = AffExpr()
     for t in f.terms

src/constraints.jl

@@ -340,7 +340,7 @@ end
 Return the function of the constraint `constraint` in the function-in-set form
 as a `AbstractJuMPScalar` or `Vector{AbstractJuMPScalar}`.
 """
-function jump_function end
+jump_function(constraint::AbstractConstraint) = constraint.func
 
 """
     moi_function(constraint::AbstractConstraint)
@@ -362,7 +362,7 @@ Return the set of the constraint `constraint` in the function-in-set form as a
 
 Returns the MOI set of dimension `dim` corresponding to the JuMP set `s`.
 """
-function moi_set end
+moi_set(constraint::AbstractConstraint) = constraint.set
 
 """
     constraint_object(con_ref::ConstraintRef)
@@ -385,8 +385,6 @@ struct ScalarConstraint{F <: AbstractJuMPScalar,
     set::S
 end
 
-jump_function(constraint::ScalarConstraint) = constraint.func
-moi_set(constraint::ScalarConstraint) = constraint.set
 reshape_set(set::MOI.AbstractScalarSet, ::ScalarShape) = set
 shape(::ScalarConstraint) = ScalarShape()
 
@@ -429,8 +427,6 @@ function VectorConstraint(func::Vector{<:AbstractJuMPScalar},
     VectorConstraint(func, set, VectorShape())
 end
 
-jump_function(constraint::VectorConstraint) = constraint.func
-moi_set(constraint::VectorConstraint) = constraint.set
 reshape_set(set::MOI.AbstractVectorSet, ::VectorShape) = set
 shape(con::VectorConstraint) = con.shape
 function constraint_object(con_ref::ConstraintRef{Model, _MOICON{FuncType, SetType}}) where