Skip to content

Commit 9cd562a

Browse files
nevansnevans
committed
Many documentation improvements
* updated obsoleted RFCs to current versions * linked most references to their RFCs * linked extension commands to their RFCs * removed unidiomatic `()` from instance method links * escaped `IMAP` in a few places * converted all response structs to explicit classes: this makes much nicer rdoc output than listing them all under "constants" * grouped flags constants into their own sections
1 parent 64d1080 commit 9cd562a

File tree

3 files changed

+163
-84
lines changed

3 files changed

+163
-84
lines changed

‎lib/net/imap.rb

Lines changed: 106 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,13 @@ module Net
3232

3333
#
3434
# Net::IMAP implements Internet Message Access Protocol (IMAP) client
35-
# functionality. The protocol is described in [IMAP].
35+
# functionality. The protocol is described in
36+
# [IMAP[https://tools.ietf.org/html/rfc3501]].
3637
#
3738
# == IMAP Overview
3839
#
39-
# An IMAP client connects to a server, and then authenticates
40-
# itself using either #authenticate() or #login(). Having
40+
# An \IMAP client connects to a server, and then authenticates
41+
# itself using either #authenticate or #login. Having
4142
# authenticated itself, there is a range of commands
4243
# available to it. Most work with mailboxes, which may be
4344
# arranged in an hierarchical namespace, and each of which
@@ -47,8 +48,8 @@ module Net
4748
# within a hierarchy of directories.
4849
#
4950
# To work on the messages within a mailbox, the client must
50-
# first select that mailbox, using either #select() or (for
51-
# read-only access) #examine(). Once the client has successfully
51+
# first select that mailbox, using either #select or (for
52+
# read-only access) #examine. Once the client has successfully
5253
# selected a mailbox, they enter _selected_ state, and that
5354
# mailbox becomes the _current_ mailbox, on which mail-item
5455
# related commands implicitly operate.
@@ -69,7 +70,7 @@ module Net
6970
# be assigned in ascending (but not necessarily sequential)
7071
# order within a mailbox; this means that if a non-IMAP client
7172
# rearranges the order of mailitems within a mailbox, the
72-
# UIDs have to be reassigned. An IMAP client thus cannot
73+
# UIDs have to be reassigned. An \IMAP client thus cannot
7374
# rearrange message orders.
7475
#
7576
# == Examples of Usage
@@ -159,50 +160,71 @@ module Net
159160
#
160161
# == References
161162
#
162-
# [[IMAP]]
163-
# M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
164-
# RFC 2060, December 1996. (Note: since obsoleted by RFC 3501)
163+
# [[IMAP[https://tools.ietf.org/html/rfc3501]]]
164+
# Crispin, M. "INTERNET MESSAGE ACCESS PROTOCOL - \VERSION 4rev1",
165+
# RFC-3501[https://tools.ietf.org/html/rfc3501], March 2003. (Note:
166+
# obsoletes RFC-2060[https://tools.ietf.org/html/rfc2060], December 1996.)
165167
#
166-
# [[LANGUAGE-TAGS]]
167-
# Alvestrand, H., "Tags for the Identification of
168-
# Languages", RFC 1766, March 1995.
168+
# [[LANGUAGE-TAGS[https://tools.ietf.org/html/rfc1766]]]
169+
# Phillips, A. and Davis, M. "Tags for Identifying Languages",
170+
# RFC-5646[https://tools.ietf.org/html/rfc5646], September 2009.
171+
# (Note: obsoletes
172+
# RFC-3066[https://tools.ietf.org/html/rfc3066], January 2001,
173+
# RFC-4646[https://tools.ietf.org/html/rfc4646], September 2006, and
174+
# RFC-1766[https://tools.ietf.org/html/rfc1766], March 1995.)
169175
#
170-
# [[MD5]]
171-
# Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
172-
# 1864, October 1995.
176+
# [[MD5[https://tools.ietf.org/html/rfc1864]]]
177+
# Myers, J. and M. Rose, "The Content-MD5 Header Field",
178+
# RFC-1864[https://tools.ietf.org/html/rfc1864], October 1995.
173179
#
174-
# [[MIME-IMB]]
175-
# Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
176-
# Mail Extensions) Part One: Format of Internet Message Bodies", RFC
177-
# 2045, November 1996.
180+
# [[MIME-IMB[https://tools.ietf.org/html/rfc2045]]]
181+
# Freed, N. and N. Borenstein, "MIME (Multipurpose Internet
182+
# Mail Extensions) Part One: Format of Internet Message Bodies",
183+
# RFC-2045[https://tools.ietf.org/html/rfc2045], November 1996.
178184
#
179-
# [[RFC-822]]
180-
# Crocker, D., "Standard for the Format of ARPA Internet Text
181-
# Messages", STD 11, RFC 822, University of Delaware, August 1982.
185+
# [[RFC-5322[https://tools.ietf.org/html/rfc5322]]]
186+
# Resnick, P., "Internet Message Format",
187+
# RFC-5322[https://tools.ietf.org/html/rfc5322], October 2008.
188+
# (Note: obsoletes
189+
# RFC-2822[https://tools.ietf.org/html/rfc2822], April 2001, and
190+
# RFC-822[https://tools.ietf.org/html/rfc822], August 1982.)
182191
#
183-
# [[RFC-2087]]
184-
# Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
192+
# [[EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]]
193+
# Myers, J., "IMAP4 QUOTA extension",
194+
# RFC-2087[https://tools.ietf.org/html/rfc2087], January 1997.
185195
#
186-
# [[RFC-2086]]
187-
# Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
196+
# [[EXT-NAMESPACE[https://tools.ietf.org/html/rfc2342]]]
197+
# Gahrns, M. and Newman, C., "IMAP4 Namespace",
198+
# RFC-2342[https://tools.ietf.org/html/rfc2342], May 1998.
188199
#
189-
# [[RFC-2195]]
190-
# Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension
191-
# for Simple Challenge/Response", RFC 2195, September 1997.
200+
# [[EXT-ID[https://tools.ietf.org/html/rfc2971]]]
201+
# Showalter, T., "IMAP4 ID extension",
202+
# RFC-2971[https://tools.ietf.org/html/rfc2971], October 2000.
192203
#
193-
# [[SORT-THREAD-EXT]]
194-
# Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD
195-
# Extensions", draft-ietf-imapext-sort, May 2003.
204+
# [[EXT-ACL[https://tools.ietf.org/html/rfc4314]]]
205+
# Melnikov, A., "IMAP4 ACL extension",
206+
# RFC-4314[https://tools.ietf.org/html/rfc4314], December 2005. (Note:
207+
# obsoletes RFC-2086[https://tools.ietf.org/html/rfc2086], January 1997.)
208+
#
209+
# [[EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]]
210+
# Crispin, M. and Muchison, K., "INTERNET MESSAGE ACCESS PROTOCOL - SORT
211+
# and THREAD Extensions", RFC-5256[https://tools.ietf.org/html/rfc5256],
212+
# June 2008.
213+
#
214+
# [[EXT-MOVE[https://tools.ietf.org/html/rfc6851]]]
215+
# Gulbrandsen, A. and Freed, N., "Internet Message Access Protocol (\IMAP) -
216+
# MOVE Extension", RFC-6851[https://tools.ietf.org/html/rfc6851], January
217+
# 2013.
196218
#
197219
# [[OSSL]]
198220
# http://www.openssl.org
199221
#
200222
# [[RSSL]]
201223
# http://savannah.gnu.org/projects/rubypki
202224
#
203-
# [[UTF7]]
225+
# [[UTF7[https://tools.ietf.org/html/rfc2152]]]
204226
# Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of
205-
# Unicode", RFC 2152, May 1997.
227+
# Unicode", RFC-2152[https://tools.ietf.org/html/rfc2152], May 1997.
206228
#
207229
class IMAP < Protocol
208230
VERSION = "0.2.1"
@@ -326,7 +348,7 @@ def capability
326348
# )
327349
# end
328350
#
329-
# See RFC 2971, Section 3.3, for defined fields.
351+
# See [EXT-ID[https://tools.ietf.org/html/rfc2971]] for field definitions.
330352
def id(client_id=nil)
331353
synchronize do
332354
send_command("ID", ClientID.new(client_id))
@@ -373,7 +395,7 @@ def starttls(options = {}, verify = true)
373395
#
374396
# For both of these mechanisms, there should be two +args+: username
375397
# and (cleartext) password. A server may not support one or the other
376-
# of these mechanisms; check #capability() for a capability of
398+
# of these mechanisms; check #capability for a capability of
377399
# the form "AUTH=LOGIN" or "AUTH=CRAM-MD5".
378400
#
379401
# Authentication is done using the appropriate authenticator object:
@@ -399,8 +421,8 @@ def authenticate(auth_type, *args)
399421

