RDoc comments provided by William Webber <wew@williamwebber.com>

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

1 files changed, 405 insertions, 467 deletions

diff --git a/lib/net/pop.rb b/lib/net/pop.rb
index 09d172df06..5b4ad69c73 100644
--- a/lib/net/pop.rb
+++ b/lib/net/pop.rb
@@ -1,468 +1,191 @@
-=begin
-
-= net/pop.rb
-
-Copyright (c) 1999-2003 Yukihiro Matsumoto
-Copyright (c) 1999-2003 Minero Aoki
-
-written & maintained by Minero Aoki <aamine@loveruby.net>
-
-This program is free software. You can re-distribute and/or
-modify this program under the same terms as Ruby itself,
-Ruby Distribute License or GNU General Public License.
-
-NOTE: You can find Japanese version of this document in
-the doc/net directory of the standard ruby interpreter package.
-
-$Id$
-
-== What is This Module?
-
-This module provides your program the function to retrieve
-mails via POP3, Post Office Protocol version 3. For details
-of POP3, refer [RFC1939] ((<URL:http://www.ietf.org/rfc/rfc1939.txt>)).
-
-== Examples
-
-=== Retrieving Mails
-
-This example retrieves mails from server and delete it (on server).
-Mails are written in file named 'inbox/1', 'inbox/2', ....
-Replace 'pop3.server.address' your POP3 server address.
-
-    require 'net/pop'
-
-    pop = Net::POP3.new('pop.example.com', 110)
-    pop.start('YourAccount', 'YourPassword')             # (1)
-    if pop.mails.empty?
-      puts 'no mail.'
-    else
-      i = 0
-      pop.each_mail do |m|   # or "pop.mails.each ..."   # (2)
-        File.open("inbox/#{i}", 'w') {|f|
-          f.write m.pop
-        }
-        m.delete
-        i += 1
-      end
-      puts "#{pop.mails.size} mails popped."
-    end
-    pop.finish                                           # (3)
-
-(1) call Net::POP3#start and start POP session
-(2) access mails by using POP3#each_mail and/or POP3#mails
-(3) close POP session by calling POP3#finish or use block form #start.
-
-This example is using block form #start to close the session.
-
-=== Enshort Code
-
-The example above is very verbose. You can enshort code by using
-some utility methods. At first, block form of Net::POP3.start can
-alternates POP3.new, POP3#start and POP3#finish.
-
-    require 'net/pop'
-
-    Net::POP3.start('pop.example.com', 110,
-                    'YourAccount', 'YourPassword') {|pop|
-      if pop.mails.empty?
-        puts 'no mail.'
-      else
-        i = 0
-        pop.each_mail do |m|   # or "pop.mails.each ..."
-          File.open("inbox/#{i}", 'w') {|f|
-            f.write m.pop
-          }
-          m.delete
-          i += 1
-        end
-        puts "#{pop.mails.size} mails popped."
-      end
-    }
-
-POP3#delete_all alternates #each_mail and m.delete.
-
-    require 'net/pop'
-
-    Net::POP3.start('pop.example.com', 110,
-                    'YourAccount', 'YourPassword') {|pop|
-      if pop.mails.empty?
-        puts 'no mail.'
-      else
-        i = 1
-        pop.delete_all do |m|
-          File.open("inbox/#{i}", 'w') {|f|
-            f.write m.pop
-          }
-          i += 1
-        end
-      end
-    }
-
-And here is more shorter example.
-
-    require 'net/pop'
-
-    i = 0
-    Net::POP3.delete_all('pop.example.com', 110,
-                         'YourAccount', 'YourPassword') do |m|
-      File.open("inbox/#{i}", 'w') {|f|
-        f.write m.pop
-      }
-      i += 1
-    end
-
-=== Memory Space Issue
-
-All examples above get mail as one big string.
-This example does not create such one.
-
-    require 'net/pop'
-
-    i = 1
-    Net::POP3.delete_all('pop.example.com', 110,
-                         'YourAccount', 'YourPassword') do |m|
-      File.open("inbox/#{i}", 'w') {|f|
-        m.pop do |chunk|    # get a message little by little.
-          f.write chunk
-        end
-        i += 1
-      }
-    end
-
-=== Using APOP
-
-The net/pop library supports APOP authentication.
-To use APOP, use Net::APOP class instead of Net::POP3 class.
-You can use utility method, Net::POP3.APOP(). Example:
-
-    require 'net/pop'
-
-    # Use APOP authentication if $isapop == true
-    pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110)
-    pop.start(YourAccount', 'YourPassword') {|pop|
-      # Rest code is same.
-    }
-
-=== Fetch Only Selected Mail Using `UIDL' POP Command
-
-If your POP server provides UIDL function,
-you can pop only selected mails from POP server.
-e.g.
-
-    def need_pop?( id )
-      # determine if we need pop this mail...
-    end
-
-    Net::POP3.start('pop.example.com', 110,
-                    'Your account', 'Your password') {|pop|
-      pop.mails.select {|m| need_pop?(m.unique_id) }.each do |m|
-        do_something(m.pop)
-      end
-    }
-
-POPMail#unique_id method returns the unique-id of the message (String).
-Normally unique-id is a hash of the message.
-
-
-== class Net::POP3
-
-=== Class Methods
-
-: new( address, port = 110, isapop = false )
-    creates a new Net::POP3 object.
-    This method does NOT open TCP connection yet.
-
-: start( address, port = 110, account, password, isapop = false )
-: start( address, port = 110, account, password, isapop = false ) {|pop| .... }
-    equals to Net::POP3.new(address, port, isapop).start(account, password).
-    This method raises POPAuthenticationError if authentication is failed.
-
-        # Typical usage
-        Net::POP3.start(addr, port, account, password) {|pop|
-          pop.each_mail do |m|
-            file.write m.pop
-            m.delete
-          end
-        }
-
-: APOP( is_apop )
-    returns Net::APOP class object if IS_APOP.
-    Else, IS_APOP.  Use this method like:
-
-        # Example 1
-        pop = Net::POP3::APOP($is_apop).new(addr, port)
-
-        # Example 2
-        Net::POP3::APOP($is_apop).start(addr, port) {|pop|
-          ....
-        }
-
-: foreach( address, port = 110, account, password, isapop = false ) {|popmail| .... }
-    starts POP3 protocol and iterates for each POPMail object.
-    This method equals to:
-
-        Net::POP3.start(address, port, account, password) {|pop|
-          pop.each_mail do |m|
-            yield m
-          end
-        }
-
-    This method raises POPAuthenticationError if authentication is failed.
-
-        # Typical usage
-        Net::POP3.foreach('pop.example.com', 110,
-                          'YourAccount', 'YourPassword') do |m|
-          file.write m.pop
-          m.delete if $DELETE
-        end
-
-: delete_all( address, port = 110, account, password, isapop = false )
-: delete_all( address, port = 110, account, password, isapop = false ) {|popmail| .... }
-    starts POP3 session and delete all mails.
-    If block is given, iterates for each POPMail object before delete.
-    This method raises POPAuthenticationError if authentication is failed.
-
-        # Example
-        Net::POP3.delete_all('pop.example.com', 110,
-                             'YourAccount', 'YourPassword') do |m|
-          file.write m.pop
-        end
-
-: auth_only( address, port = 110, account, password, isapop = false )
-    (just for POP-before-SMTP)
-
-    opens POP3 session and does autholize and quit.
-    This method must not be called while POP3 session is opened.
-    This method raises POPAuthenticationError if authentication is failed.
-
-        # Example 1: normal POP3
-        Net::POP3.auth_only('pop.example.com', 110,
-                            'YourAccount', 'YourPassword')
-
-        # Example 2: APOP
-        Net::POP3.auth_only('pop.example.com', 110,
-                            'YourAccount', 'YourPassword', true)
-
-=== Instance Methods
-
-: start( account, password )
-: start( account, password ) {|pop| .... }
-    starts POP3 session.
-
-    When called with block, gives a POP3 object to block and
-    closes the session after block call finish.
-
-    This method raises POPAuthenticationError if authentication is failed.
-
-: started?
-: active?   OBSOLETE
-    true if POP3 session is started.
-
-: address
-    the address to connect
-
-: port
-    the port number to connect
-
-: open_timeout
-: open_timeout=(n)
-    seconds to wait until connection is opened.
-    If POP3 object cannot open a conection in this seconds,
-    it raises TimeoutError exception.
-
-: read_timeout
-: read_timeout=(n)
-    seconds to wait until reading one block (by one read(1) call).
-    If POP3 object cannot open a conection in this seconds,
-    it raises TimeoutError exception.
-
-: finish
-    finishes POP3 session.
-    If POP3 session had not be started, raises an IOError.
-
-: n_mails
-    returns the number of mails on the POP server.
-
-: n_bytes
-    returns the bytes of all mails on the POP server.
-
-: mails
-    an array of Net::POPMail objects.
-    This array is renewed when session restarts.
-
-    This method raises POPError if any problem happened.
-
-: each_mail {|popmail| .... }
-: each {|popmail| .... }
-    is equals to:
-    
-      pop3.mails.each do |popmail|
-        ....
-      end
-
-    This method raises POPError if any problem happened.
-
-: delete_all
-: delete_all {|popmail| .... }
-    deletes all mails on server.
-    If called with block, gives mails to the block before deleting.
-
-        # Example
-        n = 1
-        pop.delete_all do |m|
-          File.open("inbox/#{n}") {|f|
-            f.write m.pop
-          }
-          n += 1
-        end
-
-    This method raises POPError if any problem happened.
-
-: reset
-    reset the session. All "deleted mark" are removed.
-
-    This method raises POPError if any problem happened.
-
-: set_debug_output( output )
-    WARNING: This method causes serious security hole.
-    Use this method for only debugging.
-
-    set output stream for debugging.
-
-      # Example
-      pop = Net::POP.new(addr, port)
-      pop.set_debug_output $stderr
-      pop.start(account, passwd) {
-        ....
-      }
-
-
-== class Net::APOP
-
-This class defines no new methods.
-Only difference from POP3 is using APOP authentification.
-
-=== Super Class
-
-Net::POP3
-
-
-== class Net::POPMail
-
-A class of mail which exists on POP server.
-
-=== Instance Methods
-
-: pop
-    This method fetches a message as a String.
-
-    This method may raise POPError.
-
-        # Example
-        POP3.start('pop.example.com', 110,
-                   'YourAccount, 'YourPassword') {|pop|
-          n = 1
-          pop.mails.each do |popmail|
-            File.open("inbox/#{n}", 'w') {|f|
-              f.write popmail.pop               ####
-            }
-            popmail.delete
-            n += 1
-          end
-        }
-
-: pop {|chunk| .... }
-    gives the block parts of the message.
-
-    This method may raise POPError.
-
-        # Example
-        POP3.start('pop.example.com', 110,
-                   'YourAccount, 'YourPassword') {|pop|
-          n = 1
-          pop.mails.each do |popmail|
-            File.open("inbox/#{n}", 'w') {|f|
-              popmail.pop do |chunk|            ####
-                f.write chunk
-              end
-            }
-            n += 1
-          end
-        }
-
-: header
-    fetches the message header.
-
-    This method may raise POPError.
-
-: top( lines )
-    fetches the message header and LINES lines of body.
-
-    This method may raise POPError.
-
-: delete
-    deletes the message on the POP server.
-
-    This method may raise POPError.
-
-        # Example
-        POP3.start('pop.example.com', 110,
-                   'YourAccount, 'YourPassword') {|pop|
-          n = 1
-          pop.mails.each do |popmail|
-            File.open("inbox/#{n}", 'w') {|f|
-              f.write popmail.pop
-            }
-            popmail.delete         ####
-            n += 1
-          end
-        }
-
-: length
-: size
-    the length of the message (in octets).
-
-: deleted?
-    true if mail was deleted.
-
-: unique_id
-    returns the unique-id of the message.
-    Normally unique-id is a hash string of the message.
-
-    This method may raise POPError.
-
-
-== POP3 Related Exception Classes
-
-: POPError
-    POP3 protocol error (reply code "-ERR", except authentication).
-
-    ancestors: ProtocolError (obsolete)
-
-: POPAuthenticationError
-    POP3 authentication error.
-
-    ancestors: POPError, ProtoAuthError (obsolete), ProtocolError (obsolete)
-
-: POPBadResponse
-    Unexpected response got from server.
-
-    ancestors: POPError
-
-=end
-
+# = net/pop.rb
+#
+#--
+# Copyright (c) 1999-2003 Yukihiro Matsumoto
+# Copyright (c) 1999-2003 Minero Aoki
+# 
+# written & maintained by Minero Aoki <aamine@loveruby.net>
+# 
+# This program is free software. You can re-distribute and/or
+# modify this program under the same terms as Ruby itself,
+# Ruby Distribute License or GNU General Public License.
+# 
+# NOTE: You can find Japanese version of this document in
+# the doc/net directory of the standard ruby interpreter package.
+# 
+# $Id$
+#++
+#
+# == What is This Library?
+# 
+# This library provides functionality for retrieving 
+# email via POP3, the Post Office Protocol version 3. For details
+# of POP3, see [RFC1939] (http://www.ietf.org/rfc/rfc1939.txt).
+# 
+# == Examples
+# 
+# === Retrieving Messages 
+# 
+# This example retrieves messages from the server and deletes them 
+# on the server.
+# Messages are written to files named 'inbox/1', 'inbox/2', ....
+# Replace 'pop.example.com' with your POP3 server address, and
+# 'YourAccount' and 'YourPassword' with the appropriate account
+# details.
+# 
+#     require 'net/pop'
+# 
+#     pop = Net::POP3.new('pop.example.com')
+#     pop.start('YourAccount', 'YourPassword')             # (1)
+#     if pop.mails.empty?
+#       puts 'no mail.'
+#     else
+#       i = 0
+#       pop.each_mail do |m|   # or "pop.mails.each ..."   # (2)
+#         File.open("inbox/#{i}", 'w') {|f|
+#           f.write m.pop
+#         }
+#         m.delete
+#         i += 1
+#       end
+#       puts "#{pop.mails.size} mails popped."
+#     end
+#     pop.finish                                           # (3)
+# 
+# 1. call Net::POP3#start and start POP session
+# 2. access messages by using POP3#each_mail and/or POP3#mails
+# 3. close POP session by calling POP3#finish or use the block form of #start.
+# 
+# === Shortened Code
+# 
+# The example above is very verbose. You can shorten the code by using
+# some utility methods. First, the block form of Net::POP3.start can
+# be used instead of POP3.new, POP3#start and POP3#finish.
+# 
+#     require 'net/pop'
+# 
+#     Net::POP3.start('pop.example.com', 110,
+#                     'YourAccount', 'YourPassword') {|pop|
+#       if pop.mails.empty?
+#         puts 'no mail.'
+#       else
+#         i = 0
+#         pop.each_mail do |m|   # or "pop.mails.each ..."
+#           File.open("inbox/#{i}", 'w') {|f|
+#             f.write m.pop
+#           }
+#           m.delete
+#           i += 1
+#         end
+#         puts "#{pop.mails.size} mails popped."
+#       end
+#     }
+# 
+# POP3#delete_all alternates #each_mail and m.delete.
+# 
+#     require 'net/pop'
+# 
+#     Net::POP3.start('pop.example.com', 110,
+#                     'YourAccount', 'YourPassword') {|pop|
+#       if pop.mails.empty?
+#         puts 'no mail.'
+#       else
+#         i = 1
+#         pop.delete_all do |m|
+#           File.open("inbox/#{i}", 'w') {|f|
+#             f.write m.pop
+#           }
+#           i += 1
+#         end
+#       end
+#     }
+# 
+# And here is an even shorter example.
+# 
+#     require 'net/pop'
+# 
+#     i = 0
+#     Net::POP3.delete_all('pop.example.com', 110,
+#                          'YourAccount', 'YourPassword') do |m|
+#       File.open("inbox/#{i}", 'w') {|f|
+#         f.write m.pop
+#       }
+#       i += 1
+#     end
+# 
+# === Memory Space Issues
+# 
+# All the examples above get each message as one big string.
+# This example avoids this.
+# 
+#     require 'net/pop'
+# 
+#     i = 1
+#     Net::POP3.delete_all('pop.example.com', 110,
+#                          'YourAccount', 'YourPassword') do |m|
+#       File.open("inbox/#{i}", 'w') {|f|
+#         m.pop do |chunk|    # get a message little by little.
+#           f.write chunk
+#         end
+#         i += 1
+#       }
+#     end
+# 
+# === Using APOP
+# 
+# The net/pop library supports APOP authentication.
+# To use APOP, use the Net::APOP class instead of the Net::POP3 class.
+# You can use the utility method, Net::POP3.APOP(). For example:
+# 
+#     require 'net/pop'
+# 
+#     # Use APOP authentication if $isapop == true
+#     pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110)
+#     pop.start(YourAccount', 'YourPassword') {|pop|
+#       # Rest code is same.
+#     }
+# 
+# === Fetch Only Selected Mail Using `UIDL' POP Command
+# 
+# If your POP server provides UIDL functionality,
+# you can grab only selected mails from the POP server.
+# e.g.
+# 
+#     def need_pop?( id )
+#       # determine if we need pop this mail...
+#     end
+# 
+#     Net::POP3.start('pop.example.com', 110,
+#                     'Your account', 'Your password') {|pop|
+#       pop.mails.select {|m| need_pop?(m.unique_id) }.each do |m|
+#         do_something(m.pop)
+#       end
+#     }
+# 
+# The POPMail#unique_id() method returns the unique-id of the message as a
+# String. Normally the unique-id is a hash of the message.
+# 
 require 'net/protocol'
 require 'digest/md5'
 
-
 module Net
 
+  # Non-authentication POP3 protocol error (reply code "-ERR", except
+  # authentication.
   class POPError < ProtocolError; end
+
+  # POP3 authentication error.
   class POPAuthenticationError < ProtoAuthError; end
+
+  # Unexpected response from the server.
   class POPBadResponse < POPError; end
 
 
+  #
+  # Class providing POP3 client functionality.
+  #
+  # See documentation for the file pop.rb for examples of usage.
+  #
   class POP3 < Protocol
 
     Revision = %q$Revision$.split[1]
@@ -471,12 +194,13 @@ module Net
     # Class Parameters
     #
 
+    # The default port for POP3 connections, port 110
     def POP3.default_port
       110
     end
 
     # obsolete
-    def POP3.socket_type
+    def POP3.socket_type # :nodoc:
       Net::InternetMessageIO
     end
 
@@ -484,18 +208,57 @@ module Net
     # Utilities
     #
 
+    # Returns the APOP class if +isapop+ is true; otherwise, returns
+    # the POP class.  For example:
+    #
+    #     # Example 1
+    #     pop = Net::POP3::APOP($is_apop).new(addr, port)
+    #
+    #     # Example 2
+    #     Net::POP3::APOP($is_apop).start(addr, port) {|pop|
+    #       ....
+    #     }
     def POP3.APOP( isapop )
       isapop ? APOP : POP3
     end
 
+    # Starts a POP3 session and iterates over each POPMail object,
+    # yielding it to the +block+.
+    # This method is equivalent to:
+    #
+    #     Net::POP3.start(address, port, account, password) {|pop|
+    #       pop.each_mail do |m|
+    #         yield m
+    #       end
+    #     }
+    #
+    # This method raises a POPAuthenticationError if authentication fails.
+    #
+    #     # Typical usage
+    #     Net::POP3.foreach('pop.example.com', 110,
+    #                       'YourAccount', 'YourPassword') do |m|
+    #       file.write m.pop
+    #       m.delete if $DELETE
+    #     end
     def POP3.foreach( address, port = nil,
                       account = nil, password = nil,
-                      isapop = false, &block )
+                      isapop = false, &block )  # :yields: message
       start(address, port, account, password, isapop) {|pop|
         pop.each_mail(&block)
       }
     end
 
