Documentation cleanup.

Includes patches by Hugh Sasse:
* ping.rb
* weakref.rb
* mailread.rb


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

1 files changed, 12 insertions, 10 deletions

diff --git a/lib/weakref.rb b/lib/weakref.rb
index bc1b916619..b1c430523b 100644
--- a/lib/weakref.rb
+++ b/lib/weakref.rb
@@ -1,13 +1,13 @@
-
 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 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
 #   foo = Object.new
 #   p foo.to_s			# original's class
@@ -64,9 +64,9 @@ class WeakRef<Delegator
     super
   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).
+  # Return the object this WeakRef references. Raises RefError if the object
+  # has been garbage collected.  The object returned is the object to which
+  # method calls are delegated (see Delegator).
   def __getobj__
     unless @@id_rev_map[self.object_id] == @__id
       Kernel::raise RefError, "Illegal Reference - probably recycled", Kernel::caller(2)
@@ -77,10 +77,12 @@ class WeakRef<Delegator
       Kernel::raise RefError, "Illegal Reference - probably recycled", Kernel::caller(2)
     end
   end
+
   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