1 files changed, 66 insertions, 13 deletions
diff --git a/doc/syntax/modules_and_classes.rdoc b/doc/syntax/modules_and_classes.rdoc
index f4ab1ea6f9..9e05c5c774 100644
--- a/doc/syntax/modules_and_classes.rdoc
+++ b/doc/syntax/modules_and_classes.rdoc
@@ -4,8 +4,8 @@ Modules serve two purposes in Ruby, namespacing and mix-in functionality.
 
 A namespace can be used to organize code by package or functionality that
 separates common names from interference by other packages.  For example, the
-Curses namespace provides functionality for curses that prevents a collision
-for the common name "Window".
+IRB namespace provides functionality for irb that prevents a collision
+for the common name "Context".
 
 Mix-in functionality allows sharing common methods across multiple classes or
 modules.  Ruby comes with the Enumerable mix-in module which provides many
@@ -40,9 +40,9 @@ functionality:
     remove_method :my_method
   end
 
-Reopening classes is a very powerful feature of Ruby, but it is best to only
-reopen classes you own.  Reopening classes you do not own may lead to naming
-conflicts or difficult to diagnose bugs.
+Reopening modules (or classes) is a very powerful feature of Ruby, but it is
+best to only reopen modules you own.  Reopening modules you do not own may lead
+to naming conflicts or difficult to diagnose bugs.
 
 == Nesting
 
@@ -94,7 +94,7 @@ nesting:
   end
 
 However, if you use <code>::</code> to define <code>A::B</code> without
-nesting it inside +A+ a NameError exception will be raised because the nesting
+nesting it inside +A+, a NameError exception will be raised because the nesting
 does not include +A+:
 
   module A
@@ -129,7 +129,7 @@ method on a module is often called a "class method" instead of a "module
 method".  See also Module#module_function which can convert an instance method
 into a class method.)
 
-When a class method references a constant it uses the same rules as referencing
+When a class method references a constant, it uses the same rules as referencing
 it outside the method as the scope is the same.
 
 Instance methods defined in a module are only callable when included.  These
@@ -155,8 +155,8 @@ Ruby has three types of visibility.  The default is +public+.  A public method
 may be called from any other object.
 
 The second visibility is +protected+.  When calling a protected method the
-sender must be a subclass of the receiver or the receiver must be a subclass of
-the sender.  Otherwise a NoMethodError will be raised.
+sender must inherit the Class or Module which defines the method.  Otherwise a
+NoMethodError will be raised.
 
 Protected visibility is most frequently used to define <code>==</code> and
 other comparison methods where the author does not wish to expose an object's
@@ -190,9 +190,41 @@ Here is an example:
   b.n b #=> 1 -- m called on defining class
   a.n b # raises NoMethodError A is not a subclass of B
 
-The third visibility is +private+.  A private method may not be called with a
-receiver, not even +self+.  If a private method is called with a receiver a
-NoMethodError will be raised.
+The third visibility is +private+.  A private method may only be called from
+inside the owner class without a receiver, or with a literal +self+
+as a receiver.  If a private method is called with a
+receiver other than a literal +self+, a NoMethodError will be raised.
+
+  class A
+    def without
+      m
+    end
+
+    def with_self
+      self.m
+    end
+
+    def with_other
+      A.new.m
+    end
+
+    def with_renamed
+      copy = self
+      copy.m
+    end
+
+    def m
+      1
+    end
+
+    private :m
+  end
+
+  a = A.new
+  a.without      #=> 1
+  a.with_self    #=> 1
+  a.with_other   # NoMethodError (private method `m' called for #<A:0x0000559c287f27d0>)
+  a.with_renamed # NoMethodError (private method `m' called for #<A:0x0000559c285f8330>)
 
 === +alias+ and +undef+
 
@@ -227,6 +259,28 @@ includes a minimum of built-in methods.  You can use BasicObject to create an
 independent inheritance structure.  See the BasicObject documentation for
 further details.
 
+Just like modules, classes can also be reopened.  You can omit its superclass
+when you reopen a class.  Specifying a different superclass than the previous
+definition will raise an error.
+
+  class C
+  end
+
+  class D < C
+  end
+
+  # OK
+  class D < C
+  end
+
+  # OK
+  class D
+  end
+
+  # TypeError: superclass mismatch for class D
+  class D < String
+  end
+
 == Inheritance
 
 Any method defined on a class is callable from its subclass:
@@ -342,4 +396,3 @@ is equivalent to this code block:
   end
 
 Both objects will have a +my_method+ that returns +2+.
-