400422
# Sends a LOGIN command to identify the client and carries
401423
# the plaintext +password+ authenticating this +user+. Note
402-
# that, unlike calling #authenticate() with an +auth_type+
403-
# of "LOGIN", #login() does *not* use the login authenticator.
424+
# that, unlike calling #authenticate with an +auth_type+
425+
# of "LOGIN", #login does *not* use the login authenticator.
404426
#
405427
# A Net::IMAP::NoResponseError is raised if authentication fails.
406428
def login(user, password)
@@ -414,7 +436,7 @@ def login(user, password)
414436
# number of items in that mailbox from +@responses["EXISTS"][-1]+,
415437
# and the number of recent messages from +@responses["RECENT"][-1]+.
416438
# Note that these values can change if new messages arrive
417-
# during a session; see #add_response_handler() for a way of
439+
# during a session; see #add_response_handler for a way of
418440
# detecting this event.
419441
#
420442
# A Net::IMAP::NoResponseError is raised if the mailbox does not
@@ -427,7 +449,7 @@ def select(mailbox)
427449
end
428450

429451
# Sends a EXAMINE command to select a +mailbox+ so that messages
430-
# in the +mailbox+ can be accessed. Behaves the same as #select(),
452+
# in the +mailbox+ can be accessed. Behaves the same as #select,
431453
# except that the selected +mailbox+ is identified as read-only.
432454
#
433455
# A Net::IMAP::NoResponseError is raised if the mailbox does not
@@ -469,7 +491,7 @@ def rename(mailbox, newname)
469491

