RDoc updated by William Webber

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

lib/net/imap.rb

@@ -7,61 +7,6 @@
 # You can freely distribute/modify this library.
 #++
 #
-# Client functionality for the IMAP mail protocol.  
-# See the Net::IMAP class for details and examples of use.
-#
-# == References
-#
-# [[IMAP]]
-#    M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
-#    RFC 2060, December 1996.  (Note: since obsoleted by RFC 3501)
-#
-# [[LANGUAGE-TAGS]]
-#    Alvestrand, H., "Tags for the Identification of
-#    Languages", RFC 1766, March 1995.
-#
-# [[MD5]]
-#    Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
-#    1864, October 1995.
-#
-# [[MIME-IMB]]
-#    Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
-#    Mail Extensions) Part One: Format of Internet Message Bodies", RFC
-#    2045, November 1996.
-#
-# [[RFC-822]]
-#    Crocker, D., "Standard for the Format of ARPA Internet Text
-#    Messages", STD 11, RFC 822, University of Delaware, August 1982.
-#
-# [[RFC-2087]]
-#    Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
-#
-# [[RFC-2086]]
-#    Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
-#
-# [[SORT-THREAD-EXT]]
-#    Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD
-#    Extensions", draft-ietf-imapext-sort, May 2003.
-#
-# [[OSSL]]
-#    http://www.openssl.org
-#
-# [[RSSL]]
-#    http://savannah.gnu.org/projects/rubypki
-
-require "socket"
-require "monitor"
-require "digest/md5"
-begin
-  require "openssl"
-rescue LoadError
-end
-
-module Net
-
-  # Net::IMAP implements Internet Message Access Protocol (IMAP) client
-  # functionality.  The protocol is described in [IMAP].
-  #
 # == IMAP OVERVIEW
 #
 # An IMAP client connects to a server, and then authenticates
@@ -104,7 +49,7 @@ module Net
 #
 # === List sender and subject of all recent messages in the default mailbox
 #
-  #   imap = Net::IMAP.new('mail.example.com', 143)
+#   imap = Net::IMAP.new('mail.example.com')
 #   imap.authenticate('LOGIN', 'joe_user', 'joes_password')
 #   imap.examine('INBOX')
 #   imap.search(["RECENT"]).each do |message_id|
@@ -114,7 +59,7 @@ module Net
 #
 # === Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
 #
-  #   imap = Net::IMAP.new('mail.example.com', 143)
+#   imap = Net::IMAP.new('mail.example.com')
 #   imap.authenticate('LOGIN', 'joe_user', 'joes_password')
 #   imap.select('Mail/sent-mail')
 #   if not imap.list('Mail/', 'sent-apr03')
@@ -184,6 +129,68 @@ module Net
 # between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is 
 # thrown if a server response is non-parseable. 
 #
+#
+# == References
+#
+# [[IMAP]]
+#    M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
+#    RFC 2060, December 1996.  (Note: since obsoleted by RFC 3501)
+#
+# [[LANGUAGE-TAGS]]
+#    Alvestrand, H., "Tags for the Identification of
+#    Languages", RFC 1766, March 1995.
+#
+# [[MD5]]
+#    Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
+#    1864, October 1995.
+#
+# [[MIME-IMB]]
+#    Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
+#    Mail Extensions) Part One: Format of Internet Message Bodies", RFC
+#    2045, November 1996.
+#
+# [[RFC-822]]
+#    Crocker, D., "Standard for the Format of ARPA Internet Text
+#    Messages", STD 11, RFC 822, University of Delaware, August 1982.
+#
+# [[RFC-2087]]
+#    Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
+#
+# [[RFC-2086]]
+#    Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
+#
+# [[RFC-2195]]
+#    Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension
+#    for Simple Challenge/Response", RFC 2195, September 1997.
+#
+# [[SORT-THREAD-EXT]]
+#    Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD
+#    Extensions", draft-ietf-imapext-sort, May 2003.
+#
+# [[OSSL]]
+#    http://www.openssl.org
+#
+# [[RSSL]]
+#    http://savannah.gnu.org/projects/rubypki
+#
+# [[UTF7]]
+#    Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of
+#    Unicode", RFC 2152, May 1997.
+
+require "socket"
+require "monitor"
+require "digest/md5"
+begin
+  require "openssl"
+rescue LoadError
+end
+
+module Net
+
+  # Net::IMAP implements Internet Message Access Protocol (IMAP) client
+  # functionality.  The protocol is described in [IMAP].
+  #
+  # See comment to the file imap.rb for examples of usage.
   class IMAP
     include MonitorMixin
     if defined?(OpenSSL)
@@ -256,7 +263,15 @@ module Net
       return @@debug = val
     end
 
-    # Adds an authenticator for Net::IMAP#authenticate.
+    # Adds an authenticator for Net::IMAP#authenticate.  +auth_type+
+    # is the type of authentication this authenticator supports
+    # (for instance, "LOGIN").  The +authenticator+ is an object
+    # which defines a process() method to handle authentication with
+    # the server.  See Net::IMAP::LoginAuthenticator and 
+    # Net::IMAP::CramMD5Authenticator for examples.
+    #
+    # If +auth_type+ refers to an existing authenticator, it will be
+    # replaced by the new one.
     def self.add_authenticator(auth_type, authenticator)
       @@authenticators[auth_type] = authenticator
     end
@@ -268,8 +283,16 @@ module Net
       @sock.close
     end
 
-    # Sends a CAPABILITY command, and returns a listing of
+    # Sends a CAPABILITY command, and returns an array of
-    # capabilities that the server supports.
+    # capabilities that the server supports.  Each capability
+    # is a string.  See [IMAP] for a list of possible
+    # capabilities.
+    #
+    # Note that the Net::IMAP class does not modify its
+    # behaviour according to the capabilities of the server;
+    # it is up to the user of the class to ensure that 
+    # a certain capability is supported by a server before
+    # using it.
     def capability
       synchronize do
 	send_command("CAPABILITY")
