Skip to content

Commit 2dfdfd4

Browse files
nevansnevans
committed
📚 Update message flags and mailbox attrs rdoc
* Fix formatting and linking that wasn't obviously wrong before, because rdoc wasn't rendering the section comments before. * Add some missing links. * Update mailbox attributes section names * link to #list * simplify section names
1 parent 4fabec9 commit 2dfdfd4

File tree

1 file changed

+83
-74
lines changed

1 file changed

+83
-74
lines changed

‎lib/net/imap/flags.rb

Lines changed: 83 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,28 @@ module Net
44
class IMAP < Protocol
55

66
# -------------------------------------------------------------------------
7-
# :section: Message Flags: system flags
7+
# :section: System Flags
88
#
99
# A message has a list of zero or more named tokens, known as "flags",
1010
# associated with it. A flag is set by its addition to this list and is
11-
# cleared by its removal. There are two types of flags in IMAP4rev2: system
12-
# flags and keywords. A flag of either type can be permanent or
13-
# session-only.
14-
#
15-
# A "system flag" is a message flag name that is predefined in the IMAP
16-
# specification and begins with "\". +Net::IMAP+ returns all system flags
17-
# as symbols, without the "\" prefix.
18-
#
19-
# The descriptions here were copied from the IMAP4rev2 specification:
20-
# [RFC-9051 § 2.3.2](https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2)
21-
#
22-
# See [RFC-3501 § 2.3.2](https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2)
23-
# for a description of the flags message attribute and system flag semantics
24-
# in IMAP4rev1.
11+
# cleared by its removal. There are two types of flags in
12+
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html] and
13+
# IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html]: flags and
14+
# keywords. A flag of either type can be permanent or session-only.
15+
#
16+
# A "system flag" is a message flag name that is predefined in the \IMAP
17+
# specifications and begins with <tt>"\"</tt>. Net::IMAP returns all
18+
# system flags as symbols, without the <tt>"\"</tt> prefix.
19+
#
20+
# <em>The descriptions here were copied from</em> {[RFC-9051
21+
# §2.3.2]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2].
22+
# <em>See also</em> {[RFC-3501
23+
# §2.3.2]}[https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2],
24+
# <em>which describes the flags message attribute semantics under</em>
25+
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html].
2526
# -------------------------------------------------------------------------
2627

28+
##
2729
# Flag indicating a message has been read.
2830
SEEN = :Seen
2931

@@ -52,30 +54,32 @@ class IMAP < Protocol
5254
# of this message.
5355
#
5456
# This flag was defined by
55-
# IMAP4rev1 [RFC-3501](https://www.rfc-editor.org/rfc/rfc3501.html),
56-
# and has been deprecated by
57-
# IMAP4rev2 [RFC-9051](https://www.rfc-editor.org/rfc/rfc9051.html).
57+
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html]
58+
# and is deprecated by
59+
# IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html].
5860
RECENT = :Recent
5961

6062
# -------------------------------------------------------------------------
61-
# :section: Mailbox Name Attributes, Base attributes
62-
# Mailbox name attributes will be returned in LIST responses. Base
63+
# :section: Basic Mailbox Attributes
64+
# Mailbox name attributes will be returned in #list responses. Base
6365
# attributes must be returned according to the server's capabilities.
6466
#
6567
# IMAP4 specifies that all mailbox name attributes, including future
66-
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
67-
# symbols, without the "\" prefix.
68+
# extensions, begin with <tt>"\"</tt>. Net::IMAP returns all mailbox
69+
# attributes as symbols, without the <tt>"\"</tt> prefix.
6870
#
69-
# The descriptions here were copied from the IMAP4rev2 specification:
70-
# [RFC9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
7171
#
72-
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
73-
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
72+
# <em>The descriptions here were copied from</em> {[RFC-9051 §
73+
# 7.3.1]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1].
74+
#
75+
# Other mailbox name attributes can be found in the {IANA IMAP Mailbox Name
76+
# Attributes registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml].
7477
# -------------------------------------------------------------------------
7578

