* 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

2 files changed, 31 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index d12917ae16..197e7a360a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Tue Jul  2 17:23:33 2013  Shugo Maeda  <shugo@ruby-lang.org>
+
+	* doc/syntax/refinements.rdoc: add description of Module#using and
+	  refinement inheritance by module inclusion.
+
 Tue Jul  2 17:22:44 2013  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* internal.h: add EUC-JP and Windows-31J.
@@ -38,8 +43,6 @@ Tue Jul  2 17:22:44 2013  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 Tue Jul  2 11:14:36 2013  Shota Fukumori  <sorah@cookpad.com>
 
-Tue Jul  2 11:14:36 2013  Shota Fukumori  <sorah@cookpad.com>
-
 	* lib/mkmf.rb (try_config): Fix to not replace $LDFLAGS with $libs
 	  (1.9.3 behavior) [ruby-core:55752] [Bug #8595]
 
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