Adds missing jsdoc and adds lint rule require-jsdoc to build process (#3354)

* Change lint rules

* Get eslint passing with require-jsdoc

.eslintrc

@@ -19,6 +19,16 @@
     "no-unreachable": 1,
     "no-useless-escape": 0,
     "no-console": 0,
+    "require-jsdoc": ["error", {
+        "require": {
+            "FunctionDeclaration": true,
+            "MethodDefinition": false,
+            "ClassDeclaration": false,
+            "ArrowFunctionExpression": false
+        }
+
+    }],
+    //    "valid-jsdoc": 2
     // To flag presence of console.log without breaking linting:
     //"no-console": ["warn", { allow: ["warn", "error"] }],
   }

lib/DataSet.js

@@ -42,8 +42,8 @@ var Queue = require('./Queue');
  *                                              - {number} delay  Delay in ms, null by default
  *                                              - {number} max    Maximum number of entries in the queue, Infinity by default
  * @constructor DataSet
+ * // TODO: add a DataSet constructor DataSet(data, options)
  */
-// TODO: add a DataSet constructor DataSet(data, options)
 function DataSet (data, options) {
   // correctly read optional arguments
   if (data && !Array.isArray(data)) {

lib/graph3d/Graph3d.js

@@ -2007,6 +2007,11 @@ Graph3d.prototype._insideTriangle = function (point, triangle) {
     b = triangle[1],
     c = triangle[2];
 
+  /**
+   *
+   * @param {Number} x
+   * @returns {Number}
+   */
   function sign (x) {
     return x > 0 ? 1 : x < 0 ? -1 : 0;
   }

lib/graph3d/Settings.js

@@ -230,7 +230,11 @@ function setDefaults(src, dst) {
   dst.eye = new Point3d(0, 0, -1);  // TODO: set eye.z about 3/4 of the width of the window?
 }
 
-
+/**
+ *
+ * @param options {Object}
+ * @param dst
+ */
 function setOptions(options, dst) {
   if (options === undefined) {
     return;
@@ -342,7 +346,11 @@ function checkStyleNumber(style) {
   return valid;
 }
 
-
+/**
+ *
+ * @param {String | Number} style
+ * @param dst
+ */
 function setStyle(style, dst) {
   if (style === undefined) {
     return;   // Nothing to do
@@ -398,7 +406,11 @@ function setBackgroundColor(backgroundColor, dst) {
   dst.frame.style.borderStyle = 'solid';
 }
 
-
+/**
+ *
+ * @param {String | Object} dataColor
+ * @param dst
+ */
 function setDataColor(dataColor, dst) {
   if (dataColor === undefined) {
     return;    // Nothing to do
@@ -425,7 +437,11 @@ function setDataColor(dataColor, dst) {
   }
 }
 
-
+/**
+ *
+ * @param {Object} cameraPosition
+ * @param dst
+ */
 function setCameraPosition(cameraPosition, dst) {
   var camPos = cameraPosition;
   if (camPos === undefined) {

lib/module/uuid.js

@@ -1,3 +1,5 @@
+/* eslint-disable require-jsdoc */
+
 var _rng;
 
 var globalVar = typeof window !== 'undefined'

lib/network/dotparser.js

@@ -109,12 +109,12 @@ function nextPreview() {
   return dot.charAt(index + 1);
 }
 
+var regexAlphaNumeric = /[a-zA-Z_0-9.:#]/;
 /**
  * Test whether given character is alphabetic or numeric
  * @param {String} c
  * @return {Boolean} isAlphaNumeric
  */
-var regexAlphaNumeric = /[a-zA-Z_0-9.:#]/;
 function isAlphaNumeric(c) {
   return regexAlphaNumeric.test(c);
 }

lib/network/gephiParser.js

@@ -1,4 +1,9 @@
-
+/**
+ *
+ * @param {json} gephiJSON
+ * @param {obj} optionsObj
+ * @returns {{nodes: Array, edges: Array}}
+ */
 function parseGephi(gephiJSON, optionsObj) {
   var edges = [];
   var nodes = [];

lib/timeline/Core.js

@@ -164,6 +164,10 @@ Core.prototype._create = function (container) {
     me.emit('release', event);
   }.bind(this));
 
+  /**
+   *
+   * @param {WheelEvent} event
+   */
   function onMouseWheel(event) {
     if (this.isActive()) {
       this.emit('mousewheel', event);
@@ -222,7 +226,7 @@ Core.prototype._create = function (container) {
         animation: false,
         byUser: true,
         event: event
-      }
+      };
       this.range.setRange(newStart, newEnd, options);
     }
   }
@@ -237,6 +241,10 @@ Core.prototype._create = function (container) {
     this.dom.centerContainer.attachEvent("onmousewheel", onMouseWheel.bind(this));
   }
 
+  /**
+   *
+   * @param {scroll} event
+   */
   function onMouseScrollSide(event) {
     if (!me.options.verticalScroll) return;
     event.preventDefault();
@@ -253,6 +261,11 @@ Core.prototype._create = function (container) {
 
   var itemAddedToTimeline = false;
 
+  /**
+   *
+   * @param {dragover} event
+   * @returns {boolean}
+   */
   function handleDragOver(event) {
     if (event.preventDefault) {
       event.preventDefault(); // Necessary. Allows us to drop.
@@ -269,6 +282,11 @@ Core.prototype._create = function (container) {
     return false;
   }
 
+  /**
+   *
+   * @param {drop} event
+   * @returns {boolean}
+   */
   function handleDrop(event) {
     // prevent redirect to blank page - Firefox
     if(event.preventDefault) { event.preventDefault(); }
@@ -1035,7 +1053,7 @@ Core.prototype._setDOM = function () {
   dom.center.style.left               = '0';
   dom.left.style.left                 = '0';
   dom.right.style.left                = '0';
-}
+};
 
 // TODO: deprecated since version 1.1.0, remove some day
 Core.prototype.repaint = function () {

lib/timeline/Range.js

@@ -129,7 +129,9 @@ function validateDirection (direction) {
 Range.prototype.startRolling = function() {
   var me = this;
 
-
+  /**
+   *  Updates the current time.
+   */
   function update () {
     me.stopRolling();
     me.rolling = true;

lib/timeline/TimeStep.js

@@ -613,10 +613,20 @@ TimeStep.prototype.getClassName = function() {
   var step = this.step;
   var classNames = [];
 
+  /**
+   *
+   * @param {Number} value
+   * @returns {String}
+   */
   function even(value) {
     return (value / step % 2 == 0) ? ' vis-even' : ' vis-odd';
   }
 
+  /**
+   *
+   * @param {Date} date
+   * @returns {String}
+   */
   function today(date) {
     if (date.isSame(new Date(), 'day')) {
       return ' vis-today';
@@ -630,14 +640,29 @@ TimeStep.prototype.getClassName = function() {
     return '';
   }
 
+  /**
+   *
+   * @param {Date} date
+   * @returns {String}
+   */
   function currentWeek(date) {
     return date.isSame(new Date(), 'week') ? ' vis-current-week' : '';
   }
 
+  /**
+   *
+   * @param {Date} date
+   * @returns {String}
+   */
   function currentMonth(date) {
     return date.isSame(new Date(), 'month') ? ' vis-current-month' : '';
   }
 
+  /**
+   *
+   * @param {Date} date
+   * @returns {String}
+   */
   function currentYear(date) {
     return date.isSame(new Date(), 'year') ? ' vis-current-year' : '';
   }

lib/timeline/Timeline.js

@@ -429,11 +429,20 @@ Timeline.prototype.fit = function (options) {
   }
 };
 
-
+/**
+ *
+ * @param {vis.Item} item
+ * @returns {Number}
+ */
 function getStart(item) {
   return util.convert(item.data.start, 'Date').valueOf()
 }
 
+/**
+ *
+ * @param {vis.Item} item
+ * @returns {Number}
+ */
 function getEnd(item) {
   var end = item.data.end != undefined ? item.data.end : item.data.start;
   return util.convert(end, 'Date').valueOf();

lib/timeline/component/CurrentTime.js

@@ -124,7 +124,10 @@ CurrentTime.prototype.redraw = function() {
 CurrentTime.prototype.start = function() {
   var me = this;
 
-  function update () {
+    /**
+     *  Updates the current time.
+     */
+    function update () {
     me.stop();
 
     // determine interval to refresh

lib/timeline/component/CustomTime.js

@@ -14,7 +14,6 @@ var locales = require('../locales');
  * @constructor CustomTime
  * @extends Component
  */
-
 function CustomTime (body, options) {
   this.body = body;
 
@@ -78,6 +77,10 @@ CustomTime.prototype._create = function() {
   drag.style.height = '100%';
   drag.style.width = '20px';
 
+  /**
+   *
+   * @param {WheelEvent} e
+   */
   function onMouseWheel (e) {
     this.body.range._onMouseWheel(e);
   }

lib/timeline/component/DataScale.js

@@ -1,4 +1,15 @@
-
+/**
+ *
+ * @param {number} start
+ * @param {number} end
+ * @param {boolean} autoScaleStart
+ * @param {boolean} autoScaleEnd
+ * @param {number} containerHeight
+ * @param {number} majorCharHeight
+ * @param {boolean} zeroAlign
+ * @param {function} formattingFunction
+ * @constructor
+ */
 function DataScale(start, end, autoScaleStart, autoScaleEnd, containerHeight, majorCharHeight, zeroAlign = false, formattingFunction=false) {
   this.majorSteps = [1, 2, 5, 10];
   this.minorSteps = [0.25, 0.5, 1, 2];

lib/timeline/component/graph2d_types/bar.js

@@ -1,6 +1,12 @@
 var DOMutil = require('../../../DOMutil');
 var Points = require('./points');
 
+/**
+ *
+ * @param {vis.Group.id} groupId
+ * @param {Object} options   // TODO: Describe options
+ * @constructor
+ */
 function Bargraph(groupId, options) {  // eslint-disable-line no-unused-vars
 }
 

lib/timeline/component/graph2d_types/line.js

@@ -1,5 +1,11 @@
 var DOMutil = require('../../../DOMutil');
 
+/**
+ *
+ * @param {Number | String} groupId
+ * @param {Object} options   // TODO: Describe options
+ * @constructor
+ */
 function Line(groupId, options) {  // eslint-disable-line no-unused-vars
 }
 
@@ -18,7 +24,7 @@ Line.calcPath = function (dataset, group) {
             return d;
         }
     }
-}
+};
 
 Line.drawIcon = function (group, x, y, iconWidth, iconHeight, framework) {
     var fillHeight = iconHeight * 0.5;

lib/timeline/component/graph2d_types/points.js

@@ -1,5 +1,12 @@
 var DOMutil = require('../../../DOMutil');
 
+/**
+ *
+ * @param {Number | String} groupId
+ * @param {Object} options   // TODO: Describe options
+ *
+ * @constructor
+ */
 function Points(groupId, options) {  // eslint-disable-line no-unused-vars
 }
 
@@ -43,6 +50,12 @@ Points.drawIcon = function (group, x, y, iconWidth, iconHeight, framework) {
   DOMutil.drawPoint(x + 0.5 * iconWidth, y, getGroupTemplate(group), framework.svgElements, framework.svg);
 };
 
+/**
+ *
+ * @param {vis.Group} group
+ * @param {any} callbackResult
+ * @returns {{style: *, styles: (*|string), size: *, className: *}}
+ */
 function getGroupTemplate(group, callbackResult) {
   callbackResult = (typeof callbackResult === 'undefined') ? {} : callbackResult;
   return {
@@ -53,6 +66,12 @@ function getGroupTemplate(group, callbackResult) {
   };
 }
 
+/**
+ *
+ * @param {Object} framework            | SVG DOM element
+ * @param {vis.Group} group
+ * @returns {function}
+ */
 function getCallback(framework, group) {
   var callback = undefined;
   // check for the graph2d onRender
@@ -67,5 +86,4 @@ function getCallback(framework, group) {
   return callback;
 }
 
-
-module.exports = Points;
+module.exports = Points;

lib/timeline/component/item/BackgroundItem.js

@@ -11,8 +11,8 @@ var RangeItem = require('./RangeItem');
  *                                  Conversion functions from time to screen and vice versa
  * @param {Object} [options]        Configuration options
  *                                  // TODO: describe options
+ * // TODO: implement support for the BackgroundItem just having a start, then being displayed as a sort of an annotation
  */
-// TODO: implement support for the BackgroundItem just having a start, then being displayed as a sort of an annotation
 function BackgroundItem (data, conversion, options) {
   this.props = {
     content: {

lib/util.js

@@ -1583,6 +1583,7 @@ exports.getScrollBarWidth = function () {
   return (w1 - w2);
 };
 
+
 exports.topMost = function (pile, accessors) {
   let candidate;
   if (!Array.isArray(accessors)) {