From: Austin Ziegler <halostatue@...>
Date: 2005-11-09T05:41:59+09:00
Subject: Re: Object#clone missing documentation

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.

-austin
--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca