Update dataclasses.py docstrings

pydantic/dataclasses.py

@@ -59,7 +59,6 @@ def dataclass(
         kw_only: bool = ...,
         slots: bool = ...,
     ) -> type[PydanticDataclass]:
-        """Overload for `dataclass`."""
         ...
 
 else:
@@ -77,7 +76,6 @@ def dataclass(
         config: ConfigDict | type[object] | None = None,
         validate_on_init: bool | None = None,
     ) -> Callable[[type[_T]], type[PydanticDataclass]]:  # type: ignore
-        """Overload for `dataclass`."""
         ...
 
     @dataclass_transform(field_specifiers=(dataclasses.field, Field))
@@ -94,7 +92,6 @@ def dataclass(
         config: ConfigDict | type[object] | None = None,
         validate_on_init: bool | None = None,
     ) -> type[PydanticDataclass]:
-        """Overload for `dataclass`."""
         ...
 
 
@@ -117,26 +114,13 @@ def dataclass(
     A decorator used to create a Pydantic-enhanced dataclass, similar to the standard Python `dataclasses`,
     but with added validation.
 
-    Args:
-        _cls (type[_T] | None): The target dataclass.
-        init (Literal[False]): If set to `False`, the `dataclass` will not generate an `__init__`,
-            and you will need to provide one. Defaults to `False`.
-        repr (bool): Determines if a `__repr__` should be generated for the class. Defaults to `True`.
-        eq (bool): Determines if a `__eq__` should be generated for the class. Defaults to `True`.
-        order (bool): Determines if comparison magic methods should be generated, such as `__lt__`, but
-            not `__eq__`. Defaults to `False`.
-        unsafe_hash (bool): Determines if an unsafe hashing function should be included in the class.
-        frozen (bool): Determines if the generated class should be a 'frozen' dataclass, which does not allow its
-            attributes to be modified from its constructor. Defaults to `False`.
-        config (ConfigDict | type[object] | None): A configuration for the `dataclass` generation. Defaults to `None`.
-        validate_on_init (bool | None): Determines whether the `dataclass` will be validated upon creation.
-        kw_only (bool): Determines if keyword-only parameters should be used on the `__init__` method. Defaults
-            to `False`.
+    This function should be used similarly to `dataclasses.dataclass`.
 
     Args:
         _cls: The target dataclass.
-        init: If set to `False`, the dataclass will not generate an `__init__`,
-            and you will need to provide one. Defaults to `False`.
+        init: Included for signature compatibility with `dataclasses.dataclass`, and is passed through to
+            `dataclasses.dataclass` when appropriate. If specified, must be set to `False`, as pydantic inserts its
+            own  `__init__` function. Defaults to `False`.
         repr: Determines if a `__repr__` should be generated for the class. Defaults to `True`.
         eq: Determines if a `__eq__` should be generated for the class. Defaults to `True`.
         order: Determines if comparison magic methods should be generated, such as` __lt__`, but
@@ -145,35 +129,33 @@ def dataclass(
         frozen: Determines if the generated class should be a 'frozen' dataclass, which does not allow its
             attributes to be modified from its constructor. Defaults to `False`.
         config: A configuration for the dataclass generation. Defaults to `None`.
-        validate_on_init: Determines whether the dataclass will be validated upon creation.
-        kw_only: Determines if keyword-only parameters should be used on the `__init__` method. Defaults
-            to `False`.
+        validate_on_init: A deprecated parameter included for backwards compatibility; in V2, all pydantic dataclasses
+            are validated on init.
+        kw_only: Determines if `__init__` method parameters must be specified by keyword only. Defaults to `False`.
 
     Returns:
-        A callable that takes a `type` as its argument, and returns a `type` of `PydanticDataclass`. This can
-        also return a `tyoe` of `PydanticDataclass` directly.
+        A decorator that accepts a class as its argument and returns a Pydantic dataclass.
 
     Raises:
-        AssertionError: Raised if `init` is not `False`.
+        AssertionError: Raised if `init` is not `False` or `validate_on_init` is `False`.
     """
     assert init is False, 'pydantic.dataclasses.dataclass only supports init=False'
+    assert validate_on_init is not False, 'validate_on_init=False is no longer supported'
 
     if sys.version_info >= (3, 10):
         kwargs = dict(kw_only=kw_only, slots=slots)
     else:
         kwargs = {}
 
     def create_dataclass(cls: type[Any]) -> type[PydanticDataclass]:
-        """Create a Pydantic dataclass from a regular dataclass.
+        """
+        Create a Pydantic dataclass from a regular dataclass.
 
         Args:
             cls: The class to create the Pydantic dataclass from.
 
         Returns:
             A Pydantic dataclass.
-
-        Raises:
-            TypeError: If a non-class value is provided.
         """
 
         original_cls = cls
@@ -259,7 +241,10 @@ def rebuild_dataclass(
     _types_namespace: dict[str, Any] | None = None,
 ) -> bool | None:
     """
-    Try to rebuild or reconstruct the dataclass core schema.
+    Try to rebuild the pydantic-core schema for the dataclass.
+
+    This may be necessary when one of the annotations is a ForwardRef which could not be resolved during
+    the initial attempt to build the schema, and automatic rebuilding fails.
 
     This is analogous to `BaseModel.model_rebuild`.
 
@@ -271,8 +256,8 @@ def rebuild_dataclass(
         _types_namespace: The types namespace, defaults to `None`.
 
     Returns:
-        Returns `None` if model schema is complete and no rebuilding is required.
-            If rebuilding _is_ required, returns `True` if rebuilding was successful, otherwise `False`.
+        Returns `None` if the schema is already "complete" and rebuilding was not required.
+        If rebuilding _was_ required, returns `True` if rebuilding was successful, otherwise `False`.
     """
     if not force and cls.__pydantic_complete__:
         return None

pydantic/main.py

@@ -553,7 +553,10 @@ def model_rebuild(
         _types_namespace: dict[str, Any] | None = None,
     ) -> bool | None:
         """
-        Tries to rebuild or reconstruct the model core schema.
+        Try to rebuild the pydantic-core schema for the model.
+
+        This may be necessary when one of the annotations is a ForwardRef which could not be resolved during
+        the initial attempt to build the schema, and automatic rebuilding fails.
 
         Args:
             force: Whether to force the rebuilding of the model schema, defaults to `False`.
@@ -562,8 +565,8 @@ def model_rebuild(
             _types_namespace: The types namespace, defaults to `None`.
 
         Returns:
-            Returns `None` if model schema is complete and no rebuilding is required.
-                If rebuilding _is_ required, returns `True` if rebuilding was successful, otherwise `False`.
+            Returns `None` if the schema is already "complete" and rebuilding was not required.
+            If rebuilding _was_ required, returns `True` if rebuilding was successful, otherwise `False`.
         """
         if not force and cls.__pydantic_complete__:
             return None