gh-95913: Copyedit, xref and organize enum section (GH-98295)

* Whatsnew: Convert literals in enum section to actual x-references

* Whatsnew: Rewrite enum section for clear and consistant phrasing

* Whatsnew: Combine directly related enum items instead of seperating them

* gh-98250: Describe __str__/__format__ changes more clearly/accurately

* Tweak enum section language per feedback from Ethan
(cherry picked from commit 73e5180faf37e2d362e13f4ef12955a8b8535d7b)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

1 files changed, 64 insertions, 38 deletions

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index d6ad79e..97e8600 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -632,48 +632,74 @@ datetime
   formats (barring only those that support fractional hours and minutes).
   (Contributed by Paul Ganssle in :gh:`80010`.)
 
-enum
-----
-
-* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias).
-
-* ``StrEnum`` added -- enum members are and must be strings.
-
-* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the
-  ``__str__`` nor the ``__format__``.
-
-* ``FlagBoundary`` added -- controls behavior when invalid values are given to
-  a flag.
-
-* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints.
 
-* ``verify`` added -- function to ensure given ``EnumCheck`` constraints.
+.. _whatsnew311-enum:
 
-* ``member`` added -- decorator to ensure given object is converted to an enum
-  member.
-
-* ``nonmember`` added -- decorator to ensure given object is not converted to
-  an enum member.
-
-* ``property`` added -- use instead of ``types.DynamicClassAttribute``.
-
-* ``global_enum`` added -- enum decorator to adjust ``__repr__`` and ``__str__``
-  to show members in the global context -- see ``re.RegexFlag`` for an example.
-
-* ``Flag`` enhancements: members support length,  iteration, and containment
-  checks.
-
-* ``Enum``/``Flag`` fixes: members are now defined before ``__init_subclass__``
-  is called; ``dir()`` now includes methods, etc., from mixed-in data types.
+enum
+----
 
-* ``Flag`` fixes: only primary values (power of two) are considered canonical
-  while composite values (3, 6, 10, etc.) are considered aliases;  inverted
-  flags are coerced to their positive equivalent.
+* Renamed :class:`!EnumMeta` to :class:`~enum.EnumType`
+  (:class:`!EnumMeta` kept as an alias).
+
+* Added :class:`~enum.StrEnum`,
+  with members that can be used as (and must be) strings.
+
+* Added :class:`~enum.ReprEnum`,
+  which only modifies the :meth:`~object.__repr__` of members
+  while returning their literal values (rather than names)
+  for :meth:`~object.__str__` and :meth:`~object.__format__`
+  (used by :func:`str`, :func:`format` and :term:`f-string`\s).
+
+* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum`
+  to now inherit from :class:`ReprEnum`,
+  so their :func:`str` output now matches :func:`format`
+  (both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``,
+  whereas before ``str(AnIntEnum.ONE)`` returned ``'AnIntEnum.ONE'``.
+
+* Changed :meth:`Enum.__format__() <enum.Enum.__format__>`
+  (the default for :func:`format`, :meth:`str.format` and :term:`f-string`\s)
+  of enums with mixed-in types (e.g. :class:`int`, :class:`str`)
+  to also include the class name in the output, not just the member's key.
+  This matches the existing behavior of :meth:`enum.Enum.__str__`,
+  returning e.g. ``'AnEnum.MEMBER'`` for an enum ``AnEnum(str, Enum)``
+  instead of just ``'MEMBER'``.
+
+* Added a new *boundary* class parameter to :class:`~enum.Flag` enums
+  and the :class:`~enum.FlagBoundary` enum with its options,
+  to control how to handle out-of-range flag values.
+
+* Added the :func:`~enum.verify` enum decorator
+  and the :class:`~enum.EnumCheck` enum with its options,
+  to check enum classes against several specific constraints.
+
+* Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators,
+  to ensure the decorated object is/is not converted to an enum member.
+
+* Added the :func:`~enum.property` decorator,
+  which works like :func:`property` except for enums.
+  Use this instead of :func:`types.DynamicClassAttribute`.
+
+* Added the :func:`~enum.global_enum` enum decorator,
+  which adjusts :meth:`~object.__repr__` and :meth:`~object.__str__`
+  to show values as members of their module rather than the enum class.
+  For example, ``'re.ASCII'`` for the :data:`~re.ASCII` member
+  of :class:`re.RegexFlag` rather than ``'RegexFlag.ASCII'``.
+
+* Enhanced :class:`~enum.Flag` to support
+  :func:`len`, iteration and :keyword:`in`/:keyword:`not in` on its members.
+  For example, the following now works:
+  ``len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)``
+
+* Changed :class:`~enum.Enum` and :class:`~enum.Flag`
+  so that members are now defined
+  before :meth:`~object.__init_subclass__` is called;
+  :func:`dir` now includes methods, etc., from mixed-in data types.
+
+* Changed :class:`~enum.Flag`
+  to only consider primary values (power of two) canonical
+  while composite values (``3``, ``6``, ``10``, etc.) are considered aliases;
+  inverted flags are coerced to their positive equivalent.
 
-* ``IntEnum`` / ``IntFlag`` / ``StrEnum`` fixes: these now inherit from
-  ``ReprEnum`` so the ``str()`` output now matches ``format()`` output,
-  which is the data types' (so both ``str(AnIntEnum.ONE)`` and
-  ``format(AnIntEnum.ONE)`` is equal to ``'1'``).
 
 fractions
 ---------