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.

Author: Snuffleupagus

package-lock.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",

package.json

@@ -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/annotation_layer.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/api.js

@@ -13,9 +13,23 @@
  * 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 {PDFPageProxy} [pdfPage]
+ * @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 +157,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 +271,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(",")})`;

src/display/xfa_layer.js

@@ -272,7 +272,7 @@ class Rasterize {
   static async xfaLayer(
     ctx,
     viewport,
-    xfa,
+    xfaHtml,
     fontRules,
     annotationStorage,
     isPrint
@@ -285,7 +285,7 @@ class Rasterize {
 
       // Rendering XFA layer as HTML.
       XfaLayer.render({
-        xfa,
+        xfaHtml,
         div,
         viewport: viewport.clone({ dontFlip: true }),
         annotationStorage,
@@ -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

test/driver.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(