1 files changed, 38 insertions, 7 deletions

diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc
index 83300cbece..3988f82e5f 100644
--- a/doc/syntax/assignment.rdoc
+++ b/doc/syntax/assignment.rdoc
@@ -8,6 +8,9 @@ example assigns the number five to the local variable +v+:
 Assignment creates a local variable if the variable was not previously
 referenced.
 
+An assignment expression result is always the assigned value, including
+{assignment methods}[rdoc-ref:@Assignment+Methods].
+
 == Local Variable Names
 
 A local variable name must start with a lowercase US-ASCII letter or a
@@ -92,8 +95,9 @@ Now any reference to +big_calculation+ is considered a local variable and will
 be cached.  To call the method, use <code>self.big_calculation</code>.
 
 You can force a method call by using empty argument parentheses as shown above
-or by using an explicit receiver like <code>self.</code>.  Using an explicit
-receiver may raise a NameError if the method's visibility is not public.
+or by using an explicit receiver like <code>self</code>.  Using an explicit
+receiver may raise a NameError if the method's visibility is not public or the
+receiver is the literal <code>self</code>.
 
 Another commonly confusing case is when using a modifier +if+:
 
@@ -103,12 +107,34 @@ Rather than printing "true" you receive a NameError, "undefined local variable
 or method `a'".  Since ruby parses the bare +a+ left of the +if+ first and has
 not yet seen an assignment to +a+ it assumes you wish to call a method.  Ruby
 then sees the assignment to +a+ and will assume you are referencing a local
-method.
+variable.
 
 The confusion comes from the out-of-order execution of the expression.  First
 the local variable is assigned-to then you attempt to call a nonexistent
 method.
 
+== Local Variables and eval
+
+Using +eval+ to evaluate Ruby code will allow access to local variables defined
+in the same scope, even if the local variables are not defined until after the
+call to +eval+.  However, local variables defined inside the call to +eval+
+will not be reflected in the surrounding scope.  Inside the call to +eval+,
+local variables defined in the surrounding scope and local variables defined
+inside the call to +eval+ will be accessible.  However, you will not be able
+to access local variables defined in previous or subsequent calls to +eval+ in
+the same scope. Consider each +eval+ call a separate nested scope. Example:
+
+  def m
+    eval "bar = 1"
+    lvs = eval "baz = 2; ary = [local_variables, foo, baz]; x = 2; ary"
+    eval "quux = 3"
+    foo = 1
+    lvs << local_variables
+  end
+
+  m
+  # => [[:baz, :ary, :x, :lvs, :foo], nil, 2, [:lvs, :foo]]
+
 == Instance Variables
 
 Instance variables are shared across all methods for the same object.
@@ -136,9 +162,7 @@ Here is an example of instance variable usage:
   p object1.value # prints "some value"
   p object2.value # prints "other value"
 
-An uninitialized instance variable has a value of +nil+.  If you run Ruby with
-warnings enabled, you will get a warning when accessing an uninitialized
-instance variable.
+An uninitialized instance variable has a value of +nil+.
 
 The +value+ method has access to the value set by the +initialize+ method, but
 only for the same object.
@@ -255,7 +279,7 @@ An uninitialized global variable has a value of +nil+.
 
 Ruby has some special globals that behave differently depending on context
 such as the regular expression match variables or that have a side-effect when
-assigned to.  See the {global variables documentation}[rdoc-ref:globals.rdoc]
+assigned to.  See the {global variables documentation}[rdoc-ref:language/globals.md]
 for details.
 
 == Assignment Methods
@@ -319,6 +343,9 @@ This prints:
   local_variables:
   @value: 42
 
+Note that the value returned by an assignment method is ignored whatever,
+since an assignment expression result is always the assignment value.
+
 == Abbreviated Assignment
 
 You can mix several of the operators and assignment.  To add 1 to an object
@@ -374,6 +401,10 @@ assigning.  This is similar to multiple assignment:
 
   p a # prints [1, 2, 3]
 
+  b = *1
+
+  p b # prints [1]
+
 You can splat anywhere in the right-hand side of the assignment:
 
   a = 1, *[2, 3]