1 files changed, 29 insertions, 7 deletions
diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc
index adfe6485a4..a1806e4c48 100644
--- a/doc/syntax/assignment.rdoc
+++ b/doc/syntax/assignment.rdoc
@@ -1,6 +1,6 @@
 = Assignment
 
-In Ruby assignment uses the <code>=</code> (equals sign) character.  This
+In Ruby, assignment uses the <code>=</code> (equals sign) character.  This
 example assigns the number five to the local variable +v+:
 
   v = 5
@@ -92,8 +92,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+:
 
@@ -109,6 +110,28 @@ 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.
@@ -137,7 +160,7 @@ Here is an example of instance variable usage:
   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
+warnings enabled, you will get a warning when accessing an uninitialized
 instance variable.
 
 The +value+ method has access to the value set by the +initialize+ method, but
@@ -279,7 +302,7 @@ to an instance variable most people use Module#attr_accessor:
   end
 
 When using method assignment you must always have a receiver.  If you do not
-have a receiver Ruby assumes you are assigning to a local variable:
+have a receiver, Ruby assumes you are assigning to a local variable:
 
   class C
     attr_accessor :value
@@ -409,7 +432,7 @@ You can use multiple assignment to swap two values in-place:
   # prints {:new_value=>1, :old_value=>2}
 
 If you have more values on the right hand side of the assignment than variables
-on the left hand side the extra values are ignored:
+on the left hand side, the extra values are ignored:
 
   a, b = 1, 2, 3
 
@@ -452,4 +475,3 @@ Since each decomposition is considered its own multiple assignment you can use
 
   p a: a, b: b, c: c, d: d
   # prints {:a=>1, :b=>2, :c=>[3, 4], :d=>[5, 6]}
-