* lib/weakref.rb (rdoc): Clean up usage, add example,

note ArgumentError on WeakRef.new


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38139 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Sun Dec  2 16:48:00 2012  Zachary Scott  <zachary@zacharyscott.net>
+
+	* lib/weakref.rb (rdoc): Clean up usage, add example,
+	  note ArgumentError on WeakRef.new
+
 Sun Dec  2 16:45:00 2012  Zachary Scott  <zachary@zacharyscott.net>
 
 	* gc.c (WeakMap): Add doc for internal reference, use lib/weakref.rb

lib/weakref.rb

@@ -1,18 +1,66 @@
 require "delegate"
 
 # Weak Reference class that allows a referenced object to be
-# garbage-collected.  A WeakRef may be used exactly like the object it
-# references.
+# garbage-collected.
+#
+# A WeakRef may be used exactly like the object it references.
 #
 # Usage:
 #
-#   foo = Object.new
-#   foo = Object.new
+#   foo = Object.new            # create a new object instance
 #   p foo.to_s                  # original's class
-#   foo = WeakRef.new(foo)
+#   foo = WeakRef.new(foo)      # reassign foo with WeakRef instance
 #   p foo.to_s                  # should be same class
-#   ObjectSpace.garbage_collect
+#   GC.start                    # start the garbage collector
 #   p foo.to_s                  # should raise exception (recycled)
+#
+# == Example
+#
+# With help from WeakRef, we can implement our own redimentary WeakHash class.
+#
+# We will call it WeakHash, since it's really just a Hash except all of it's
+# keys and values can be garbage collected.
+#
+#     require 'weakref'
+#
+#     class WeakHash < Hash
+#       def []= key, obj
+#         super WeakRef.new(key), WeakRef.new(obj)
+#       end
+#     end
+#
+# This is just a simple implementation, we've opened the Hash class and changed
+# Hash#store to create a new WeakRef object with +key+ and +obj+ parameters
+# before passing them as our key-value pair to the hash.
+#
+# With this you will have to limit your self to String key's, otherwise you
+# will get an ArgumentError because WeakRef cannot create a finalizer for a
+# Symbol. Symbols are immutable and cannot be garbage collected.
+#
+# Let's see it in action:
+#
+#   omg = "lol"
+#   c = WeakHash.new
+#   c['foo'] = "bar"
+#   c['baz'] = Object.new
+#   c['qux'] = omg
+#   puts c.inspect
+#   #=> {"foo"=>"bar", "baz"=>#<Object:0x007f4ddfc6cb48>, "qux"=>"omg"}
+#
+#   # Now run the garbage collector
+#   GC.start
+#   c['foo'] #=> nil
+#   c['baz'] #=> nil
+#   c['qux'] #=> nil
+#   omg      #=> "lol"
+#
+#   puts c.inspect
+#   #=> WeakRef::RefError: Invalid Reference - probably recycled
+#
+# You can see the local variable +omg+ stayed, although it's reference in our
+# hash object was garbage collected, along with the rest of the keys and
+# values. Also, when we tried to inspect our hash, we got a WeakRef::RefError,
+# this is because these objects were also garbage collected.
 
 class WeakRef < Delegator
 
@@ -27,6 +75,9 @@ class WeakRef < Delegator
 
   ##
   # Creates a weak reference to +orig+
+  #
+  # Raises an ArgumentError if the given +orig+ is immutable, such as Symbol,
+  # Fixnum, or Float.
 
   def initialize(orig)
     case orig