Re: doc patch: weakref.rb - against HEAD

Here is a patch against HEAD from CVS grabbed this afternoon,
which I think addresses the reservations expressed so far.

        HTH
        Hugh

--- ./lib/weakref.rb.orig	2006-07-31 07:31:38.000000000 +0100
+++ ./lib/weakref.rb	2006-08-02 18:37:26.917118000 +0100
@@ -1,11 +1,12 @@
 
 require "delegate"
 
-# Weak Reference class that does not bother GCing.  This allows the
-# referenced object to be garbage collected as if nothing else is
-# referring to it.  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.
+# WeakRef is a class to represent a reference to an object that is
+# not seen by the tracing phase of the garbage collector.  This
+# allows the referenced object to be garbage collected as if nothing
+# else is referring to it.  Because WeakRef delegates method calls
+# to the referenced object, it may be used in place of that object,
+# i.e.it is of the same Duck Type.
 #
 # Usage:
 #   foo = Object.new
@@ -80,7 +81,8 @@
   def __setobj__(obj)
   end
 
-  # Determine if this Weakref still refers to anything.
+  # Returns true if the referenced object still exists, and
+  # false if it has been garbage collected.
   def weakref_alive?
     @@id_rev_map[self.object_id] == @__id
   end