docs: Improve API reference (#826)

Author: lorensr

packages/activity/src/index.ts

@@ -15,15 +15,19 @@
  *
  * ### Cancellation
  *
- * Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
+ * Activity Cancellation serves three purposes:
+ *
+ * - It lets an Activity know it doesn't need to keep doing work.
+ * - It gives the Activity time to clean up any resources it has created.
+ *
+ * Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * (which can't heartbeat but receive Cancellation anyway).
  *
  * There are two ways to handle Activity cancellation:
  * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
- *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a
- *    {@link CancelledFailure}.
+ *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
- *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that
- *    supports it.
+ *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### Examples
  *
@@ -145,13 +149,16 @@ export interface Info {
    */
   heartbeatTimeoutMs?: number;
   /**
-   * Hold the details supplied to the last heartbeat on previous attempts of this Activity.
-   * Use this in order to resume your Activity from checkpoint.
+   * The {@link Context.heartbeat | details} from the last recorded heartbeat from the last attempt of this Activity.
+   *
+   * Use this to resume your Activity from a checkpoint.
    */
   heartbeatDetails: any;
 
   /**
-   * Task queue the Activity is scheduled in, set to the Workflow's task queue in case of local Activity.
+   * Task Queue the Activity is scheduled in.
+   *
+   * For Local Activities, this is set to the Workflow's Task Queue.
    */
   taskQueue: string;
 }
@@ -224,7 +231,9 @@ export class Context {
    * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
    * {@link TimeoutFailure.lastHeartbeatDetails}.
    *
-   * Activities must heartbeat in order to receive cancellation.
+   * Calling `heartbeat()` from a Local Activity has no effect.
+   *
+   * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
    */
   public heartbeat(details?: unknown): void {
     this.heartbeatFn(details);

packages/common/src/failure.ts

@@ -37,14 +37,9 @@ export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 /**
  * Represents failures that can cross Workflow and Activity boundaries.
  *
- * Only exceptions that extend this class will be propagated to the caller.
+ * **Never extend this class or any of its children.**
  *
- * **Never extend this class or any of its derivatives.** They are to be used by the SDK code
- * only. Throw an instance {@link ApplicationFailure} to pass application specific errors between
- * Workflows and Activities.
- *
- * Any unhandled exception thrown by an Activity or Workflow will be converted to an instance of
- * {@link ApplicationFailure}.
+ * The only child class you should ever throw from your code is {@link ApplicationFailure}.
  */
 export class TemporalFailure extends Error {
   public readonly name: string = 'TemporalFailure';
@@ -79,19 +74,17 @@ export class ServerFailure extends TemporalFailure {
  * `ApplicationFailure`, the Workflow Execution will fail.
  *
  * In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the
- * latter case, the `Error` will be converted to an `ApplicationFailure`. If the
- * {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
- * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
- * Workflow.
- *
- * The conversion of an error that doesn't extend {@link TemporalFailure} to an `ApplicationFailure` is done as
- * following:
+ * latter case, the `Error` will be converted to an `ApplicationFailure`. The conversion is done as following:
  *
  * - `type` is set to `error.constructor?.name ?? error.name`
  * - `message` is set to `error.message`
  * - `nonRetryable` is set to false
  * - `details` are set to null
  * - stack trace is copied from the original error
+ *
+ * When an {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
+ * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
+ * Workflow.
  */
 export class ApplicationFailure extends TemporalFailure {
   public readonly name: string = 'ApplicationFailure';

packages/worker/src/worker-options.ts

@@ -86,7 +86,9 @@ export interface WorkerOptions {
   workflowsPath?: string;
 
   /**
-   * Use a pre-built bundle for Workflow code. Use {@link bundleWorkflowCode} to generate a bundle.
+   * Use a pre-built bundle for Workflow code. Use {@link bundleWorkflowCode} to generate the bundle. The version of
+   * `@temporalio/worker` used when calling `bundleWorkflowCode` must be the exact same version used when calling
+   * `Worker.create`.
    *
    * This is the recommended way to deploy Workers to production.
    *

packages/worker/src/worker.ts

@@ -457,7 +457,7 @@ export class Worker {
    * Create a replay Worker, and run the provided history against it. Will resolve as soon as
    * the history has finished being replayed, or if the workflow produces a nondeterminism error.
    *
-   * @throws DeterminismViolationError if the workflow code is not compatible with the history.
+   * @throws {@link DeterminismViolationError} if the workflow code is not compatible with the history.
    */
   public static async runReplayHistory(options: ReplayWorkerOptions, history: History | unknown): Promise<void> {
     if (typeof history !== 'object' || history == null) {
@@ -653,10 +653,18 @@ export class Worker {
   }
 
   /**
-   * Start shutting down the Worker. Immediately transitions {@link state} to `'STOPPING'` and asks Core to shut down.
-   * Once Core has confirmed that it's shutting down, the Worker enters `'DRAINING'` state unless the Worker has already
-   * been `'DRAINED'`. All currently running Activities are Cancelled. Once all currently running Activities and
-   * Workflow Tasks have completed, the Worker transitions to `'STOPPED'`.
+   * Start shutting down the Worker. The Worker stops polling for new tasks and sends
+   * {@link https://typescript.temporal.io/api/namespaces/activity#cancellation | cancellation} (via a
+   * {@link CancelledFailure} with `message` set to `'WORKER_SHUTDOWN'`) to running Activities. Note: if the Activity
+   * accepts cancellation (i.e. re-throws or allows the `CancelledFailure` to be thrown out of the Activity function),
+   * the Activity Task will be marked as failed, not cancelled. It's helpful for the Activity Task to be marked failed
+   * during shutdown because the Server will retry the Activity sooner (than if the Server had to wait for the Activity
+   * Task to time out).
+   *
+   * When called, immediately transitions {@link state} to `'STOPPING'` and asks Core to shut down. Once Core has
+   * confirmed that it's shutting down, the Worker enters `'DRAINING'` state unless the Worker has already been
+   * `'DRAINED'`. Once all currently running Activities and Workflow Tasks have completed, the Worker transitions to
+   * `'STOPPED'`.
    */
   shutdown(): void {
     if (this.state !== 'RUNNING') {