+    # Starts a POP3 session and deletes all messages on the server.
+    # If a block is given, each POPMail object is yielded to it before
+    # being deleted.
+    #
+    # This method raises a POPAuthenticationError if authentication fails.
+    #
+    #     # Example
+    #     Net::POP3.delete_all('pop.example.com', 110,
+    #                          'YourAccount', 'YourPassword') do |m|
+    #       file.write m.pop
+    #     end
     def POP3.delete_all( address, port = nil,
                          account = nil, password = nil,
                          isapop = false, &block )
@@ -504,12 +267,26 @@ module Net
       }
     end
 
+    # Opens a POP3 session, attempts authentication, and quits.
+    #
+    # This method raises POPAuthenticationError if authentication fails.
+    #
+    #     # Example 1: normal POP3
+    #     Net::POP3.auth_only('pop.example.com', 110,
+    #                         'YourAccount', 'YourPassword')
+    #
+    #     # Example 2: APOP
+    #     Net::POP3.auth_only('pop.example.com', 110,
+    #                         'YourAccount', 'YourPassword', true)
     def POP3.auth_only( address, port = nil,
                         account = nil, password = nil,
                         isapop = false )
       new(address, port, isapop).auth_only account, password
     end
 
+    # Starts a pop3 session, attempts authentication, and quits.
+    # This method must not be called while POP3 session is opened.
+    # This method raises POPAuthenticationError if authentication fails.
     def auth_only( account, password )
       raise IOError, 'opening already opened POP session' if started?
       start(account, password) {
@@ -521,12 +298,33 @@ module Net
     # Session management
     #
 
+    # Creates a new POP3 object and open the connection.  Equivalent to 
+    # Net::POP3.new(address, port, isapop).start(account, password)
+    #
+    # If +block+ is provided, yields the newly-opened POP3 object to it,
+    # and automatically closes it at the end of the session.
+    #
+    # Typical usage:
+    #
+    #    Net::POP3.start(addr, port, account, password) {|pop|
+    #      pop.each_mail do |m|
+    #        file.write m.pop
+    #        m.delete
+    #      end
+    #    }
+    #
     def POP3.start( address, port = nil,
                     account = nil, password = nil,
-                    isapop = false, &block )
+                    isapop = false, &block ) # :yield: pop
       new(address, port, isapop).start(account, password, &block)
     end
 
