Clarifying comments

Author: bergundy

openapi/openapiv2.json

@@ -8968,7 +8968,7 @@
         },
         "runId": {
           "type": "string",
-          "title": "Run Id of the workflow which scheduled this activity"
+          "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity."
         },
         "activityId": {
           "type": "string",
@@ -9027,7 +9027,7 @@
         },
         "runId": {
           "type": "string",
-          "title": "Run Id of the workflow which scheduled this activity"
+          "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity."
         },
         "activityId": {
           "type": "string",
@@ -9086,7 +9086,7 @@
         },
         "runId": {
           "type": "string",
-          "title": "Run Id of the workflow which scheduled this activity"
+          "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity."
         },
         "activityId": {
           "type": "string",
@@ -14329,7 +14329,7 @@
         },
         "activityId": {
           "type": "string",
-          "description": "The autogenerated or user specified identifier of this activity. Can be used to complete the\nactivity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage\nhas resolved, but unique IDs for every activity invocation is a good idea."
+          "description": "The autogenerated or user specified identifier of this activity. Can be used to complete the\nactivity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage\nhas resolved, but unique IDs for every activity invocation is a good idea.\nNote that only a workflow activity ID may be autogenerated."
         },
         "header": {
           "$ref": "#/definitions/v1Header",

openapi/openapiv3.yaml

@@ -10821,6 +10821,7 @@ components:
             The autogenerated or user specified identifier of this activity. Can be used to complete the
              activity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage
              has resolved, but unique IDs for every activity invocation is a good idea.
+             Note that only a workflow activity ID may be autogenerated.
         header:
           allOf:
             - $ref: '#/components/schemas/Header'
@@ -11788,7 +11789,9 @@ components:
           description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity
         runId:
           type: string
-          description: Run Id of the workflow which scheduled this activity
+          description: |-
+            For a workflow activity - the run ID of the workflow which scheduled this activity.
+             For a standalone activity - the run ID of the activity.
         activityId:
           type: string
           description: Id of the activity to confirm is cancelled
@@ -11855,7 +11858,9 @@ components:
           description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity
         runId:
           type: string
-          description: Run Id of the workflow which scheduled this activity
+          description: |-
+            For a workflow activity - the run ID of the workflow which scheduled this activity.
+             For a standalone activity - the run ID of the activity.
         activityId:
           type: string
           description: Id of the activity to complete
@@ -11918,7 +11923,9 @@ components:
           description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity
         runId:
           type: string
-          description: Run Id of the workflow which scheduled this activity
+          description: |-
+            For a workflow activity - the run ID of the workflow which scheduled this activity.
+             For a standalone activity - the run ID of the activity.
         activityId:
           type: string
           description: Id of the activity to fail

temporal/api/workflowservice/v1/request_response.proto

@@ -461,6 +461,7 @@ message PollActivityTaskQueueResponse {
     // The autogenerated or user specified identifier of this activity. Can be used to complete the
     // activity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage
     // has resolved, but unique IDs for every activity invocation is a good idea.
+    // Note that only a workflow activity ID may be autogenerated.
     string activity_id = 6;
     // Headers specified by the scheduling workflow. Commonly used to propagate contextual info
     // from the workflow to its activities. For example, tracing contexts.
@@ -580,7 +581,8 @@ message RespondActivityTaskCompletedByIdRequest {
     string namespace = 1;
     // Id of the workflow which scheduled this activity, leave empty to target a standalone activity
     string workflow_id = 2;
-    // Run Id of the workflow which scheduled this activity
+    // For a workflow activity - the run ID of the workflow which scheduled this activity.
+    // For a standalone activity - the run ID of the activity.
     string run_id = 3;
     // Id of the activity to complete
     string activity_id = 4;
@@ -627,7 +629,8 @@ message RespondActivityTaskFailedByIdRequest {
     string namespace = 1;
     // Id of the workflow which scheduled this activity, leave empty to target a standalone activity
     string workflow_id = 2;
-    // Run Id of the workflow which scheduled this activity
+    // For a workflow activity - the run ID of the workflow which scheduled this activity.
+    // For a standalone activity - the run ID of the activity.
     string run_id = 3;
     // Id of the activity to fail
     string activity_id = 4;
@@ -674,7 +677,8 @@ message RespondActivityTaskCanceledByIdRequest {
     string namespace = 1;
     // Id of the workflow which scheduled this activity, leave empty to target a standalone activity
     string workflow_id = 2;
-    // Run Id of the workflow which scheduled this activity
+    // For a workflow activity - the run ID of the workflow which scheduled this activity.
+    // For a standalone activity - the run ID of the activity.
     string run_id = 3;
     // Id of the activity to confirm is cancelled
     string activity_id = 4;