From: Eero Saynatkari <ruby-ml@...>
Date: 2005-11-09T06:02:58+09:00
Subject: Re: Object#clone missing documentation

Austin Ziegler wrote:
> On 11/8/05, Eero Saynatkari <ruby-ml@magical-cat.org> wrote:
> 
>>Austin Ziegler wrote:
>>
>>>>> *  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."
>>>
>>>The text should be tighter than that.
>>
>>I think clarity should be overriding :) How about the original then?
> 
> 
> The problem is that your rewrite added lots of words with little
> clarity. My attempt was to fuse the two without adding words that have
> no value (e.g., "actually", a few other things). Fewer words are
> generally clearer than more words. In Ruby documentation, all words
> should have meaning.

My apologies, I thought the section at the bottom was just a quote
from the patch. I see my error now.

> -austin

E