470492
# Sends a SUBSCRIBE command to add the specified +mailbox+ name to
471493
# the server's set of "active" or "subscribed" mailboxes as returned
472-
# by #lsub().
494+
# by #lsub.
473495
#
474496
# A Net::IMAP::NoResponseError is raised if +mailbox+ cannot be
475497
# subscribed to; for instance, because it does not exist.
@@ -516,15 +538,16 @@ def list(refname, mailbox)
516538
end
517539
end
518540

519-
# Sends a NAMESPACE command [RFC2342] and returns the namespaces that are
520-
# available. The NAMESPACE command allows a client to discover the prefixes
521-
# of namespaces used by a server for personal mailboxes, other users'
541+
# Sends a NAMESPACE command and returns the namespaces that are available.
542+
# The NAMESPACE command allows a client to discover the prefixes of
543+
# namespaces used by a server for personal mailboxes, other users'
522544
# mailboxes, and shared mailboxes.
523545
#
524-
# This extension predates IMAP4rev1 (RFC3501), so most IMAP servers support
525-
# it. Many popular IMAP servers are configured with the default personal
526-
# namespaces as `("" "/")`: no prefix and "/" hierarchy delimiter. In that
527-
# common case, the naive client may not have any trouble naming mailboxes.
546+
# The NAMESPACE extension predates [IMAP4rev1[https://tools.ietf.org/html/rfc2501]],
547+
# so most IMAP servers support it. Many popular IMAP servers are configured
548+
# with the default personal namespaces as `("" "/")`: no prefix and "/"
549+
# hierarchy delimiter. In that common case, the naive client may not have
550+
# any trouble naming mailboxes.
528551
#
529552
# But many servers are configured with the default personal namespace as
530553
# e.g. `("INBOX." ".")`, placing all personal folders under INBOX, with "."
@@ -563,6 +586,8 @@ def list(refname, mailbox)
563586
# imap.create(prefix + %w[path to my folder].join(delim))
564587
# end
565588
# end
589+
#
590+
# The NAMESPACE extension is described in [EXT-NAMESPACE[https://tools.ietf.org/html/rfc2342]]
566591
def namespace
567592
synchronize do
568593
send_command("NAMESPACE")
@@ -606,6 +631,8 @@ def xlist(refname, mailbox)
606631
# This command is generally available to both admin and user.
607632
# If this mailbox exists, it returns an array containing objects of type
608633
# Net::IMAP::MailboxQuotaRoot and Net::IMAP::MailboxQuota.
634+
#
635+
# The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]
609636
def getquotaroot(mailbox)
610637
synchronize do
611638
send_command("GETQUOTAROOT", mailbox)
@@ -620,6 +647,8 @@ def getquotaroot(mailbox)
620647
# If this mailbox exists, then an array containing a
621648
# Net::IMAP::MailboxQuota object is returned. This
622649
# command is generally only available to server admin.
650+
#
651+
# The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]
623652
def getquota(mailbox)
624653
synchronize do
625654
send_command("GETQUOTA", mailbox)
@@ -630,8 +659,9 @@ def getquota(mailbox)
630659
# Sends a SETQUOTA command along with the specified +mailbox+ and
631660
# +quota+. If +quota+ is nil, then +quota+ will be unset for that
632661
# mailbox. Typically one needs to be logged in as a server admin
633-
# for this to work. The IMAP quota commands are described in
634-
# [RFC-2087].
662+
# for this to work.
663+
#
664+
# The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]
635665
def setquota(mailbox, quota)
636666
if quota.nil?
637667
data = '()'
@@ -644,7 +674,8 @@ def setquota(mailbox, quota)
644674
# Sends the SETACL command along with +mailbox+, +user+ and the
645675
# +rights+ that user is to have on that mailbox. If +rights+ is nil,
646676
# then that user will be stripped of any rights to that mailbox.
647-
# The IMAP ACL commands are described in [RFC-2086].
677+
#
678+
# The ACL extension is described in [EXT-ACL[https://tools.ietf.org/html/rfc4314]]
648679
def setacl(mailbox, user, rights)
649680
if rights.nil?
650681
send_command("SETACL", mailbox, user, "")
@@ -656,6 +687,8 @@ def setacl(mailbox, user, rights)
656687
# Send the GETACL command along with a specified +mailbox+.
657688
# If this mailbox exists, an array containing objects of
658689
# Net::IMAP::MailboxACLItem will be returned.
690+
#
691+
# The ACL extension is described in [EXT-ACL[https://tools.ietf.org/html/rfc4314]]
659692
def getacl(mailbox)
660693
synchronize do
661694
send_command("GETACL", mailbox)
@@ -666,7 +699,8 @@ def getacl(mailbox)
666699
# Sends a LSUB command, and returns a subset of names from the set
667700
# of names that the user has declared as being "active" or
668701
# "subscribed." +refname+ and +mailbox+ are interpreted as
669-
# for #list().
702+
# for #list.
703+
#
670704
# The return value is an array of +Net::IMAP::MailboxList+.
671705
def lsub(refname, mailbox)
672706
synchronize do
@@ -794,7 +828,7 @@ def search(keys, charset = nil)
794828
return search_internal("SEARCH", keys, charset)
795829
end
796830

