From: Hugh Sasse <hgs@...>
Date: 2006-08-02T18:53:50+09:00
Subject: Re: doc patch: weakref.

On Wed, 2 Aug 2006, Eric Hodel wrote:

> On Aug 1, 2006, at 2:13 AM, Hugh Sasse wrote:
> > On Tue, 1 Aug 2006, Eric Hodel wrote:
> > > On Jul 31, 2006, at 3:20 AM, Hugh Sasse wrote:
> > > 
> > > > When this happens #weakref_alive? will return false.
> > > 
> > > I think this part of the description should be added to #weakref_alive?
> > 
> > I just thought something in the introductory text would provide context
> > for reading the other methods.
> 
> It also ends up being documented twice.

OK, violation of DRY in comments is probably as bad as code for maintennce.
I'll concede this.
> 
> > > > Because Weakref inherits from Delegator it passes method calls to the
> > > > object
> > > > from which it was constructed, so it is of the same Duck Type.
> > > 
> > > How about something like:
> > > 
> > > A Weakref delegates calls to the referenced object so it can be used in
> > > place of the real object.
> > 
> > My text explains the use of the constructor, helps support the docs
> > of Delegator (as a concrete example) and explains that it works because
> > of Duck Typing rather than anything else.
> > I feel your text leaves some of this unsaid.  But it would suffice
> 
> It is also an implementation detail.  I'd rather explain how it works than how
> it is implemented.  They can read the code to determine the implementation.

Not sure that's such a problem: the interface is unlikely to change
once established, and helping people understand how parts of the 
standard library work is the point of docs.  But I don't feel strongly 
about this.  It could be argued this violates DRY also, though.
> 
> > > > +  # Determine if this Weakref still refers to anything.
> > > >  def weakref_alive?
> > > >    @@id_rev_map[self.__id__] == @__id
> > > >  end
> > > 
> > > How about:
> > > 
> > > Returns false if the referenced object has been garbage collected.
> > 
> > It's a method ending in ? so we know it is a boolean. You text has
> > an implicit not in there i.e. "returns false if [...] garbage collected,
> > [returns true if it has not]"  which I think is less clear, because
> > it is the opposite sense to what the method name says.
> 
> I feel my description makes it most clear which states return which result.

OK, what about:

   # Returns true if the referenced object still exists, and
   # false if it has been garbage collected.

then?   
> 
        Hugh