From 4d5d9acb22ee8c6908ebd4fdc3d17472f8b286e3 Mon Sep 17 00:00:00 2001
From: Stephen Gildea <stepheng-bpo@gildea.com>
Date: Wed, 13 Dec 2023 23:53:08 -0800
Subject: 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.
---
 Doc/library/mailbox.rst | 80 ++++++++++++++++++++++++-------------------------
 1 file changed, 40 insertions(+), 40 deletions(-)

diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 05ffaf6..fd60d16 100644
--- 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::
 
-- 
cgit v0.12