@@ -291,7 +314,24 @@ module Net
     # Sends an AUTHENTICATE command to authenticate the client.
     # The +auth_type+ parameter is a string that represents
     # the authentication mechanism to be used. Currently Net::IMAP
-    # supports "LOGIN" and "CRAM-MD5" for the +auth_type+. For example:
+    # supports authentication mechanisms:
+    #
+    #   LOGIN:: login using cleartext user and password. 
+    #   CRAM-MD5:: login with cleartext user and encrypted password
+    #              (see [RFC-2195] for a full description).  This
+    #              mechanism requires that the server have the user's
+    #              password stored in clear-text password.
+    #
+    # For both these mechanisms, there should be two +args+: username
+    # and (cleartext) password.  A server may not support one or other
+    # of these mechanisms; check #capability() for a capability of
+    # the form "AUTH=LOGIN" or "AUTH=CRAM-MD5".
+    #
+    # Authentication is done using the appropriate authenticator object:
+    # see @@authenticators for more information on plugging in your own
+    # authenticator.
+    #
+    # For example:
     #
     #    imap.authenticate('LOGIN', user, password)
     #
@@ -312,7 +352,9 @@ module Net
     end
 
     # Sends a LOGIN command to identify the client and carries
-    # the plaintext +password+ authenticating this +user+.
+    # the plaintext +password+ authenticating this +user+.  Note
+    # that, unlike calling #authenticate() with an +auth_type+
+    # of "LOGIN", #login() does *not* use the login authenticator.
     #
     # A Net::IMAP::NoResponseError is raised if authentication fails.
     def login(user, password)
@@ -755,6 +797,14 @@ module Net
       return thread_internal("UID THREAD", algorithm, search_keys, charset)
     end
 
+    # Decode a string from modified UTF-7 format to UTF-8.
+    #
+    # UTF-7 is a 7-bit encoding of Unicode [UTF7].  IMAP uses a
+    # slightly modified version of this to encode mailbox names
+    # containing non-ASCII characters; see [IMAP] section 5.1.3.
+    #
+    # Net::IMAP does _not_ automatically encode and decode
+    # mailbox names to and from utf7.
     def self.decode_utf7(s)
       return s.gsub(/&(.*?)-/n) {
 	if $1.empty?
@@ -770,6 +820,7 @@ module Net
       }
     end
 
+    # Encode a string from UTF-8 format to modified UTF-7.
     def self.encode_utf7(s)
       return s.gsub(/(&)|([^\x20-\x25\x27-\x7e]+)/n) { |x|
 	if $1
@@ -1221,7 +1272,7 @@ module Net
     end
     private_class_method :u8tou16
 
-    class RawData
+    class RawData # :nodoc:
       def format_data
 	return @data
       end
@@ -1233,7 +1284,7 @@ module Net
       end
     end
 
-    class Atom
+    class Atom # :nodoc:
       def format_data
 	return @data
       end
@@ -1245,7 +1296,7 @@ module Net
       end
     end
 
-    class QuotedString
+    class QuotedString # :nodoc:
       def format_data
 	return '"' + @data.gsub(/["\\]/n, "\\\\\\&") + '"'
       end
@@ -1257,7 +1308,7 @@ module Net
       end
     end
 
-    class Literal
+    class Literal # :nodoc:
       def format_data
 	return "{" + @data.length.to_s + "}" + CRLF + @data
       end
@@ -1269,7 +1320,7 @@ module Net
       end
     end
 
-    class MessageSet
+    class MessageSet # :nodoc:
       def format_data
 	return format_internal(@data)
       end
@@ -1743,7 +1794,7 @@ module Net
       end
     end
 
-    class ResponseParser
+    class ResponseParser # :nodoc:
       def parse(str)
 	@str = str
 	@pos = 0
@@ -2964,6 +3015,8 @@ module Net
       end
     end
 
+    # Authenticator for the "LOGIN" authentication type.  See
+    # #authenticate().
     class LoginAuthenticator
       def process(data)
 	case @state
@@ -2988,6 +3041,8 @@ module Net
     end
     add_authenticator "LOGIN", LoginAuthenticator
 
+    # Authenticator for the "CRAM-MD5" authentication type.  See
+    # #authenticate().
     class CramMD5Authenticator
       def process(challenge)
 	digest = hmac_md5(challenge, @password)
@@ -3020,24 +3075,37 @@ module Net
     end
     add_authenticator "CRAM-MD5", CramMD5Authenticator
 
+    # Superclass of IMAP errors.
     class Error < StandardError
     end
 
+    # Error raised when data is in the incorrect format.
     class DataFormatError < Error
     end
 
+    # Error raised when a response from the server is non-parseable.
     class ResponseParseError < Error
     end
 
+    # Superclass of all errors used to encapsulate "fail" responses
+    # from the server.
     class ResponseError < Error
     end
 
+    # Error raised upon a "NO" response from the server, indicating
+    # that the client command could not be completed successfully.
     class NoResponseError < ResponseError
     end
 
+    # Error raised upon a "BAD" response from the server, indicating
+    # that the client command violated the IMAP protocol, or an internal
+    # server failure has occurred.
     class BadResponseError < ResponseError
     end
 
+    # Error raised upon a "BYE" response from the server, indicating 
+    # that the client is not being allowed to login, or has been timed
+    # out due to inactivity.
     class ByeResponseError < ResponseError
     end
   end
@@ -3183,3 +3251,4 @@ EOF
     imap.disconnect
   end
 end
+