From: Hugh Sasse <hgs@...>
Date: 2006-08-03T18:43:30+09:00
Subject: doc patch for mailread.rb

Here is a documentation patch for mailread.rb.  (HEAD and stable seem
to be the same, but this was agains 1.8 HEAD)

I think I have found a problem with this library:  My reading of
the code suggests that successive received lines in the headers will
overwrite each other.  With a weekend before the final release of 1.8.5
I won't have chance to examine this thoroughly and get the results
reviewed, so I've not attempted to tackle this issue.

        HTH
        Hugh

--- ./lib/mailread.rb.orig	2001-10-02 05:31:23.000000000 +0100
+++ ./lib/mailread.rb	2006-08-03 10:36:04.283049000 +0100
@@ -1,5 +1,13 @@
+# The Mail class represents an internet mail message
+# (as per RFC822, RFC2822) with headers and a body. 
 class Mail
 
+  # +f+ is either a stream which responds to gets(), or a path to a
+  # file.  If it is a file it will be opened.  If the message is in
+  # mbox format (i.e. starts with a line beginning "From " then that
+  # line is ignored.  The whole message is then read so it can be
+  # made available through #header, #[] and #body methods.  If +f+
+  # was opened, it is closed again.
   def initialize(f)
     unless defined? f.gets
       f = open(f, "r")
@@ -34,14 +42,18 @@
     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+. 
+  # Done with a case insenstive match.
   def [](field)
     @header[field.capitalize]
   end