Re: doc patch: weakref.

On Sun, 30 Jul 2006, Mauricio Fernandez wrote:

> 
> Some people don't know how Ruby's GC works, or even what a mark&sweep GC is.
> They wouldn't understand what the above means (maybe).
> 
> "WeakRef is a class to represent a reference to an object that may be
> reclaimed by the GC. The WeakRef is invalidated when this happens."

OK, how is this?
        Hugh


--- ./lib/weakref.rb.orig	2003-12-10 08:26:36.000000000 +0000
+++ ./lib/weakref.rb	2006-07-31 10:40:01.154757000 +0100
@@ -1,4 +1,14 @@
-# Weak Reference class that does not bother GCing.
+
+require "delegate"
+
+# 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.  When
+# this happens #weakref_alive? will return false.  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.
 #
 # Usage:
 #   foo = Object.new
@@ -8,11 +18,9 @@
 #   p foo.to_s			# should be same class
 #   ObjectSpace.garbage_collect
 #   p foo.to_s			# should raise exception (recycled)
-
-require "delegate"
-
 class WeakRef<Delegator
 
+  # RefError is raised if an object cannot be referenced by a WeakRef.
   class RefError<StandardError
   end
 
@@ -40,6 +48,7 @@
     end
   }
 
+  # Create a new WeakRef from +orig+.
   def initialize(orig)
     super
     @__id = orig.__id__
@@ -56,6 +65,9 @@
     @@id_rev_map[self.__id__] = @__id
   end
 
+  # Return the object this WeakRef references. Raise
+  # RefError if this is impossible.  The object is that
+  # to which method calls are delegated (see Delegator).
   def __getobj__
     unless @@id_rev_map[self.__id__] == @__id
       raise RefError, "Illegal Reference - probably recycled", caller(2)
@@ -67,6 +79,7 @@
     end
   end
 
+  # Determine if this Weakref still refers to anything.
   def weakref_alive?
     @@id_rev_map[self.__id__] == @__id
   end