More and better comments (#121)

temporal/api/command/v1/message.proto

@@ -48,37 +48,46 @@ message ScheduleActivityTaskCommandAttributes {
     temporal.api.taskqueue.v1.TaskQueue task_queue = 4;
     temporal.api.common.v1.Header header = 5;
     temporal.api.common.v1.Payloads input = 6;
+    // Indicates how long the caller is willing to wait for activity completion. Limits how long
+    // retries will be attempted. Either this or `start_to_close_timeout` must be specified. When
+    // not specified, defaults to the workflow execution timeout.
+    //
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "to" is used to indicate interval. --)
-    // Indicates how long the caller is willing to wait for an activity completion.
-    // Limits for how long retries are happening. Either this or start_to_close_timeout_seconds must be specified.
-    // When not specified defaults to the workflow execution timeout.
     google.protobuf.Duration schedule_to_close_timeout = 7 [(gogoproto.stdduration) = true];
+    // Limits the time an activity task can stay in a task queue before a worker picks it up. This
+    // timeout is always non retryable, as all a retry would achieve is to put it back into the same
+    // queue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if that is not
+    // specified.
+    //
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "to" is used to indicate interval. --)
-    // Limits time an activity task can stay in a task queue before a worker picks it up.
-    // This timeout is always non retryable as all a retry would achieve is to put it back into the same queue.
-    // Defaults to schedule_to_close_timeout_seconds or workflow execution timeout if not specified.
     google.protobuf.Duration schedule_to_start_timeout = 8 [(gogoproto.stdduration) = true];
+    // Maximum time an activity is allowed to execute after being picked up by a worker. This
+    // timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified.
+    //
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "to" is used to indicate interval. --)
-    // Maximum time an activity is allowed to execute after a pick up by a worker.
-    // This timeout is always retryable. Either this or schedule_to_close_timeout_seconds must be specified.
     google.protobuf.Duration start_to_close_timeout = 9 [(gogoproto.stdduration) = true];
-    // Maximum time between successful worker heartbeats.
+    // Maximum permitted time between successful worker heartbeats.
     google.protobuf.Duration heartbeat_timeout = 10 [(gogoproto.stdduration) = true];
-    // Activities are provided by a default retry policy controlled through the service dynamic configuration.
-    // Retries are happening up to schedule_to_close_timeout.
-    // To disable retries set retry_policy.maximum_attempts to 1.
+    // Activities are provided by a default retry policy which is controlled through the service's
+    // dynamic configuration. Retries will be attempted until `schedule_to_close_timeout` has
+    // elapsed. To disable retries set retry_policy.maximum_attempts to 1.
     temporal.api.common.v1.RetryPolicy retry_policy = 11;
 }
 
 message RequestCancelActivityTaskCommandAttributes {
+    // The `ACTIVITY_TASK_SCHEDULED` event id for the activity being cancelled.
     int64 scheduled_event_id = 1;
 }
 
 message StartTimerCommandAttributes {
+    // An id for the timer, currently live timers must have different ids. Typically autogenerated
+    // by the SDK.
     string timer_id = 1;
+    // How long until the timer fires, producing a `TIMER_FIRED` event.
+    //
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "to" is used to indicate interval. --)
     google.protobuf.Duration start_to_fire_timeout = 2 [(gogoproto.stdduration) = true];
@@ -93,6 +102,7 @@ message FailWorkflowExecutionCommandAttributes {
 }
 
 message CancelTimerCommandAttributes {
+    // The same timer id from the start timer command
     string timer_id = 1;
 }
 
