Integrated static type-checking via JSDoc and Flow

src/assets/javascripts/components/Material/Nav/Scrolling.js

@@ -31,7 +31,7 @@ export default class Scrolling {
    *
    * @constructor
    *
-   * @property {HTMLElement} el_ - Navigation
+   * @property {HTMLElement} el_ - Primary navigation
    *
    * @param {(string|HTMLElement)} el - Selector or HTML element
    */
@@ -55,7 +55,9 @@ export default class Scrolling {
     /* Find all toggles and check which one is active */
     const toggles = this.el_.querySelectorAll("[data-md-toggle]")
     Array.prototype.forEach.call(toggles, toggle => {
-      if (toggle instanceof HTMLInputElement && toggle.checked) {
+      if (!(toggle instanceof HTMLInputElement))
+        throw new ReferenceError
+      if (toggle.checked) {
 
         /* Find corresponding navigational pane */
         let pane = toggle.nextElementSibling
@@ -144,7 +146,9 @@ export default class Scrolling {
     /* Find all toggles and check which one is active */
     const toggles = this.el_.querySelectorAll("[data-md-toggle]")
     Array.prototype.forEach.call(toggles, toggle => {
-      if (toggle instanceof HTMLInputElement && toggle.checked) {
+      if (!(toggle instanceof HTMLInputElement))
+        throw new ReferenceError
+      if (toggle.checked) {
 
         /* Find corresponding navigational pane */
         let pane = toggle.nextElementSibling

src/assets/javascripts/components/Material/Search/Lock.js

@@ -31,9 +31,9 @@ export default class Lock {
    *
    * @constructor
    *
-   * @property {HTMLInputElement} el_ - TODO
-   * @property {HTMLElement} lock_ - Element to lock
-   * @property {number} offset_ - TODO
+   * @property {HTMLInputElement} el_ - Lock toggle
+   * @property {HTMLElement} lock_ - Element to lock (document body)
+   * @property {number} offset_ - Current page y-offset
    *
    * @param {(string|HTMLElement)} el - Selector or HTML element
    */

src/assets/javascripts/components/Material/Search/Result.jsx

@@ -33,14 +33,15 @@ export default class Result {
    *
    * @constructor
    *
-   * @property {HTMLElement} el_ - TODO
-   * @property {(Object|Array<Object>|Function)} data_ - TODO (very dirty)
-   * @property {*} meta_ - // TODO (must be done like this, as React$Component does not return the correct thing) (React$Element<*>|Element)
-   * @property {*} list_ - // TODO (must be done like this, as React$Component does not return the correct thing)
-   * @property {Object} index_ - TODO
+   * @property {HTMLElement} el_ - Search result container
+   * @property {(Array<Object>|Function)} data_ - Raw document data
+   * @property {Object} docs_ - Indexed documents
+   * @property {HTMLElement} meta_ - Search meta information
+   * @property {HTMLElement} list_ - Search result list
+   * @property {Object} index_ - Search index
    *
    * @param {(string|HTMLElement)} el - Selector or HTML element
-   * @param {(Array<Object>|Function)} data - Promise or array providing data     // TODO ????
+   * @param {(Array<Object>|Function)} data - Function providing data or array
    */
   constructor(el, data) {
     const ref = (typeof el === "string")
@@ -73,9 +74,9 @@ export default class Result {
    * would be better to create something more intelligent, highlighting the
    * search occurrences and making a better summary out of it
    *
-   * @param {string} string - TODO
-   * @param {number} n - TODO
-   * @return {string} TODO
+   * @param {string} string - String to be truncated
+   * @param {number} n - Number of characters
+   * @return {string} Truncated string
    */
   truncate_(string, n) {
     let i = n
@@ -107,7 +108,7 @@ export default class Result {
         })
 
         /* Index documents */
-        this.data_ = data.reduce((docs, doc) => {
+        this.docs_ = data.reduce((docs, doc) => {
           this.index_.add(doc)
           docs[doc.location] = doc
           return docs
@@ -132,10 +133,9 @@ export default class Result {
         this.list_.removeChild(this.list_.firstChild)
 
       /* Perform search on index and render documents */
-      let result = this.index_.search(target.value)
-      result += 3
+      const result = this.index_.search(target.value)
       result.forEach(item => {
-        const doc = this.data_[item.ref]
+        const doc = this.docs_[item.ref]
 
         /* Check if it's a anchor link on the current page */
         let [pathname] = doc.location.split("#")
@@ -166,7 +166,9 @@ export default class Result {
       Array.prototype.forEach.call(anchors, anchor => {
         anchor.addEventListener("click", ev2 => {
           const toggle = document.querySelector("[data-md-toggle=search]")
-          if (toggle instanceof HTMLInputElement && toggle.checked) {
+          if (!(toggle instanceof HTMLInputElement))
+            throw new ReferenceError
+          if (toggle.checked) {
             toggle.checked = false
             toggle.dispatchEvent(new CustomEvent("change"))
           }

src/assets/javascripts/components/Material/Sidebar/Position.js

@@ -31,10 +31,10 @@ export default class Position {
    *
    * @constructor
    *
-   * @property {HTMLElement} el_ - TODO
-   * @property {HTMLElement} parent_ - TODO
-   * @property {number} height_ - TODO
-   * @property {number} offset_ - TODO
+   * @property {HTMLElement} el_ - Sidebar
+   * @property {HTMLElement} parent_ - Sidebar container
+   * @property {number} height_ - Current sidebar height
+   * @property {number} offset_ - Current page y-offset
    *
    * @param {(string|HTMLElement)} el - Selector or HTML element
    */

src/assets/javascripts/components/Material/Source/Adapter/Abstract.js

@@ -29,13 +29,13 @@ import Cookies from "js-cookie"
 export default class Abstract {
 
   /**
-   * Retrieve source information
+   * Retrieve repository information
    *
    * @constructor
    *
-   * @property {HTMLAnchorElement} el_ - TODO
-   * @property {string} base_ - TODO
-   * @property {number} salt_ - TODO
+   * @property {HTMLAnchorElement} el_ - Link to repository
+   * @property {string} base_ - API base URL
+   * @property {number} salt_ - Unique identifier
    *
    * @param {(string|HTMLAnchorElement)} el - Selector or HTML element
    */
@@ -56,7 +56,7 @@ export default class Abstract {
   /**
    * Retrieve data from Cookie or fetch from respective API
    *
-   * @return {Promise<*>} Promise that returns an array of facts                  // TODO: @returns {Promise.<string, Error>}
+   * @return {Promise<Array<string>>} Promise that returns an array of facts
    */
   fetch() {
     return new Promise(resolve => {

src/assets/javascripts/components/Material/Source/Adapter/GitHub.js

@@ -29,7 +29,7 @@ import Abstract from "./Abstract"
 export default class GitHub extends Abstract {
 
   /**
-   * Retrieve source information from GitHub
+   * Retrieve repository information from GitHub
    *
    * @constructor
    * @param {(string|HTMLAnchorElement)} el - Selector or HTML element
@@ -42,9 +42,9 @@ export default class GitHub extends Abstract {
   }
 
   /**
-   * Fetch relevant source information from GitHub
+   * Fetch relevant repository information from GitHub
    *
-   * @return {Promise<*>} Promise returning an array of facts
+   * @return {Promise<Array<string>>} Promise returning an array of facts
    */
   fetch_() {
     return fetch(this.base_)

src/assets/javascripts/components/Material/Source/Repository.jsx

@@ -31,7 +31,7 @@ export default class Repository {
    *
    * @constructor
    *
-   * @property {HTMLElement} el_ - TODO
+   * @property {HTMLElement} el_ - Repository information
    *
    * @param {(string|HTMLElement)} el - Selector or HTML element
    */
@@ -45,12 +45,12 @@ export default class Repository {
   }
 
   /**
-   * Initialize the source repository
+   * Initialize the repository
    *
    * @param {Array<string>} facts - Facts to be rendered
    */
   initialize(facts) {
-    if (facts.length)
+    if (facts.length && this.el_.children.length)
       this.el_.children[this.el_.children.length - 1].appendChild(
         <ul class="md-source__facts">
           {facts.map(fact => <li class="md-source__fact">{fact}</li>)}