+    # Creates a new POP3 object.
+    # +address+ is the hostname or ip address of your POP3 server.
+    # The optional +port+ is the port to connect to; it defaults to 110.
+    # The optional +isapop+ specifies whether this connection is going
+    # to use APOP authentication; it defaults to +false+.
+    # This method does *not* open the TCP connection.
     def initialize( addr, port = nil, isapop = false )
       @address = addr
       @port = port || self.class.default_port
@@ -544,36 +342,67 @@ module Net
       @n_bytes = nil
     end
 
+    # Does this instance use APOP authentication?
     def apop?
       @apop
     end
 
+    # Provide human-readable stringification of class state.
     def inspect
       "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
     end
 
+    # *WARNING*: This method causes a serious security hole.
+    # Use this method only for debugging.
+    #
+    # Set an output stream for debugging.
+    #
+    #   # Example
+    #   pop = Net::POP.new(addr, port)
+    #   pop.set_debug_output $stderr
+    #   pop.start(account, passwd) {
+    #     ....
+    #   }
     def set_debug_output( arg )
       @debug_output = arg
     end
 
+    # The address to connect to.
     attr_reader :address
+
+    # The port number to connect to.
     attr_reader :port
 
+    # Seconds to wait until a connection is opened.
+    # If the POP3 object cannot open a connection within this time,
+    # it raises a TimeoutError exception.
     attr_accessor :open_timeout
