Re: doc patch: weakref.

On Tue, 1 Aug 2006, Eric Hodel wrote:

> On Jul 31, 2006, at 3:20 AM, Hugh Sasse wrote:
> 
> > An object may be reclaimed by the garbage collector if there are
> > no references to it.  A Weakref represents a reference the garbage
> > collector will ignore,  This allows the referenced object to be
> > garbage collected as if nothing else is referring to it.
> 
> I think this is good enough.
> 
> > 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.
> 
> > 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
> 
> > +  # 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.

> 
        Thank you,
        Hugh