Docstring tweaks

Author: dandavison

temporalio/client.py

@@ -488,7 +488,7 @@ async def start_workflow(
             static_details: General fixed details for this workflow execution that may appear in
                 UI/CLI. This can be in Temporal markdown format and can span multiple lines. This is
                 a fixed value on the workflow that cannot be updated. For details that can be
-                updated, use `Workflow.CurrentDetails` within the workflow.
+                updated, use :py:meth:`temporalio.workflow.get_current_details` within the workflow.
             start_delay: Amount of time to wait before starting the workflow.
                 This does not work with ``cron_schedule``.
             start_signal: If present, this signal is sent as signal-with-start
@@ -1283,7 +1283,7 @@ async def create_schedule(
             static_details: General fixed details for this workflow execution that may appear in
                 UI/CLI. This can be in Temporal markdown format and can span multiple lines. This is
                 a fixed value on the workflow that cannot be updated. For details that can be
-                updated, use `Workflow.CurrentDetails` within the workflow.
+                updated, use :py:meth:`temporalio.workflow.get_current_details` within the workflow.
             rpc_metadata: Headers used on the RPC call. Keys here override
                 client-level RPC metadata keys.
             rpc_timeout: Optional RPC deadline to set for the RPC call.
@@ -1517,9 +1517,8 @@ def id(self) -> str:
 
     @property
     def run_id(self) -> Optional[str]:
-        """Run ID used for :py:meth:`signal`, :py:meth:`query`, and
-        :py:meth:`update` calls if present to ensure the signal/query/update
-        happen on this exact run.
+        """If present, run ID used to ensure that requested operations apply
+        to this exact run.
 
         This is only created via :py:meth:`Client.get_workflow_handle`.
         :py:meth:`Client.start_workflow` will not set this value.
@@ -1546,8 +1545,7 @@ def result_run_id(self) -> Optional[str]:
 
     @property
     def first_execution_run_id(self) -> Optional[str]:
-        """Run ID used for :py:meth:`cancel` and :py:meth:`terminate` calls if
-        present to ensure the cancel and terminate happen for a workflow ID
+        """Run ID used to ensure requested operations apply to a workflow ID
         started with this run ID.
 
         This can be set when using :py:meth:`Client.get_workflow_handle`. When
@@ -2304,13 +2302,13 @@ async def start_update(
 
         Args:
             update: Update function or name on the workflow. arg: Single argument to the
-            update.
+                update.
             wait_for_stage: Required stage to wait until returning: either ACCEPTED or
                 COMPLETED. ADMITTED is not currently supported. See
                 https://docs.temporal.io/workflows#update for more details.
-            args: Multiple arguments to the update. Cannot be set if arg is. id: ID of the
-            update. If not set, the default is a new UUID. result_type: For string
-            updates, this can set the specific result
+            args: Multiple arguments to the update. Cannot be set if arg is.
+            id: ID of the update. If not set, the default is a new UUID.
+            result_type: For string updates, this can set the specific result
                 type hint to deserialize into.
             rpc_metadata: Headers used on the RPC call. Keys here override
                 client-level RPC metadata keys.
@@ -2427,7 +2425,6 @@ def get_update_handle_for(
             id: Update ID to get a handle to.
             workflow_run_id: Run ID to tie the handle to. If this is not set,
                 the :py:attr:`run_id` will be used.
-            result_type: The result type to deserialize into if known.
 
         Returns:
             The update handle.
@@ -2444,8 +2441,7 @@ class WithStartWorkflowOperation(Generic[SelfType, ReturnType]):
     workflow if necessary.
 
     .. warning::
-    This API is experimental
-
+        This API is experimental
     """
 
     # Overload for no-param workflow, with_start
@@ -4866,7 +4862,7 @@ def __init__(
         """Create a workflow update handle.
 
         Users should not create this directly, but rather use
-        :py:meth:`Client.start_workflow_update`.
+        :py:meth:`WorkflowHandle.start_update` or :py:meth:`WorkflowHandle.get_update_handle`.
         """
         self._client = client
         self._id = id
@@ -5586,15 +5582,16 @@ async def terminate_workflow(self, input: TerminateWorkflowInput) -> None:
     async def start_workflow_update(
         self, input: StartWorkflowUpdateInput
     ) -> WorkflowUpdateHandle[Any]:
-        """Called for every :py:meth:`WorkflowHandle.update` and :py:meth:`WorkflowHandle.start_update` call."""
+        """Called for every :py:meth:`WorkflowHandle.start_update` and :py:meth:`WorkflowHandle.execute_update` call."""
         return await self.next.start_workflow_update(input)
 
     async def start_update_with_start_workflow(
         self, input: StartWorkflowUpdateWithStartInput
     ) -> WorkflowUpdateHandle[Any]:
-        """Called for every :py:meth:`Client.start_update_with_start` and :py:meth:`Client.execute_update_with_start` call.
+        """Called for every :py:meth:`Client.start_update_with_start_workflow` and :py:meth:`Client.execute_update_with_start_workflow` call.
+
         .. warning::
-           This API is experimental
+            This API is experimental
         """
         return await self.next.start_update_with_start_workflow(input)
 

temporalio/worker/_workflow.py

@@ -442,7 +442,7 @@ class _DeadlockError(Exception):
     """Exception class for deadlocks. Contains functionality to swap the default traceback for another."""
 
     def __init__(self, message: str, replacement_tb: Optional[TracebackType] = None):
-        """Create a new DeadlockError, with message `msg` and optionally a traceback `tb` to be swapped in later.
+        """Create a new DeadlockError, with message `message` and optionally a traceback `replacement_tb` to be swapped in later.
 
         Args:
             message: Message to be presented through exception.

temporalio/workflow.py

@@ -1190,7 +1190,7 @@ async def wait_condition(
         fn: Non-async callback that accepts no parameters and returns a boolean.
         timeout: Optional number of seconds to wait until throwing
             :py:class:`asyncio.TimeoutError`.
-        timeout_summary: Optional simple string identifying the timer (created if `timeout` is
+        timeout_summary: Optional simple string identifying the timer (created if ``timeout`` is
             present) that may be visible in UI/CLI. While it can be normal text, it is best to treat
             as a timer ID.
     """
@@ -1313,7 +1313,7 @@ class LoggerAdapter(logging.LoggerAdapter):
 
     Values added to ``extra`` are merged with the ``extra`` dictionary from a
     logging call, with values from the logging call taking precedence. I.e. the
-    behavior is that of `merge_extra=True` in Python >= 3.13.
+    behavior is that of ``merge_extra=True`` in Python >= 3.13.
     """
 
     def __init__(
@@ -3954,7 +3954,7 @@ async def start_child_workflow(
         static_details: General fixed details for this child workflow execution that may appear in
             UI/CLI. This can be in Temporal markdown format and can span multiple lines. This is
             a fixed value on the workflow that cannot be updated. For details that can be
-            updated, use `Workflow.CurrentDetails` within the workflow.
+            updated, use :py:meth:`Workflow.get_current_details` within the workflow.
 
     Returns:
         A workflow handle to the started/existing workflow.