gh-114803: Mention that `@dataclass` should not be applied on enums (GH-114891)

Co-authored-by: Kirill Podoprigora <kirill.bast9@mail.ru>
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index 1e9ac9b6761b64738eb61df91d28a1586d85b7b7..30be15230fc088eed430510795309f8012ac00ae 100644 (file)
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -497,13 +497,30 @@ the :meth:`~Enum.__repr__` omits the inherited class' name.  For example::
     >>> Creature.DOG
     <Creature.DOG: size='medium', legs=4>
 
-Use the :func:`!dataclass` argument ``repr=False``
+Use the :func:`~dataclasses.dataclass` argument ``repr=False``
 to use the standard :func:`repr`.
 
 .. versionchanged:: 3.12
    Only the dataclass fields are shown in the value area, not the dataclass'
    name.
 
+.. note::
+
+   Adding :func:`~dataclasses.dataclass` decorator to :class:`Enum`
+   and its subclasses is not supported. It will not raise any errors,
+   but it will produce very strange results at runtime, such as members
+   being equal to each other::
+
+      >>> @dataclass               # don't do this: it does not make any sense
+      ... class Color(Enum):
+      ...    RED = 1
+      ...    BLUE = 2
+      ...
+      >>> Color.RED is Color.BLUE
+      False
+      >>> Color.RED == Color.BLUE  # problem is here: they should not be equal
+      True
+
 
 Pickling
 --------