Improve/fix comments explaining message passing introduction sample (#148)

Author: dandavison

Diff for: message_passing/introduction/workflows.py

@@ -24,18 +24,20 @@ class ApproveInput:
 @workflow.defn
 class GreetingWorkflow:
     """
-    A workflow that that returns a greeting in one of two languages.
-
-    It supports a Query to obtain the current language, an Update to change the
-    current language and receive the previous language in response, and a Signal
-    to approve the Workflow so that it is allowed to return its result.
+    A workflow that that returns a greeting in one of multiple supported
+    languages.
+
+    It exposes a query to obtain the current language, a signal to approve the
+    workflow so that it is allowed to return its result, and two updates for
+    changing the current language and receiving the previous language in
+    response.
+
+    One of the update handlers is not an `async def`, so it can only mutate and
+    return local workflow state; the other update handler is `async def` and
+    executes an activity which calls a remote service, giving access to language
+    translations which are not available in local workflow state.
     """
 
-    # 👉 This Workflow does not use any async handlers and so cannot use any
-    # Activities. It only supports two languages, whose greetings are hardcoded
-    # in the Workflow definition. See GreetingWorkflowWithAsyncHandler below for
-    # a Workflow that uses an async Update handler to call an Activity.
-
     def __init__(self) -> None:
         self.approved_for_release = False
         self.approver_name: Optional[str] = None
@@ -97,12 +99,14 @@ async def set_language_using_activity(self, language: Language) -> Language:
                     language,
                     start_to_close_timeout=timedelta(seconds=10),
                 )
+                # 👉 The requested language might not be supported by the remote
+                # service. If so, we raise ApplicationError, which will fail the
+                # Update. The WorkflowExecutionUpdateAccepted event will still
+                # be added to history. (Update validators can be used to reject
+                # updates before any event is written to history, but they
+                # cannot be async, and so we cannot use an update validator for
+                # this purpose.)
                 if greeting is None:
-                    # 👉 An update validator cannot be async, so cannot be used
-                    # to check that the remote call_greeting_service supports
-                    # the requested language. Raising ApplicationError will fail
-                    # the Update, but the WorkflowExecutionUpdateAccepted event
-                    # will still be added to history.
                     raise ApplicationError(
                         f"Greeting service does not support {language.name}"
                     )