gh-98298, gh-74730: [Enum] update docs (GH-103163)

fix FlagBoundary statements
add warning about reloading modules and enum identity
(cherry picked from commit 5ffc1e5)

Co-authored-by: Ethan Furman <ethan@stoneleaf.us>

Doc/howto/enum.rst

@@ -371,6 +371,11 @@ below)::
     >>> Color.BLUE == 2
     False
 
+.. warning::
+
+   It is possible to reload modules -- if a reloaded module contains
+   enums, they will be recreated, and the new members may not
+   compare identical/equal to the original members.
 
 Allowed members and attributes of enumerations
 ----------------------------------------------

Doc/library/enum.rst

@@ -141,9 +141,8 @@ Module Contents
    :func:`global_enum`
 
       Modify the :class:`str() <str>` and :func:`repr` of an enum
-      to show its members as belonging to the module instead of its class.
-      Should only be used if the enum members will be exported to the
-      module global namespace.
+      to show its members as belonging to the module instead of its class,
+      and export the enum members to the global namespace.
 
    :func:`show_flag_values`
 
@@ -170,6 +169,27 @@ Data Types
    final *enum*, as well as creating the enum members, properly handling
    duplicates, providing iteration over the enum class, etc.
 
+   .. method:: EnumType.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
+
+      This method is called in two different ways:
+
+      * to look up an existing member:
+
+         :cls:   The enum class being called.
+         :value: The value to lookup.
+
+      * to use the ``cls`` enum to create a new enum (only if the existing enum
+        does not have any members):
+
+         :cls:   The enum class being called.
+         :value: The name of the new Enum to create.
+         :names: The names/values of the members for the new Enum.
+         :module:    The name of the module the new Enum is created in.
+         :qualname:  The actual location in the module where this Enum can be found.
+         :type:  A mix-in type for the new Enum.
+         :start: The first integer value for the Enum (used by :class:`auto`).
+         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
+
    .. method:: EnumType.__contains__(cls, member)
 
       Returns ``True`` if member belongs to the ``cls``::
@@ -262,26 +282,6 @@ Data Types
       names will also be removed from the completed enumeration.  See
       :ref:`TimePeriod <enum-time-period>` for an example.
 
-   .. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
-
-      This method is called in two different ways:
-
-      * to look up an existing member:
-
-         :cls:   The enum class being called.
-         :value: The value to lookup.
-
-      * to use the ``cls`` enum to create a new enum:
-
-         :cls:   The enum class being called.
-         :value: The name of the new Enum to create.
-         :names: The names/values of the members for the new Enum.
-         :module:    The name of the module the new Enum is created in.
-         :qualname:  The actual location in the module where this Enum can be found.
-         :type:  A mix-in type for the new Enum.
-         :start: The first integer value for the Enum (used by :class:`auto`).
-         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
-
    .. method:: Enum.__dir__(self)
 
       Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
@@ -722,7 +722,6 @@ Data Types
    .. attribute:: EJECT
 
       Out-of-range values lose their *Flag* membership and revert to :class:`int`.
-      This is the default for :class:`IntFlag`::
 
          >>> from enum import Flag, EJECT, auto
          >>> class EjectFlag(Flag, boundary=EJECT):
@@ -734,8 +733,8 @@ Data Types
 
    .. attribute:: KEEP
 
-      Out-of-range values are kept, and the *Flag* membership is kept. This is
-      used for some stdlib flags::
+      Out-of-range values are kept, and the *Flag* membership is kept.
+      This is the default for :class:`IntFlag`::
 
          >>> from enum import Flag, KEEP, auto
          >>> class KeepFlag(Flag, boundary=KEEP):

Lib/enum.py

@@ -1302,10 +1302,10 @@ def _reduce_ex_by_global_name(self, proto):
 class FlagBoundary(StrEnum):
     """
     control how out of range values are handled
-    "strict" -> error is raised  [default for Flag]
-    "conform" -> extra bits are discarded
-    "eject" -> lose flag status [default for IntFlag]
-    "keep" -> keep flag status and all bits
+    "strict" -> error is raised
+    "conform" -> extra bits are discarded   [default for Flag]
+    "eject" -> lose flag status
+    "keep" -> keep flag status and all bits [default for IntFlag]
     """
     STRICT = auto()
     CONFORM = auto()