📚 Improve documentation on FetchData

lib/net/imap/fetch_data.rb

@@ -63,8 +63,7 @@ class IMAP < Protocol
     #   * <b><tt>"X-GM-MSGID"</tt></b> --- unique message ID.  Access via #attr.
     #   * <b><tt>"X-GM-THRID"</tt></b> --- Thread ID.  Access via #attr.
     #
-    # [Note:]
-    #   >>>
+    # [NOTE:]
     #     Additional static fields are defined in other \IMAP extensions, but
     #     Net::IMAP can't parse them yet.
     #
@@ -87,8 +86,7 @@ class IMAP < Protocol
     #   extension]}[https://developers.google.com/gmail/imap/imap-extensions]
     #   * <b><tt>"X-GM-LABELS"</tt></b> --- Gmail labels.  Access via #attr.
     #
-    # [Note:]
-    #   >>>
+    # [NOTE:]
     #     Additional dynamic fields are defined in other \IMAP extensions, but
     #     Net::IMAP can't parse them yet.
     #
@@ -100,21 +98,24 @@ class IMAP < Protocol
     # <tt>BODY.PEEK[#{section}]</tt> or <tt>BINARY.PEEK[#{section}]</tt>
     # instead.
     #
-    # Note that the data will always be _returned_ without <tt>".PEEK"</tt>, in
-    # <tt>BODY[#{specifier}]</tt> or <tt>BINARY[#{section}]</tt>.
+    # [NOTE:]
+    #   The data will always be _returned_ without the <tt>".PEEK"</tt> suffix,
+    #   as <tt>BODY[#{specifier}]</tt> or <tt>BINARY[#{section}]</tt>.
     #
     class FetchData < Struct.new(:__msg_id_num__, :attr)
       protected :__msg_id_num__
 
       alias seqno __msg_id_num__
+      # why won't rdoc 6.7 render documention added directly above this alias?
+
       ##
       # method: seqno
       # :call-seq: seqno -> Integer
       #
       # The message sequence number.
       #
-      # [Note]
-      #   This is never the unique identifier (UID), not even for the
+      # [NOTE:]
+      #   This is not the same as the unique identifier (UID), not even for the
       #   Net::IMAP#uid_fetch result.  The UID is available from #uid, if it was
       #   returned.
 
@@ -127,8 +128,8 @@ class FetchData < Struct.new(:__msg_id_num__, :attr)
       # accessor methods.  The definitions of each attribute type is documented
       # on its accessor.
       #
-      # >>>
-      #   *Note:* #seqno is not a message attribute.
+      # [NOTE:]
+      #   #seqno is not a message attribute.
 
       # :call-seq: attr_upcase -> hash
       #
@@ -145,7 +146,7 @@ def attr_upcase; attr.transform_keys(&:upcase) end
       #
       # This is the same as getting the value for <tt>"BODY"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   Use #message, #part, #header, #header_fields, #header_fields_not,
       #   #text, or #mime to retrieve <tt>BODY[#{section_spec}]</tt> attributes.
       def body; attr["BODY"] end
@@ -324,15 +325,15 @@ def bodystructure; attr["BODYSTRUCTURE"] end
       # #attr.
       def envelope; attr["ENVELOPE"] end
 
-      # :call-seq: flags -> array of Symbols and Strings
+      # :call-seq: flags -> array of Symbols and Strings, or nil
       #
       # A array of flags that are set for this message.  System flags are
       # symbols that have been capitalized by String#capitalize.  Keyword flags
       # are strings and their case is not changed.
       #
       # This is the same as getting the value for <tt>"FLAGS"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   The +FLAGS+ field is dynamic, and can change for a uniquely identified
       #   message.
       def flags; attr["FLAGS"] end
@@ -347,7 +348,7 @@ def flags; attr["FLAGS"] end
       # This is similar to getting the value for <tt>"INTERNALDATE"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   <tt>attr["INTERNALDATE"]</tt> returns a string, and this method
       #   returns a Time object.
       def internaldate
@@ -356,25 +357,25 @@ def internaldate
 
       alias internal_date internaldate
 
-      # :call-seq: rfc822 -> String
+      # :call-seq: rfc822 -> String or nil
       #
       # Semantically equivalent to #message with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822</tt>.
       def rfc822; attr["RFC822"] end
 
-      # :call-seq: rfc822_size -> Integer
+      # :call-seq: rfc822_size -> Integer or nil
       #
       # A number expressing the [RFC5322[https://tools.ietf.org/html/rfc5322]]
       # size of the message.
       #
       # This is the same as getting the value for <tt>"RFC822.SIZE"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   \IMAP was originally developed for the older
       #   RFC822[https://www.rfc-editor.org/rfc/rfc822.html] standard, and as a
       #   consequence several fetch items in \IMAP incorporate "RFC822" in their
@@ -385,30 +386,36 @@ def rfc822; attr["RFC822"] end
       #   RFC5322[https://www.rfc-editor.org/rfc/rfc5322.html] standard.
       def rfc822_size; attr["RFC822.SIZE"] end
 
-      alias size rfc822_size
+      # NOTE: a bug in rdoc 6.7 prevents us from adding a call-seq to
+      # rfc822_size _and_ aliasing size => rfc822_size.  Is it because this
+      # class inherits from Struct?
+
+      # Alias for: rfc822_size
+      def size; rfc822_size end
+
 
-      # :call-seq: rfc822_header -> String
+      # :call-seq: rfc822_header -> String or nil
       #
       # Semantically equivalent to #header, with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822.HEADER"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822.HEADER</tt>.
       def rfc822_header; attr["RFC822.HEADER"] end
 
-      # :call-seq: rfc822_text -> String
+      # :call-seq: rfc822_text -> String or nil
       #
       # Semantically equivalent to #text, with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822.TEXT"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822.TEXT</tt>.
       def rfc822_text; attr["RFC822.TEXT"] end
 
-      # :call-seq: uid -> Integer
+      # :call-seq: uid -> Integer or nil
       #
       # A number expressing the unique identifier of the message.
       #
@@ -458,7 +465,7 @@ def binary_size(*part_nums)
         attr[section_attr("BINARY.SIZE", part_nums)]
       end
 
-      # :call-seq: modseq -> Integer
+      # :call-seq: modseq -> Integer or nil
       #
       # The modification sequence number associated with this IMAP message.
       #
@@ -467,7 +474,7 @@ def binary_size(*part_nums)
       # The server must support the +CONDSTORE+ extension
       # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
       #
-      # [Note]
+      # [NOTE:]
       #   The +MODSEQ+ field is dynamic, and can change for a uniquely
       #   identified message.
       def modseq; attr["MODSEQ"] end

rakelib/rfcs.rake

@@ -146,6 +146,7 @@ RFCS = {
   8970 => "IMAP PREVIEW",
   9208 => "IMAP QUOTA, QUOTA=, QUOTASET",
   9394 => "IMAP PARTIAL",
+  9586 => "IMAP UIDONLY",
 
   # etc...
   3629 => "UTF8",