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

+106-65
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)