docs(frozen_dataclass): convert docstrings to reStructuredText with NumPy style

Author: tony

src/libtmux/_internal/frozen_dataclass_sealable.py

@@ -7,7 +7,7 @@
 
 1. Field-level mutability control:
 
-   Use the `mutable_during_init` decorator to mark fields that should be mutable
+   Use the ``mutable_during_init`` decorator to mark fields that should be mutable
    during the initialization phase but become immutable after sealing.
 
 2. Two-phase initialization:
@@ -50,11 +50,14 @@ def mutable_field(
 ) -> dataclasses.Field[t.Any]:
     """Create a field that is mutable during initialization but immutable after sealing.
 
-    Args:
-        factory: A callable that returns the default value for the field
+    Parameters
+    ----------
+    factory : callable, optional
+        A callable that returns the default value for the field, by default list
 
     Returns
     -------
+    dataclasses.Field
         A dataclass Field with metadata indicating it's mutable during initialization
     """
     return dataclasses.field(
@@ -69,15 +72,20 @@ def mutable_during_init(
 
     This decorator applies to a method that returns the field's default value.
 
-    Args:
-        field_method: A method that returns the default value for the field
+    Parameters
+    ----------
+    field_method : callable, optional
+        A method that returns the default value for the field, by default None
 
     Returns
     -------
+    dataclasses.Field
         A dataclass Field with metadata indicating it's mutable during initialization
 
-    Example:
-        ```python
+    Examples
+    --------
+    .. code-block:: python
+
         @frozen_dataclass_sealable
         class Example:
             # Using field with metadata directly (recommended)
@@ -93,7 +101,6 @@ def values(self) -> dict[str, int]:
 
             # Regular immutable field
             name: str
-        ```
     """
     if field_method is None:
         # Used with parentheses: @mutable_during_init()
@@ -129,37 +136,41 @@ def seal(self) -> None:
 def is_sealable(cls_or_obj: t.Any) -> bool:
     """Check if a class or object is sealable.
 
-    Args:
-        cls_or_obj: The class or object to check
+    Parameters
+    ----------
+    cls_or_obj : Any
+        The class or object to check
 
     Returns
     -------
+    bool
         True if the class or object is sealable, False otherwise
     
-    Examples:
-        >>> from dataclasses import dataclass
-        >>> from libtmux._internal.frozen_dataclass_sealable import (
-        ...     frozen_dataclass_sealable, is_sealable
-        ... )
-        
-        >>> # Regular class is not sealable
-        >>> @dataclass
-        ... class Regular:
-        ...     value: int
-        
-        >>> is_sealable(Regular)
-        False
-        >>> regular = Regular(value=42)
-        >>> is_sealable(regular)
-        False
-        
-        >>> # Non-class objects are not sealable
-        >>> is_sealable("string")
-        False
-        >>> is_sealable(42)
-        False
-        >>> is_sealable(None)
-        False
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> from libtmux._internal.frozen_dataclass_sealable import (
+    ...     frozen_dataclass_sealable, is_sealable
+    ... )
+    
+    >>> # Regular class is not sealable
+    >>> @dataclass
+    ... class Regular:
+    ...     value: int
+    
+    >>> is_sealable(Regular)
+    False
+    >>> regular = Regular(value=42)
+    >>> is_sealable(regular)
+    False
+    
+    >>> # Non-class objects are not sealable
+    >>> is_sealable("string")
+    False
+    >>> is_sealable(42)
+    False
+    >>> is_sealable(None)
+    False
     """
     # If it's a class, check if it has a seal method
     if isinstance(cls_or_obj, type):
@@ -176,23 +187,30 @@ def frozen_dataclass_sealable(
     """Create a dataclass that is immutable, with field-level mutability control.
 
     Enhances the standard dataclass with:
+    
     - Core immutability (like dataclasses.frozen=True)
     - Field-level mutability control during initialization
     - Explicit sealing mechanism
     - Support for inheritance from mutable base classes
 
-    Args:
-        cls: The class to decorate
-        **kwargs: Additional arguments passed to dataclasses.dataclass
+    Parameters
+    ----------
+    cls : type, optional
+        The class to decorate, by default None
+    **kwargs : dict
+        Additional arguments passed to dataclasses.dataclass
 
     Returns
     -------
-        A decorated class with immutability features
+    type or callable
+        A decorated class with immutability features, or a decorator function if cls is None
 
     Examples
     --------
-        Basic usage:
-        ```python
+    Basic usage:
+    
+    .. code-block:: python
+    
         @frozen_dataclass_sealable
         class Config:
             name: str
@@ -201,10 +219,11 @@ class Config:
                 default_factory=dict,
                 metadata={"mutable_during_init": True}
             )
-        ```
 
-        With deferred sealing:
-        ```python
+    With deferred sealing:
+    
+    .. code-block:: python
+    
         @frozen_dataclass_sealable
         class Node:
             value: int
@@ -222,7 +241,6 @@ class Node:
         # Seal nodes
         node1.seal()
         node2.seal()
-        ```
     """
     # Support both @frozen_dataclass_sealable and @frozen_dataclass_sealable() usage
     if cls is None:
@@ -428,8 +446,10 @@ def custom_init(self: t.Any, *args: t.Any, **kwargs: t.Any) -> None:
     def seal(self: t.Any, deep: bool = False) -> None:
         """Seal the object to prevent further modifications.
 
-        Args:
-            deep: If True, recursively seal any nested sealable objects
+        Parameters
+        ----------
+        deep : bool, optional
+            If True, recursively seal any nested sealable objects, by default False
         """
         # First seal this object
         object.__setattr__(self, "_sealed", True)
@@ -453,7 +473,13 @@ def seal(self: t.Any, deep: bool = False) -> None:
     # Add a class method to check if the class is sealable
     @classmethod
     def is_sealable(cls) -> bool:
-        """Check if this class is sealable."""
+        """Check if this class is sealable.
+
+        Returns
+        -------
+        bool
+            Always returns True for classes decorated with frozen_dataclass_sealable
+        """
         return True
 
     cls.is_sealable = is_sealable  # type: ignore