Rollup merge of rust-lang#140314 - lolbinarycat:rustdoc-js-scrape-examples-typecheck, r=notriddle

Rustdoc: typecheck scrape-examples.js

more typechecking progress, this time we're mostly held back by the fact that `document.querySelectorAll` can't return nice types if its given a compound query (see the issue linked in a code comment).

Additionally, it seems like the generated `data-locs` attribute has fields that are never used by anything?

r? `@notriddle`

Author: jhpratt

src/librustdoc/html/static/js/rustdoc.d.ts

@@ -514,4 +514,13 @@ declare namespace rustdoc {
         options?: string[],
         default: string | boolean,
     }
+
+    /**
+     * Single element in the data-locs field of a scraped example.
+     * First field is the start and end char index,
+     * other fields seem to be unused.
+     *
+     * Generated by `render_call_locations` in `render/mod.rs`.
+     */
+    type ScrapedLoc = [[number, number], string, string]
 }

src/librustdoc/html/static/js/scrape-examples.js

@@ -1,7 +1,4 @@
-/* global addClass, hasClass, removeClass, onEachLazy */
-
-// Eventually fix this.
-// @ts-nocheck
+ /* global addClass, hasClass, removeClass, onEachLazy, nonnull */
 
 "use strict";
 
@@ -14,8 +11,16 @@
     const DEFAULT_MAX_LINES = 5;
     const HIDDEN_MAX_LINES = 10;
 
-    // Scroll code block to the given code location
+    /**
+     * Scroll code block to the given code location
+     * @param {HTMLElement} elt
+     * @param {[number, number]} loc
+     * @param {boolean} isHidden
+     */
     function scrollToLoc(elt, loc, isHidden) {
+        /** @type {HTMLElement[]} */
+        // blocked on https://github.com/microsoft/TypeScript/issues/29037
+        // @ts-expect-error
         const lines = elt.querySelectorAll("[data-nosnippet]");
         let scrollOffset;
 
@@ -35,10 +40,15 @@
             scrollOffset = offsetMid - halfHeight;
         }
 
-        lines[0].parentElement.scrollTo(0, scrollOffset);
-        elt.querySelector(".rust").scrollTo(0, scrollOffset);
+        nonnull(lines[0].parentElement).scrollTo(0, scrollOffset);
+        nonnull(elt.querySelector(".rust")).scrollTo(0, scrollOffset);
     }
 
+    /**
+     * @param {HTMLElement} parent
+     * @param {string} className
+     * @param {string} content
+     */
     function createScrapeButton(parent, className, content) {
         const button = document.createElement("button");
         button.className = className;
@@ -50,20 +60,24 @@
     window.updateScrapedExample = (example, buttonHolder) => {
         let locIndex = 0;
         const highlights = Array.prototype.slice.call(example.querySelectorAll(".highlight"));
-        const link = example.querySelector(".scraped-example-title a");
+
+        /** @type {HTMLAnchorElement} */
+        const link = nonnull(example.querySelector(".scraped-example-title a"));
         let expandButton = null;
 
         if (!example.classList.contains("expanded")) {
             expandButton = createScrapeButton(buttonHolder, "expand", "Show all");
         }
-        const isHidden = example.parentElement.classList.contains("more-scraped-examples");
+        const isHidden = nonnull(example.parentElement).classList.contains("more-scraped-examples");
 
+        // @ts-expect-error
         const locs = example.locs;
         if (locs.length > 1) {
             const next = createScrapeButton(buttonHolder, "next", "Next usage");
             const prev = createScrapeButton(buttonHolder, "prev", "Previous usage");
 
             // Toggle through list of examples in a given file
+            /** @type {function(function(): void): void} */
             const onChangeLoc = changeIndex => {
                 removeClass(highlights[locIndex], "focus");
                 changeIndex();
@@ -106,10 +120,19 @@
         }
     };
 
+    /**
+     * Initialize the `locs` field
+     *
+     * @param {HTMLElement & {locs?: rustdoc.ScrapedLoc[]}} example
+     * @param {boolean} isHidden
+     */
     function setupLoc(example, isHidden) {
-        example.locs = JSON.parse(example.attributes.getNamedItem("data-locs").textContent);
+        const locs_str = nonnull(example.attributes.getNamedItem("data-locs")).textContent;
+        const locs =
+              JSON.parse(nonnull(nonnull(locs_str)));
+        example.locs = locs;
         // Start with the first example in view
-        scrollToLoc(example, example.locs[0][0], isHidden);
+        scrollToLoc(example, locs[0][0], isHidden);
     }
 
     const firstExamples = document.querySelectorAll(".scraped-example-list > .scraped-example");