docs: Misc minor improvements (#964)

Author: lorensr

packages/client/src/connection.ts

@@ -54,14 +54,14 @@ export interface ConnectionOptions {
   channelArgs?: grpc.ChannelOptions;
 
   /**
-   * Grpc interceptors which will be applied to every RPC call performed by this connection. By default, an interceptor
-   * will be included which automatically retries retryable errors. If you do not wish to perform automatic retries, set
-   * this to an empty list (or a list with your own interceptors). If you want to add your own interceptors while
-   * keeping the default retry behavior, add this to your list of interceptors:
-   * `makeGrpcRetryInterceptor(defaultGrpcRetryOptions())`. See:
+   * {@link https://grpc.github.io/grpc/node/module-src_client_interceptors.html | gRPC interceptors} which will be
+   * applied to every RPC call performed by this connection. By default, an interceptor will be included which
+   * automatically retries retryable errors. If you do not wish to perform automatic retries, set this to an empty list
+   * (or a list with your own interceptors). If you want to add your own interceptors while keeping the default retry
+   * behavior, add this to your list of interceptors: `makeGrpcRetryInterceptor(defaultGrpcRetryOptions())`. See:
    *
-   * - @link makeGrpcRetryInterceptor
-   * - @link defaultGrpcRetryOptions
+   * - {@link makeGrpcRetryInterceptor}
+   * - {@link defaultGrpcRetryOptions}
    */
   interceptors?: grpc.Interceptor[];
 

packages/common/src/activity-options.ts

@@ -45,17 +45,24 @@ export interface ActivityOptions {
   retry?: RetryPolicy;
 
   /**
-   * 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 {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for timely failure detection.
-
+   * 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 {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for
+   * timely failure detection.
+   *
    * Either this option or {@link scheduleToCloseTimeout} is required.
+   *
+   * @default `scheduleToCloseTimeout` or unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   startToCloseTimeout?: string | number;
+
   /**
    * 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.
    * `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.
-   * @default unlimited
+   *
+   * @default `scheduleToCloseTimeout` or unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   scheduleToStartTimeout?: string | number;
@@ -64,7 +71,8 @@ Note that the Temporal Server doesn't detect Worker process failures directly. I
    * 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 {@link startToCloseTimeout} to limit the time of a single attempt).
    *
-   * Either this option or {@link startToCloseTimeout} is required
+   * Either this option or {@link startToCloseTimeout} is required.
+   *
    * @default unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */

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

@@ -43,10 +43,10 @@ export function cutoffStackTrace(stack?: string): string {
 }
 
 /**
- * A `FailureConverter` is responsible to convert from proto `Failure` instances to JS `Errors` and back.
+ * A `FailureConverter` is responsible for converting from proto `Failure` instances to JS `Errors` and back.
  *
- * It is recommended to use the {@link DefaultFailureConverter} and not attempt to customize the default implementation
- * in order to maintain cross language failure serialization compatibility.
+ * We recommended using the {@link DefaultFailureConverter} instead of customizing the default implementation in order
+ * to maintain cross-language Failure serialization compatibility.
  *
  * @experimental
  */
@@ -81,11 +81,12 @@ export interface DefaultFailureConverterOptions {
 }
 
 /**
- * Default cross language compatible failure converter.
+ * Default, cross-language-compatible Failure converter.
  *
- * By default, it will leave error messages and stack traces as plain text. In order to encrypt those, set
- * `encodeCommonAttributes` to `true` in the constructor options and make sure to use a {@link PayloadCodec} that can
- * encrypt / decrypt payloads in your Worker and Client options.
+ * By default, it will leave error messages and stack traces as plain text. In order to encrypt them, set
+ * `encodeCommonAttributes` to `true` in the constructor options and use a {@link PayloadCodec} that can encrypt /
+ * decrypt Payloads in your {@link WorkerOptions.dataConverter | Worker} and
+ * {@link ClientOptions.dataConverter | Client options}.
  *
  * @experimental
  */