Re: doc patch: weakref.

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.

>>> 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.

>>> +  # 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.

-- 
Eric Hodel - [e-mail] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com