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

lib/mailread.rb

@@ -1,5 +1,14 @@
+# The Mail class represents an internet mail message (as per RFC822, RFC2822)
+# with headers and a body. 
 class Mail
 
+  # Create a new Mail where +f+ is either a stream which responds to gets(),
+  # or a path to a file.  If +f+ is a path it will be opened.
+  #
+  # The whole message is read so it can be made available through the #header,
+  # #[] and #body methods.
+  #
+  # The "From " line is ignored if the mail is in mbox format.
   def initialize(f)
     unless defined? f.gets
       f = open(f, "r")
@@ -34,14 +43,19 @@ class Mail
     end
   end
 
+  # Return the headers as a Hash.
   def header
     return @header
   end
 
+  # Return the message body as an Array of lines
   def body
     return @body
   end
 
+  # Return the header corresponding to +field+. 
+  #
+  # Matching is case-insensitive.
   def [](field)
     @header[field.capitalize]
   end