style(doctest): improve doctest readability with narrative descriptions

Author: tony

src/libtmux/_internal/frozen_dataclass_sealable.py

@@ -91,44 +91,49 @@ def mutable_during_init(
     >>> 
     >>> @frozen_dataclass_sealable
     ... class Example:
-    ...     # Regular immutable field (required fields must come first)
     ...     name: str
-    ...     # Using field with metadata directly (recommended approach)
     ...     items: list[str] = field(
     ...         default_factory=list,
     ...         metadata={"mutable_during_init": True}
     ...     )
-    >>> 
-    >>> # Create an instance with deferred sealing
+
+    Create an instance with deferred sealing:
+
     >>> example = Example(name="test-example")
-    >>> 
-    >>> # Cannot modify immutable fields even before sealing
+
+    Cannot modify immutable fields even before sealing:
+
     >>> try:
     ...     example.name = "new-name"
     ... except AttributeError as e:
     ...     print(f"Error: {type(e).__name__}")
     Error: AttributeError
-    >>> 
-    >>> # Can modify mutable field before sealing
+
+    Can modify mutable field before sealing:
+
     >>> example.items.append("item1")
     >>> example.items
     ['item1']
-    >>> 
-    >>> # Now seal the object
+
+    Now seal the object:
+
     >>> example.seal()
-    >>> 
-    >>> # Verify the object is sealed
+
+    Verify the object is sealed:
+
     >>> hasattr(example, "_sealed") and example._sealed
     True
-    >>> 
-    >>> # Cannot modify mutable field after sealing
+
+    Cannot modify mutable field after sealing:
+
     >>> try:
     ...     example.items = ["new-item"]
     ... except AttributeError as e:
     ...     print(f"Error: {type(e).__name__}")
     Error: AttributeError
-    >>> 
-    >>> # But can still modify the contents of mutable containers
+
+    But can still modify the contents of mutable containers:
+
     >>> example.items.append("item2")
     >>> example.items
     ['item1', 'item2']
@@ -239,7 +244,7 @@ def frozen_dataclass_sealable(
     Examples
     --------
     Basic usage:
-    
+
     >>> from dataclasses import field
     >>> from typing import Optional
     >>> from libtmux._internal.frozen_dataclass_sealable import (
@@ -253,85 +258,99 @@ def frozen_dataclass_sealable(
     ...         default_factory=dict,
     ...         metadata={"mutable_during_init": True}
     ...     )
-    >>> 
-    >>> # Create an instance
+
+    Create an instance:
+
     >>> config = Config(name="test-config")
     >>> config.name
     'test-config'
-    >>> 
-    >>> # Cannot modify frozen field
+
+    Cannot modify frozen field:
+
     >>> try:
     ...     config.name = "modified"
     ... except AttributeError as e:
     ...     print(f"Error: {type(e).__name__}")
     Error: AttributeError
-    >>> 
-    >>> # Can modify mutable field before sealing
+
+    Can modify mutable field before sealing:
+
     >>> config.values["key1"] = 100
     >>> config.values
     {'key1': 100}
-    >>> 
-    >>> # Can also directly assign to mutable field before sealing
+
+    Can also directly assign to mutable field before sealing:
+
     >>> new_values = {"key2": 200}
     >>> config.values = new_values
     >>> config.values
     {'key2': 200}
-    >>> 
-    >>> # Seal the object
+
+    Seal the object:
+
     >>> config.seal()
-    >>> 
-    >>> # Verify the object is sealed
+
+    Verify the object is sealed:
+
     >>> hasattr(config, "_sealed") and config._sealed
     True
-    >>> 
-    >>> # Cannot modify mutable field after sealing
+
+    Cannot modify mutable field after sealing:
+
     >>> try:
     ...     config.values = {"key3": 300}
     ... except AttributeError as e:
     ...     print(f"Error: {type(e).__name__}")
     Error: AttributeError
-    >>> 
-    >>> # But can still modify the contents of mutable containers after sealing
+
+    But can still modify the contents of mutable containers after sealing:
+
     >>> config.values["key3"] = 300
     >>> config.values
     {'key2': 200, 'key3': 300}
 
     With deferred sealing:
-    
+
     >>> @frozen_dataclass_sealable
     ... class Node:
     ...     value: int
     ...     next_node: Optional['Node'] = field(
     ...         default=None,
     ...         metadata={"mutable_during_init": True}
     ...     )
-    >>> 
-    >>> # Create a linked list
+
+    Create a linked list:
+
     >>> node1 = Node(value=1)  # Not sealed automatically
     >>> node2 = Node(value=2)  # Not sealed automatically
-    >>> 
-    >>> # Can modify mutable field before sealing
+
+    Can modify mutable field before sealing:
+
     >>> node1.next_node = node2
-    >>> 
-    >>> # Verify structure
+
+    Verify structure:
+
     >>> node1.value
     1
     >>> node2.value
     2
     >>> node1.next_node is node2
     True
-    >>> 
-    >>> # Seal nodes
+
+    Seal nodes:
+
     >>> node1.seal()
     >>> node2.seal()
-    >>> 
-    >>> # Verify sealed status
+
+    Verify sealed status:
+
     >>> hasattr(node1, "_sealed") and node1._sealed
     True
     >>> hasattr(node2, "_sealed") and node2._sealed
     True
-    >>> 
-    >>> # Cannot modify mutable field after sealing
+
+    Cannot modify mutable field after sealing:
+
     >>> try:
     ...     node1.next_node = None
     ... except AttributeError as e: