From d78e7628d1376d1fe1feaff4079f590ba305aac9 Mon Sep 17 00:00:00 2001 From: binarycat Date: Fri, 25 Apr 2025 15:26:52 -0500 Subject: [PATCH 1/6] scrape-examples.js: give each function a signature --- .../html/static/js/scrape-examples.js | 33 ++++++++++++++----- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index d641405c87532..7ffa5d5b42a7d 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/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,7 +11,12 @@ 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) { const lines = elt.querySelectorAll("[data-nosnippet]"); let scrollOffset; @@ -35,10 +37,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,14 +57,15 @@ window.updateScrapedExample = (example, buttonHolder) => { let locIndex = 0; const highlights = Array.prototype.slice.call(example.querySelectorAll(".highlight")); - const link = example.querySelector(".scraped-example-title a"); + 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"); @@ -106,7 +114,14 @@ } }; + /** + * Intitialize the `locs` field + * + * @param {HTMLElement} example + * @param {boolean} isHidden + */ function setupLoc(example, isHidden) { + // @ts-expect-error example.locs = JSON.parse(example.attributes.getNamedItem("data-locs").textContent); // Start with the first example in view scrollToLoc(example, example.locs[0][0], isHidden); From b4c77e12408a3ae05ef6779eff0d8af3613716e4 Mon Sep 17 00:00:00 2001 From: binarycat Date: Fri, 25 Apr 2025 16:16:18 -0500 Subject: [PATCH 2/6] rustdoc js: add ScrapedLoc type --- src/librustdoc/html/static/js/rustdoc.d.ts | 7 +++++++ src/librustdoc/html/static/js/scrape-examples.js | 13 +++++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/src/librustdoc/html/static/js/rustdoc.d.ts b/src/librustdoc/html/static/js/rustdoc.d.ts index 0d2e19e019f34..a10f724149204 100644 --- a/src/librustdoc/html/static/js/rustdoc.d.ts +++ b/src/librustdoc/html/static/js/rustdoc.d.ts @@ -491,4 +491,11 @@ 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. + */ + type ScrapedLoc = [[number, number], string, string] } diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index 7ffa5d5b42a7d..32642799d8871 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/src/librustdoc/html/static/js/scrape-examples.js @@ -18,6 +18,9 @@ * @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; @@ -57,6 +60,8 @@ window.updateScrapedExample = (example, buttonHolder) => { let locIndex = 0; const highlights = Array.prototype.slice.call(example.querySelectorAll(".highlight")); + + /** @type {HTMLAnchorElement} */ const link = nonnull(example.querySelector(".scraped-example-title a")); let expandButton = null; @@ -72,6 +77,7 @@ 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(); @@ -117,14 +123,13 @@ /** * Intitialize the `locs` field * - * @param {HTMLElement} example + * @param {HTMLElement & {locs?: rustdoc.ScrapedLoc[]}} example * @param {boolean} isHidden */ function setupLoc(example, isHidden) { - // @ts-expect-error - example.locs = JSON.parse(example.attributes.getNamedItem("data-locs").textContent); + const locs = example.locs = JSON.parse(nonnull(nonnull(example.attributes.getNamedItem("data-locs")).textContent)); // 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"); From 35ba7dd217f3a1af420189927205d89cc2c02718 Mon Sep 17 00:00:00 2001 From: binarycat Date: Fri, 25 Apr 2025 16:28:50 -0500 Subject: [PATCH 3/6] rustdoc js: add rustdoc.ScrapedLoc type --- src/librustdoc/html/static/js/rustdoc.d.ts | 2 ++ src/librustdoc/html/static/js/scrape-examples.js | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/librustdoc/html/static/js/rustdoc.d.ts b/src/librustdoc/html/static/js/rustdoc.d.ts index a10f724149204..2c0d47447c0b5 100644 --- a/src/librustdoc/html/static/js/rustdoc.d.ts +++ b/src/librustdoc/html/static/js/rustdoc.d.ts @@ -496,6 +496,8 @@ declare namespace rustdoc { * 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] } diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index 32642799d8871..5dab4cc015612 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/src/librustdoc/html/static/js/scrape-examples.js @@ -127,7 +127,9 @@ * @param {boolean} isHidden */ function setupLoc(example, isHidden) { - const locs = example.locs = JSON.parse(nonnull(nonnull(example.attributes.getNamedItem("data-locs")).textContent)); + const locs_str = example.attributes.getNamedItem("data-locs")).textContent; + const locs = example.locs = + JSON.parse(nonnull(nonnull(locs_str)); // Start with the first example in view scrollToLoc(example, locs[0][0], isHidden); } From 8799d3dd97e38af3e31a2e76369d647e01b8a423 Mon Sep 17 00:00:00 2001 From: binarycat Date: Mon, 28 Apr 2025 18:44:46 -0500 Subject: [PATCH 4/6] fix typo --- src/librustdoc/html/static/js/scrape-examples.js | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index 5dab4cc015612..7a231dc3b7741 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/src/librustdoc/html/static/js/scrape-examples.js @@ -1,4 +1,4 @@ -/* global addClass, hasClass, removeClass, onEachLazy, nonnull */ + /* global addClass, hasClass, removeClass, onEachLazy, nonnull */ "use strict"; @@ -127,9 +127,10 @@ * @param {boolean} isHidden */ function setupLoc(example, isHidden) { - const locs_str = example.attributes.getNamedItem("data-locs")).textContent; - const locs = example.locs = - JSON.parse(nonnull(nonnull(locs_str)); + const locs_str = 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, locs[0][0], isHidden); } From b06113dc5cd6fbb2cc63918f9e861929537f41fd Mon Sep 17 00:00:00 2001 From: binarycat Date: Thu, 22 May 2025 16:14:15 -0500 Subject: [PATCH 5/6] scrape-examples.js: add another nonnull() invokation --- src/librustdoc/html/static/js/scrape-examples.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index 7a231dc3b7741..ec472666ce166 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/src/librustdoc/html/static/js/scrape-examples.js @@ -127,7 +127,7 @@ * @param {boolean} isHidden */ function setupLoc(example, isHidden) { - const locs_str = 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; From c021e7a9d2818e7d9f71bd38124d4e2c212007d6 Mon Sep 17 00:00:00 2001 From: lolbinarycat Date: Tue, 27 May 2025 12:50:14 -0500 Subject: [PATCH 6/6] scrape-examples.js: fix typos Co-authored-by: Guillaume Gomez --- src/librustdoc/html/static/js/rustdoc.d.ts | 2 +- src/librustdoc/html/static/js/scrape-examples.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/html/static/js/rustdoc.d.ts b/src/librustdoc/html/static/js/rustdoc.d.ts index 2c0d47447c0b5..686d77abde514 100644 --- a/src/librustdoc/html/static/js/rustdoc.d.ts +++ b/src/librustdoc/html/static/js/rustdoc.d.ts @@ -497,7 +497,7 @@ declare namespace rustdoc { * First field is the start and end char index, * other fields seem to be unused. * - * generated by `render_call_locations` in `render/mod.rs`. + * Generated by `render_call_locations` in `render/mod.rs`. */ type ScrapedLoc = [[number, number], string, string] } diff --git a/src/librustdoc/html/static/js/scrape-examples.js b/src/librustdoc/html/static/js/scrape-examples.js index ec472666ce166..eeab591bcd807 100644 --- a/src/librustdoc/html/static/js/scrape-examples.js +++ b/src/librustdoc/html/static/js/scrape-examples.js @@ -121,7 +121,7 @@ }; /** - * Intitialize the `locs` field + * Initialize the `locs` field * * @param {HTMLElement & {locs?: rustdoc.ScrapedLoc[]}} example * @param {boolean} isHidden