797-
# Similar to #search(), but returns unique identifiers.
831+
# Similar to #search, but returns unique identifiers.
798832
def uid_search(keys, charset = nil)
799833
return search_internal("UID SEARCH", keys, charset)
800834
end
@@ -838,7 +872,7 @@ def fetch(set, attr, mod = nil)
838872
return fetch_internal("FETCH", set, attr, mod)
839873
end
840874

841-
# Similar to #fetch(), but +set+ contains unique identifiers.
875+
# Similar to #fetch, but +set+ contains unique identifiers.
842876
def uid_fetch(set, attr, mod = nil)
843877
return fetch_internal("UID FETCH", set, attr, mod)
844878
end
@@ -861,7 +895,7 @@ def store(set, attr, flags)
861895
return store_internal("STORE", set, attr, flags)
862896
end
863897

864-
# Similar to #store(), but +set+ contains unique identifiers.
898+
# Similar to #store, but +set+ contains unique identifiers.
865899
def uid_store(set, attr, flags)
866900
return store_internal("UID STORE", set, attr, flags)
867901
end
@@ -874,7 +908,7 @@ def copy(set, mailbox)
874908
copy_internal("COPY", set, mailbox)
875909
end
876910

877-
# Similar to #copy(), but +set+ contains unique identifiers.
911+
# Similar to #copy, but +set+ contains unique identifiers.
878912
def uid_copy(set, mailbox)
879913
copy_internal("UID COPY", set, mailbox)
880914
end
@@ -883,12 +917,15 @@ def uid_copy(set, mailbox)
883917
# of the specified destination +mailbox+. The +set+ parameter is
884918
# a number, an array of numbers, or a Range object. The number is
885919
# a message sequence number.
886-
# The IMAP MOVE extension is described in [RFC-6851].
920+
#
921+
# The MOVE extension is described in [EXT-MOVE[https://tools.ietf.org/html/rfc6851]].
887922
def move(set, mailbox)
888923
copy_internal("MOVE", set, mailbox)
889924
end
890925

