Evolve documentation of update polling parameters

Author: dandavison

temporal/api/update/v1/message.proto

@@ -35,12 +35,9 @@ import "temporal/api/common/v1/message.proto";
 import "temporal/api/enums/v1/update.proto";
 import "temporal/api/failure/v1/message.proto";
 
-// Specifies to the gRPC server how long the client wants the an update-related
-// RPC call to wait before returning control to the caller.
+// How long the client wants an update-related RPC call to wait before returning control to the caller.
 message WaitPolicy {
-
-    // Indicates the update lifecycle stage that the gRPC call should wait for
-    // before returning.
+    // The update stage that this request should attempt to wait for.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage lifecycle_stage = 1;
 }
 

temporal/api/workflowservice/v1/request_response.proto

@@ -1389,8 +1389,7 @@ message UpdateWorkflowExecutionRequest {
     // part of the same execution chain as this id.
     string first_execution_run_id = 3;
 
-    // Describes when this request should return - basically whether the
-    // update is synchronous, asynchronous, or somewhere in between.
+    // How long to wait before returning control to the caller.
     temporal.api.update.v1.WaitPolicy wait_policy = 4;
 
     // The request information that will be delivered all the way down to the
@@ -1409,14 +1408,12 @@ message UpdateWorkflowExecutionResponse {
 
     // The most advanced lifecycle stage that the Update is known to have
     // reached, where lifecycle stages are ordered
-    // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.
-    // UNSPECIFIED will be returned if and only if the server's maximum wait
-    // time was reached before the Update reached the stage specified in the
-    // request WaitPolicy, and before the context deadline expired; clients may
-    // may then retry the call as needed.
+    // If the server's maximum wait time was reached before the stage requested by the client, then
+    // the returned stage may be less than the requested stage. Clients may then retry the call as
+    // needed.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 3;
 }
 
@@ -1535,14 +1532,12 @@ message PollWorkflowExecutionUpdateResponse {
     temporal.api.update.v1.Outcome outcome = 1;
     // The most advanced lifecycle stage that the Update is known to have
     // reached, where lifecycle stages are ordered
-    // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.
-    // UNSPECIFIED will be returned if and only if the server's maximum wait
-    // time was reached before the Update reached the stage specified in the
-    // request WaitPolicy, and before the context deadline expired; clients may
-    // may then retry the call as needed.
+    // If the server's maximum wait time was reached before the stage requested by the client, then
+    // the returned stage may be less than the requested stage. Clients may then retry the call as
+    // needed.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 2;
     // Sufficient information to address this update.
     temporal.api.update.v1.UpdateRef update_ref = 3;