76-
# The "\NonExistent" attribute indicates that a mailbox name does not refer
79+
##
80+
# The +\NonExistent+ attribute indicates that a mailbox name does not refer
7781
# to an existing mailbox. Note that this attribute is not meaningful by
78-
# itself, as mailbox names that match the canonical LIST pattern but don't
82+
# itself, as mailbox names that match the canonical #list pattern but don't
7983
# exist must not be returned unless one of the two conditions listed below
8084
# is also satisfied:
8185
#
@@ -84,23 +88,23 @@ class IMAP < Protocol
8488
# specified).
8589
#
8690
# 2. "RECURSIVEMATCH" has been specified, and the mailbox name has at least
87-
# one descendant mailbox name that does not match the LIST pattern and
91+
# one descendant mailbox name that does not match the #list pattern and
8892
# does match the selection criteria.
8993
#
90-
# In practice, this means that the "\NonExistent" attribute is usually
91-
# returned with one or more of "\Subscribed", "\Remote", "\HasChildren", or
94+
# In practice, this means that the +\NonExistent+ attribute is usually
95+
# returned with one or more of +\Subscribed+, +\Remote+, +\HasChildren+, or
9296
# the CHILDINFO extended data item.
9397
#
94-
# The client must treat the presence of the \NonExistent attribute as if the
95-
# \NoSelect attribute was also sent by the server
98+
# The client must treat the presence of the +\NonExistent+ attribute as if the
99+
# +\NoSelect+ attribute was also sent by the server
96100
NONEXISTENT = :NonExistent
97101

98102
# Mailbox attribute indicating it is not possible for any child levels of
99103
# hierarchy to exist under this name; no child levels exist now and none can
100104
# be created in the future children.
101105
#
102-
# The client must treat the presence of the \NoInferiors attribute as if the
103-
# \HasNoChildren attribute was also sent by the server
106+
# The client must treat the presence of the +\NoInferiors+ attribute as if the
107+
# +\HasNoChildren+ attribute was also sent by the server
104108
NOINFERIORS = :Noinferiors
105109

106110
# Mailbox attribute indicating it is not possible to use this name as a
@@ -110,80 +114,83 @@ class IMAP < Protocol
110114
# The presence of this attribute indicates that the mailbox has child
111115
# mailboxes. A server SHOULD NOT set this attribute if there are child
112116
# mailboxes and the user does not have permission to access any of them. In
113-
# this case, \HasNoChildren SHOULD be used. In many cases, however, a server
114-
# may not be able to efficiently compute whether a user has access to any
115-
# child mailboxes. Note that even though the \HasChildren attribute for a
116-
# mailbox must be correct at the time of processing the mailbox, a client
117-
# must be prepared to deal with a situation when a mailbox is marked with
118-
# the \HasChildren attribute, but no child mailbox appears in the response
119-
# to the LIST command. This might happen, for example, due to child
117+
# this case, +\HasNoChildren+ SHOULD be used. In many cases, however, a
118+
# server may not be able to efficiently compute whether a user has access to
119+
# any child mailboxes. Note that even though the +\HasChildren+ attribute
120+
# for a mailbox must be correct at the time of processing the mailbox, a
121+
# client must be prepared to deal with a situation when a mailbox is marked
122+
# with the +\HasChildren+ attribute, but no child mailbox appears in the
123+
# response to the #list command. This might happen, for example, due to child
120124
# mailboxes being deleted or made inaccessible to the user (using access
121125
# control) by another client before the server is able to list them.
122126
#
123-
# It is an error for the server to return both a \HasChildren and a
124-
# \HasNoChildren attribute in the same LIST response. A client that
125-
# encounters a LIST response with both \HasChildren and \HasNoChildren
126-
# attributes present should act as if both are absent in the LIST response.
127+
# It is an error for the server to return both a +\HasChildren+ and a
128+
# +\HasNoChildren+ attribute in the same #list response. A client that
129+
# encounters a #list response with both +\HasChildren+ and +\HasNoChildren+
130+
# attributes present should act as if both are absent in the #list response.
127131
HAS_CHILDREN = :HasChildren
128132

129133
# The presence of this attribute indicates that the mailbox has NO child
130134
# mailboxes that are accessible to the currently authenticated user.
131135
#
132-
# It is an error for the server to return both a \HasChildren and a
133-
# \HasNoChildren attribute in the same LIST response. A client that
134-
# encounters a LIST response with both \HasChildren and \HasNoChildren
135-
# attributes present should act as if both are absent in the LIST response.
136+
# It is an error for the server to return both a +\HasChildren+ and a
137+
# +\HasNoChildren+ attribute in the same #list response. A client that
138+
# encounters a #list response with both +\HasChildren+ and +\HasNoChildren+
139+
# attributes present should act as if both are absent in the #list response.
136140
#
137-
# Note: the \HasNoChildren attribute should not be confused with the
138-
# \NoInferiors attribute, which indicates that no child mailboxes exist now
139-
# and none can be created in the future.
141+
# Note: the +\HasNoChildren+ attribute should not be confused with the
142+
# +\NoInferiors+ attribute, which indicates that no child mailboxes exist
143+
# now and none can be created in the future.
140144
HAS_NO_CHILDREN = :HasNoChildren
141145

