From: Eero Saynatkari <ruby-ml@...>
Date: 2005-11-08T18:40:52+09:00
Subject: Re: Object#clone missing documentation

Kev Jackson wrote:
> I've attached a documentation patch which tries to address this 
> shortcoming.
> 
> Kev
> 
> 
> ------------------------------------------------------------------------
> 
> Index: object.c
> ===================================================================
> RCS file: /src/ruby/object.c,v
> retrieving revision 1.181
> diff -u -r1.181 object.c
> --- object.c	22 Oct 2005 04:08:55 -0000	1.181
> +++ object.c	8 Nov 2005 06:21:04 -0000
> @@ -239,8 +239,26 @@
>   *  the discussion under <code>Object#clone</code>. In general,
>   *  <code>clone</code> and <code>dup</code> may have different semantics
>   *  in descendent classes. While <code>clone</code> is used to duplicate
> - *  an object, including its internal state, <code>dup</code> typically
> - *  uses the class of the descendent object to create the new instance.
> + *  an object, including its internal state (and any singleton methods),
> + *  <code>dup</code> typically uses the class of the descendent object to 
> + *  create the new instance.

Mm, not quite sure that is clear enough.. if you want to draw a direct
parallel to #dup, perhaps something like

"While both #dup and #clone duplicate the content of an object, #clone actually
  does more by duplicating the object's entire state including singleton methods,
  taintedness and whether the object is frozen."

> + *  # new class
> + *  class Klass
> + *     attr_reader :str
> + *   end
> + *   k1 = Klass.new   #=> #<Klass:0x401b3a38>
> + *   #add singleton method
> + *   def k1.str=(s)
> + *     @str = s
> + *   end                 #=> nil
> + *   k1.str="hello!"   #=> "hello!"
> + *   k1.str              #=> "hello!"
> + *   #clone object - the singleton method just added will be included in the
> + *   #new object
> + *   k2 = k1.clone    #=> #<Klass:0x29392c8 @str="hello!">
> + *   k2.str="goodbye!" #=> "goodbye!"
> + *   k2.str                #=> "goodbye!"
>   *
>   *  This method may have class-specific behavior.  If so, that
>   *  behavior will be documented under the #+initialize_copy+ method of


E