Updated timeout property documentation (#401)

Author: vkoby

internal/activity.go

@@ -81,25 +81,33 @@ type (
 		// optional: The default task queue with the same name as the workflow task queue.
 		TaskQueue string
 
-		// ScheduleToCloseTimeout - The end to end timeout for the activity needed.
+		// ScheduleToCloseTimeout - Total time that a workflow is willing to wait for Activity to complete.
+		// ScheduleToCloseTimeout limits the total time of an Activity's execution including retries
+		// 		(use StartToCloseTimeout to limit the time of a single attempt).
 		// The zero value of this uses default value.
-		// Optional: The default value is the sum of ScheduleToStartTimeout and StartToCloseTimeout
+		// Either this option or StartToClose is required: Defaults to unlimited.
 		ScheduleToCloseTimeout time.Duration
 
-		// ScheduleToStartTimeout - The maximum time an activity task can stay in a task queue before being picked up by a worker.
-		// Note that ScheduleToStartTimeout is not retryable as retry would return it back into the same task queue.
-		// In almost all situations that don't involve routing activities to specific hosts
-		// it is better to rely on the default value.
-		// Optional: defaults to unlimited
+		// ScheduleToStartTimeout - Time that the Activity Task can stay in the Task Queue before it is picked up by
+		// a Worker. Do not specify this timeout unless using host specific Task Queues for Activity Tasks are being
+		// used for routing. In almost all situations that don't involve routing activities to specific hosts it is
+		// better to rely on the default value.
+		// ScheduleToStartTimeout is always non-retryable. Retrying after this timeout doesn't make sense as it would
+		// just put the Activity Task back into the same Task Queue.
+		// If ScheduleToClose is not provided then this timeout is required.
+		// Optional: Defaults to unlimited.
 		ScheduleToStartTimeout time.Duration
 
-		// StartToCloseTimeout - The timeout from the start of execution to end of it.
-		// Mandatory: No default.
+		// StartToCloseTimeout - Maximum time of a single Activity execution attempt.
+		// Note that the Temporal Server doesn't detect Worker process failures directly. It relies on this timeout
+		// to detect that an Activity that didn't complete on time. So this timeout should be as short as the longest
+		// possible execution of the Activity body. Potentially long running Activities must specify HeartbeatTimeout
+		// and call Activity.RecordHeartbeat(ctx, "my-heartbeat") periodically for timely failure detection.
+		// If ScheduleToClose is not provided then this timeout is required: Defaults to the ScheduleToCloseTimeout value.
 		StartToCloseTimeout time.Duration
 
-		// HeartbeatTimeout - The periodic timeout while the activity is in execution. This is
-		// the max interval the server needs to hear at-least one ping from the activity.
-		// Optional: Default zero, means no heart beating is needed.
+		// HeartbeatTimeout - Heartbeat interval. Activity must call Activity.RecordHeartbeat(ctx, "my-heartbeat")
+		// before this interval passes after the last heartbeat or the Activity starts.
 		HeartbeatTimeout time.Duration
 
 		// WaitForCancellation - Whether to wait for canceled activity to be completed(

internal/workflow.go

@@ -215,8 +215,10 @@ type (
 		// Optional: defaults to WorkflowExecutionTimeout
 		WorkflowRunTimeout time.Duration
 
-		// WorkflowTaskTimeout - The workflow task timeout for the child workflow.
-		// Optional: default is 10s if this is not provided (or if 0 is provided).
+		// WorkflowTaskTimeout - Maximum execution time of a single Workflow Task. In the majority of cases there is
+		// no need to change this timeout. Note that this timeout is not related to the overall Workflow duration in
+		// any way. It defines for how long the Workflow can get blocked in the case of a Workflow Worker crash.
+		// Default is 10 seconds. Maximum value allowed by the Temporal Server is 1 minute.
 		WorkflowTaskTimeout time.Duration
 
 		// WaitForCancellation - Whether to wait for canceled child workflow to be ended (child workflow can be ended