+
+    # Seconds to wait until reading one block (by one read(1) call).
+    # If the POP3 object cannot complete a read() within this time,
+    # it raises a TimeoutError exception.
     attr_reader :read_timeout
 
+    # Set the read timeout.
     def read_timeout=( sec )
       @command.socket.read_timeout = sec if @command
       @read_timeout = sec
     end
 
+    # +true+ if the POP3 session has started.
     def started?
       @started
     end
 
     alias active? started?   # obsolete
 
-    def start( account, password )
+    # Starts a POP3 session.
+    #
+    # When called with block, gives a POP3 object to the block and
+    # closes the session after block call finishes.
+    #
+    # This method raises a POPAuthenticationError if authentication fails.
+    def start( account, password ) # :yield: pop
       raise IOError, 'POP session already started' if @started
 
       if block_given?
@@ -607,6 +436,8 @@ module Net
     end
     private :on_connect
 
+    # Finishes a POP3 session.
+    # If a POP3 session has not been started, raises an IOError.
     def finish
       raise IOError, 'already closed POP session' unless @started
       @mails = nil
@@ -628,18 +459,26 @@ module Net
     # POP protocol wrapper
     #
 
+    # Returns the number of messages on the POP server.
     def n_mails
       return @n_mails if @n_mails
       @n_mails, @n_bytes = command().stat
       @n_mails
     end
 
