gh-91860: documentation for typing.dataclass_transform (#92768)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Doc/library/typing.rst

@@ -2429,6 +2429,75 @@ Functions and decorators
 
    .. versionadded:: 3.11
 
+.. decorator:: dataclass_transform
+
+   :data:`~typing.dataclass_transform` may be used to
+   decorate a class, metaclass, or a function that is itself a decorator.
+   The presence of ``@dataclass_transform()`` tells a static type checker that the
+   decorated object performs runtime "magic" that
+   transforms a class, giving it :func:`dataclasses.dataclass`-like behaviors.
+
+   Example usage with a decorator function::
+
+      T = TypeVar("T")
+
+      @dataclass_transform()
+      def create_model(cls: type[T]) -> type[T]:
+          ...
+          return cls
+
+      @create_model
+      class CustomerModel:
+          id: int
+          name: str
+
+   On a base class::
+
+      @dataclass_transform()
+      class ModelBase: ...
+
+      class CustomerModel(ModelBase):
+          id: int
+          name: str
+
+   On a metaclass::
+
+      @dataclass_transform()
+      class ModelMeta(type): ...
+
+      class ModelBase(metaclass=ModelMeta): ...
+
+      class CustomerModel(ModelBase):
+          id: int
+          name: str
+
+   The ``CustomerModel`` classes defined above will
+   be treated by type checkers similarly to classes created with
+   :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
+   For example, type checkers will assume these classes have
+   ``__init__`` methods that accept ``id`` and ``name``.
+
+   The arguments to this decorator can be used to customize this behavior:
+
+   * ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
+     ``True`` or ``False`` if it is omitted by the caller.
+   * ``order_default`` indicates whether the ``order`` parameter is
+     assumed to be True or False if it is omitted by the caller.
+   * ``kw_only_default`` indicates whether the ``kw_only`` parameter is
+     assumed to be True or False if it is omitted by the caller.
+   * ``field_specifiers`` specifies a static list of supported classes
+     or functions that describe fields, similar to ``dataclasses.field()``.
+   * Arbitrary other keyword arguments are accepted in order to allow for
+     possible future extensions.
+
+   At runtime, this decorator records its arguments in the
+   ``__dataclass_transform__`` attribute on the decorated object.
+   It has no other runtime effect.
+
+   See :pep:`681` for more details.
+
+   .. versionadded:: 3.11
+
 .. decorator:: overload
 
    The ``@overload`` decorator allows describing functions and methods