From 6869a65a8c6801984ae5bfc1b793843933925ef6 Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Thu, 21 Nov 2013 05:19:32 +0000
Subject: * object.c: [DOC] Clarify Object#dup vs #clone [Bug #9128]   Moving
 existing doc for this comparison to separate section of #dup   Adding
 examples to document behavior of #dup with Module#extend.   Based on a patch
 by stevegoobermanhill

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43747 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog |  7 +++++++
 object.c  | 39 ++++++++++++++++++++++++++++++++-------
 2 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4bb0548e0e..861d11110c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Thu Nov 21 14:18:24 2013  Zachary Scott  <e@zzak.io>
+
+	* object.c: [DOC] Clarify Object#dup vs #clone [Bug #9128]
+	  Moving existing doc for this comparison to separate section of #dup
+	  Adding examples to document behavior of #dup with Module#extend.
+	  Based on a patch by stevegoobermanhill
+
 Thu Nov 21 14:06:02 2013  Koichi Sasada  <ko1@atdot.net>
 
 	* gc.c (gc_marks_check): do not dump all refs.
diff --git a/object.c b/object.c
index e7b61d6687..70f6d66e5e 100644
--- a/object.c
+++ b/object.c
@@ -356,17 +356,42 @@ rb_obj_clone(VALUE obj)
  *     obj.dup -> an_object
  *
  *  Produces a shallow copy of <i>obj</i>---the instance variables of
- *  <i>obj</i> are copied, but not the objects they reference.
- *  <code>dup</code> copies the tainted state of <i>obj</i>. See also
- *  the discussion under <code>Object#clone</code>. In general,
- *  <code>clone</code> and <code>dup</code> may have different semantics
- *  in descendant classes. While <code>clone</code> is used to duplicate
- *  an object, including its internal state, <code>dup</code> typically
- *  uses the class of the descendant object to create the new instance.
+ *  <i>obj</i> are copied, but not the objects they reference. <code>dup</code>
+ *  copies the tainted state of <i>obj</i>.
  *
  *  This method may have class-specific behavior.  If so, that
  *  behavior will be documented under the #+initialize_copy+ method of
  *  the class.
+ *
+ *  === on dup vs clone
+ *
+ *  In general, <code>clone</code> and <code>dup</code> may have different
+ *  semantics in descendant classes. While <code>clone</code> is used to
+ *  duplicate an object, including its internal state, <code>dup</code>
+ *  typically uses the class of the descendant object to create the new
+ *  instance.
+ *
+ *  When using #dup any modules that the object has been extended with will not
+ *  be copied.
+ *
+ *	class Klass
+ *	  attr_accessor :str
+ *	end
+ *
+ *	module Foo
+ *	  def foo; 'foo'; end
+ *	end
+ *
+ *	s1 = Klass.new #=> #<Klass:0x401b3a38>
+ *	s1.extend(Foo) #=> #<Klass:0x401b3a38>
+ *	s1.foo #=> "foo"
+ *
+ *	s2 = s1.clone #=> #<Klass:0x401b3a38>
+ *	s2.foo #=> "foo"
+ *
+ *	s3 = s1.dup #=> #<Klass:0x401b3a38>
+ *	s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401b3a38>
+ *
  */
 
 VALUE
-- 
cgit v1.2.3