PR-suggested comments

temporal/api/command/v1/message.proto

@@ -237,14 +237,14 @@ message ProtocolMessageCommandAttributes {
 
 message Command {
     temporal.api.enums.v1.CommandType command_type = 1;
-    // Metadata on the command. This is carried over to the event if there is an associated event.
-    // Most commands won't have this information, and how this information is used is dependent upon
-    // the interface that reads it.
+    // Metadata on the command. This is sometimes carried over to the history event if one is
+    // created as a result of the command. Most commands won't have this information, and how this
+    // information is used is dependent upon the interface that reads it.
     //
     // Current well-known uses:
     //  * start_child_workflow_execution_command_attributes - populates
     //    temporal.api.workflow.v1.WorkflowExecutionInfo.user_metadata where the summary and details
-    //    are used by user interfaces to show fixed as-of-start workflow summary and description.
+    //    are used by user interfaces to show fixed as-of-start workflow summary and details.
     //  * start_timer_command_attributes - populates temporal.api.history.v1.HistoryEvent for timer
     //    started where the summary is used to identify the timer.
     temporal.api.sdk.v1.UserMetadata user_metadata = 301;

temporal/api/sdk/v1/user_metadata.proto

@@ -37,12 +37,13 @@ import "temporal/api/common/v1/message.proto";
 // Information a user can set, often for use by user interfaces.
 message UserMetadata {
   // Short-form text that provides a summary. This payload should be a "json/plain"-encoded payload
-  // that is a single JSON string. Formatting may not apply to this text when used in "title"
-  // situations. The payload data section is limited to 400 bytes by default.
+  // that is a single JSON string for use in user interfaces. User interface formatting may not
+  // apply to this text when used in "title" situations. The payload data section is limited to 400
+  // bytes by default.
   temporal.api.common.v1.Payload summary = 1;
 
   // Long-form text that provides details. This payload should be a "json/plain"-encoded payload
-  // that is a single JSON string. Formatting may apply to this text in common use. The payload data
-  // section is limited to 20000 bytes by default.
+  // that is a single JSON string for use in user interfaces. User interface formatting may apply to
+  // this text in common use. The payload data section is limited to 20000 bytes by default.
   temporal.api.common.v1.Payload details = 2;
 }

temporal/api/workflow/v1/message.proto

@@ -155,7 +155,7 @@ message NewWorkflowExecutionInfo {
     temporal.api.common.v1.SearchAttributes search_attributes = 12;
     temporal.api.common.v1.Header header = 13;
     // Metadata on the workflow if it is started. This is carried over to the WorkflowExecutionInfo
-    // for use by user interfaces to display the fixed as-of-start summary and description of the
+    // for use by user interfaces to display the fixed as-of-start summary and details of the
     // workflow.
     temporal.api.sdk.v1.UserMetadata user_metadata = 14;
 }

temporal/api/workflowservice/v1/request_response.proto

@@ -194,7 +194,7 @@ message StartWorkflowExecutionRequest {
     // Callback addresses must be whitelisted in the server's dynamic configuration.
     repeated temporal.api.common.v1.Callback completion_callbacks = 21;
     // Metadata on the workflow if it is started. This is carried over to the WorkflowExecutionInfo
-    // for use by user interfaces to display the fixed as-of-start summary and description of the
+    // for use by user interfaces to display the fixed as-of-start summary and details of the
     // workflow.
     temporal.api.sdk.v1.UserMetadata user_metadata = 23;
 }
@@ -682,7 +682,7 @@ message SignalWithStartWorkflowExecutionRequest {
     // Indicates that a new workflow task should not be generated when this signal is received.
     bool skip_generate_workflow_task = 21;
     // Metadata on the workflow if it is started. This is carried over to the WorkflowExecutionInfo
-    // for use by user interfaces to display the fixed as-of-start summary and description of the
+    // for use by user interfaces to display the fixed as-of-start summary and details of the
     // workflow.
     temporal.api.sdk.v1.UserMetadata user_metadata = 23;
 }