Permalink
Browse files

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
  • Loading branch information...
1 parent a0b46b5 commit 7dba51288fa2926e65afcc1022491a0f4e3c4d5c Erich Menge committed May 11, 2012
Showing with 26 additions and 1 deletion.
  1. +26 −1 activerecord/lib/active_record/core.rb
@@ -204,13 +204,38 @@ def init_with(coder)
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)

0 comments on commit 7dba512

Please sign in to comment.