+    # Returns the total size in bytes of all the messages on the POP server.
     def n_bytes
       return @n_bytes if @n_bytes
       @n_mails, @n_bytes = command().stat
       @n_bytes
     end
 
+    # Returns an array of Net::POPMail objects, representing all the
+    # messages on the server.  This array is renewed when the session
+    # restarts; otherwise, it is fetched from the server the first time
+    # this method is called (directly or indirectly) and cached.
+    #
+    # This method raises a POPError if an error occurs.
     def mails
       return @mails.dup if @mails
       if n_mails() == 0
@@ -654,19 +493,44 @@ module Net
       @mails.dup
     end
 
-    def each_mail( &block )
+    # Yields each message to the passed-in block in turn.
+    # Equivalent to:
+    # 
+    #   pop3.mails.each do |popmail|
+    #     ....
+    #   end
+    #
+    # This method raises a POPError if an error occurs.
+    def each_mail( &block )  # :yield: message
       mails().each(&block)
     end
 
     alias each each_mail
 
-    def delete_all
+    # Deletes all messages on the server.
+    #
+    # If called with a block, yields each message in turn before deleting it.
+    #
+    #     # Example
+    #     n = 1
+    #     pop.delete_all do |m|
+    #       File.open("inbox/#{n}") {|f|
+    #         f.write m.pop
+    #       }
+    #       n += 1
+    #     end
+    #
+    # This method raises a POPError if an error occurs.
+    def delete_all # :yield: message
       mails().each do |m|
         yield m if block_given?
         m.delete unless m.deleted?
       end
     end
 
