docs: Review API docs (#744)

Author: lorensr

packages/activity/src/index.ts

@@ -1,25 +1,42 @@
 /**
- * This library provides tools for authoring activities.
+ * This package's main export is {@link Context}. Get the current Activity's context with
+ * {@link Context.current | `Context.current()`}:
  *
- * Import this module from Activity code - must **not** be used in Workflows.
+ * ```ts
+ * import { Context } from '@temporalio/activity';
  *
- * Any function can be used as an Activity as long as its parameters and return value are serializable using a [`DataConverter`](../interfaces/worker.DataConverter.md).
+ * export async function myActivity() {
+ *   const context = Context.current();
+ * }
+ * ```
+ *
+ * Any function can be used as an Activity as long as its parameters and return value are serializable using a
+ * {@link https://docs.temporal.io/concepts/what-is-a-data-converter/ | DataConverter}.
  *
  * ### Cancellation
- * Activities may be cancelled only if they [emit heartbeats](../classes/activity.Context.md#heartbeat).<br/>
- * There are 2 ways to handle Activity cancellation:
- * 1. await on [`Context.current().cancelled`](../classes/activity.Context.md#cancelled)
- * 1. Pass the context's [abort signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) at [`Context.current().cancellationSignal`](../classes/activity.Context.md#cancellationsignal) to a library that supports it
+ *
+ * Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
+ *
+ * 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}.
+ * 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.
  *
  * ### Examples
  *
- * #### An Activity that fakes progress and can be cancelled
+ * #### An Activity that sends progress heartbeats and can be cancelled
  *
  * <!--SNIPSTART typescript-activity-fake-progress-->
  * <!--SNIPEND-->
  *
  * #### An Activity that makes a cancellable HTTP request
  *
+ * It passes the `AbortSignal` to {@link https://github.com/node-fetch/node-fetch#api | `fetch`}: `fetch(url, { signal:
+ * Context.current().cancellationSignal })`.
+ *
  * <!--SNIPSTART typescript-activity-cancellable-fetch-->
  * <!--SNIPEND-->
  *
@@ -38,11 +55,21 @@ export {
 export * from '@temporalio/internal-workflow-common/lib/errors';
 
 /**
- * Throw this error from an Activity in order to make the Worker
- * forget about this Activity.
+ * Throw this error from an Activity in order to make the Worker forget about this Activity.
+ *
+ * The Activity can then be completed asynchronously (from anywhere—usually outside the Worker) using
+ * {@link AsyncCompletionClient}.
+ *
+ * @example
  *
- * The Activity can be completed asynchronously using
- * {@link AsyncCompletionClient}
+ *```ts
+ *import { CompleteAsyncError } from '@temporalio/activity';
+ *
+ *export async function myActivity(): Promise<never> {
+ *  // ...
+ *  throw new CompleteAsyncError();
+ *}
+ *```
  */
 export class CompleteAsyncError extends Error {
   public readonly name: string = 'CompleteAsyncError';
@@ -56,7 +83,7 @@ export class CompleteAsyncError extends Error {
 export const asyncLocalStorage = new AsyncLocalStorage<Context>();
 
 /**
- * Holds information about the current executing Activity
+ * Holds information about the current Activity Execution. Retrieved inside an Activity with `Context.current().info`.
  */
 export interface Info {
   taskToken: Uint8Array;
@@ -124,9 +151,14 @@ export interface Info {
 }
 
 /**
- * Activity Context manager.
+ * Activity Context, used to:
+ *
+ * - Get {@link Info} about the current Activity Execution
+ * - Send {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeats}
+ * - Get notified of Activity cancellation
+ * - Sleep (cancellation-aware)
  *
- * Call `Context.current()` from Activity code in order to send heartbeats and get notified of Activity cancellation.
+ * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 export class Context {
   /**
@@ -136,13 +168,21 @@ export class Context {
   /**
    * Await this promise in an Activity to get notified of cancellation.
    *
-   * This promise will never be resolved, it will only be rejected with a {@link CancelledFailure}.
+   * This promise will never resolve—it will only be rejected with a {@link CancelledFailure}.
+   *
+   * @see [Cancellation](/api/namespaces/activity#cancellation)
    */
   public readonly cancelled: Promise<never>;
   /**
-   * An `AbortSignal` which can be used to cancel requests on Activity cancellation.
+   * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
+   * Activity cancellation.
    *
-   * Typically used by the {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} and {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process} libraries but is supported by a few other libraries as well.
+   * Used by {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
+   * in-progress request and
+   * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
+   * to abort a child process, and is supported by some other libraries as well.
+   *
+   * @see [Cancellation](/api/namespaces/activity#cancellation)
    */
   public readonly cancellationSignal: AbortSignal;
   /**
@@ -168,11 +208,17 @@ export class Context {
   }
 
   /**
-   * Send a heartbeat from an Activity.
+   * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
+   *
+   * If an Activity times out, then during the next retry, the last value of `details` is available at
+   * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
    *
-   * If an Activity times out, the last value of details is included in the {@link ActivityFailure} delivered to a Workflow in the `cause` attribute which will be set to {@link TimeoutFailure}. Then the Workflow can pass the details to the next Activity invocation. This acts as a periodic checkpoint mechanism for the progress of an Activity.
+   * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
+   * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
+   * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
+   * {@link TimeoutFailure.lastHeartbeatDetails}.
    *
-   * The Activity must heartbeat in order to receive cancellation.
+   * Activities must heartbeat in order to receive cancellation.
    */
   public heartbeat(details?: unknown): void {
     this.heartbeatFn(details);
@@ -193,8 +239,8 @@ export class Context {
 
   /**
    * Helper function for sleeping in an Activity.
-   * @param ms sleep duration - {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   * @returns a Promise that either resolves when deadline is reached or rejects when the Context is cancelled
+   * @param ms Sleep duration: an {@link https://www.npmjs.com/package/ms | ms}-formatted string or number of milliseconds
+   * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
    */
   public sleep(ms: number | string): Promise<void> {
     let handle: NodeJS.Timeout;

packages/client/src/async-completion-client.ts

@@ -13,16 +13,16 @@ import { isServerErrorResponse } from './errors';
 import { ConnectionLike, WorkflowService } from './types';
 
 /**
- * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat
- * an Activity which does not exist in the system.
+ * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat an Activity that does not exist in the
+ * system.
  */
 export class ActivityNotFoundError extends Error {
   public readonly name = 'ActivityNotFoundError';
 }
 
 /**
  * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat
- * an Activity for any reason apart from "not found".
+ * an Activity for any reason apart from {@link ActivityNotFoundError}.
  */
 export class ActivityCompletionError extends Error {
   public readonly name = 'ActivityCompletionError';

packages/client/src/connection.ts

@@ -8,7 +8,7 @@ import pkg from './pkg';
 import { CallContext, Metadata, OperatorService, WorkflowService } from './types';
 
 /**
- * GRPC + Temporal server connection options
+ * gRPC and Temporal Server connection options
  */
 export interface ConnectionOptions {
   /**
@@ -147,25 +147,35 @@ export interface ConnectionCtorOptions {
 }
 
 /**
- * Client connection to the Temporal Service
+ * Client connection to the Temporal Server
  *
- * NOTE: Connections are expensive to construct and should be reused.
- * Make sure to `close()` any unused connections to avoid leaking resources.
+ * ⚠️ Connections are expensive to construct and should be reused. Make sure to {@link close} any unused connections to
+ * avoid leaking resources.
  */
 export class Connection {
+  /**
+   * @internal
+   */
   public static readonly Client = grpc.makeGenericClientConstructor({}, 'WorkflowService', {});
 
   public readonly options: ConnectionOptionsWithDefaults;
   protected readonly client: grpc.Client;
+
   /**
    * Used to ensure `ensureConnected` is called once.
    */
   protected connectPromise?: Promise<void>;
 
   /**
-   * Raw gRPC access to the Temporal service.
+   * Raw gRPC access to Temporal Server's {@link
+   * https://github.com/temporalio/api/blob/master/temporal/api/workflowservice/v1/service.proto | Workflow service}
    */
   public readonly workflowService: WorkflowService;
+
+  /**
+   * Raw gRPC access to Temporal Server's
+   * {@link https://github.com/temporalio/api/blob/master/temporal/api/operatorservice/v1/service.proto | Operator service}
+   */
   public readonly operatorService: OperatorService;
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
 
@@ -213,9 +223,11 @@ export class Connection {
   /**
    * Ensure connection can be established.
    *
+   * Does not need to be called if you use {@link connect}.
+   *
    * This method's result is memoized to ensure it runs only once.
    *
-   * Calls WorkflowService.getSystemInfo internally.
+   * Calls {@link proto.temporal.api.workflowservice.v1.WorkflowService.getSystemInfo} internally.
    */
   async ensureConnected(): Promise<void> {
     if (this.connectPromise == null) {
@@ -241,19 +253,19 @@ export class Connection {
   }
 
   /**
-   * Create a lazy Connection instance.
+   * Create a lazy `Connection` instance.
    *
-   * This method does not verify connectivity with the server, it is recommended to use
-   * {@link connect} instead.
+   * This method does not verify connectivity with the server. We recommend using {@link connect} instead.
    */
   static lazy(options?: ConnectionOptions): Connection {
     return new this(this.createCtorOptions(options));
   }
 
   /**
-   * Establish a connection with the server and return a Connection instance.
+   * Establish a connection with the server and return a `Connection` instance.
    *
-   * This is the preferred method of creating connections as it verifies connectivity.
+   * This is the preferred method of creating connections as it verifies connectivity by calling
+   * {@link ensureConnected}.
    */
   static async connect(options?: ConnectionOptions): Promise<Connection> {
     const conn = this.lazy(options);
@@ -303,29 +315,31 @@ export class Connection {
 
   /**
    * Set the deadline for any service requests executed in `fn`'s scope.
+   *
+   * @returns value returned from `fn`
    */
-  async withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R> {
+  async withDeadline<ReturnType>(deadline: number | Date, fn: () => Promise<ReturnType>): Promise<ReturnType> {
     const cc = this.callContextStorage.getStore();
     return await this.callContextStorage.run({ deadline, metadata: cc?.metadata }, fn);
   }
 
   /**
    * Set metadata for any service requests executed in `fn`'s scope.
    *
-   * The provided metadata is merged on top of any existing metadata in current scope
-   * including metadata provided in {@link ConnectionOptions.metadata}
+   * The provided metadata is merged on top of any existing metadata in current scope, including metadata provided in
+   * {@link ConnectionOptions.metadata}.
    *
-   * @returns returned value of `fn`
+   * @returns value returned from `fn`
    *
    * @example
    *
-   * ```ts
-   * await conn.withMetadata({ apiKey: 'secret' }, () =>
-   *   conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
-   * );
-   * ```
+   *```ts
+   *const workflowHandle = await conn.withMetadata({ apiKey: 'secret' }, () =>
+   *  conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
+   *);
+   *```
    */
-  async withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R> {
+  async withMetadata<ReturnType>(metadata: Metadata, fn: () => Promise<ReturnType>): Promise<ReturnType> {
     const cc = this.callContextStorage.getStore();
     metadata = { ...cc?.metadata, ...metadata };
     return await this.callContextStorage.run({ metadata, deadline: cc?.deadline }, fn);

packages/client/src/index.ts

@@ -1,7 +1,7 @@
 /**
- * Client for communicating with the Temporal service.
+ * Client for communicating with Temporal Server.
  *
- * Interact with workflows using {@link WorkflowClient} or call GRPC methods directly using {@link Connection.workflowService}.
+ * Most functionality is available through {@link WorkflowClient}, but you can also call gRPC methods directly using {@link Connection.workflowService} and {@link Connection.operatorService}.
  *
  * ### Usage
  * <!--SNIPSTART typescript-hello-client-->

packages/client/src/workflow-client.ts

@@ -906,9 +906,9 @@ export class WorkflowClient {
    *   most recent Workflow Execution in the *Chain* that started with `firstExecutionRunId`.
    *
    * A *Chain* is a series of Workflow Executions that share the same Workflow ID and are connected by:
-   * - Being part of the same [Cron](https://docs.temporal.io/typescript/clients#scheduling-cron-workflows)
-   * - [Continue As New](https://docs.temporal.io/typescript/workflows#continueasnew)
-   * - [Retries](https://typescript.temporal.io/api/interfaces/client.workflowoptions/#retry)
+   * - Being part of the same {@link https://docs.temporal.io/typescript/clients#scheduling-cron-workflows | Cron}
+   * - {@link https://docs.temporal.io/typescript/workflows#continueasnew | Continue As New}
+   * - {@link https://typescript.temporal.io/api/interfaces/client.workflowoptions/#retry | Retries}
    *
    * This method does not validate `workflowId`. If there is no Workflow Execution with the given `workflowId`, handle
    * methods like `handle.describe()` will throw a {@link WorkflowNotFoundError} error.

packages/common/src/converter/data-converter.ts

@@ -7,9 +7,9 @@ import { defaultPayloadConverter } from './payload-converters';
  * binary in a {@link Payload} Protobuf message.
  *
  * The default `DataConverter` supports `undefined`, `Uint8Array`, and JSON serializables (so if
- * [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description)
- * works, the default data converter will work). Protobufs are supported via [this
- * API](https://docs.temporal.io/typescript/data-converters#protobufs).
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default data converter will work). Protobufs are supported via
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | this API}.
  *
  * Use a custom `DataConverter` to control the contents of your {@link Payload}s. Common reasons for using a custom
  * `DataConverter` are:

packages/common/src/converter/payload-converter.ts

@@ -3,7 +3,7 @@ import { Payload } from './types';
 /**
  * Used by the framework to serialize/deserialize data like parameters and return values.
  *
- * This is called inside the [Workflow isolate](https://docs.temporal.io/typescript/determinism).
+ * This is called inside the {@link https://docs.temporal.io/typescript/determinism | Workflow isolate}.
  * To write async code or use Node APIs (or use packages that use Node APIs), use a {@link PayloadCodec}.
  */
 export interface PayloadConverter {

packages/common/src/converter/payload-converters.ts

@@ -137,8 +137,9 @@ export class DefaultPayloadConverter extends CompositePayloadConverter {
 }
 
 /**
- * The default {@link PayloadConverter} used by the SDK.
- * Supports `Uint8Array` and JSON serializables (so if [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) works, the default payload converter will work).
+ * The default {@link PayloadConverter} used by the SDK. Supports `Uint8Array` and JSON serializables (so if
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default payload converter will work).
  *
  * To also support Protobufs, create a custom payload converter with {@link DefaultPayloadConverter}:
  *