Better document the difference between #clone and #dup.

Add #nodoc to initialize_dup and use :method: to document the #dup method.
Relates to issue #6235

1 files changed, 26 insertions, 1 deletions

diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb
index a869ed8c04..f376cd034a 100644
--- a/activerecord/lib/active_record/core.rb
+++ b/activerecord/lib/active_record/core.rb
@@ -204,13 +204,38 @@ module ActiveRecord
 
       self
     end
-
+    
+    ##
+    # :method: clone
+    # Identical to Ruby's clone method.  This is a "shallow" copy.  Be warned that your attributes are not copied.
+    # That means that modifying attributes of the clone will modify the original, since they will both point to the
+    # same attributes hash.  If you need a copy of your attributes hash, please use the #dup method.
+    #
+    # Example: 
+    #
+    #   user = User.first
+    #   new_user = user.clone
+    #   user.name               # => "Bob"
+    #   new_user.name = "Joe"
+    #   user.name               # => "Joe"
+    #
+    #   user.object_id == new_user.object_id            # => false
+    #   user.name.object_id == new_user.name.object_id  # => true
+    # 
+    # Use #dup instead, for a copy of the attributes hash.
+    #   user.name.object_id == user.dup.name.object_id  # => false
+    
+    ##
+    # :method: dup
     # Duped objects have no id assigned and are treated as new records. Note
     # that this is a "shallow" copy as it copies the object's attributes
     # only, not its associations. The extent of a "deep" copy is application
     # specific and is therefore left to the application to implement according
     # to its need.
     # The dup method does not preserve the timestamps (created|updated)_(at|on).
+    
+    ##
+    # :nodoc:
     def initialize_dup(other)
       cloned_attributes = other.clone_attributes(:read_attribute_before_type_cast)
       self.class.initialize_attributes(cloned_attributes)