Update doc blocks for delay/retry functions

Author: jerelmiller

src/link/retry/delayFunction.ts

@@ -8,35 +8,40 @@ export interface DelayFunction {
   (count: number, operation: ApolloLink.Operation, error: any): number;
 }
 
+/**
+ * Configuration options for the standard retry delay strategy.
+ */
 export interface DelayFunctionOptions {
   /**
    * The number of milliseconds to wait before attempting the first retry.
    *
    * Delays will increase exponentially for each attempt. E.g. if this is
    * set to 100, subsequent retries will be delayed by 200, 400, 800, etc,
-   * until they reach maxDelay.
+   * until they reach the maximum delay.
    *
    * Note that if jittering is enabled, this is the _average_ delay.
    *
-   * Defaults to 300.
+   * @defaultValue 300
    */
   initial?: number;
 
   /**
    * The maximum number of milliseconds that the link should wait for any
    * retry.
    *
-   * Defaults to Infinity.
+   * @defaultValue Infinity
    */
   max?: number;
 
   /**
    * Whether delays between attempts should be randomized.
    *
-   * This helps avoid thundering herd type situations by better distributing
-   * load during major outages.
+   * This helps avoid [thundering herd](https://en.wikipedia.org/wiki/Thundering_herd_problem)
+   * type situations by better distributing load during major outages. Without
+   * these strategies, when your server comes back up it will be hit by all
+   * of your clients at once, possibly causing it to go down again.
    *
-   * Defaults to true.
+   * @defaultValue true
    */
   jitter?: boolean;
 }

src/link/retry/retryFunction.ts

@@ -12,14 +12,20 @@ export interface RetryFunction {
   ): boolean | Promise<boolean>;
 }
 
+/**
+ * Configuration options for the standard retry attempt strategy.
+ */
 export interface RetryFunctionOptions {
   /**
    * The max number of times to try a single operation before giving up.
    *
+   * @remarks
    * Note that this INCLUDES the initial request as part of the count.
-   * E.g. maxTries of 1 indicates no retrying should occur.
+   * E.g. `max` of 1 indicates no retrying should occur.
+   *
+   * Pass `Infinity` for infinite retries.
    *
-   * Defaults to 5. Pass Infinity for infinite retries.
+   * @defaultValue 5
    */
   max?: number;