Improve comments

Author: dandavison

hello_nexus/basic/caller/workflows.py

@@ -6,22 +6,30 @@
 NEXUS_ENDPOINT = "my-nexus-endpoint"
 
 
+# This is a workflow that calls a nexus operation.
 @workflow.defn
 class CallerWorkflow:
+    # An __init__ method is always optional on a Workflow class. Here we use it to set the
+    # NexusClient, but that could alternatively be done in the run method.
     def __init__(self):
         self.nexus_client = NexusClient(
             MyNexusService,
             endpoint=NEXUS_ENDPOINT,
         )
 
+    # The Wokflow run method invokes two Nexus operations.
     @workflow.run
     async def run(self, name: str) -> tuple[MyOutput, MyOutput]:
-        sync_result: MyOutput = await self.nexus_client.execute_operation(
-            MyNexusService.my_sync_operation,
-            MyInput(name),
-        )
+        # Start the Nexus operation and wait for the result in one go, using execute_operation.
         wf_result: MyOutput = await self.nexus_client.execute_operation(
             MyNexusService.my_workflow_run_operation,
             MyInput(name),
         )
+        # We could use execute_operation for this one also, but here we demonstrate
+        # obtaining the operation handle and then using it to get the result.
+        sync_operation_handle = await self.nexus_client.start_operation(
+            MyNexusService.my_sync_operation,
+            MyInput(name),
+        )
+        sync_result = await sync_operation_handle
         return sync_result, wf_result

hello_nexus/basic/handler/service_handler.py

@@ -1,7 +1,13 @@
 """
-This file demonstrates how to define operation handlers by implementing the `start`
-method only, using the "shorthand" decorators sync_operation_handler and
-workflow_run_operation_handler.
+This file demonstrates how to define operation handlers by using the "shorthand"
+decorators sync_operation_handler and workflow_run_operation_handler. In this style you
+implement the `start` method only. workflow_run_operation_handler implements `cancel` for
+you automatically, but apart from that, the other operation methods (`fetch_info`,
+`fetch_result`, and `cancel` for sync_operation_handler) are all automatically created
+with "raise NotImplementedError" implementations.
+
+See hello_nexus/basic/handler/service_handler_with_operation_handler_classes.py for the
+alternative "fully manual" style where you implement an OperationHandler class directly.
 """
 
 from __future__ import annotations

hello_nexus/basic/handler/service_handler_with_operation_handler_classes.py

@@ -1,12 +1,14 @@
 """
-Notes:
+This file demonstrates how to define operation handlers by implementing an OperationHandler
+class directly.
+
+See hello_nexus/basic/handler/service_handler.py for the alternative "shorthand" style
+where you implement the `start` method only.
 
 Sync operations:
 ---------------
 Implementations are free to make arbitrary network calls, or perform CPU-bound
-computations such as this one. Total execution duration must not exceed 10s. To
-perform Temporal client calls such as signaling/querying/listing workflows, use
-self.client.
+computations such as this one. Total execution duration must not exceed 10s.
 
 
 Workflow operations:
@@ -62,11 +64,16 @@ def my_workflow_run_operation(
         return MyWorkflowRunOperation()
 
 
+# This is a Nexus operation that responds synchronously to all requests.
 class MySyncOperation(OperationHandler[MyInput, MyOutput]):
     # You can add an __init__ method taking any required arguments, since you are in
     # control of instantiating the OperationHandler inside the operation handler method
     # above decorated with @operation_handler.
 
+    # Unlike the workflow run operation below, the `start` method for a sync operation
+    # returns the final operation result. Sync operations are free to make arbitrary
+    # network calls, or perform CPU-bound computations. Total execution duration must not
+    # exceed 10s. async def start(
     async def start(
         self, ctx: StartOperationContext, input: MyInput
     ) -> StartOperationResultSync[MyOutput]:
@@ -103,7 +110,21 @@ async def cancel(
         )
 
 
+# This is a Nexus operation that is backed by a Temporal workflow. That means that it
+# responds asynchronously to all requests: it starts a workflow and responds with a token
+# that the handler can associate with the worklow is started.
 class MyWorkflowRunOperation(OperationHandler[MyInput, MyOutput]):
+    # You can add an __init__ method taking any required arguments, since you are in
+    # control of instantiating the OperationHandler inside the operation handler method
+    # above decorated with @operation_handler.
+
+    # The start method starts a workflow, and returns a WorkflowRunOperationResult that it
+    # creates from the workflow handle. This return value contains the Nexus operation
+    # token that the handler can use to obtain a handle and interact with the workflow on
+    # future requests (for example if a cancel request is subsequently sent by the
+    # caller). The Temporal server takes care of delivering the workflow result to the
+    # calling workflow. The task queue defaults to the task queue being used by the Nexus
+    # worker.
     async def start(
         self, ctx: StartOperationContext, input: MyInput
     ) -> WorkflowRunOperationResult:

hello_nexus/basic/handler/worker.py

@@ -32,8 +32,8 @@ async def main(
     )
 
     # Create an instance of the service handler. Your service handler class __init__ can
-    # take anything that your operation handlers need when handling requests. In this
-    # example we provide a database client object to the service hander.
+    # be written to accept any arguments that your operation handlers need when handling
+    # requests. In this example we provide a database client object to the service hander.
     connected_db_client = MyDBClient.connect()
 
     my_nexus_service_handler = (
@@ -45,8 +45,9 @@ async def main(
     )
 
     # Start the worker, passing the Nexus service handler instance, in addition to the
-    # workflow class that is used by the workflow-backed nexus operation. This Worker will
-    # poll for both workflow tasks and Nexus tasks.
+    # workflow classes that are started by your nexus operations, and any activities
+    # needed. This Worker will poll for both workflow tasks and Nexus tasks (this example
+    # doesn't use any activities).
     async with Worker(
         client,
         task_queue=TASK_QUEUE,