JavaScript clean-up and documenting

docs/js/extra.js

@@ -29,7 +29,8 @@ var nodemcu = nodemcu || {};
   }
 
   /**
-   * Adds a language selector to the RTD fly out menu found bottom left. Example
+   * Adds a language selector to the RTD fly-out menu found bottom left. Example:
+   *
    * <dl>
    *   <dt>Languages</dt>
    *   <dd><a href="http://nodemcu.readthedocs.org/en/<branch>/de/">de</a></dd>
@@ -38,28 +39,37 @@ var nodemcu = nodemcu || {};
    *   </strong>
    * </dl>
    *
-   * UGLY. That menu is added by RTD with an AJAX call after page load. Hence, we need to react to
+   * UGLY! That fly-out menu is added by RTD with an AJAX call after page load. Hence, we need to
-   * the subsequent DOM manipulation using a DOM4 MutationObserver.
+   * react to the subsequent DOM manipulation using a DOM4 MutationObserver. The provided structure
+   * is as follows:
+   *
+   * <div class="rst-other-versions">
+   *   <!-- Inserted RTD Footer -->
+   *   <div class="injected">
    */
   function addLanguageSelectorToRtdFlyOutMenu() {
-    var observer = new MutationObserver(function (mutations) {
+    var flyOutWrapper = $('.rst-other-versions');
-      // since mutation on the target node was triggered we can safely assume the inject RTD div has now been added
+    // only relevant on RTD
-      var injectedDiv = $('.rst-other-versions .injected');
+    if (flyOutWrapper.size() > 0) {
-      var selectedLanguageCode = determineSelectedLanguageCode();
+      var observer = new MutationObserver(function (mutations) {
-      var dl = document.createElement('dl');
+        // since mutation on the target node was triggered we can safely assume the injected RTD div has now been added
-      var dt = document.createElement('dt');
+        var injectedDiv = $('.rst-other-versions .injected');
-      dl.appendChild(dt);
+        var selectedLanguageCode = determineSelectedLanguageCode();
-      dt.appendChild(document.createTextNode('Languages'));
+        var dl = document.createElement('dl');
-      for (var languageCode in languageCodeToNameMap) {
+        var dt = document.createElement('dt');
-        dl.appendChild(createLanguageLinkFor(languageCode, selectedLanguageCode === languageCode));
+        dl.appendChild(dt);
-      }
+        dt.appendChild(document.createTextNode('Languages'));
-      injectedDiv.prepend(dl);
+        for (var languageCode in languageCodeToNameMap) {
-      // no need for that observer anymore
+          dl.appendChild(createLanguageLinkFor(languageCode, selectedLanguageCode === languageCode));
-      observer.disconnect();
+        }
-    });
+        injectedDiv.prepend(dl);
+        // no need for that observer anymore
+        observer.disconnect();
+      });
 
-    // observed target node is the fly-out wrapper, the only event we care about is when children are modified
+      // observed target node is the fly-out wrapper, the only event we care about is when children are modified
-    observer.observe($('.rst-other-versions')[0], {childList: true});
+      observer.observe(flyOutWrapper[0], {childList: true});
+    }
   }
   function createLanguageLinkFor(languageCode, isCurrentlySelected) {
     var strong;
@@ -79,6 +89,14 @@ var nodemcu = nodemcu || {};
     }
   }
 
+  /**
+   * Analyzes the URL of the current page to find out what the selected language is. It's usually
+   * part of the location path. The code needs to distinguish between running MkDocs standalone
+   * and docs served from RTD. If no valid language could be determined the default language is
+   * returned.
+   *
+   * @returns 2-char language code
+   */
   function determineSelectedLanguageCode() {
     var selectedLanguageCode, path = window.location.pathname;
     if (window.location.origin.indexOf('readthedocs') > -1) {