Fix broken/missing JSDocs and typedefs, to allow updating TypeScript to the latest version (issue 14342)

This patch circumvents the issues seen when trying to update TypeScript to version `4.5`, by "simply" fixing the broken/missing JSDocs and `typedef`s such that `gulp typestest` now passes.
As always, given that I don't really know anything about TypeScript, I cannot tell if this is a "correct" and/or proper way of doing things; we'll need TypeScript users to help out with testing!

*Please note:* I'm sorry about the size of this patch, but given how intertwined all of this unfortunately is it just didn't seem easy to split this into smaller parts.
However, one good thing about this TypeScript update is that it helped uncover a number of pre-existing bugs in our JSDocs comments.

package-lock.json

@@ -59,7 +59,7 @@
         "terser": "^5.10.0",
         "through2": "^4.0.2",
         "ttest": "^3.0.0",
-        "typescript": "~4.4.4",
+        "typescript": "^4.5.4",
         "typogr": "^0.6.8",
         "vinyl": "^2.2.1",
         "vinyl-fs": "^3.0.3",
@@ -12389,7 +12389,6 @@
     },
     "node_modules/npm/node_modules/lodash._baseindexof": {
       "version": "3.1.0",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT"
     },
@@ -12405,19 +12404,16 @@
     },
     "node_modules/npm/node_modules/lodash._bindcallback": {
       "version": "3.0.1",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT"
     },
     "node_modules/npm/node_modules/lodash._cacheindexof": {
       "version": "3.0.2",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT"
     },
     "node_modules/npm/node_modules/lodash._createcache": {
       "version": "3.1.2",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT",
       "dependencies": {
@@ -12432,7 +12428,6 @@
     },
     "node_modules/npm/node_modules/lodash._getnative": {
       "version": "3.9.1",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT"
     },
@@ -12450,7 +12445,6 @@
     },
     "node_modules/npm/node_modules/lodash.restparam": {
       "version": "3.6.1",
-      "extraneous": true,
       "inBundle": true,
       "license": "MIT"
     },
