From a0f4b6987537a8e09329f9a983e0e37828ae2d38 Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Fri, 20 Nov 2020 02:26:20 -0800
Subject: [PATCH] Referencify Assignment Operator

I'm being wish-washy with expression/operand in the syntax section. I'm
not quite sure if we should call them `place operands` everywhere.
---
 src/expressions/operator-expr.md | 44 ++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/src/expressions/operator-expr.md b/src/expressions/operator-expr.md
index c48eccced..7cd859824 100644
--- a/src/expressions/operator-expr.md
+++ b/src/expressions/operator-expr.md
@@ -409,20 +409,35 @@ halfway between two floating point numbers.
 > _AssignmentExpression_ :\
 > &nbsp;&nbsp; [_Expression_] `=` [_Expression_]
 
-An _assignment expression_ consists of a [place expression] followed by an
-equals sign (`=`) and a [value expression]. Such an expression always has
-the [`unit` type].
-
-Evaluating an assignment expression [drops](../destructors.md) the left-hand
-operand, unless it's an uninitialized local variable or field of a local variable,
-and [either copies or moves](../expressions.md#moved-and-copied-types) its
-right-hand operand to its left-hand operand. The left-hand operand must be a
-place expression: using a value expression results in a compiler error, rather
+An *assignment expression* moves a value into a specified place.
+
+An assignment expression consists of a [mutable] [place expression], the
+*assigned place operand*, followed by an equals sign (`=`) and a [value
+expression], the *assigned value operand*.
+
+Unlike other place operands, the assigned place operand must be a place
+expression. Attempting to use a value expression is a compiler error rather
 than promoting it to a temporary.
 
+Evaluating assignment expressions begins by evaluating its operands. The
+assigned value operand is evaluated first, followed by the assigned place
+operand.
+
+> **Note**: This is different than other expressions in that the right operand
+> is evaluated before the left one.
+
+It then has the effect of first [dropping] the value at the assigned place,
+unless the place is an uninitialized local variable or field of a local
+variable. Next it either [copies or moves] the assigned value to the assigned
+place.
+
+An assignment expression always produces [the unit value][unit].
+
+Example:
+
 ```rust
-# let mut x = 0;
-# let y = 0;
+let mut x = 0;
+let y = 0;
 x = y;
 ```
 
@@ -444,7 +459,7 @@ x = y;
 The `+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, and `>>` operators may be
 composed with the `=` operator. The expression `place_exp OP= value` is
 equivalent to `place_expr = place_expr OP val`. For example, `x = x + 1` may be
-written as `x += 1`. Any such expression always has the [`unit` type].
+written as `x += 1`. Any such expression always has the [`unit` type][unit].
 These operators can all be overloaded using the trait with the same name as for
 the normal operation followed by 'Assign', for example, `std::ops::AddAssign`
 is used to overload `+=`. As with `=`, `place_expr` must be a [place
@@ -456,11 +471,14 @@ x += 4;
 assert_eq!(x, 14);
 ```
 
+[copies or moves]: ../expressions.md#moved-and-copied-types
+[dropping]: ../destructors.md
+[mutable]: ../expressions.md#mutability
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
+[unit]: ../types/tuple.md
 [value expression]: ../expressions.md#place-expressions-and-value-expressions
 [temporary value]: ../expressions.md#temporaries
 [float-float]: https://github.com/rust-lang/rust/issues/15536
-[`unit` type]: ../types/tuple.md
 [Function pointer]: ../types/function-pointer.md
 [Function item]: ../types/function-item.md