* doc/syntax/refinements.rdoc: add description of Module#using and

  refinement inheritance by module inclusion.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@41746 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 26 insertions, 1 deletions

diff --git a/doc/syntax/refinements.rdoc b/doc/syntax/refinements.rdoc
index 7b3f0f6127..519082e2f9 100644
--- a/doc/syntax/refinements.rdoc
+++ b/doc/syntax/refinements.rdoc
@@ -48,7 +48,7 @@ Activate the refinement with #using:
 
 == Scope
 
-You may only activate refinements at top-level to the end of the file or in a
+You may activate refinements at top-level to the end of the file or in a
 string passed to Kernel#eval, Kernel#instance_eval or Kernel#module_eval until
 the end of the string.
 
@@ -186,6 +186,25 @@ called:
 
   p [{1=>2}, {3=>4}].to_json # prints "[{\"1\":2},{\"3\":4}]"
 
+You may also activate refinements in a class or module definition, in which
+case the refinements are activated from the point where using is called to
+the end of the class or module definition:
+
+  # not activated here
+  class Foo
+    # not activated here
+    using M
+    # activated here
+    def foo
+      # activated here
+    end
+    # activated here
+  end
+  # not activated here
+
+Note that the refinements in M are not activated automatically even if the class
+Foo is reopened later.
+
 == Method Lookup
 
 When looking up a method for an instance of class +C+ Ruby checks:
@@ -232,6 +251,12 @@ method lookup.
 
 This behavior may be changed in the future.
 
+== Refinements and module inclusion
+
+Refinements are inherited by module inclusion.  That is, using activates all
+refinements in the ancestors of the specified module.  Refinements in a
+descendant have priority over refinements in an ancestor.
+
 == Further Reading
 
 See http://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RefinementsSpec for the