ruby-changes:66077
From: nicholas <ko1@a...>
Date: Thu, 6 May 2021 15:20:59 +0900 (JST)
Subject: [ruby-changes:66077] 5a02281fab (master): [ruby/net-imap] Many documentation improvements
https://git.ruby-lang.org/ruby.git/commit/?id=5a02281fab From 5a02281fab4f2fc328007bd6238448c73b8d029d Mon Sep 17 00:00:00 2001 From: "nicholas a. evans" <nicholas.evans@g...> Date: Wed, 5 May 2021 15:01:35 -0400 Subject: [ruby/net-imap] 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 https://github.com/ruby/net-imap/commit/9cd562ac84 --- lib/net/imap.rb | 171 ++++++++++++++++++++++++++---------------- lib/net/imap/flags.rb | 20 +++++ lib/net/imap/response_data.rb | 56 +++++++++----- 3 files changed, 163 insertions(+), 84 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 11bc62f..fe5fc14 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -32,12 +32,13 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L32 # # Net::IMAP implements Internet Message Access Protocol (IMAP) client - # functionality. The protocol is described in [IMAP]. + # functionality. The protocol is described in + # [IMAP[https://tools.ietf.org/html/rfc3501]]. # # == IMAP Overview # - # An IMAP client connects to a server, and then authenticates - # itself using either #authenticate() or #login(). Having + # An \IMAP client connects to a server, and then authenticates + # itself using either #authenticate or #login. Having # authenticated itself, there is a range of commands # available to it. Most work with mailboxes, which may be # arranged in an hierarchical namespace, and each of which @@ -47,8 +48,8 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L48 # within a hierarchy of directories. # # To work on the messages within a mailbox, the client must - # first select that mailbox, using either #select() or (for - # read-only access) #examine(). Once the client has successfully + # first select that mailbox, using either #select or (for + # read-only access) #examine. Once the client has successfully # selected a mailbox, they enter _selected_ state, and that # mailbox becomes the _current_ mailbox, on which mail-item # related commands implicitly operate. @@ -69,7 +70,7 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L70 # be assigned in ascending (but not necessarily sequential) # order within a mailbox; this means that if a non-IMAP client # rearranges the order of mailitems within a mailbox, the - # UIDs have to be reassigned. An IMAP client thus cannot + # UIDs have to be reassigned. An \IMAP client thus cannot # rearrange message orders. # # == Examples of Usage @@ -159,40 +160,61 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L160 # # == References # - # [[IMAP]] - # M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", - # RFC 2060, December 1996. (Note: since obsoleted by RFC 3501) + # [[IMAP[https://tools.ietf.org/html/rfc3501]]] + # Crispin, M. "INTERNET MESSAGE ACCESS PROTOCOL - \VERSION 4rev1", + # RFC-3501[https://tools.ietf.org/html/rfc3501], March 2003. (Note: + # obsoletes RFC-2060[https://tools.ietf.org/html/rfc2060], December 1996.) # - # [[LANGUAGE-TAGS]] - # Alvestrand, H., "Tags for the Identification of - # Languages", RFC 1766, March 1995. + # [[LANGUAGE-TAGS[https://tools.ietf.org/html/rfc1766]]] + # Phillips, A. and Davis, M. "Tags for Identifying Languages", + # RFC-5646[https://tools.ietf.org/html/rfc5646], September 2009. + # (Note: obsoletes + # RFC-3066[https://tools.ietf.org/html/rfc3066], January 2001, + # RFC-4646[https://tools.ietf.org/html/rfc4646], September 2006, and + # RFC-1766[https://tools.ietf.org/html/rfc1766], March 1995.) # - # [[MD5]] - # Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC - # 1864, October 1995. + # [[MD5[https://tools.ietf.org/html/rfc1864]]] + # Myers, J. and M. Rose, "The Content-MD5 Header Field", + # RFC-1864[https://tools.ietf.org/html/rfc1864], 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. + # [[MIME-IMB[https://tools.ietf.org/html/rfc2045]]] + # Freed, N. and N. Borenstein, "MIME (Multipurpose Internet + # Mail Extensions) Part One: Format of Internet Message Bodies", + # RFC-2045[https://tools.ietf.org/html/rfc2045], 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-5322[https://tools.ietf.org/html/rfc5322]]] + # Resnick, P., "Internet Message Format", + # RFC-5322[https://tools.ietf.org/html/rfc5322], October 2008. + # (Note: obsoletes + # RFC-2822[https://tools.ietf.org/html/rfc2822], April 2001, and + # RFC-822[https://tools.ietf.org/html/rfc822], August 1982.) # - # [[RFC-2087]] - # Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997. + # [[EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]] + # Myers, J., "IMAP4 QUOTA extension", + # RFC-2087[https://tools.ietf.org/html/rfc2087], January 1997. # - # [[RFC-2086]] - # Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. + # [[EXT-NAMESPACE[https://tools.ietf.org/html/rfc2342]]] + # Gahrns, M. and Newman, C., "IMAP4 Namespace", + # RFC-2342[https://tools.ietf.org/html/rfc2342], May 1998. # - # [[RFC-2195]] - # Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension - # for Simple Challenge/Response", RFC 2195, September 1997. + # [[EXT-ID[https://tools.ietf.org/html/rfc2971]]] + # Showalter, T., "IMAP4 ID extension", + # RFC-2971[https://tools.ietf.org/html/rfc2971], October 2000. # - # [[SORT-THREAD-EXT]] - # Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD - # Extensions", draft-ietf-imapext-sort, May 2003. + # [[EXT-ACL[https://tools.ietf.org/html/rfc4314]]] + # Melnikov, A., "IMAP4 ACL extension", + # RFC-4314[https://tools.ietf.org/html/rfc4314], December 2005. (Note: + # obsoletes RFC-2086[https://tools.ietf.org/html/rfc2086], January 1997.) + # + # [[EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]] + # Crispin, M. and Muchison, K., "INTERNET MESSAGE ACCESS PROTOCOL - SORT + # and THREAD Extensions", RFC-5256[https://tools.ietf.org/html/rfc5256], + # June 2008. + # + # [[EXT-MOVE[https://tools.ietf.org/html/rfc6851]]] + # Gulbrandsen, A. and Freed, N., "Internet Message Access Protocol (\IMAP) - + # MOVE Extension", RFC-6851[https://tools.ietf.org/html/rfc6851], January + # 2013. # # [[OSSL]] # http://www.openssl.org @@ -200,9 +222,9 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L222 # [[RSSL]] # http://savannah.gnu.org/projects/rubypki # - # [[UTF7]] + # [[UTF7[https://tools.ietf.org/html/rfc2152]]] # Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of - # Unicode", RFC 2152, May 1997. + # Unicode", RFC-2152[https://tools.ietf.org/html/rfc2152], May 1997. # class IMAP < Protocol VERSION = "0.2.1" @@ -326,7 +348,7 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L348 # ) # end # - # See RFC 2971, Section 3.3, for defined fields. + # See [EXT-ID[https://tools.ietf.org/html/rfc2971]] for field definitions. def id(client_id=nil) synchronize do send_command("ID", ClientID.new(client_id)) @@ -373,7 +395,7 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L395 # # For both of these mechanisms, there should be two +args+: username # and (cleartext) password. A server may not support one or the other - # of these mechanisms; check #capability() for a capability of + # 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: @@ -399,8 +421,8 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L421 # Sends a LOGIN command to identify the client and carries # the plaintext +password+ authenticating this +user+. Note - # that, unlike calling #authenticate() with an +auth_type+ - # of "LOGIN", #login() does *not* use the login authenticator. + # 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) @@ -414,7 +436,7 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L436 # number of items in that mailbox from +@responses["EXISTS"][-1]+, # and the number of recent messages from +@responses["RECENT"][-1]+. # Note that these values can change if new messages arrive - # during a session; see #add_response_handler() for a way of + # during a session; see #add_response_handler for a way of # detecting this event. # # A Net::IMAP::NoResponseError is raised if the mailbox does not @@ -427,7 +449,7 @@ module Net https://github.com/ruby/ruby/blob/trunk/lib/net/imap.rb#L449 end # Sends a EXAMINE command to select a +mailbox+ so that messages - # in the +mailbox+ can be accessed. Behaves the same as #select(), + # in the +mailbox+ can be accessed. Behaves the same as #select, # except that the selected +mailbox+ is identified as read-only. # # A Net::IMAP::NoResponseError is rais (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/