+    # Resets the session.  This clears all "deleted" marks from messages.
+    #
+    # This method raises a POPError if an error occurs.
     def reset
       command().rset
       mails().each do |m|
@@ -690,7 +554,10 @@ module Net
   POPSession  = POP3
   POP3Session = POP3
 
+  # This class is equivalent to POP3, except that it uses APOP authentication.
   class APOP < POP3
+
+    # Always returns true.
     def apop?
       true
     end
@@ -698,10 +565,12 @@ module Net
 
   APOPSession = APOP
 
-
+  # This class represents a message which exists on the POP server.
+  # Instances of this class are created by the POP3 class; they should
+  # not be directly created by the user.
   class POPMail
 
-    def initialize( num, len, pop, cmd )
+    def initialize( num, len, pop, cmd ) # :nodoc:
       @number = num
       @length = len
       @pop = pop
@@ -710,15 +579,53 @@ module Net
       @uid = nil
     end
 
+    # The sequence number of the message on the server.
     attr_reader :number
+
+    # The length of the message in octets.
     attr_reader :length
     alias size length
 
+    # Provide human-readable stringification of class state.
     def inspect
       "#<#{self.class} #{@number}#{@deleted ? ' deleted' : ''}>"
     end
 
-    def pop( dest = '', &block )
+    # This method fetches the message.  If called with a block, the
+    # message is yielded to the block one chunk at a time.  If called
+    # without a block, the message is returned as a String.  The optional 
+    # +dest+ argument will be prepended to the returned String; this
+    # argument is essentially obsolete.
+    #
+    #     # Example without block
+    #     POP3.start('pop.example.com', 110,
+    #                'YourAccount, 'YourPassword') {|pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') {|f|
+    #           f.write popmail.pop              
+    #         }
+    #         popmail.delete
+    #         n += 1
+    #       end
+    #     }
+    #
+    #     # Example with block
+    #     POP3.start('pop.example.com', 110,
+    #                'YourAccount, 'YourPassword') {|pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') {|f|
+    #           popmail.pop do |chunk|            ####
+    #             f.write chunk
+    #           end
+    #         }
+    #         n += 1
+    #       end
+    #     }
+    #
+    # This method raises a POPError if an error occurs.
+    def pop( dest = '', &block ) # :yield: message_chunk
       if block_given?
         @command.retr(@number, &block)
         nil
