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.

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,8 +163,8 @@ class DefaultAnnotationLayerFactory {
    * @param {Object} [mouseState]
    * @param {Promise<Object<string, Array<Object>> | null>}
    *   [fieldObjectsPromise]
-   * @param {Map<string, Canvas> | null} [annotationCanvasMap] - Map some
-   *  annotation ids with canvases used to render them.
+   * @param {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
+   *   annotation ids with canvases used to render them.
    * @returns {AnnotationLayerBuilder}
    */
   createAnnotationLayerBuilder(

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,8 +190,8 @@ class IPDFAnnotationLayerFactory {
    * @param {Object} [mouseState]
    * @param {Promise<Object<string, Array<Object>> | null>}
    *   [fieldObjectsPromise]
-   * @property {Map<string, Canvas> | null} [annotationCanvasMap] - Map some
-   *  annotation ids with canvases used to render them.
+   * @param {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
+   *   annotation ids with canvases used to render them.
    * @returns {AnnotationLayerBuilder}
    */
   createAnnotationLayerBuilder(
@@ -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]
    */