891-
# Similar to #move(), but +set+ contains unique identifiers.
926+
# Similar to #move, but +set+ contains unique identifiers.
927+
#
928+
# The MOVE extension is described in [EXT-MOVE[https://tools.ietf.org/html/rfc6851]].
892929
def uid_move(set, mailbox)
893930
copy_internal("UID MOVE", set, mailbox)
894931
end
@@ -901,12 +938,14 @@ def uid_move(set, mailbox)
901938
# p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
902939
# #=> [6, 7, 8, 1]
903940
#
904-
# See [SORT-THREAD-EXT] for more details.
941+
# The SORT extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]].
905942
def sort(sort_keys, search_keys, charset)
906943
return sort_internal("SORT", sort_keys, search_keys, charset)
907944
end
908945

909-
# Similar to #sort(), but returns an array of unique identifiers.
946+
# Similar to #sort, but returns an array of unique identifiers.
947+
#
948+
# The SORT extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]].
910949
def uid_sort(sort_keys, search_keys, charset)
911950
return sort_internal("UID SORT", sort_keys, search_keys, charset)
912951
end
@@ -933,7 +972,7 @@ def remove_response_handler(handler)
933972
@response_handlers.delete(handler)
934973
end
935974

936-
# Similar to #search(), but returns message sequence numbers in threaded
975+
# Similar to #search, but returns message sequence numbers in threaded
937976
# format, as a Net::IMAP::ThreadMember tree. The supported algorithms
938977
# are:
939978
#
@@ -942,24 +981,26 @@ def remove_response_handler(handler)
942981
# REFERENCES:: split into threads by parent/child relationships determined
943982
# by which message is a reply to which.
944983
#
945-
# Unlike #search(), +charset+ is a required argument. US-ASCII
984+
# Unlike #search, +charset+ is a required argument. US-ASCII
946985
# and UTF-8 are sample values.
947986
#
948-
# See [SORT-THREAD-EXT] for more details.
987+
# The THREAD extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]].
949988
def thread(algorithm, search_keys, charset)
950989
return thread_internal("THREAD", algorithm, search_keys, charset)
951990
end
952991

953-
# Similar to #thread(), but returns unique identifiers instead of
992+
# Similar to #thread, but returns unique identifiers instead of
954993
# message sequence numbers.
994+
#
995+
# The THREAD extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]].
955996
def uid_thread(algorithm, search_keys, charset)
956997
return thread_internal("UID THREAD", algorithm, search_keys, charset)
957998
end
958999

9591000
# Sends an IDLE command that waits for notifications of new or expunged
9601001
# messages. Yields responses from the server during the IDLE.
9611002
#
962-
# Use #idle_done() to leave IDLE.
1003+
# Use #idle_done to leave IDLE.
9631004
#
9641005
# If +timeout+ is given, this method returns after +timeout+ seconds passed.
9651006
# +timeout+ can be used for keep-alive. For example, the following code

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy