gh-90890: Reorder mailbox.Maildir method documentation (GH-113071)

When new mailbox.Maildir methods were added for 3.13.0a2, their
documentation was added at the end of the mailbox.Maildir section
instead of grouping them with other methods Maildir adds to Mailbox.

This commit moves the new methods' documentation adjacent to
documentation for existing Maildir-specific methods, so that
the "special remarks" for common methods remains at the end.

diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 05ffaf6c9b336e2eb291b3e5bbec9651e696e380..fd60d163378f071b023030983fedf3fe81efed93 100644 (file)
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -383,46 +383,6 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
       last 36 hours. The Maildir specification says that mail-reading programs
       should do this occasionally.
 
-   Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
-   remarks:
-
-
-   .. method:: add(message)
-               __setitem__(key, message)
-               update(arg)
-
-      .. warning::
-
-         These methods generate unique file names based upon the current process
-         ID. When using multiple threads, undetected name clashes may occur and
-         cause corruption of the mailbox unless threads are coordinated to avoid
-         using these methods to manipulate the same mailbox simultaneously.
-
-
-   .. method:: flush()
-
-      All changes to Maildir mailboxes are immediately applied, so this method
-      does nothing.
-
-
-   .. method:: lock()
-               unlock()
-
-      Maildir mailboxes do not support (or require) locking, so these methods do
-      nothing.
-
-
-   .. method:: close()
-
-      :class:`Maildir` instances do not keep any open files and the underlying
-      mailboxes do not support locking, so this method does nothing.
-
-
-   .. method:: get_file(key)
-
-      Depending upon the host platform, it may not be possible to modify or
-      remove the underlying message while the returned file remains open.
-
 
    .. method:: get_flags(key)
 
@@ -525,6 +485,46 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
 
       .. versionadded:: 3.13
 
+   Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
+   remarks:
+
+
+   .. method:: add(message)
+               __setitem__(key, message)
+               update(arg)
+
+      .. warning::
+
+         These methods generate unique file names based upon the current process
+         ID. When using multiple threads, undetected name clashes may occur and
+         cause corruption of the mailbox unless threads are coordinated to avoid
+         using these methods to manipulate the same mailbox simultaneously.
+
+
+   .. method:: flush()
+
+      All changes to Maildir mailboxes are immediately applied, so this method
+      does nothing.
+
+
+   .. method:: lock()
+               unlock()
+
+      Maildir mailboxes do not support (or require) locking, so these methods do
+      nothing.
+
+
+   .. method:: close()
+
+      :class:`Maildir` instances do not keep any open files and the underlying
+      mailboxes do not support locking, so this method does nothing.
+
+
+   .. method:: get_file(key)
+
+      Depending upon the host platform, it may not be possible to modify or
+      remove the underlying message while the returned file remains open.
+
 
 .. seealso::