From 25513543ffe6308352f3724f0be2332dda4cde62 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Thu, 30 Jun 2011 00:37:00 +0000
Subject: [PATCH] 	* lib/weakref.rb:  Attach documentation to WeakRef and
 add missing 	  documentation

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32314 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog      |  5 +++++
 lib/weakref.rb | 26 ++++++++++++++++++++------
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c5c6c93ebe..02a91c70c8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Thu Jun 30 09:36:37 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/weakref.rb:  Attach documentation to WeakRef and add missing
+	  documentation
+
 Thu Jun 30 09:30:14 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/yaml.rb:  Document toplevel YAML and YAML::ENGINE to describe
diff --git a/lib/weakref.rb b/lib/weakref.rb
index b3f3856db9..efb853050d 100644
--- a/lib/weakref.rb
+++ b/lib/weakref.rb
@@ -1,6 +1,12 @@
-# Weak Reference class that does not bother GCing.
+require "delegate"
+require 'thread'
+
+# Weak Reference class that does allows a referenced object to be
+# garbage-collected.  A WeakRef may be used exactly like the object it
+# references.
 #
 # Usage:
+#
 #   foo = Object.new
 #   foo = Object.new
 #   p foo.to_s                  # original's class
@@ -9,11 +15,12 @@
 #   ObjectSpace.garbage_collect
 #   p foo.to_s                  # should raise exception (recycled)
 
-require "delegate"
-require 'thread'
-
 class WeakRef < Delegator
 
+  ##
+  # RefError is raised when a referenced object has been recycled by the
+  # garbage collector
+
   class RefError < StandardError
   end
 
@@ -38,6 +45,9 @@ class WeakRef < Delegator
     }
   }
 
+  ##
+  # Creates a weak reference to +orig+
+
   def initialize(orig)
     @__id = orig.object_id
     ObjectSpace.define_finalizer orig, @@final
@@ -50,7 +60,7 @@ class WeakRef < Delegator
     super
   end
 
-  def __getobj__
+  def __getobj__ # :nodoc:
     unless @@id_rev_map[self.object_id] == @__id
       Kernel::raise RefError, "Invalid Reference - probably recycled", Kernel::caller(2)
     end
@@ -60,9 +70,13 @@ class WeakRef < Delegator
       Kernel::raise RefError, "Invalid Reference - probably recycled", Kernel::caller(2)
     end
   end
-  def __setobj__(obj)
+
+  def __setobj__(obj) # :nodoc:
   end
 
+  ##
+  # Returns true if the referenced object is still alive.
+
   def weakref_alive?
     @@id_rev_map[self.object_id] == @__id
   end