Improve verbiage around let statements and variable initialization

src/statements.md

@@ -42,12 +42,13 @@ fn outer() {
 
 ### `let` statements
 
-A *`let` statement* introduces a new set of variables, given by a pattern. The
-pattern may be followed by a type annotation, and/or an initializer expression.
-When no type annotation is given, the compiler will infer the type, or signal
-an error if insufficient type information is available for definite inference.
-Any variables introduced by a variable declaration are visible from the point of
-declaration until the end of the enclosing block scope.
+A *`let` statement* introduces a new set of [variables], given by a pattern. The
+pattern is followed optionally by a type annotation and then optionally by an
+initializer expression. When no type annotation is given, the compiler will
+infer the type, or signal an error if insufficient type information is
+available for definite inference. Any variables introduced by a variable
+declaration are visible from the point of declaration until the end of the
+enclosing block scope.
 
 ## Expression statements
 
@@ -96,3 +97,4 @@ if true {
 [module]: items/modules.html
 [canonical path]: paths.html#canonical-paths
 [implementations]: items/implementations.html
+[variables]: variables.html

src/variables.md

@@ -7,15 +7,17 @@ variable.
 A _local variable_ (or *stack-local* allocation) holds a value directly,
 allocated within the stack's memory. The value is a part of the stack frame.
 
-Local variables are immutable unless declared otherwise. For example: `let mut x = ...`.
+Local variables are immutable unless declared otherwise. For example:
+`let mut x = ...`.
 
 Function parameters are immutable unless declared with `mut`. The `mut` keyword
-applies only to the following parameter. For example: `|mut x, y|` and `fn f(mut x:
-Box<i32>, y: Box<i32>)` declare one mutable variable `x` and one immutable
-variable `y`.
+applies only to the following parameter. For example: `|mut x, y|` and 
+`fn f(mut x: Box<i32>, y: Box<i32>)` declare one mutable variable `x` and one
+immutable variable `y`.
 
 Methods that take either `self` or `Box<Self>` can optionally place them in a
-mutable variable by prefixing them with `mut` (similar to regular arguments). For example:
+mutable variable by prefixing them with `mut` (similar to regular arguments).
+For example:
 
 ```rust
 trait Changer: Sized {
@@ -24,8 +26,29 @@ trait Changer: Sized {
 }
 ```
 
-Local variables are not initialized when allocated. Instead, the entire frame worth of
-local variables are allocated, on frame-entry, in an uninitialized
+Local variables are not initialized when allocated. Instead, the entire frame
+worth of local variables are allocated, on frame-entry, in an uninitialized
 state. Subsequent statements within a function may or may not initialize the
 local variables. Local variables can be used only after they have been
-initialized; this is enforced by the compiler.
+initialized through all reachable control flow paths.
+
+In this next example, `init_after_if` is initialized after the [`if` expression]
+while `uninit_after_if` is not because it is not initialized in the `else` case.
+
+```rust
+# fn random_bool() -> bool { true }
+fn initialization_example() {
+    let init_after_if: ();
+    let uninit_after_if: ();
+
+    if random_bool() {
+        init_after_if = ();
+        uninit_after_if = ();
+    } else {
+        init_after_if = ();
+    }
+
+    init_after_if; // ok
+    // uninit_after_if; // err: use of possibly uninitialized `uninit_after_if`
+}
+```