[3.12] Improve docs for typing.dataclass_transform (GH-105792) (#105809)

miss-islington · AlexWaygood · web-flow · commit 1573f1605ffd · 2023-06-15T07:12:26.000+01:00
Improve docs for `typing.dataclass_transform` (GH-105792) (cherry picked from commit 006a453) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -2526,16 +2526,19 @@ Functions and decorators
 
    .. versionadded:: 3.11
 
-.. decorator:: dataclass_transform
+.. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \
+                                   kw_only_default=False, frozen_default=False, \
+                                   field_specifiers=(), **kwargs)
 
    Decorator to mark an object as providing
-   :func:`~dataclasses.dataclass`-like behavior.
+   :func:`dataclass <dataclasses.dataclass>`-like behavior.
 
    ``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 in a similar way to :func:`dataclasses.dataclass`.
+   transforms a class in a similar way to
+   :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
 
    Example usage with a decorator function:
 
@@ -2589,42 +2592,71 @@ Functions and decorators
    customize the default behaviors of the decorated class, metaclass, or
    function:
 
-   * ``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.
-   * ``frozen_default`` indicates whether the ``frozen`` parameter is
-     assumed to be True or False if it is omitted by the caller.
-
-     .. versionadded:: 3.12
-   * ``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.
-
-   Type checkers recognize the following optional arguments on field
+   :param bool eq_default:
+       Indicates whether the ``eq`` parameter is assumed to be
+       ``True`` or ``False`` if it is omitted by the caller.
+       Defaults to ``True``.
+
+   :param bool order_default:
+       Indicates whether the ``order`` parameter is
+       assumed to be ``True`` or ``False`` if it is omitted by the caller.
+       Defaults to ``False``.
+
+   :param bool kw_only_default:
+       Indicates whether the ``kw_only`` parameter is
+       assumed to be ``True`` or ``False`` if it is omitted by the caller.
+       Defaults to ``False``.
+
+   :param bool frozen_default:
+       Indicates whether the ``frozen`` parameter is
+       assumed to be ``True`` or ``False`` if it is omitted by the caller.
+       Defaults to ``False``.
+
+       .. versionadded:: 3.12
+
+   :param field_specifiers:
+       Specifies a static list of supported classes
+       or functions that describe fields, similar to :func:`dataclasses.field`.
+       Defaults to ``()``.
+   :type field_specifiers: tuple[Callable[..., Any], ...]
+
+   :param Any \**kwargs:
+       Arbitrary other keyword arguments are accepted in order to allow for
+       possible future extensions.
+
+   Type checkers recognize the following optional parameters on field
    specifiers:
 
-   * ``init`` indicates whether the field should be included in the
-     synthesized ``__init__`` method. If unspecified, ``init`` defaults to
-     ``True``.
-   * ``default`` provides the default value for the field.
-   * ``default_factory`` provides a runtime callback that returns the
-     default value for the field. If neither ``default`` nor
-     ``default_factory`` are specified, the field is assumed to have no
-     default value and must be provided a value when the class is
-     instantiated.
-   * ``factory`` is an alias for ``default_factory``.
-   * ``kw_only`` indicates whether the field should be marked as
-     keyword-only. If ``True``, the field will be keyword-only. If
-     ``False``, it will not be keyword-only. If unspecified, the value of
-     the ``kw_only`` parameter on the object decorated with
-     ``dataclass_transform`` will be used, or if that is unspecified, the
-     value of ``kw_only_default`` on ``dataclass_transform`` will be used.
-   * ``alias`` provides an alternative name for the field. This alternative
-     name is used in the synthesized ``__init__`` method.
+   .. list-table:: **Recognised parameters for field specifiers**
+      :header-rows: 1
+      :widths: 20 80
+
+      * - Parameter name
+        - Description
+      * - ``init``
+        - Indicates whether the field should be included in the
+          synthesized ``__init__`` method. If unspecified, ``init`` defaults to
+          ``True``.
+      * - ``default``
+        - Provides the default value for the field.
+      * - ``default_factory``
+        - Provides a runtime callback that returns the
+          default value for the field. If neither ``default`` nor
+          ``default_factory`` are specified, the field is assumed to have no
+          default value and must be provided a value when the class is
+          instantiated.
+      * - ``factory``
+        - An alias for the ``default_factory`` parameter on field specifiers.
+      * - ``kw_only``
+        - Indicates whether the field should be marked as
+          keyword-only. If ``True``, the field will be keyword-only. If
+          ``False``, it will not be keyword-only. If unspecified, the value of
+          the ``kw_only`` parameter on the object decorated with
+          ``dataclass_transform`` will be used, or if that is unspecified, the
+          value of ``kw_only_default`` on ``dataclass_transform`` will be used.
+      * - ``alias``
+        - Provides an alternative name for the field. This alternative
+          name is used in the synthesized ``__init__`` method.
 
    At runtime, this decorator records its arguments in the
    ``__dataclass_transform__`` attribute on the decorated object.
