rustdoc js: add nonnull helper and typecheck src-script.js

Author: lolbinarycat

src/librustdoc/html/static/js/main.js

@@ -11,6 +11,26 @@
 window.RUSTDOC_TOOLTIP_HOVER_MS = 300;
 window.RUSTDOC_TOOLTIP_HOVER_EXIT_MS = 450;
 
+/**
+ * Assert that the passed value is nonnull, then return it.
+ *
+ * Takes an optional error message argument.
+ *
+ * @template T
+ * @param {T|null} x
+ * @param {string=} msg
+ * @returns T
+ */
+// used in other files, not yet used in this one.
+// eslint-disable-next-line no-unused-vars
+function nonnull(x, msg) {
+    if (x === null) {
+        throw (msg || "unexpected null value!");
+    } else {
+        return x;
+    }
+}
+
 /**
  * Given a basename (e.g. "storage") and an extension (e.g. ".js"), return a URL
  * for a resource under the root-path, with the resource-suffix.

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

@@ -4,6 +4,10 @@
 
 /* eslint-disable */
 declare global {
+    /** Map from crate name to directory structure, for source view */
+    declare var srcIndex: Map<string, rustdoc.Dir>;
+    /** Defined and documented in `main.js` */
+    declare function nonnull(x: T|null, msg: string|undefined);
     interface Window {
         /** Make the current theme easy to find */
         currentTheme: HTMLLinkElement|null;
@@ -40,6 +44,23 @@ declare global {
          * or if this is a docs page, this function does nothing.
          */
         rustdocShowSourceSidebar: function(),
+        /**
+         * Close the sidebar in source code view
+         */
+        rustdocCloseSourceSidebar?: function(),
+        /**
+         * Shows the sidebar in source code view
+         */
+        rustdocShowSourceSidebar?: function(),
+        /**
+         * Toggles the sidebar in source code view
+         */
+        rustdocToggleSrcSidebar?: function(),
+        /**
+         * create's the sidebar in source code view.
+         * called in generated `src-files.js`.
+         */
+        createSrcSidebar?: function(),
         /**
          * Set up event listeners for a scraped source example.
          */
@@ -438,4 +459,12 @@ declare namespace rustdoc {
     type TypeImpls = {
         [cratename: string]: Array<Array<string|0>>
     }
+
+    /**
+     * Directory structure for source code view,
+     * defined in generated `src-files.js`.
+     *
+     * is a tuple of (filename, subdirs, filenames).
+     */
+    type Dir = [string, rustdoc.Dir[], string[]]
 }

src/librustdoc/html/static/js/src-script.js

@@ -3,10 +3,8 @@
 
 // Local js definitions:
 /* global addClass, onEachLazy, removeClass, browserSupportsHistoryApi */
-/* global updateLocalStorage, getVar */
+/* global updateLocalStorage, getVar, nonnull */
 
-// Eventually fix this.
-// @ts-nocheck
 
 "use strict";
 
@@ -29,6 +27,14 @@ function closeSidebarIfMobile() {
     }
 }
 
+/**
+ * @param {rustdoc.Dir} elem
+ * @param {HTMLElement} parent
+ * @param {string} fullPath
+ * @param {boolean} hasFoundFile
+ *
+ * @returns {boolean} - new value for hasFoundFile
+ */
 function createDirEntry(elem, parent, fullPath, hasFoundFile) {
     const dirEntry = document.createElement("details");
     const summary = document.createElement("summary");
@@ -95,7 +101,7 @@ window.rustdocToggleSrcSidebar = () => {
 // This function is called from "src-files.js", generated in `html/render/write_shared.rs`.
 // eslint-disable-next-line no-unused-vars
 function createSrcSidebar() {
-    const container = document.querySelector("nav.sidebar");
+    const container = nonnull(document.querySelector("nav.sidebar"));
 
     const sidebar = document.createElement("div");
     sidebar.id = "src-sidebar";
@@ -111,6 +117,7 @@ function createSrcSidebar() {
     // Focus on the current file in the source files sidebar.
     const selected_elem = sidebar.getElementsByClassName("selected")[0];
     if (typeof selected_elem !== "undefined") {
+        // @ts-expect-error
         selected_elem.focus();
     }
 }
@@ -130,19 +137,20 @@ function highlightSrcLines() {
         to = from;
         from = tmp;
     }
-    let elem = document.getElementById(from);
+    const from_s = "" + from;
+    let elem = document.getElementById(from_s);
     if (!elem) {
         return;
     }
-    const x = document.getElementById(from);
+    const x = document.getElementById(from_s);
     if (x) {
         x.scrollIntoView();
     }
     onEachLazy(document.querySelectorAll("a[data-nosnippet]"), e => {
         removeClass(e, "line-highlighted");
     });
     for (let i = from; i <= to; ++i) {
-        elem = document.getElementById(i);
+        elem = document.getElementById("" + i);
         if (!elem) {
             break;
         }
@@ -153,11 +161,12 @@ function highlightSrcLines() {
 const handleSrcHighlight = (function() {
     let prev_line_id = 0;
 
+    /** @type {function(string): void} */
     const set_fragment = name => {
         const x = window.scrollX,
             y = window.scrollY;
         if (browserSupportsHistoryApi()) {
-            history.replaceState(null, null, "#" + name);
+            history.replaceState(null, "", "#" + name);
             highlightSrcLines();
         } else {
             location.replace("#" + name);
@@ -166,6 +175,7 @@ const handleSrcHighlight = (function() {
         window.scrollTo(x, y);
     };
 
+    // @ts-expect-error
     return ev => {
         let cur_line_id = parseInt(ev.target.id, 10);
         // This event handler is attached to the entire line number column, but it should only
@@ -191,7 +201,7 @@ const handleSrcHighlight = (function() {
         } else {
             prev_line_id = cur_line_id;
 
-            set_fragment(cur_line_id);
+            set_fragment("" + cur_line_id);
         }
     };
 }());