142146
# The mailbox has been marked "interesting" by the server; the mailbox
143147
# probably contains messages that have been added since the last time the
144148
# mailbox was selected.
145149
#
146150
# If it is not feasible for the server to determine whether or not the
147-
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
148-
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
149-
# and \Noselect for a single mailbox, and it MAY send none of these.
151+
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
152+
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
153+
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
154+
# these.
150155
MARKED = :Marked
151156

152157
# The mailbox does not contain any additional messages since the last time
153158
# the mailbox was selected.
154159
#
155160
# If it is not feasible for the server to determine whether or not the
156-
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
157-
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
158-
# and \Noselect for a single mailbox, and it MAY send none of these.
161+
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
162+
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
163+
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
164+
# these.
159165
UNMARKED = :Unmarked
160166

161-
# The mailbox name was subscribed to using the SUBSCRIBE command.
167+
# The mailbox name was subscribed to using the #subscribe command.
162168
SUBSCRIBED = :Subscribed
163169

164170
# The mailbox is a remote mailbox.
165171
REMOTE = :Remove
166172

167173
# -------------------------------------------------------------------------
168-
# :section: Mailbox Name Attributes, Special Use
169-
# Mailbox name attributes will be returned in LIST responses. In addition
170-
# to the base mailbox name attributes defined above, an IMAP server MAY also
171-
# include any or all of the following attributes that denote "role" (or
174+
# :section: Mailbox role attributes
175+
#
176+
# Mailbox name attributes will be returned in #list responses. In addition
177+
# to the base mailbox name attributes defined above, an \IMAP server MAY
178+
# also include any or all of the following attributes that denote "role" (or
172179
# "special-use") of a mailbox. These attributes are included along with base
173180
# attributes defined above. A given mailbox may have none, one, or more than
174181
# one of these attributes. In some cases, a special use is advice to a
175182
# client about what to put in that mailbox. In other cases, it's advice to a
176183
# client about what to expect to find there.
177184
#
178185
# IMAP4 specifies that all mailbox name attributes, including future
179-
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
180-
# symbols, without the "\" prefix.
186+
# extensions, begin with <tt>"\"</tt>. Net::IMAP returns all mailbox
187+
# attributes as symbols, without the <tt>"\"</tt> prefix.
181188
#
182-
# The descriptions here were copied from the IMAP4rev2 specification:
183-
# [RFC-9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
189+
# <em>The descriptions here were copied from</em> {[RFC-9051 §
190+
# 7.3.1]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1].
184191
#
185-
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
186-
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
192+
# Other mailbox name attributes can be found in the {IANA IMAP Mailbox Name
193+
# Attributes registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml].
187194
# -------------------------------------------------------------------------
188195

189196
# Mailbox attribute indicating that this mailbox presents all messages in
@@ -206,7 +213,9 @@ class IMAP < Protocol
206213
# client put drafts here
207214
DRAFTS = :Drafts
208215

209-
# FLAGGED is defined with the system flags section.
216+
#--
217+
# n.b. FLAGGED is defined in the system flags section.
218+
#++
210219

211220
# Mailbox attribute indicating that this mailbox is where messages deemed to
212221
# be junk mail are held. Some server implementations might put messages here
@@ -223,10 +232,10 @@ class IMAP < Protocol
223232
# Mailbox attribute indicating that this mailbox is used to hold messages
224233
# that have been deleted or marked for deletion. In some server
225234
# implementations, this might be a virtual mailbox, containing messages from
226-
# other mailboxes that are marked with the "\Deleted" message flag.
235+
# other mailboxes that are marked with the +\Deleted+ message flag.
227236
# Alternatively, this might just be advice that a client that chooses not to
228-
# use the IMAP "\Deleted" model should use as its trash location. In server
229-
# implementations that strictly expect the IMAP "\Deleted" model, this
237+
# use the \IMAP +\Deleted+ model should use as its trash location. In server
238+
# implementations that strictly expect the \IMAP +\Deleted+ model, this
230239
# special use is likely not to be supported.
231240
TRASH = :Trash
232241

0 commit comments

Comments
 (0)