@@ -17845,9 +17839,9 @@
       }
     },
     "node_modules/typescript": {
-      "version": "4.4.4",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.4.4.tgz",
-      "integrity": "sha512-DqGhF5IKoBl8WNf8C1gu8q0xZSInh9j1kJJMqT3a94w1JzVaBU4EXOSMrz9yDqMT0xt3selp83fuFMQ0uzv6qA==",
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.4.tgz",
+      "integrity": "sha512-VgYs2A2QIRuGphtzFV7aQJduJ2gyfTljngLzjpfW9FoYZF6xuw1W0vW9ghCKLfcWrCFxK81CSGRAvS1pn4fIUg==",
       "dev": true,
       "bin": {
         "tsc": "bin/tsc",
@@ -28465,8 +28459,7 @@
         },
         "lodash._baseindexof": {
           "version": "3.1.0",
-          "bundled": true,
-          "extraneous": true
+          "bundled": true
         },
         "lodash._baseuniq": {
           "version": "4.6.0",
@@ -28479,18 +28472,15 @@
         },
         "lodash._bindcallback": {
           "version": "3.0.1",
-          "bundled": true,
-          "extraneous": true
+          "bundled": true
         },
         "lodash._cacheindexof": {
           "version": "3.0.2",
-          "bundled": true,
-          "extraneous": true
+          "bundled": true
         },
         "lodash._createcache": {
           "version": "3.1.2",
           "bundled": true,
-          "extraneous": true,
           "requires": {
             "lodash._getnative": "^3.0.0"
           }
@@ -28502,8 +28492,7 @@
         },
         "lodash._getnative": {
           "version": "3.9.1",
-          "bundled": true,
-          "extraneous": true
+          "bundled": true
         },
         "lodash._root": {
           "version": "3.0.1",
@@ -28517,8 +28506,7 @@
         },
         "lodash.restparam": {
           "version": "3.6.1",
-          "bundled": true,
-          "extraneous": true
+          "bundled": true
         },
         "lodash.union": {
           "version": "4.6.0",
@@ -32730,9 +32718,9 @@
       }
     },
     "typescript": {
-      "version": "4.4.4",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.4.4.tgz",
-      "integrity": "sha512-DqGhF5IKoBl8WNf8C1gu8q0xZSInh9j1kJJMqT3a94w1JzVaBU4EXOSMrz9yDqMT0xt3selp83fuFMQ0uzv6qA==",
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.4.tgz",
+      "integrity": "sha512-VgYs2A2QIRuGphtzFV7aQJduJ2gyfTljngLzjpfW9FoYZF6xuw1W0vW9ghCKLfcWrCFxK81CSGRAvS1pn4fIUg==",
       "dev": true
     },
     "typogr": {

package.json

@@ -52,7 +52,7 @@
     "terser": "^5.10.0",
     "through2": "^4.0.2",
     "ttest": "^3.0.0",
-    "typescript": "~4.4.4",
+    "typescript": "^4.5.4",
     "typogr": "^0.6.8",
     "vinyl": "^2.2.1",
     "vinyl-fs": "^3.0.3",

src/display/annotation_layer.js

@@ -13,6 +13,11 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./api").PDFPageProxy} PDFPageProxy */
+/** @typedef {import("./display_utils").PageViewport} PageViewport */
+/** @typedef {import("./interfaces").IDownloadManager} IDownloadManager */
+/** @typedef {import("../../web/interfaces").IPDFLinkService} IPDFLinkService */
+
 import {
   AnnotationBorderStyleType,
   AnnotationType,
@@ -39,10 +44,10 @@ const GetElementsByNameSet = new WeakSet();
  * @typedef {Object} AnnotationElementParameters
  * @property {Object} data
  * @property {HTMLDivElement} layer
- * @property {PDFPage} page
+ * @property {PDFPageProxy} page
  * @property {PageViewport} viewport
  * @property {IPDFLinkService} linkService
- * @property {DownloadManager} downloadManager
+ * @property {IDownloadManager} downloadManager
  * @property {AnnotationStorage} [annotationStorage]
  * @property {string} [imageResourcesPath] - Path for image resources, mainly
  *   for annotation icons. Include trailing slash.
@@ -1700,7 +1705,7 @@ class PopupElement {
       (!this.contentsObj?.str || this.contentsObj.str === this.richText.str)
     ) {
       XfaLayer.render({
-        xfa: this.richText.html,
+        xfaHtml: this.richText.html,
         intent: "richText",
         div: popup,
       });
@@ -2302,15 +2307,16 @@ class FileAttachmentAnnotationElement extends AnnotationElement {
  * @property {PageViewport} viewport
  * @property {HTMLDivElement} div
  * @property {Array} annotations
- * @property {PDFPage} page
+ * @property {PDFPageProxy} page
  * @property {IPDFLinkService} linkService
- * @property {DownloadManager} downloadManager
+ * @property {IDownloadManager} downloadManager
  * @property {string} [imageResourcesPath] - Path for image resources, mainly
  *   for annotation icons. Include trailing slash.
  * @property {boolean} renderForms
  * @property {boolean} [enableScripting] - Enable embedded script execution.
  * @property {boolean} [hasJSActions] - Some fields have JS actions.
  *   The default value is `false`.
+ * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap]
  */
 
 class AnnotationLayer {

src/display/api.js

@@ -1168,8 +1168,8 @@ class PDFDocumentProxy {
  *   created from `PDFDocumentProxy.getOptionalContentConfig`. If `null`,
  *   the configuration will be fetched automatically with the default visibility
  *   states set.
- * @property {Map<string, Canvas>} [annotationCanvasMap] - Map some annotation
- *   ids with canvases used to render them.
+ * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
+ *   annotation ids with canvases used to render them.
  */
 
 /**

src/display/xfa_layer.js

@@ -13,9 +13,22 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./display_utils").PageViewport} PageViewport */
+/** @typedef {import("../../web/interfaces").IPDFLinkService} IPDFLinkService */
+
 import { warn } from "../shared/util.js";
 import { XfaText } from "./xfa_text.js";
 
+/**
+ * @typedef {Object} XfaLayerParameters
+ * @property {PageViewport} viewport
+ * @property {HTMLDivElement} div
+ * @property {Object} xfaHtml
+ * @property {AnnotationStorage} [annotationStorage]
+ * @property {IPDFLinkService} linkService
+ * @property {string} [intent] - (default value is 'display').
+ */
+
 class XfaLayer {
   static setupStorage(html, id, element, storage, intent) {
     const storedData = storage.getValue(id, { value: null });
@@ -143,10 +156,15 @@ class XfaLayer {
     }
   }
 
+  /**
+   * Render the XFA layer.
+   *
+   * @param {XfaLayerParameters} parameters
+   */
   static render(parameters) {
     const storage = parameters.annotationStorage;
     const linkService = parameters.linkService;
-    const root = parameters.xfa;
+    const root = parameters.xfaHtml;
     const intent = parameters.intent || "display";
     const rootHtml = document.createElement(root.name);
     if (root.attributes) {
@@ -252,11 +270,9 @@ class XfaLayer {
   }
 
   /**
-   * Update the xfa layer.
+   * Update the XFA layer.
    *
-   * @public
    * @param {XfaLayerParameters} parameters
-   * @memberof XfaLayer
    */
   static update(parameters) {
     const transform = `matrix(${parameters.viewport.transform.join(",")})`;

test/driver.js

@@ -272,7 +272,7 @@ class Rasterize {
   static async xfaLayer(
     ctx,
     viewport,
-    xfa,
+    xfaHtml,
     fontRules,
     annotationStorage,
     isPrint
@@ -285,9 +285,9 @@ class Rasterize {
 
       // Rendering XFA layer as HTML.
       XfaLayer.render({
-        xfa,
-        div,
         viewport: viewport.clone({ dontFlip: true }),
+        div,
+        xfaHtml,
         annotationStorage,
         linkService: new SimpleLinkService(),
         intent: isPrint ? "print" : "display",
@@ -688,11 +688,11 @@ class Driver {
                   initPromise = page.getAnnotations({ intent: "display" });
                   annotationCanvasMap = new Map();
                 } else {
-                  initPromise = page.getXfa().then(function (xfa) {
+                  initPromise = page.getXfa().then(function (xfaHtml) {
                     return Rasterize.xfaLayer(
                       annotationLayerContext,
                       viewport,
-                      xfa,
+                      xfaHtml,
                       task.fontRules,
                       task.pdfDoc.annotationStorage,
                       task.renderPrint

web/annotation_layer_builder.js

@@ -13,8 +13,14 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFPageProxy} PDFPageProxy */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
+/** @typedef {import("./interfaces").IDownloadManager} IDownloadManager */
+/** @typedef {import("./interfaces").IL10n} IL10n */
 // eslint-disable-next-line max-len
 /** @typedef {import("./interfaces").IPDFAnnotationLayerFactory} IPDFAnnotationLayerFactory */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
 
 import { AnnotationLayer } from "pdfjs-lib";
 import { NullL10n } from "./l10n_utils.js";
@@ -23,20 +29,20 @@ import { SimpleLinkService } from "./pdf_link_service.js";
 /**
  * @typedef {Object} AnnotationLayerBuilderOptions
  * @property {HTMLDivElement} pageDiv
- * @property {PDFPage} pdfPage
+ * @property {PDFPageProxy} pdfPage
  * @property {AnnotationStorage} [annotationStorage]
  * @property {string} [imageResourcesPath] - Path for image resources, mainly
  *   for annotation icons. Include trailing slash.
  * @property {boolean} renderForms
  * @property {IPDFLinkService} linkService
- * @property {DownloadManager} downloadManager
+ * @property {IDownloadManager} downloadManager
  * @property {IL10n} l10n - Localization service.
  * @property {boolean} [enableScripting]
  * @property {Promise<boolean>} [hasJSActionsPromise]
  * @property {Promise<Object<string, Array<Object>> | null>}
  *   [fieldObjectsPromise]
  * @property {Object} [mouseState]
- * @property {Map<string, Canvas>} [annotationCanvasMap]
+ * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap]
  */
 
 class AnnotationLayerBuilder {
@@ -146,7 +152,7 @@ class AnnotationLayerBuilder {
 class DefaultAnnotationLayerFactory {
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage]
    * @param {string} [imageResourcesPath] - Path for image resources, mainly
    *   for annotation icons. Include trailing slash.
@@ -157,7 +163,7 @@ class DefaultAnnotationLayerFactory {
    * @param {Object} [mouseState]
    * @param {Promise<Object<string, Array<Object>> | null>}
    *   [fieldObjectsPromise]
-   * @param {Map<string, Canvas> | null} [annotationCanvasMap] - Map some
+   * @param {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
    *   annotation ids with canvases used to render them.
    * @returns {AnnotationLayerBuilder}
    */

web/base_viewer.js

@@ -13,6 +13,22 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFDocumentProxy} PDFDocumentProxy */
+/** @typedef {import("../src/display/api").PDFPageProxy} PDFPageProxy */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
+/** @typedef {import("./interfaces").IDownloadManager} IDownloadManager */
+/** @typedef {import("./interfaces").IL10n} IL10n */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFAnnotationLayerFactory} IPDFAnnotationLayerFactory */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFStructTreeLayerFactory} IPDFStructTreeLayerFactory */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFTextLayerFactory} IPDFTextLayerFactory */
+/** @typedef {import("./interfaces").IPDFXfaLayerFactory} IPDFXfaLayerFactory */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 import {
   AnnotationMode,
   createPromiseCapability,
@@ -68,7 +84,7 @@ const PagesCountLimit = {
  * @property {HTMLDivElement} [viewer] - The viewer element.
  * @property {EventBus} eventBus - The application event bus.
  * @property {IPDFLinkService} linkService - The navigation/linking service.
- * @property {DownloadManager} [downloadManager] - The download manager
+ * @property {IDownloadManager} [downloadManager] - The download manager
  *   component.
  * @property {PDFFindController} [findController] - The find controller
  *   component.
@@ -171,6 +187,11 @@ class PDFPageViewBuffer {
 
 /**
  * Simple viewer control to display PDF content/pages.
+ *
+ * @implements {IPDFAnnotationLayerFactory}
+ * @implements {IPDFStructTreeLayerFactory}
+ * @implements {IPDFTextLayerFactory}
+ * @implements {IPDFXfaLayerFactory}
  */
 class BaseViewer {
   #buffer = null;
@@ -525,7 +546,7 @@ class BaseViewer {
   }
 
   /**
-   * @param pdfDocument {PDFDocument}
+   * @param {PDFDocumentProxy} pdfDocument
    */
   setDocument(pdfDocument) {
     if (this.pdfDocument) {
@@ -1587,7 +1608,7 @@ class BaseViewer {
 
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage] - Storage for annotation
    *   data in forms.
    * @param {string} [imageResourcesPath] - Path for image resources, mainly
@@ -1599,7 +1620,7 @@ class BaseViewer {
    * @param {Object} [mouseState]
    * @param {Promise<Object<string, Array<Object>> | null>}
    *   [fieldObjectsPromise]
-   * @param {Map<string, Canvas>} [annotationCanvasMap]
+   * @param {Map<string, HTMLCanvasElement>} [annotationCanvasMap]
    * @returns {AnnotationLayerBuilder}
    */
   createAnnotationLayerBuilder(
@@ -1637,7 +1658,7 @@ class BaseViewer {
 
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage] - Storage for annotation
    *   data in forms.
    * @returns {XfaLayerBuilder}
@@ -1653,7 +1674,7 @@ class BaseViewer {
   }
 
   /**
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @returns {StructTreeLayerBuilder}
    */
   createStructTreeLayerBuilder(pdfPage) {

web/download_manager.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces").IDownloadManager} IDownloadManager */
+
 import { createObjectURL, createValidAbsoluteUrl, isPdfFile } from "pdfjs-lib";
 import { compatibilityParams } from "./app_options.js";
 
@@ -42,6 +44,9 @@ function download(blobUrl, filename) {
   a.remove();
 }
 
+/**
+ * @implements {IDownloadManager}
+ */
 class DownloadManager {
   constructor() {
     this._openBlobUrls = new WeakMap();

web/genericl10n.js

@@ -13,11 +13,16 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces").IL10n} IL10n */
+
 import "../external/webL10n/l10n.js";
 import { fixupLangCode, getL10nFallback } from "./l10n_utils.js";
 
 const webL10n = document.webL10n;
 
+/**
+ * @implements {IL10n}
+ */
 class GenericL10n {
   constructor(lang) {
     this._lang = lang;

web/interfaces.js

@@ -14,6 +14,21 @@
  */
 /* eslint-disable getter-return */
 
+/** @typedef {import("../src/display/api").PDFPageProxy} PDFPageProxy */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
+// eslint-disable-next-line max-len
+/** @typedef {import("./annotation_layer_builder").AnnotationLayerBuilder} AnnotationLayerBuilder */
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_rendering_queue").RenderingStates} RenderingStates */
+// eslint-disable-next-line max-len
+/** @typedef {import("./struct_tree_builder").StructTreeLayerBuilder} StructTreeLayerBuilder */
+/** @typedef {import("./text_highlighter").TextHighlighter} TextHighlighter */
+// eslint-disable-next-line max-len
+/** @typedef {import("./text_layer_builder").TextLayerBuilder} TextLayerBuilder */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+/** @typedef {import("./xfa_layer_builder").XfaLayerBuilder} XfaLayerBuilder */
+
 /**
  * @interface
  */
@@ -163,7 +178,7 @@ class IPDFTextLayerFactory {
 class IPDFAnnotationLayerFactory {
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage] - Storage for annotation
    *   data in forms.
    * @param {string} [imageResourcesPath] - Path for image resources, mainly
@@ -175,7 +190,7 @@ class IPDFAnnotationLayerFactory {
    * @param {Object} [mouseState]
    * @param {Promise<Object<string, Array<Object>> | null>}
    *   [fieldObjectsPromise]
-   * @property {Map<string, Canvas> | null} [annotationCanvasMap] - Map some
+   * @param {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
    *   annotation ids with canvases used to render them.
    * @returns {AnnotationLayerBuilder}
    */
@@ -200,7 +215,7 @@ class IPDFAnnotationLayerFactory {
 class IPDFXfaLayerFactory {
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage]
    * @param {Object} [xfaHtml]
    * @returns {XfaLayerBuilder}
@@ -218,12 +233,46 @@ class IPDFXfaLayerFactory {
  */
 class IPDFStructTreeLayerFactory {
   /**
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @returns {StructTreeLayerBuilder}
    */
   createStructTreeLayerBuilder(pdfPage) {}
 }
 
+/**
+ * @interface
+ */
+class IDownloadManager {
+  /**
+   * @param {string} url
+   * @param {string} filename
+   */
+  downloadUrl(url, filename) {}
+
+  /**
+   * @param {Uint8Array} data
+   * @param {string} filename
+   * @param {string} [contentType]
+   */
+  downloadData(data, filename, contentType) {}
+
+  /**
+   * @param {HTMLElement} element
+   * @param {Uint8Array} data
+   * @param {string} filename
+   * @returns {boolean} Indicating if the data was opened.
+   */
+  openOrDownloadData(element, data, filename) {}
+
+  /**
+   * @param {Blob} blob
+   * @param {string} url
+   * @param {string} filename
+   * @param {string} [sourceEventType]
+   */
+  download(blob, url, filename, sourceEventType = "download") {}
+}
+
 /**
  * @interface
  */
@@ -243,11 +292,11 @@ class IL10n {
    * property bag. If the key was not found, translation falls back to the
    * fallback text.
    * @param {string} key
-   * @param {object} args
-   * @param {string} fallback
+   * @param {Object | null} [args]
+   * @param {string} [fallback]
    * @returns {Promise<string>}
    */
-  async get(key, args, fallback) {}
+  async get(key, args = null, fallback) {}
 
   /**
    * Translates HTML element.
@@ -258,6 +307,7 @@ class IL10n {
 }
 
 export {
+  IDownloadManager,
   IL10n,
   IPDFAnnotationLayerFactory,
   IPDFLinkService,

web/pdf_find_controller.js

@@ -13,6 +13,10 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFDocumentProxy} PDFDocumentProxy */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 import { createPromiseCapability } from "pdfjs-lib";
 import { getCharacterType } from "./pdf_find_utils.js";
 import { scrollIntoView } from "./ui_utils.js";

web/pdf_history.js

@@ -13,6 +13,9 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 import {
   isValidRotation,
   parseQueryString,

web/pdf_link_service.js

@@ -14,6 +14,7 @@
  */
 
 /** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
 
 import { addLinkAttributes, LinkTarget } from "pdfjs-lib";
 import { parseQueryString } from "./ui_utils.js";

web/pdf_page_view.js

@@ -13,7 +13,22 @@
  * limitations under the License.
  */
 
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/optional_content_config").OptionalContentConfig} OptionalContentConfig */
+/** @typedef {import("./interfaces").IL10n} IL10n */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFAnnotationLayerFactory} IPDFAnnotationLayerFactory */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFStructTreeLayerFactory} IPDFStructTreeLayerFactory */
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces").IPDFTextLayerFactory} IPDFTextLayerFactory */
+/** @typedef {import("./interfaces").IL10n} IPDFXfaLayerFactory */
 /** @typedef {import("./interfaces").IRenderableView} IRenderableView */
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_rendering_queue").PDFRenderingQueue} PDFRenderingQueue */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
 
 import {
   AnnotationMode,

web/pdf_rendering_queue.js

@@ -13,6 +13,11 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces").IRenderableView} IRenderableView */
+/** @typedef {import("./pdf_viewer").PDFViewer} PDFViewer */
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_thumbnail_viewer").PDFThumbnailViewer} PDFThumbnailViewer */
+
 import { RenderingCancelledException } from "pdfjs-lib";
 
 const CLEANUP_TIMEOUT = 30000;

web/pdf_scripting_manager.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 import { createPromiseCapability, shadow } from "pdfjs-lib";
 import { apiPageLayoutToViewerModes } from "./ui_utils.js";
 import { RenderingStates } from "./pdf_rendering_queue.js";

web/pdf_thumbnail_view.js

@@ -13,6 +13,12 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces").IL10n} IL10n */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+/** @typedef {import("./interfaces").IRenderableView} IRenderableView */
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_rendering_queue").PDFRenderingQueue} PDFRenderingQueue */
+
 import { getOutputScale } from "./ui_utils.js";
 import { RenderingCancelledException } from "pdfjs-lib";
 import { RenderingStates } from "./pdf_rendering_queue.js";

web/pdf_thumbnail_viewer.js

@@ -13,6 +13,13 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFDocumentProxy} PDFDocumentProxy */
+/** @typedef {import("./interfaces").IL10n} IL10n */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_rendering_queue").PDFRenderingQueue} PDFRenderingQueue */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 import {
   getVisibleElements,
   isValidRotation,
@@ -37,8 +44,6 @@ const THUMBNAIL_SELECTED_CLASS = "selected";
 
 /**
  * Viewer control to display thumbnails for pages in a PDF document.
- *
- * @implements {IRenderableView}
  */
 class PDFThumbnailViewer {
   /**
@@ -172,6 +177,9 @@ class PDFThumbnailViewer {
     this.container.textContent = "";
   }
 
+  /**
+   * @param {PDFDocumentProxy} pdfDocument
+   */
   setDocument(pdfDocument) {
     if (this.pdfDocument) {
       this._cancelRendering();

web/struct_tree_layer_builder.js

@@ -13,6 +13,7 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFPageProxy} PDFPageProxy */
 // eslint-disable-next-line max-len
 /** @typedef {import("./interfaces").IPDFStructTreeLayerFactory} IPDFStructTreeLayerFactory */
 
@@ -76,7 +77,7 @@ const HEADING_PATTERN = /^H(\d+)$/;
 
 /**
  * @typedef {Object} StructTreeLayerBuilderOptions
- * @property {PDFPage} pdfPage
+ * @property {PDFPageProxy} pdfPage
  */
 
 class StructTreeLayerBuilder {
@@ -142,7 +143,7 @@ class StructTreeLayerBuilder {
  */
 class DefaultStructTreeLayerFactory {
   /**
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @returns {StructTreeLayerBuilder}
    */
   createStructTreeLayerBuilder(pdfPage) {

web/text_highlighter.js

@@ -13,6 +13,10 @@
  * limitations under the License.
  */
 
+// eslint-disable-next-line max-len
+/** @typedef {import("./pdf_find_controller").PDFFindController} PDFFindController */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
+
 /**
  * @typedef {Object} TextHighlighterOptions
  * @property {PDFFindController} findController

web/text_layer_builder.js

@@ -13,8 +13,12 @@
  * limitations under the License.
  */
 
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
 // eslint-disable-next-line max-len
 /** @typedef {import("./interfaces").IPDFTextLayerFactory} IPDFTextLayerFactory */
+/** @typedef {import("./text_highlighter").TextHighlighter} TextHighlighter */
+/** @typedef {import("./ui_utils").EventBus} EventBus */
 
 import { renderTextLayer } from "pdfjs-lib";
 

web/xfa_layer_builder.js

@@ -13,6 +13,10 @@
  * limitations under the License.
  */
 
+/** @typedef {import("../src/display/api").PDFPageProxy} PDFPageProxy */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
+/** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
 /** @typedef {import("./interfaces").IPDFXfaLayerFactory} IPDFXfaLayerFactory */
 
 import { SimpleLinkService } from "./pdf_link_service.js";
@@ -21,7 +25,7 @@ import { XfaLayer } from "pdfjs-lib";
 /**
  * @typedef {Object} XfaLayerBuilderOptions
  * @property {HTMLDivElement} pageDiv
- * @property {PDFPage} pdfPage
+ * @property {PDFPageProxy} pdfPage
  * @property {AnnotationStorage} [annotationStorage]
  * @property {IPDFLinkService} linkService
  * @property {Object} [xfaHtml]
@@ -31,7 +35,13 @@ class XfaLayerBuilder {
   /**
    * @param {XfaLayerBuilderOptions} options
    */
-  constructor({ pageDiv, pdfPage, annotationStorage, linkService, xfaHtml }) {
+  constructor({
+    pageDiv,
+    pdfPage,
+    annotationStorage = null,
+    linkService,
+    xfaHtml = null,
+  }) {
     this.pageDiv = pageDiv;
     this.pdfPage = pdfPage;
     this.annotationStorage = annotationStorage;
@@ -54,8 +64,7 @@ class XfaLayerBuilder {
       const parameters = {
         viewport: viewport.clone({ dontFlip: true }),
         div: this.div,
-        xfa: this.xfaHtml,
-        page: null,
+        xfaHtml: this.xfaHtml,
         annotationStorage: this.annotationStorage,
         linkService: this.linkService,
         intent,
@@ -73,16 +82,15 @@ class XfaLayerBuilder {
     // intent === "display"
     return this.pdfPage
       .getXfa()
-      .then(xfa => {
-        if (this._cancelled || !xfa) {
+      .then(xfaHtml => {
+        if (this._cancelled || !xfaHtml) {
           return { textDivs: [] };
         }
 
         const parameters = {
           viewport: viewport.clone({ dontFlip: true }),
           div: this.div,
-          xfa,
-          page: this.pdfPage,
+          xfaHtml,
           annotationStorage: this.annotationStorage,
           linkService: this.linkService,
           intent,
@@ -120,7 +128,7 @@ class XfaLayerBuilder {
 class DefaultXfaLayerFactory {
   /**
    * @param {HTMLDivElement} pageDiv
-   * @param {PDFPage} pdfPage
+   * @param {PDFPageProxy} pdfPage
    * @param {AnnotationStorage} [annotationStorage]
    * @param {Object} [xfaHtml]
    */