Many TSDoc tweaks (#3049)

Author: jeffposnick

packages/workbox-broadcast-update/src/BroadcastCacheUpdate.ts

@@ -97,8 +97,8 @@ class BroadcastCacheUpdate {
   /**
    * Compares two [Responses](https://developer.mozilla.org/en-US/docs/Web/API/Response)
    * and sends a message (via `postMessage()`) to all window clients if the
-   * responses differ (note: neither of the Responses can be
-   * {@link http://stackoverflow.com/questions/39109789|opaque}).
+   * responses differ. Neither of the Responses can be
+   * [opaque](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/#opaque-responses).
    *
    * The message that's posted has the following format (where `payload` can
    * be customized via the `generatePayload` option the instance is created

packages/workbox-broadcast-update/src/BroadcastUpdatePlugin.ts

@@ -26,9 +26,9 @@ class BroadcastUpdatePlugin implements WorkboxPlugin {
   private readonly _broadcastUpdate: BroadcastCacheUpdate;
 
   /**
-   * Construct a BroadcastCacheUpdate instance with the passed options and
-   * calls its {@link workbox-broadcast-update.BroadcastCacheUpdate~notifyIfUpdated}
-   * method whenever the plugin's `cacheDidUpdate` callback is invoked.
+   * Construct a {@link workbox-broadcast-update.BroadcastUpdate} instance with
+   * the passed options and calls its `notifyIfUpdated` method whenever the
+   * plugin's `cacheDidUpdate` callback is invoked.
    *
    * @param {Object} [options]
    * @param {Array<string>} [options.headersToCheck=['content-length', 'etag', 'last-modified']]

packages/workbox-broadcast-update/src/index.ts

@@ -6,13 +6,22 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {BroadcastCacheUpdate} from './BroadcastCacheUpdate.js';
+import {
+  BroadcastCacheUpdate,
+  BroadcastCacheUpdateOptions,
+} from './BroadcastCacheUpdate.js';
 import {BroadcastUpdatePlugin} from './BroadcastUpdatePlugin.js';
 import {responsesAreSame} from './responsesAreSame.js';
+
 import './_version.js';
 
 /**
  * @module workbox-broadcast-update
  */
 
-export {BroadcastCacheUpdate, BroadcastUpdatePlugin, responsesAreSame};
+export {
+  BroadcastCacheUpdate,
+  BroadcastCacheUpdateOptions,
+  BroadcastUpdatePlugin,
+  responsesAreSame,
+};

packages/workbox-build/src/generate-sw.ts

@@ -24,7 +24,7 @@ import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template
  * Based on the precache manifest and the additional configuration, it writes
  * a ready-to-use service worker file to disk at `swDest`.
  *
- * @example
+ * ```
  * // The following lists some common options; see the rest of the documentation
  * // for the full set of options and defaults.
  * const {count, size, warnings} = await generateSW({
@@ -55,6 +55,7 @@ import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template
  *   skipWaiting: ...,
  *   swDest: '...',
  * });
+ * ```
  *
  * @memberof workbox-build
  */

packages/workbox-build/src/get-manifest.ts

@@ -15,7 +15,7 @@ import {validateGetManifestOptions} from './lib/validate-options';
  * manifest", along with details about the number of entries and their size,
  * based on the options you provide.
  *
- * @example
+ * ```
  * // The following lists some common options; see the rest of the documentation
  * // for the full set of options and defaults.
  * const {count, manifestEntries, size, warnings} = await getManifest({
@@ -24,6 +24,7 @@ import {validateGetManifestOptions} from './lib/validate-options';
  *   globPatterns: ['...', '...'],
  *   maximumFileSizeToCacheInBytes: ...,
  * });
+ * ```
  *
  * @memberof workbox-build
  */

packages/workbox-build/src/inject-manifest.ts

@@ -35,7 +35,7 @@ import {validateInjectManifestOptions} from './lib/validate-options';
  * This method will not compile or bundle your `swSrc` file; it just handles
  * injecting the manifest.
  *
- * @example
+ * ```
  * // The following lists some common options; see the rest of the documentation
  * // for the full set of options and defaults.
  * const {count, size, warnings} = await injectManifest({
@@ -46,6 +46,7 @@ import {validateInjectManifestOptions} from './lib/validate-options';
  *   swDest: '...',
  *   swSrc: '...',
  * });
+ * ```
  *
  * @memberof workbox-build
  */

packages/workbox-build/src/lib/copy-workbox-libraries.ts

@@ -26,9 +26,9 @@ const BUILD_DIR = 'build';
  * Workbox from its official CDN URL.
  *
  * This method is exposed for the benefit of developers using
- * [injectManifest()]{@link workbox-build.injectManifest} who would
+ * {@link workbox-build.injectManifest} who would
  * prefer not to use the CDN copies of Workbox. Developers using
- * [generateSW()]{@link workbox-build.generateSW} don't need to
+ * {@link workbox-build.generateSW} don't need to
  * explicitly call this method.
  *
  * @param {string} destDirectory The path to the parent directory under which

packages/workbox-build/src/lib/transform-manifest.ts

@@ -21,7 +21,7 @@ import {noRevisionForURLsMatchingTransform} from './no-revision-for-urls-matchin
 /**
  * A `ManifestTransform` function can be used to modify the modify the `url` or
  * `revision` properties of some or all of the
- * {@link workbox-build.ManifestEntry|ManifestEntries} in the manifest.
+ * {@link workbox-build.ManifestEntry} in the manifest.
  *
  * Deleting the `revision` property of an entry will cause
  * the corresponding `url` to be precached without cache-busting parameters

packages/workbox-cacheable-response/src/index.ts

@@ -6,12 +6,16 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {CacheableResponse} from './CacheableResponse.js';
+import {
+  CacheableResponse,
+  CacheableResponseOptions,
+} from './CacheableResponse.js';
 import {CacheableResponsePlugin} from './CacheableResponsePlugin.js';
+
 import './_version.js';
 
 /**
  * @module workbox-cacheable-response
  */
 
-export {CacheableResponse, CacheableResponsePlugin};
+export {CacheableResponse, CacheableResponseOptions, CacheableResponsePlugin};

packages/workbox-expiration/src/index.ts

@@ -7,11 +7,12 @@
 */
 
 import {CacheExpiration} from './CacheExpiration.js';
-import {ExpirationPlugin} from './ExpirationPlugin.js';
+import {ExpirationPlugin, ExpirationPluginOptions} from './ExpirationPlugin.js';
+
 import './_version.js';
 
 /**
  * @module workbox-expiration
  */
 
-export {CacheExpiration, ExpirationPlugin};
+export {CacheExpiration, ExpirationPlugin, ExpirationPluginOptions};

packages/workbox-google-analytics/src/index.ts

@@ -6,11 +6,12 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {initialize} from './initialize.js';
+import {initialize, GoogleAnalyticsInitializeOptions} from './initialize.js';
+
 import './_version.js';
 
 /**
  * @module workbox-google-analytics
  */
 
-export {initialize};
+export {initialize, GoogleAnalyticsInitializeOptions};

packages/workbox-recipes/src/index.ts

@@ -6,12 +6,15 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {googleFontsCache} from './googleFontsCache';
-import {imageCache} from './imageCache';
-import {staticResourceCache} from './staticResourceCache';
-import {pageCache} from './pageCache';
-import {offlineFallback} from './offlineFallback';
-import {warmStrategyCache} from './warmStrategyCache';
+import {googleFontsCache, GoogleFontCacheOptions} from './googleFontsCache';
+import {imageCache, ImageCacheOptions} from './imageCache';
+import {
+  staticResourceCache,
+  StaticResourceOptions,
+} from './staticResourceCache';
+import {pageCache, PageCacheOptions} from './pageCache';
+import {offlineFallback, OfflineFallbackOptions} from './offlineFallback';
+import {warmStrategyCache, WarmStrategyCacheOptions} from './warmStrategyCache';
 
 import './_version.js';
 
@@ -20,10 +23,16 @@ import './_version.js';
  */
 
 export {
+  GoogleFontCacheOptions,
   googleFontsCache,
   imageCache,
-  staticResourceCache,
-  pageCache,
+  ImageCacheOptions,
   offlineFallback,
+  OfflineFallbackOptions,
+  pageCache,
+  PageCacheOptions,
+  staticResourceCache,
+  StaticResourceOptions,
   warmStrategyCache,
+  WarmStrategyCacheOptions,
 };

packages/workbox-recipes/src/pageCache.ts

@@ -17,7 +17,7 @@ import {
 
 import './_version.js';
 
-export interface ImageCacheOptions {
+export interface PageCacheOptions {
   cacheName?: string;
   matchCallback?: RouteMatchCallback;
   networkTimeoutSeconds?: number;
@@ -37,7 +37,7 @@ export interface ImageCacheOptions {
  * @param {WorkboxPlugin[]} [options.plugins] Additional plugins to use for this recipe
  * @param {string[]} [options.warmCache] Paths to call to use to warm this cache
  */
-function pageCache(options: ImageCacheOptions = {}): void {
+function pageCache(options: PageCacheOptions = {}): void {
   const defaultMatchCallback = ({request}: RouteMatchCallbackOptions) =>
     request.mode === 'navigate';
 

packages/workbox-routing/src/RegExpRoute.ts

@@ -27,8 +27,6 @@ import './_version.js';
  * requests against third-party servers, you must define a RegExp that matches
  * the start of the URL.
  *
- * [See the module docs for info.]{@link https://developers.google.com/web/tools/workbox/modules/workbox-routing}
- *
  * @memberof workbox-routing
  * @extends workbox-routing.Route
  */

packages/workbox-routing/src/index.ts

@@ -6,7 +6,10 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {NavigationRoute} from './NavigationRoute.js';
+import {
+  NavigationRoute,
+  NavigationRouteMatchOptions,
+} from './NavigationRoute.js';
 import {RegExpRoute} from './RegExpRoute.js';
 import {registerRoute} from './registerRoute.js';
 import {Route} from './Route.js';
@@ -28,4 +31,5 @@ export {
   Router,
   setCatchHandler,
   setDefaultHandler,
+  NavigationRouteMatchOptions,
 };

packages/workbox-routing/src/registerRoute.ts

@@ -31,8 +31,7 @@ import './_version.js';
  * is required if `capture` is not a `Route` object.
  * @param {string} [method='GET'] The HTTP method to match the Route
  * against.
- * @return {workbox-routing.Route} The generated `Route`(Useful for
- * unregistering).
+ * @return {workbox-routing.Route} The generated `Route`.
  *
  * @memberof workbox-routing
  */

packages/workbox-strategies/src/CacheFirst.ts

@@ -16,7 +16,7 @@ import {messages} from './utils/messages.js';
 import './_version.js';
 
 /**
- * An implementation of a [cache-first]{@link https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network}
+ * An implementation of a [cache-first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache-first-falling-back-to-network)
  * request strategy.
  *
  * A cache first strategy is useful for assets that have been revisioned,

packages/workbox-strategies/src/CacheOnly.ts

@@ -16,12 +16,11 @@ import {messages} from './utils/messages.js';
 import './_version.js';
 
 /**
- * An implementation of a
- * [cache-only]{@link https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-only}
+ * An implementation of a [cache-only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache-only)
  * request strategy.
  *
  * This class is useful if you want to take advantage of any
- * [Workbox plugins]{@link https://developers.google.com/web/tools/workbox/guides/using-plugins}.
+ * [Workbox plugins](https://developer.chrome.com/docs/workbox/using-plugins/).
  *
  * If there is no cache match, this will throw a `WorkboxError` exception.
  *

packages/workbox-strategies/src/NetworkFirst.ts

@@ -22,13 +22,13 @@ export interface NetworkFirstOptions extends StrategyOptions {
 
 /**
  * An implementation of a
- * [network first]{@link https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#network-falling-back-to-cache}
+ * [network first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-first-falling-back-to-cache)
  * request strategy.
  *
  * By default, this strategy will cache responses with a 200 status code as
- * well as [opaque responses]{@link https://developers.google.com/web/tools/workbox/guides/handle-third-party-requests}.
+ * well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/#opaque-responses).
  * Opaque responses are are cross-origin requests where the response doesn't
- * support [CORS]{@link https://enable-cors.org/}.
+ * support [CORS](https://enable-cors.org/).
  *
  * If the network request fails, and there is no cache match, this will throw
  * a `WorkboxError` exception.

packages/workbox-strategies/src/NetworkOnly.ts

@@ -23,11 +23,11 @@ interface NetworkOnlyOptions
 
 /**
  * An implementation of a
- * [network-only]{@link https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#network-only}
+ * [network-only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-only)
  * request strategy.
  *
  * This class is useful if you want to take advantage of any
- * [Workbox plugins]{@link https://developers.google.com/web/tools/workbox/guides/using-plugins}.
+ * [Workbox plugins](https://developer.chrome.com/docs/workbox/using-plugins/).
  *
  * If the network request fails, this will throw a `WorkboxError` exception.
  *

packages/workbox-strategies/src/StaleWhileRevalidate.ts

@@ -18,7 +18,7 @@ import './_version.js';
 
 /**
  * An implementation of a
- * [stale-while-revalidate]{@link https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#stale-while-revalidate}
+ * [stale-while-revalidate](https://developer.chrome.com/docs/workbox/reference/workbox-strategies/#type-StaleWhileRevalidate)
  * request strategy.
  *
  * Resources are requested from both the cache and the network in parallel.
@@ -27,9 +27,9 @@ import './_version.js';
  * with each successful request.
  *
  * By default, this strategy will cache responses with a 200 status code as
- * well as [opaque responses]{@link https://developers.google.com/web/tools/workbox/guides/handle-third-party-requests}.
+ * well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/#opaque-responses).
  * Opaque responses are cross-origin requests where the response doesn't
- * support [CORS]{@link https://enable-cors.org/}.
+ * support [CORS](https://enable-cors.org/).
  *
  * If the network request fails, and there is no cache match, this will throw
  * a `WorkboxError` exception.

packages/workbox-streams/src/index.ts

@@ -9,13 +9,20 @@
 import {concatenate} from './concatenate.js';
 import {concatenateToResponse} from './concatenateToResponse.js';
 import {isSupported} from './isSupported.js';
-import {strategy} from './strategy.js';
+import {strategy, StreamsHandlerCallback} from './strategy.js';
+
 import './_version.js';
 
 /**
  * @module workbox-streams
  */
 
-export {concatenate, concatenateToResponse, isSupported, strategy};
+export {
+  concatenate,
+  concatenateToResponse,
+  isSupported,
+  strategy,
+  StreamsHandlerCallback,
+};
 
 export * from './_types.js';

packages/workbox-streams/src/strategy.ts

@@ -17,7 +17,7 @@ import {isSupported} from './isSupported.js';
 import {StreamSource} from './_types.js';
 import './_version.js';
 
-interface StreamsHandlerCallback {
+export interface StreamsHandlerCallback {
   ({url, request, event, params}: RouteHandlerCallbackOptions):
     | Promise<StreamSource>
     | StreamSource;

packages/workbox-webpack-plugin/src/generate-sw.ts

@@ -24,7 +24,7 @@ const {RawSource} = webpack.sources || require('webpack-sources');
 // See https://github.com/GoogleChrome/workbox/issues/2181
 const _generatedAssetNames = new Set<string>();
 
-interface GenerateSWConfig extends WebpackGenerateSWOptions {
+export interface GenerateSWConfig extends WebpackGenerateSWOptions {
   manifestEntries?: Array<ManifestEntry>;
 }
 
@@ -36,7 +36,7 @@ interface GenerateSWConfig extends WebpackGenerateSWOptions {
  * [`plugins` array](https://webpack.js.org/concepts/plugins/#usage) of a
  * webpack config.
  *
- * @example
+ * ```
  * // The following lists some common options; see the rest of the documentation
  * // for the full set of options and defaults.
  * new GenerateSW({
@@ -64,6 +64,7 @@ interface GenerateSWConfig extends WebpackGenerateSWOptions {
  *   }],
  *   skipWaiting: ...,
  * });
+ * ```
  *
  * @memberof module:workbox-webpack-plugin
  */