docs: Document ParentClosePolicy, ChildWorkflowCancellationType, and WorkflowIdReusePolicy (temporalio#716)

lorensr · web-flow · commit fcdec2d52e7d · 2022-06-22T19:33:53.000-04:00
diff --git a/packages/internal-workflow-common/src/workflow-options.ts b/packages/internal-workflow-common/src/workflow-options.ts
@@ -6,24 +6,47 @@ import { checkExtends, Replace } from './type-helpers';
 
 // Avoid importing the proto implementation to reduce workflow bundle size
 // Copied from temporal.api.enums.v1.WorkflowIdReusePolicy
+/**
+ * Concept: [Workflow Id Reuse Policy](https://docs.temporal.io/concepts/what-is-a-workflow-id-reuse-policy/)
+ *
+ * Whether a Workflow can be started with a Workflow Id of a Closed Workflow.
+ *
+ * *Note: A Workflow can never be started with a Workflow Id of a Running Workflow.*
+ */
 export enum WorkflowIdReusePolicy {
+  /**
+   * No need to use this.
+   *
+   * (If a `WorkflowIdReusePolicy` is set to this, or is not set at all, the default value will be used.)
+   */
   WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0,
+
+  /**
+   * The Workflow can be started if the previous Workflow is in a Closed state.
+   * @default
+   */
   WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1,
+
+  /**
+   * The Workflow can be started if the previous Workflow is in a Closed state that is not Completed.
+   */
   WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2,
+
+  /**
+   * The Workflow cannot be started.
+   */
   WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE = 3,
 }
 
 checkExtends<temporal.api.enums.v1.WorkflowIdReusePolicy, WorkflowIdReusePolicy>();
 
 export interface BaseWorkflowOptions {
   /**
-   * Specifies server behavior if a completed workflow with the same id exists. Note that under no
-   * conditions Temporal allows two workflows with the same namespace and workflow id run
-   * simultaneously.
-   *   ALLOW_DUPLICATE_FAILED_ONLY is a default value. It means that workflow can start if
-   *   previous run failed or was canceled or terminated.
-   *   ALLOW_DUPLICATE allows new run independently of the previous run closure status.
-   *   REJECT_DUPLICATE doesn't allow new run independently of the previous run closure status.
+   * Whether a Workflow can be started with a Workflow Id of a Closed Workflow.
+   *
+   * *Note: A Workflow can never be started with a Workflow Id of a Running Workflow.*
+   *
+   * @default {@link WorkflowIdReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY}
    */
   workflowIdReusePolicy?: WorkflowIdReusePolicy;
 
diff --git a/packages/workflow/src/interfaces.ts b/packages/workflow/src/interfaces.ts
@@ -165,19 +165,69 @@ export interface ContinueAsNewOptions {
   searchAttributes?: SearchAttributes;
 }
 
+/**
+ * Specifies:
+ * - whether cancellation requests are sent to the Child
+ * - whether and when a {@link CanceledFailure} is thrown from {@link executeChild} or
+ *   {@link ChildWorkflowHandle.result}
+ *
+ * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
+ */
 export enum ChildWorkflowCancellationType {
+  /**
+   * Don't send a cancellation request to the Child.
+   */
   ABANDON = 0,
+
+  /**
+   * Send a cancellation request to the Child. Immediately throw the error.
+   */
   TRY_CANCEL = 1,
+
+  /**
+   * Send a cancellation request to the Child. The Child may respect cancellation, in which case an error will be thrown
+   * when cancellation has completed, and {@link isCancellation}(error) will be true. On the other hand, the Child may
+   * ignore the cancellation request, in which case an error might be thrown with a different cause, or the Child may
+   * complete successfully.
+   *
+   * @default
+   */
   WAIT_CANCELLATION_COMPLETED = 2,
+
+  /**
+   * Send a cancellation request to the Child. Throw the error once the Server receives the Child cancellation request.
+   */
   WAIT_CANCELLATION_REQUESTED = 3,
 }
 
 checkExtends<coresdk.child_workflow.ChildWorkflowCancellationType, ChildWorkflowCancellationType>();
 
+/**
+ * Concept: [Parent Close Policy](https://docs.temporal.io/concepts/what-is-a-parent-close-policy/)
+ *
+ * How a Child Workflow reacts to the Parent Workflow reaching a Closed state.
+ */
 export enum ParentClosePolicy {
+  /**
+   * If a `ParentClosePolicy` is set to this, or is not set at all, the server default value will be used.
+   */
   PARENT_CLOSE_POLICY_UNSPECIFIED = 0,
+
+  /**
+   * When the Parent is Closed, the Child is Terminated.
+   *
+   * @default
+   */
   PARENT_CLOSE_POLICY_TERMINATE = 1,
+
+  /**
+   * When the Parent is Closed, nothing is done to the Child.
+   */
   PARENT_CLOSE_POLICY_ABANDON = 2,
+
+  /**
+   * When the Parent is Closed, the Child is Cancelled.
+   */
   PARENT_CLOSE_POLICY_REQUEST_CANCEL = 3,
 }
 
@@ -198,13 +248,19 @@ export interface ChildWorkflowOptions extends CommonWorkflowOptions {
   taskQueue?: string;
 
   /**
-   * In case of a child workflow cancellation it fails with a CanceledFailure.
-   * The type defines at which point the exception is thrown.
-   * @default ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED
+   * Specifies:
+   * - whether cancellation requests are sent to the Child
+   * - whether and when an error is thrown from {@link executeChild} or
+   *   {@link ChildWorkflowHandle.result}
+   *
+   * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
    */
   cancellationType?: ChildWorkflowCancellationType;
+
   /**
-   * Specifies how this workflow reacts to the death of the parent workflow.
+   * Specifies how the Child reacts to the Parent Workflow reaching a Closed state.
+   *
+   * @default {@link ParentClosePolicy.PARENT_CLOSE_POLICY_TERMINATE}
    */
   parentClosePolicy?: ParentClosePolicy;
 }