@@ -733,7 +640,10 @@ module Net
     alias all pop    # backward compatibility
     alias mail pop   # backward compatibility
 
-    # `dest' argument is obsolete
+    # Fetches the message header and +lines+ lines of body. 
+    # The optional +dest+ argument is obsolete.
+    #
+    # This method raises a POPError if an error occurs.
     def top( lines, dest = '' )
       @command.top(@number, lines) do |chunk|
         dest << chunk
@@ -741,11 +651,32 @@ module Net
       dest
     end
 
-    # `dest' argument is obsolete
+    # Fetches the message header.     
+    # The optional +dest+ argument is obsolete.
+    #
+    # This method raises a POPError if an error occurs.
     def header( dest = '' )
       top(0, dest)
     end
 
+    # Marks a message for deletion on the server.  Deletion does not
+    # actually occur until the end of the session; deletion may be
+    # cancelled for _all_ marked messages by calling POP3#reset().
+    #
+    # This method raises a POPError if an error occurs.
+    #
+    #     # Example
+    #     POP3.start('pop.example.com', 110,
+    #                'YourAccount, 'YourPassword') {|pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') {|f|
+    #           f.write popmail.pop
+    #         }
+    #         popmail.delete         ####
+    #         n += 1
+    #       end
+    #     }
     def delete
       @command.dele @number
       @deleted = true
@@ -753,10 +684,15 @@ module Net
 
     alias delete! delete    # backward compatibility
 
+    # True if the mail has been deleted.
     def deleted?
       @deleted
     end
 
+    # Returns the unique-id of the message.
+    # Normally the unique-id is a hash string of the message.
+    #
+    # This method raises a POPError if an error occurs.
     def unique_id
       return @uid if @uid
       @pop.set_all_uids
@@ -773,7 +709,7 @@ module Net
   end   # class POPMail
 
 
-  class POP3Command
+  class POP3Command # :nodoc:
 
     def initialize( sock )
       @socket = sock
@@ -782,6 +718,7 @@ module Net
       @apop_stamp = res.slice(/<.+>/)
     end
 
+    # Provide human-readable stringification of class state.
     def inspect
       "#<#{self.class} socket=#{@socket}>"
     end
@@ -905,3 +842,4 @@ module Net
   end   # class POP3Command
 
 end   # module Net
+