* Add documentation for settings page rendering functions.

* Improve code. * Fix some documentation argument types. * Make settings order the same as before this PR. * Change timeout to 0 so that browser will render it as fast as possible.
rust-lang · May 1, 2022 · 73688e4 · 73688e4
1 parent 2f074de
commit 73688e4
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 55 deletions.
diff --git a/src/librustdoc/html/static/js/main.js b/src/librustdoc/html/static/js/main.js
@@ -206,8 +206,8 @@ window.hideSettings = function() {
  * This function inserts `newNode` after `referenceNode`. It doesn't work if `referenceNode`
  * doesn't have a parent node.
  *
- * @param {DOM} newNode
- * @param {DOM} referenceNode
+ * @param {HTMLElement} newNode
+ * @param {HTMLElement} referenceNode
  */
 function insertAfter(newNode, referenceNode) {
     referenceNode.parentNode.insertBefore(newNode, referenceNode.nextSibling);
@@ -237,7 +237,7 @@ function getOrCreateSection(id, classes) {
 /**
  * Returns the `<section>` element which contains the displayed element.
  *
- * @return {DOM}
+ * @return {HTMLElement}
  */
 function getAlternativeDisplayElem() {
     return getOrCreateSection(ALTERNATIVE_DISPLAY_ID, "content hidden");
@@ -246,7 +246,7 @@ function getAlternativeDisplayElem() {
 /**
  * Returns the `<section>` element which contains the not-displayed elements.
  *
- * @return {DOM}
+ * @return {HTMLElement}
  */
 function getNotDisplayedElem() {
     return getOrCreateSection(NOT_DISPLAYED_ID, "hidden");
@@ -255,11 +255,11 @@ function getNotDisplayedElem() {
 /**
  * To nicely switch between displayed "extra" elements (such as search results or settings menu)
  * and to alternate between the displayed and not displayed elements, we hold them in two different
- * `<section>` elements. They work in pair: one hold the not displayed elements while the other
+ * `<section>` elements. They work in pair: one holds the hidden elements while the other
  * contains the displayed element (there can be only one at the same time!). So basically, we switch
  * elements between the two `<section>` elements.
  *
- * @param {DOM} elemToDisplay
+ * @param {HTMLElement} elemToDisplay
  */
 function switchDisplayedElement(elemToDisplay) {
     const el = getAlternativeDisplayElem();

diff --git a/src/librustdoc/html/static/js/settings.js b/src/librustdoc/html/static/js/settings.js
@@ -96,10 +96,19 @@
         });
     }
 
-    function buildSettings(settings) {
+    /**
+     * This function builds the sections inside the "settings page". It takes a `settings` list
+     * as argument which describes each setting and how to render it. It returns a string
+     * representing the raw HTML.
+     *
+     * @param {Array<Object>} settings
+     *
+     * @return {string}
+     */
+    function buildSettingsPageSections(settings) {
         let output = "";
 
-        onEach(settings, function(setting) {
+        for (const setting of settings) {
             output += `<div class="setting-line">`;
             const js_data_name = setting["js_name"];
             const setting_name = setting["name"];
@@ -130,47 +139,16 @@
                     <div>${setting_name}</div>`;
             }
             output += "</div>";
-        });
-        return output;
-    }
-
-    function buildSettingsPage(settings) {
-        // First, we add the settings.css file.
-        loadCss("settings");
-
-        // Then we build the DOM.
-        const el = document.createElement("section");
-        el.id = "settings";
-        let innerHTML = `
-            <div class="main-heading">
-                <h1 class="fqn">
-                    <span class="in-band">Rustdoc settings</span>
-                </h1>
-                <span class="out-of-band">`;
-
-        if (isSettingsPage) {
-            innerHTML +=
-                `<a id="back" href="javascript:void(0)" onclick="history.back();">Back</a>`;
-        } else {
-            innerHTML +=
-                `<a id="back" href="javascript:void(0)" onclick="switchDisplayedElement(null);">\
-                    Back</a>`;
-        }
-        innerHTML += `</span>
-            </div>
-            <div class="settings">${buildSettings(settings)}</div>`;
-
-        el.innerHTML = innerHTML;
-
-        if (isSettingsPage) {
-            document.getElementById(MAIN_ID).appendChild(el);
-        } else {
-            getNotDisplayedElem().appendChild(el);
         }
-        return el;
+        return output;
     }
 
-    function createSettingsPage() {
+    /**
+     * This function builds the "settings page" and returns the generated HTML element.
+     *
+     * @return {HTMLElement}
+     */
+    function buildSettingsPage() {
         const themes = getVar("themes").split(",");
         const settings = [
             {
@@ -184,18 +162,18 @@
                 "default": "light",
                 "options": themes,
             },
-            {
-                "name": "Preferred dark theme",
-                "js_name": "preferred-dark-theme",
-                "default": "dark",
-                "options": themes,
-            },
             {
                 "name": "Preferred light theme",
                 "js_name": "preferred-light-theme",
                 "default": "light",
                 "options": themes,
             },
+            {
+                "name": "Preferred dark theme",
+                "js_name": "preferred-dark-theme",
+                "default": "dark",
+                "options": themes,
+            },
             {
                 "name": "Auto-hide item contents for large items",
                 "js_name": "auto-hide-large-items",
@@ -228,10 +206,42 @@
             },
         ];
 
-        return buildSettingsPage(settings);
+        // First, we add the settings.css file.
+        loadCss("settings");
+
+        // Then we build the DOM.
+        const el = document.createElement("section");
+        el.id = "settings";
+        let innerHTML = `
+            <div class="main-heading">
+                <h1 class="fqn">
+                    <span class="in-band">Rustdoc settings</span>
+                </h1>
+                <span class="out-of-band">`;
+
+        if (isSettingsPage) {
+            innerHTML +=
+                `<a id="back" href="javascript:void(0)" onclick="history.back();">Back</a>`;
+        } else {
+            innerHTML +=
+                `<a id="back" href="javascript:void(0)" onclick="switchDisplayedElement(null);">\
+                    Back</a>`;
+        }
+        innerHTML += `</span>
+            </div>
+            <div class="settings">${buildSettingsPageSections(settings)}</div>`;
+
+        el.innerHTML = innerHTML;
+
+        if (isSettingsPage) {
+            document.getElementById(MAIN_ID).appendChild(el);
+        } else {
+            getNotDisplayedElem().appendChild(el);
+        }
+        return el;
     }
 
-    const settingsMenu = createSettingsPage();
+    const settingsMenu = buildSettingsPage();
 
     if (isSettingsPage) {
         // We replace the existing "onclick" callback to do nothing if clicked.
@@ -261,5 +271,5 @@
         if (!isSettingsPage) {
             switchDisplayedElement(settingsMenu);
         }
-    }, 10);
+    }, 0);
 })();