Improved docstrings

sphinx/builders/__init__.py

@@ -78,10 +78,11 @@ class Builder:
     #: Builder attributes that should be returned from parallel
     #: post transformation, to be merged to the main builder in
     #: :py:class:`~sphinx.builders.Builder.merge_builder_post_transform`.
-    #: merge_builder_post_transform(). Attributes in the list must
-    #: be pickleable. The approach improves performance when
+    #: Attributes in the list must be pickleable.
+    #: The approach improves performance when
     #: pickling and sending data over pipes because only a
-    #: small subset of the builder is commonly needed for merging.
+    #: subset of the builder attributes are commonly needed for merging
+    #: to the main process builder instance.
     post_transform_merge_attr: list[str] = []
 
     def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
@@ -135,17 +136,20 @@ def init(self) -> None:
         pass
 
     def merge_builder_post_transform(self, new_attrs: dict[str, Any]) -> None:
-        """Give builders the option to merge any parallel post-transform
-        information back to the main builder. This can be useful for
-        extensions that consume that information in the build-finish phase.
-        The function is called once for each finished
-        subprocess. Builders that implement this function must also
-        define the class attribute
-        :py:attr:`~sphinx.builders.Builder.post_transform_merge_attr`.
+        """Give builders the option to merge any post-transform information
+        coming from a parallel sub-process back to the main process builder.
+        This can be useful for extensions that consume that information
+        in the build-finish phase.
+        The function is called once for each finished subprocess.
+        Builders that implement this function must also define
+        the class attribute
+        :py:attr:`~sphinx.builders.Builder.post_transform_merge_attr` as it defines
+        which builder attributes shall be returned to the main process for merging.
+
         The default implementation does nothing.
 
         :param new_attrs: the attributes from the parallel subprocess to be
-                         udpated in the main builder
+                          udpated in the main builder
         """
         pass