Clarify usage of add_to_expression! in docs

docs/src/manual/expressions.md

@@ -126,6 +126,32 @@ julia> add_to_expression!(ex, 1.0, y)
 2 x + y - 1
 ```
 
+This is a efficient way to combine previously created expressions.
+
+```jldoctest
+julia> model = Model();
+
+julia> @variable(model, x[1:2])
+2-element Vector{VariableRef}:
+ x[1]
+ x[2]
+
+julia> ex1 = @expression(model, sum(x[1:2]))
+x[1] + x[2]
+
+julia> ex2 = @expression(model, 2 * sum(x[1:2]))
+2 x[1] + 2 x[2]
+
+julia> add_to_expression!(ex1, ex2)
+3 x[1] + 3 x[2]
+
+julia> ex1
+3 x[1] + 3 x[2]
+
+julia> ex2
+2 x[1] + 2 x[2]
+```
+
 !!! warning
     Read the section [Initializing arrays](@ref) for some cases to be careful
     about when using [`add_to_expression!`](@ref).

src/aff_expr.jl

@@ -514,6 +514,30 @@ julia> add_to_expression!(expr, 3, x)
 julia> expr
 4 x + 2
 ```
+
+```jldoctest
+julia> model = Model();
+
+julia> @variable(model, x[1:2])
+2-element Vector{VariableRef}:
+ x[1]
+ x[2]
+
+julia> ex1 = @expression(model, sum(x[1:2]))
+x[1] + x[2]
+
+julia> ex2 = @expression(model, 2 * sum(x[1:2]))
+2 x[1] + 2 x[2]
+
+julia> add_to_expression!(ex1, ex2)
+3 x[1] + 3 x[2]
+
+julia> ex1
+3 x[1] + 3 x[2]
+
+julia> ex2
+2 x[1] + 2 x[2]
+```
 """
 function add_to_expression! end