📚 Document "What's here?" for Net::IMAP class [🚧 tidy up...]

This "What's here?" section is based on the new documentation style for
many core ruby classes.  It isn't purely a list of methods; paragraphs
of explanatory text are interspersed.

lib/net/imap.rb

@@ -154,6 +154,204 @@ module Net
   # between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is
   # thrown if a server response is non-parseable.
   #
+  # == What's here?
+  #
+  # * {Connection control}[rdoc-ref:Net::IMAP@Connection+control+methods]
+  # * {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands]
+  #   * {...in any state}[rdoc-ref:Net::IMAP@IMAP+commands+for+any+state]
+  #   * {...in "not authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Not+Authenticated-22+state]
+  #   * {...in "authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Authenticated-22+state]
+  #   * {...in "selected" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Selected-22+state]
+  #   * {...in "logout" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Logout-22+state]
+  # * {IMAP extensions}[rdoc-ref:Net::IMAP@Supported+IMAP+extensions]
+  # * {Handling server responses}[rdoc-ref:Net::IMAP@Handling+server+responses]
+  #
+  # === Connection control methods
+  #
+  # - Net::IMAP.new: A new client connects immediately and waits for a
+  #   successful server greeting before returning the new client object.
+  # - #starttls: Asks the server to upgrade a clear-text connection to use TLS.
+  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  # - #disconnect: Disconnects the connection (without sending #logout first).
+  # - #disconnected?: True if the connection has been closed.
+  #
+  # === Core \IMAP commands
+  #
+  # The following commands are defined either by
+  # the [IMAP4rev1[https://tools.ietf.org/html/rfc3501]] base specification, or
+  # by one of the following extensions:
+  # [IDLE[https://tools.ietf.org/html/rfc2177]],
+  # [NAMESPACE[https://tools.ietf.org/html/rfc2342]],
+  # [UNSELECT[https://tools.ietf.org/html/rfc3691]],
+  #--
+  # TODO: [ENABLE[https://tools.ietf.org/html/rfc5161]],
+  # TODO: [LIST-EXTENDED[https://tools.ietf.org/html/rfc5258]],
+  # TODO: [LIST-STATUS[https://tools.ietf.org/html/rfc5819]],
+  #++
+  # [MOVE[https://tools.ietf.org/html/rfc6851]].
+  # These extensions are widely supported by modern IMAP4rev1 servers and have
+  # all been integrated into [IMAP4rev2[https://tools.ietf.org/html/rfc9051]].
+  # <em>Note: Net::IMAP doesn't fully support IMAP4rev2 yet.</em>
+  #
+  #--
+  # TODO: When IMAP4rev2 is supported, add the following to the each of the
+  # appropriate commands below.
+  #   Note:: CHECK has been removed from IMAP4rev2.
+  #   Note:: LSUB is obsoleted by +LIST-EXTENDED and has been removed from IMAP4rev2.
+  #   <em>Some arguments require the +LIST-EXTENDED+ or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +ENABLE+    or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +NAMESPACE+ or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +IDLE+      or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +UNSELECT+  or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +UIDPLUS+   or +IMAP4rev2+ capability.</em>
+  #   <em>Requires either the +MOVE+      or +IMAP4rev2+ capability.</em>
+  #++
+  #
+  # ==== \IMAP commands for any state
+  #
+  # - #capability: Returns the server's capabilities as an array of strings.
+  #
+  #   <em>Capabilities may change after</em> #starttls, #authenticate, or #login
+  #   <em>and cached capabilities must be reloaded.</em>
+  # - #noop: Allows the server to send unsolicited untagged #responses.
+  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  #
+  # ==== \IMAP commands for the "Not Authenticated" state
+  #
+  # In addition to the universal commands, the following commands are valid in
+  # the "<em>not authenticated</em>" state:
+  #
+  # - #starttls: Upgrades a clear-text connection to use TLS.
+  #
+  #   <em>Requires the +STARTTLS+ capability.</em>
+  # - #authenticate: Identifies the client to the server using a {SASL
+  #   mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml].
+  #   Enters the "_authenticated_" state.
+  #
+  #   <em>Requires the <tt>AUTH=#{mechanism}</tt> capability for the chosen
+  #   mechanism.</em>
+  #
+  #   <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
+  # - #login: Identifies the client to the server using a simple plain text
+  #   username and password.  Only use as a last resort (after attempting and
+  #   failing with #authenticate).  Enters the "_authenticated_" state.
+  #
+  #   <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
+  #
+  # ==== \IMAP commands for the "Authenticated" state
+  #
+  # In addition to the universal commands, the following commands are valid in
+  # the "_authenticated_" state:
+  #
+  #--
+  # - #enable: <em>Not implemented by Net::IMAP, yet.</em>
+  #
+  #   <em>Requires the +ENABLE+ capability.</em>
+  #++
+  # - #select:  Open a mailbox and enter the "_selected_" state.
+  # - #examine: Open a mailbox read-only, and enter the "_selected_" state.
+  # - #create: Creates a new mailbox.
+  # - #delete: Permanently remove a mailbox.
+  # - #rename: Change the name of a mailbox.
+  # - #subscribe: Adds a mailbox to the "subscribed" set.
+  # - #unsubscribe: Removes a mailbox from the "subscribed" set.
+  # - #list: Returns names and attributes of mailboxes matching a given pattern.
+  # - #namespace: Returns the namespaces for personal mailboxes, other users'
+  #   mailboxes, and shared mailboxes, with the prefixes and path delimiters
+  #   used for the mailbox names within each namespace.
+  #
+  #   <em>Requires the +NAMESPACE+ capability.</em>
+  # - #status: Returns mailbox information, e.g. message count, unseen message
+  #   count, +UIDVALIDITY+ and +UIDNEXT+.
+  # - #append: Appends a message to the end of a mailbox.
+  # - #idle: Allows the server to send updates to the client, without the client
+  #   needing to poll using #noop.
+  #
+  #   <em>Requires the +IDLE+ capability.</em>
+  # - #lsub: Lists mailboxes the user has declared "active" or "subscribed".
+  #
+  # ==== \IMAP commands for the "Selected" state
+  #
+  # In addition to the universal commands and the "authenticated" commands, the
+  # following commands are valid in the "_selected_" state:
+  #
+  # - #close: Closes the mailbox and returns to the "_authenticated_" state.
+  #   Messages with the Deleted flag are permanently removed, unless the mailbox
+  #   was opened as read-only.
+  # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
+  #   without expunging any messages.
+  #
+  #   <em>Requires the +UNSELECT+ capability.</em>
+  # - #expunge: Permanently removes messages which have the Deleted flag set.
+  # - #uid_expunge: Restricts #expunge to only remove the specified UIDs.
+  #
+  #   <em>Requires the +UIDPLUS+ capability.</em>
+  # - #search, #uid_search: Returns sequence numbers or UIDs of messages that
+  #   match the given searching criteria.
+  # - #fetch, #uid_fetch: Returns data associated with a set of messages,
+  #   specified by sequence number or UID.
+  # - #store, #uid_store: Alters a message's flags.
+  # - #copy, #uid_copy: Copies the specified messages to the end of the
+  #   specified destination mailbox.
+  # - #move, #uid_move: Moves the specified messages to the end of the
+  #   specified destination mailbox, expunging them from the current mailbox.
+  #
+  #   <em>Requires the +MOVE+ capability.</em>
+  # - #check: Mostly obsolete.  Can be replaced with #noop or #idle.
+  #
+  # ==== \IMAP commands for the "Logout" state
+  #
+  # No \IMAP commands are valid in the +logout+ state.  If the socket is still
+  # open, Net::IMAP will close it after receiving server confirmation.
+  # Exceptions will be raised by \IMAP commands that have already started and
+  # are waiting for a response, as well as any that are called after logout.
+  #
+  # === Supported \IMAP extensions
+  #
+  # ==== +IMAP4rev2+ [RFC9051[https://tools.ietf.org/html/rfc9051]]
+  #
+  # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is <em>not supported
+  # yet</em>, Net::IMAP supports several extensions that have been folded into
+  # it: +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
+  #--
+  # TODO: +ENABLE+, +LIST-EXTENDED+, +LIST-STATUS+
+  #++
+  # Commands for these extensions are included with the {Core IMAP
+  # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.  Other supported
+  # extensons are listed below.
+  #
+  # ==== +ID+ [RFC2971[https://tools.ietf.org/html/rfc2971]]
+  # - #id: exchanges client and server implementation information.
+  # ==== +QUOTA+ [RFC2087[https://tools.ietf.org/html/rfc2087]]
+  # - #getquota: returns the resource usage and limits for a quota root
+  # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
+  #   their resource usage and limits.
+  # - #setquota: sets the resource limits for a given quota root.
+  # ==== +ACL+ [RFC4314[https://tools.ietf.org/html/rfc4314]]
+  # - #getacl: lists the authenticated user's access rights to a mailbox.
+  # - #setacl: sets the access rights for a user on a mailbox
+  # ==== +SORT+ [RFC5256[https://tools.ietf.org/html/rfc5256]]
+  # - #sort, #uid_sort: An alternate version of #search or #uid_search which
+  #   sorts the results by specified keys.
+  # ==== +THREAD+ [RFC5256[https://tools.ietf.org/html/rfc5256]]
+  # - #thread, #uid_thread: An alternate version of #search or #uid_search,
+  #   which arranges the results into ordered groups or threads according to a
+  #   chosen algorithm.
+  # ==== +XLIST+ (non-standard, deprecated)
+  # - #xlist: replaced by +SPECIAL-USE+ attributes in #list responses.
+  #
+  # === Handling server responses
+  #
+  # - #greeting: The server's initial untagged response, which can indicate a
+  #   pre-authenticated connection.
+  # - #responses: The untagged responses, as a hash.  Keys are the untagged
+  #   response type (e.g. "OK", "FETCH", "FLAGS") and response code (e.g.
+  #   "ALERT", "UIDVALIDITY", "UIDNEXT", "TRYCREATE", etc).  Values are arrays
+  #   of UntaggedResponse or ResponseCode.
+  # - #add_response_handler: Add a block to be called inside the receiver thread
+  #   with every server response.
+  # - #remove_response_handler: Remove a previously added response handler.
+  #
   #
   # == References
   #--