docs: Add example for customizing IMAP folders (#2045)

* docs: Add example for customizing IMAP folders (mailboxes)

* chore: Update `15-mailboxes.conf` to sync with upstream

This config has not been updated since 2016 (ignoring the Junk autosubscribe addition).

Synced to upstream equivalent at https://github.com/dovecot/core/blob/master/doc/example-config/conf.d/15-mailboxes.conf

Retains the `Archive` example definition from this PR and prior `auto = subscribe` additions.

---

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

target/dovecot/15-mailboxes.conf

@@ -2,19 +2,50 @@
 ## Mailbox definitions
 ##
 
+# Each mailbox is specified in a separate mailbox section. The section name
+# specifies the mailbox name. If it has spaces, you can put the name
+# "in quotes". These sections can contain the following mailbox settings:
+#
+# auto:
+#   Indicates whether the mailbox with this name is automatically created
+#   implicitly when it is first accessed. The user can also be automatically
+#   subscribed to the mailbox after creation. The following values are
+#   defined for this setting:
+#
+#     no        - Never created automatically.
+#     create    - Automatically created, but no automatic subscription.
+#     subscribe - Automatically created and subscribed.
+#
+# special_use:
+#   A space-separated list of SPECIAL-USE flags (RFC 6154) to use for the
+#   mailbox. There are no validity checks, so you could specify anything
+#   you want in here, but it's not a good idea to use flags other than the
+#   standard ones specified in the RFC:
+#
+#     \All       - This (virtual) mailbox presents all messages in the
+#                  user's message store.
+#     \Archive   - This mailbox is used to archive messages.
+#     \Drafts    - This mailbox is used to hold draft messages.
+#     \Flagged   - This (virtual) mailbox presents all messages in the
+#                  user's message store marked with the IMAP \Flagged flag.
+#     \Important - This (virtual) mailbox presents all messages in the
+#                  user's message store deemed important to user.
+#     \Junk      - This mailbox is where messages deemed to be junk mail
+#                  are held.
+#     \Sent      - This mailbox is used to hold copies of messages that
+#                  have been sent.
+#     \Trash     - This mailbox is used to hold messages that have been
+#                  deleted.
+#
+# comment:
+#   Defines a default comment or note associated with the mailbox. This
+#   value is accessible through the IMAP METADATA mailbox entries
+#   "/shared/comment" and "/private/comment". Users with sufficient
+#   privileges can override the default value for entries with a custom
+#   value.
+
 # NOTE: Assumes "namespace inbox" has been defined in 10-mail.conf.
 namespace inbox {
-
-  #mailbox name {
-    # auto=create will automatically create this mailbox.
-    # auto=subscribe will both create and subscribe to the mailbox.
-    #auto = no
-
-    # Space separated list of IMAP SPECIAL-USE attributes as specified by
-    # RFC 6154: \All \Archive \Drafts \Flagged \Junk \Sent \Trash
-    #special_use =
-  #}
-
   # These mailboxes are widely used and could perhaps be created automatically:
   mailbox Drafts {
     auto = subscribe
@@ -35,17 +66,31 @@ namespace inbox {
     auto = subscribe
     special_use = \Sent
   }
-#  mailbox "Sent Messages" {
-#    special_use = \Sent
-#  }
+
+  #mailbox "Sent Messages" {
+  #  special_use = \Sent
+  #}
+
+  #mailbox Archive {
+  #  auto = subscribe
+  #  special_use = \Archive
+  #}
 
   # If you have a virtual "All messages" mailbox:
   #mailbox virtual/All {
   #  special_use = \All
+  #  comment = All my messages
   #}
 
   # If you have a virtual "Flagged" mailbox:
   #mailbox virtual/Flagged {
   #  special_use = \Flagged
+  #  comment = All my flagged messages
+  #}
+
+  # If you have a virtual "Important" mailbox:
+  #mailbox virtual/Important {
+  #  special_use = \Important
+  #  comment = All my important messages
   #}
 }