@@ -104,16 +114,26 @@ message RequestCancelExternalWorkflowExecutionCommandAttributes {
     string namespace = 1;
     string workflow_id = 2;
     string run_id = 3;
+    // Deprecated.
     string control = 4;
+    // Set this to true if the workflow being cancelled is a child of the workflow originating this
+    // command. The request will be rejected if it is set to true and the target workflow is *not*
+    // a child of the requesting workflow.
     bool child_workflow_only = 5;
 }
 
 message SignalExternalWorkflowExecutionCommandAttributes {
     string namespace = 1;
     temporal.api.common.v1.WorkflowExecution execution = 2;
+    // The workflow author-defined name of the signal to send to the workflow.
     string signal_name = 3;
+    // Serialized value(s) to provide with the signal.
     temporal.api.common.v1.Payloads input = 4;
+    // Deprecated
     string control = 5;
+    // Set this to true if the workflow being cancelled is a child of the workflow originating this
+    // command. The request will be rejected if it is set to true and the target workflow is *not*
+    // a child of the requesting workflow.
     bool child_workflow_only = 6;
     // Headers that are passed by the workflow that is sending a signal to the external 
     // workflow that is receiving this signal.
@@ -135,20 +155,27 @@ message ContinueAsNewWorkflowExecutionCommandAttributes {
     temporal.api.common.v1.WorkflowType workflow_type = 1;
     temporal.api.taskqueue.v1.TaskQueue task_queue = 2;
     temporal.api.common.v1.Payloads input = 3;
-    // workflow_execution_timeout is omitted as it shouldn'be overridden from within a workflow.
+
     // Timeout of a single workflow run.
     google.protobuf.Duration workflow_run_timeout = 4 [(gogoproto.stdduration) = true];
     // Timeout of a single workflow task.
     google.protobuf.Duration workflow_task_timeout = 5 [(gogoproto.stdduration) = true];
+    // How long the workflow start will be delayed - not really a "backoff" in the traditional sense.
     google.protobuf.Duration backoff_start_interval = 6 [(gogoproto.stdduration) = true];
     temporal.api.common.v1.RetryPolicy retry_policy = 7;
+    // Should be removed
     temporal.api.enums.v1.ContinueAsNewInitiator initiator = 8;
+    // Should be removed
     temporal.api.failure.v1.Failure failure = 9;
+    // Should be removed
     temporal.api.common.v1.Payloads last_completion_result = 10;
+    // Should be removed. Not necessarily unused but unclear and not exposed by SDKs.
     string cron_schedule = 11;
     temporal.api.common.v1.Header header = 12;
     temporal.api.common.v1.Memo memo = 13;
     temporal.api.common.v1.SearchAttributes search_attributes = 14;
+
+    // `workflow_execution_timeout` is omitted as it shouldn't be overridden from within a workflow.
 }
 
 message StartChildWorkflowExecutionCommandAttributes {
@@ -169,6 +196,7 @@ message StartChildWorkflowExecutionCommandAttributes {
     // Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
     temporal.api.enums.v1.WorkflowIdReusePolicy workflow_id_reuse_policy = 11;
     temporal.api.common.v1.RetryPolicy retry_policy = 12;
+    // Establish a cron schedule for the child workflow.
     string cron_schedule = 13;
     temporal.api.common.v1.Header header = 14;
     temporal.api.common.v1.Memo memo = 15;

temporal/api/common/v1/message.proto

@@ -42,40 +42,57 @@ message DataBlob {
     bytes data = 2;
 }
 
+// See `Payload`
 message Payloads {
     repeated Payload payloads = 1;
 }
 
+// Represents some binary (byte array) data (ex: activity input parameters or workflow result) with
+// metadata which describes this binary data (format, encoding, encryption, etc). Serialization
+// of the data may be user-defined.
 message Payload {
     map<string,bytes> metadata = 1;
     bytes data = 2;
 }
 
+// A user-defined set of *indexed* fields that are used/exposed when listing/searching workflows.
+// The payload is not serialized in a user-defined way.
 message SearchAttributes {
     map<string, Payload> indexed_fields = 1;
 }
 
+// A user-defined set of *unindexed* fields that are exposed when listing/searching workflows
 message Memo {
     map<string, Payload> fields = 1;
 }
 
+// Contains metadata that can be attached to a variety of requests, like starting a workflow, and
+// can be propagated between, for example, workflows and activities.
 message Header {
     map<string, Payload> fields = 1;
 }
 
+// Identifies a specific workflow within a namespace. Practically speaking, because run_id is a
+// uuid, a workflow execution is globally unique. Note that many commands allow specifying an empty
+// run id as a way of saying "target the latest run of the workflow".
 message WorkflowExecution {
     string workflow_id = 1;
     string run_id = 2;
 }
 
+// Represents the identifier used by a workflow author to define the workflow. Typically, the
+// name of a function. This is sometimes referred to as the workflow's "name"
 message WorkflowType {
     string name = 1;
 }
 
+// Represents the identifier used by a activity author to define the activity. Typically, the
+// name of a function. This is sometimes referred to as the activity's "name"
 message ActivityType {
     string name = 1;
 }
 
+// How retries ought to be handled, usable by both workflows and activities
 message RetryPolicy {
     // Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries.
     google.protobuf.Duration initial_interval = 1 [(gogoproto.stdduration) = true];
@@ -89,6 +106,7 @@ message RetryPolicy {
     // Maximum number of attempts. When exceeded the retries stop even if not expired yet.
     // 1 disables retries. 0 means unlimited (up to the timeouts)
     int32 maximum_attempts = 4;
-    // Non-Retryable errors types. Will stop retrying if error type matches this list.
+    // Non-Retryable errors types. Will stop retrying if the error type matches this list. Note that
+    // this is not a substring match, the error *type* (not message) must match exactly.
     repeated string non_retryable_error_types = 5;
 }

temporal/api/enums/v1/failed_cause.proto

@@ -31,8 +31,13 @@ option java_outer_classname = "FailedCauseProto";
 option ruby_package = "Temporal::Api::Enums::V1";
 option csharp_namespace = "Temporal.Api.Enums.V1";
 
+// Workflow tasks can fail for various reasons. Note that some of these reasons can only originate
+// from the server, and some of them can only originate from the SDK/worker.
 enum WorkflowTaskFailedCause {
     WORKFLOW_TASK_FAILED_CAUSE_UNSPECIFIED = 0;
+    // Between starting and completing the workflow task (with a workflow completion command), some
+    // new command (like a signal) was processed into workflow history. The outstanding task will be
+    // failed with this reason, and a worker must pick up a new task.
     WORKFLOW_TASK_FAILED_CAUSE_UNHANDLED_COMMAND = 1;
     WORKFLOW_TASK_FAILED_CAUSE_BAD_SCHEDULE_ACTIVITY_ATTRIBUTES = 2;
     WORKFLOW_TASK_FAILED_CAUSE_BAD_REQUEST_CANCEL_ACTIVITY_ATTRIBUTES = 3;
@@ -45,6 +50,8 @@ enum WorkflowTaskFailedCause {
     WORKFLOW_TASK_FAILED_CAUSE_BAD_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_ATTRIBUTES = 10;
     WORKFLOW_TASK_FAILED_CAUSE_BAD_CONTINUE_AS_NEW_ATTRIBUTES = 11;
     WORKFLOW_TASK_FAILED_CAUSE_START_TIMER_DUPLICATE_ID = 12;
+    // The worker wishes to fail the task and have the next one be generated on a normal, not sticky
+    // queue. Generally workers should prefer to use the explicit `ResetStickyTaskQueue` RPC call.
     WORKFLOW_TASK_FAILED_CAUSE_RESET_STICKY_TASK_QUEUE = 13;
     WORKFLOW_TASK_FAILED_CAUSE_WORKFLOW_WORKER_UNHANDLED_FAILURE = 14;
     WORKFLOW_TASK_FAILED_CAUSE_BAD_SIGNAL_WORKFLOW_EXECUTION_ATTRIBUTES = 15;
@@ -56,6 +63,8 @@ enum WorkflowTaskFailedCause {
     WORKFLOW_TASK_FAILED_CAUSE_BAD_BINARY = 21;
     WORKFLOW_TASK_FAILED_CAUSE_SCHEDULE_ACTIVITY_DUPLICATE_ID = 22;
     WORKFLOW_TASK_FAILED_CAUSE_BAD_SEARCH_ATTRIBUTES = 23;
+    // The worker encountered a mismatch while replaying history between what was expected, and
+    // what the workflow code actually did.
     WORKFLOW_TASK_FAILED_CAUSE_NON_DETERMINISTIC_ERROR = 24;
 }
 

temporal/api/enums/v1/reset.proto

@@ -31,6 +31,7 @@ option java_outer_classname = "ResetProto";
 option ruby_package = "Temporal::Api::Enums::V1";
 option csharp_namespace = "Temporal.Api.Enums.V1";
 
+// TODO: What is this?
 enum ResetReapplyType {
     RESET_REAPPLY_TYPE_UNSPECIFIED = 0;
     RESET_REAPPLY_TYPE_SIGNAL = 1;

temporal/api/enums/v1/task_queue.proto

@@ -33,7 +33,20 @@ option csharp_namespace = "Temporal.Api.Enums.V1";
 
 enum TaskQueueKind {
     TASK_QUEUE_KIND_UNSPECIFIED = 0;
+    // Tasks from a normal workflow task queue always include complete workflow history
+    //
+    // The task queue specified by the user is always a normal task queue. There can be as many
+    // workers as desired for a single normal task queue. All those workers may pick up tasks from
+    // that queue.
     TASK_QUEUE_KIND_NORMAL = 1;
+    // A sticky queue only includes new history since the last workflow task, and they are
+    // per-worker.
+    //
+    // Sticky queues are created dynamically by each worker during their start up. They only exist
+    // for the lifetime of the worker process. Tasks in a sticky task queue are only available to
+    // the worker that created the sticky queue.
+    //
+    // Sticky queues are only for workflow tasks. There are no sticky task queues for activities.
     TASK_QUEUE_KIND_STICKY = 2;
 }
 

temporal/api/enums/v1/workflow.proto

@@ -31,31 +31,38 @@ option java_outer_classname = "WorkflowProto";
 option ruby_package = "Temporal::Api::Enums::V1";
 option csharp_namespace = "Temporal.Api.Enums.V1";
 
+// Defines how new runs of a workflow with a particular ID may or may not be allowed. Note that
+// it is *never* valid to have two actively running instances of the same workflow id.
 enum WorkflowIdReusePolicy {
     WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0;
-    // Allow start a workflow execution using the same workflow Id, when workflow not running.
+    // Allow starting a workflow execution using the same workflow id.
     WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1;
-    // Allow start a workflow execution using the same workflow Id, when workflow not running, and the last execution close state is in
-    // [terminated, cancelled, timed out, failed].
+    // Allow starting a workflow execution using the same workflow id, only when the last
+    // execution's final state is one of [terminated, cancelled, timed out, failed].
     WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2;
-    // Do not allow start a workflow execution using the same workflow Id at all.
+    // Do not permit re-use of the workflow id for this workflow. Future start workflow requests
+    // could potentially change the policy, allowing re-use of the workflow id.
     WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE = 3;
 }
 
+// Defines how child workflows will react to their parent completing
 enum ParentClosePolicy {
     PARENT_CLOSE_POLICY_UNSPECIFIED = 0;
-    // Terminate means terminating the child workflow.
+    // The child workflow will also terminate
     PARENT_CLOSE_POLICY_TERMINATE = 1;
-    // Abandon means not doing anything on the child workflow.
+    // The child workflow will do nothing
     PARENT_CLOSE_POLICY_ABANDON = 2;
-    // Cancel means requesting cancellation on the child workflow.
+    // Cancellation will be requested of the child workflow
     PARENT_CLOSE_POLICY_REQUEST_CANCEL = 3;
 }
 
 enum ContinueAsNewInitiator {
     CONTINUE_AS_NEW_INITIATOR_UNSPECIFIED = 0;
+    // The workflow itself requested to continue as new
     CONTINUE_AS_NEW_INITIATOR_WORKFLOW = 1;
+    // The workflow continued as new because it is retrying
     CONTINUE_AS_NEW_INITIATOR_RETRY = 2;
+    // The workflow continued as new because cron has triggered a new execution
     CONTINUE_AS_NEW_INITIATOR_CRON_SCHEDULE = 3;
 }