Tightens up jsdoc lint rules on timeline (almende#3362)

* Tightens up jsdoc lint rules on timeline

* Adds missing options param

lib/timeline/.eslintrc

@@ -0,0 +1,39 @@
+{
+  "env": {
+    "browser": true,
+    "es6": true,
+    "node": true,
+    "mocha": true
+  },
+
+  "parserOptions": {
+    "sourceType": "module",
+  },
+
+  "extends": "eslint:recommended",
+
+  // For the full list of rules, see: http://eslint.org/docs/rules/
+  "rules": {
+    "complexity": [2, 55],
+    "max-statements": [2, 115],
+    "no-unreachable": 1,
+    "no-useless-escape": 0,
+    "no-console": 0,
+    "require-jsdoc": ["error", {
+        "require": {
+            "FunctionDeclaration": true,
+            "MethodDefinition": true,
+            "ClassDeclaration": true,
+            "ArrowFunctionExpression": true
+        }
+    }],
+    "valid-jsdoc": [2, {
+      "requireReturnDescription": false,
+      "requireReturn": false,
+      "requireParamDescription": false,
+      "requireReturnType": true
+      }],
+    }
+    // To flag presence of console.log without breaking linting:
+    //"no-console": ["warn", { allow: ["warn", "error"] }],
+}

lib/timeline/DateUtil.js

@@ -5,6 +5,7 @@
  * @param {function} moment
  * @param {Object} body
  * @param {Array | Object} hiddenDates
+ * @returns {Number}
  */
 exports.convertHiddenOptions = function(moment, body, hiddenDates) {
   if (hiddenDates && !Array.isArray(hiddenDates)) {
@@ -32,9 +33,11 @@ exports.convertHiddenOptions = function(moment, body, hiddenDates) {
 
 /**
  * create new entrees for the repeating hidden dates
+ *
  * @param {function} moment
  * @param {Object} body
  * @param {Array | Object} hiddenDates
+ * @returns {null}
  */
 exports.updateHiddenDates = function (moment, body, hiddenDates) {
   if (hiddenDates && !Array.isArray(hiddenDates)) {
@@ -181,7 +184,8 @@ exports.updateHiddenDates = function (moment, body, hiddenDates) {
 /**
  * remove duplicates from the hidden dates list. Duplicates are evil. They mess everything up.
  * Scales with N^2
- * @param body
+ *
+ * @param {Object} body
  */
 exports.removeDuplicates = function(body) {
   var hiddenDates = body.hiddenDates;
@@ -229,7 +233,7 @@ exports.printDates = function(dates) {
  * Used in TimeStep to avoid the hidden times.
  * @param {function} moment
  * @param {TimeStep} timeStep
- * @param previousTime
+ * @param {Date} previousTime
  */
 exports.stepOverHiddenDates = function(moment, timeStep, previousTime) {
   var stepInHidden = false;
@@ -281,10 +285,11 @@ exports.stepOverHiddenDates = function(moment, timeStep, previousTime) {
 
 /**
  * replaces the Core toScreen methods
- * @param Core
- * @param time
- * @param width
- * @returns {number}
+ *
+ * @param {vis.Core} Core
+ * @param {Date} time
+ * @param {Number} width
+ * @returns {Number}
  */
 exports.toScreen = function (Core, time, width) {
   var conversion;
@@ -322,9 +327,10 @@ exports.toScreen = function (Core, time, width) {
 
 /**
  * Replaces the core toTime methods
- * @param Core
- * @param x
- * @param width
+ *
+ * @param {vis.Core} Core
+ * @param {number} x
+ * @param {number} width
  * @returns {Date}
  */
 exports.toTime = function(Core, x, width) {
@@ -338,17 +344,17 @@ exports.toTime = function(Core, x, width) {
     var partialDuration = totalDuration * x / width;
     var accumulatedHiddenDuration = exports.getAccumulatedHiddenDuration(Core.body.hiddenDates, Core.range, partialDuration);
 
-    var newTime = new Date(accumulatedHiddenDuration + partialDuration + Core.range.start);
-    return newTime;
+    return new Date(accumulatedHiddenDuration + partialDuration + Core.range.start);
   }
 };
 
 
 /**
  * Support function
  *
- * @param hiddenDates
- * @param range
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
+ * @param {number} start
+ * @param {number} end
  * @returns {number}
  */
 exports.getHiddenDurationBetween = function(hiddenDates, start, end) {
@@ -365,13 +371,13 @@ exports.getHiddenDurationBetween = function(hiddenDates, start, end) {
 };
 
 /**
-   * Support function
-   *
-   * @param hiddenDates
-   * @param start
-   * @param end
-   * @returns {number}
-   */
+ * Support function
+ *
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
+ * @param {number} start
+ * @param {number} end
+ * @returns {number}
+ */
 exports.getHiddenDurationBeforeStart = function (hiddenDates, start, end) {
   var duration = 0;
   for (var i = 0; i < hiddenDates.length; i++) {
@@ -388,11 +394,11 @@ exports.getHiddenDurationBeforeStart = function (hiddenDates, start, end) {
 
 /**
  * Support function
- * @param moment
- * @param hiddenDates
- * @param range
- * @param time
- * @returns {{duration: number, time: *, offset: number}}
+ * @param {function} moment
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
+ * @param {{start: number, end: number}} range
+ * @param {Date} time
+ * @returns {number}
  */
 exports.correctTimeForHidden = function(moment, hiddenDates, range, time) {
   time = moment(time).toDate().valueOf();
@@ -420,10 +426,10 @@ exports.getHiddenDurationBefore = function(moment, hiddenDates, range, time) {
 /**
  * sum the duration from start to finish, including the hidden duration,
  * until the required amount has been reached, return the accumulated hidden duration
- * @param hiddenDates
- * @param range
- * @param time
- * @returns {{duration: number, time: *, offset: number}}
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
+ * @param {{start: number, end: number}} range
+ * @param {number} [requiredDuration=0]
+ * @returns {number}
  */
 exports.getAccumulatedHiddenDuration = function(hiddenDates, range, requiredDuration) {
   var hiddenDuration = 0;
@@ -453,11 +459,11 @@ exports.getAccumulatedHiddenDuration = function(hiddenDates, range, requiredDura
 
 /**
  * used to step over to either side of a hidden block. Correction is disabled on tablets, might be set to true
- * @param hiddenDates
- * @param time
- * @param direction
- * @param correctionEnabled
- * @returns {*}
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
+ * @param {Date} time
+ * @param {Number} direction
+ * @param {Boolean} correctionEnabled
+ * @returns {Date|Number}
  */
 exports.snapAwayFromHidden = function(hiddenDates, time, direction, correctionEnabled) {
   var isHidden = exports.isHidden(time, hiddenDates);
@@ -489,8 +495,8 @@ exports.snapAwayFromHidden = function(hiddenDates, time, direction, correctionEn
 /**
  * Check if a time is hidden
  *
- * @param time
- * @param hiddenDates
+ * @param {Date} time
+ * @param {Array<{start: Window.start, end: *}>} hiddenDates
  * @returns {{hidden: boolean, startDate: Window.start, endDate: *}}
  */
 exports.isHidden = function(time, hiddenDates) {

lib/timeline/Graph2d.js

@@ -20,6 +20,7 @@ var Validator = require('../shared/Validator').default;
  * Create a timeline visualization
  * @param {HTMLElement} container
  * @param {vis.DataSet | Array} [items]
+ * @param {vis.DataSet | Array | vis.DataView | Object} [groups]
  * @param {Object} [options]  See Graph2d.setOptions for the available options.
  * @constructor
  * @extends Core
@@ -212,9 +213,10 @@ Graph2d.prototype.setGroups = function(groups) {
 
 /**
  * Returns an object containing an SVG element with the icon of the group (size determined by iconWidth and iconHeight), the label of the group (content) and the yAxisOrientation of the group (left or right).
- * @param groupId
- * @param width
- * @param height
+ * @param {vis.GraphGroup.id} groupId
+ * @param {number} width
+ * @param {number} height
+ * @returns {{icon: SVGElement, label: string, orientation: string}|string}
  */
 Graph2d.prototype.getLegend = function(groupId, width, height) {
   if (width  === undefined) {width  = 15;}
@@ -229,8 +231,8 @@ Graph2d.prototype.getLegend = function(groupId, width, height) {
 
 /**
  * This checks if the visible option of the supplied group (by ID) is true or false.
- * @param groupId
- * @returns {*}
+ * @param {vis.GraphGroup.id} groupId
+ * @returns {boolean}
  */
 Graph2d.prototype.isGroupVisible = function(groupId) {
   if (this.linegraph.groups[groupId] !== undefined) {

lib/timeline/Range.js

@@ -4,12 +4,12 @@ var Component = require('./component/Component');
 var DateUtil = require('./DateUtil');
 
 /**
- * @constructor Range
  * A Range controls a numeric range with a start and end value.
  * The Range adjusts the range based on mouse events or programmatic changes,
  * and triggers events when the range is changing or has been changed.
  * @param {{dom: Object, domProps: Object, emitter: Emitter}} body
  * @param {Object} [options]    See description at Range.setOptions
+ * @constructor Range
  */
 function Range(body, options) {
   var now = moment().hours(0).minutes(0).seconds(0).milliseconds(0);
@@ -280,6 +280,8 @@ Range.prototype.setRange = function(start, end, options, callback) {
 
 /**
  * Get the number of milliseconds per pixel.
+ *
+ * @returns {undefined|Number}
  */
 Range.prototype.getMillisecondsPerPixel = function() {
   if (this.millisecondsPerPixelCache === undefined) {
@@ -433,6 +435,7 @@ Range.prototype.getRange = function() {
  * Calculate the conversion offset and scale for current range, based on
  * the provided width
  * @param {Number} width
+ * @param {Number} [totalHidden=0]
  * @returns {{offset: number, scale: number}} conversion
  */
 Range.prototype.conversion = function (width, totalHidden) {
@@ -445,6 +448,7 @@ Range.prototype.conversion = function (width, totalHidden) {
  * @param {Number} start
  * @param {Number} end
  * @param {Number} width
+ * @param {Number} [totalHidden=0]
  * @returns {{offset: number, scale: number}} conversion
  */
 Range.conversion = function (start, end, width, totalHidden) {
@@ -657,6 +661,7 @@ Range.prototype._onMouseWheel = function(event) {
 
 /**
  * Start of a touch gesture
+ * @param {Event} event
  * @private
  */
 Range.prototype._onTouch = function (event) {  // eslint-disable-line no-unused-vars
@@ -800,6 +805,8 @@ Range.prototype.getPointer = function (touch, element) {
  *                            values below 1 will zoom in.
  * @param {Number} [center]   Value representing a date around which will
  *                            be zoomed.
+ * @param {Number} delta
+ * @param {Event} event
  */
 Range.prototype.zoom = function(scale, center, delta, event) {
   // if centerDate is not provided, take it half between start Date and end Date

lib/timeline/Stack.js

@@ -79,10 +79,11 @@ exports.stack = function(items, margin, force) {
  *            All visible items
  * @param {{item: {horizontal: number, vertical: number}, axis: number}} margin
  *            Margins between items and between items and the axis.
-* @param {subgroups[]} subgroups
+ * @param {subgroups[]} subgroups
  *            All subgroups
+ * @param {boolean} stackSubgroups
  */
- exports.nostack = function(items, margin, subgroups, stackSubgroups) {
+exports.nostack = function(items, margin, subgroups, stackSubgroups) {
   for (var i = 0; i < items.length; i++) {
     if (items[i].data.subgroup == undefined) {
       items[i].top = margin.item.vertical;
@@ -107,10 +108,10 @@ exports.stack = function(items, margin, force) {
 /**
  * Adjust vertical positions of the subgroups such that they don't overlap each
  * other.
+ * @param {Array<vis.Item>} items
+ * @param {{item: {horizontal: number, vertical: number}, axis: number}} margin Margins between items and between items and the axis.
  * @param {subgroups[]} subgroups
  *            All subgroups
- * @param {{item: {horizontal: number, vertical: number}, axis: number}} margin
- *            Margins between items and between items and the axis.
  */
 exports.stackSubgroups = function(items, margin, subgroups) {
   for (var subgroup in subgroups) {
@@ -141,7 +142,7 @@ exports.stackSubgroups = function(items, margin, subgroups) {
       items[i].top = subgroups[items[i].data.subgroup].top + 0.5 * margin.item.vertical;
     }
   }
-}
+};
 
 /**
  * Test if the two provided items collide

lib/timeline/TimeStep.js

@@ -3,7 +3,6 @@ var DateUtil = require('./DateUtil');
 var util = require('../util');
 
 /**
- * @constructor  TimeStep
  * The class TimeStep is an iterator for dates. You provide a start date and an
  * end date. The class itself determines the best scale (step size) based on the
  * provided start Date, end Date, and minimumStep.
@@ -27,6 +26,9 @@ var util = require('../util');
  *                               or new Date(2010, 9, 21, 23, 45, 00)
  * @param {Date} [end]           The end date
  * @param {Number} [minimumStep] Optional. Minimum step size in milliseconds
+ * @param {Date|Array<Date>} [hiddenDates] Optional.
+ * @param {{showMajorLabels: boolean}} [options] Optional.
+ * @constructor  TimeStep
  */
 function TimeStep(start, end, minimumStep, hiddenDates, options) {
   this.moment = moment;
@@ -561,7 +563,8 @@ TimeStep.prototype.isMajor = function() {
  * Returns formatted text for the minor axislabel, depending on the current
  * date and the scale. For example when scale is MINUTE, the current time is
  * formatted as "hh:mm".
- * @param {Date} [date] custom date. if not provided, current date is taken
+ * @param {Date} [date=this.current] custom date. if not provided, current date is taken
+ * @returns {String}
  */
 TimeStep.prototype.getLabelMinor = function(date) {
   if (date == undefined) {
@@ -591,7 +594,8 @@ TimeStep.prototype.getLabelMinor = function(date) {
  * Returns formatted text for the major axis label, depending on the current
  * date and the scale. For example when scale is MINUTE, the major scale is
  * hours, and the hour will be formatted as "hh".
- * @param {Date} [date] custom date. if not provided, current date is taken
+ * @param {Date} [date=this.current] custom date. if not provided, current date is taken
+ * @returns {String}
  */
 TimeStep.prototype.getLabelMajor = function(date) {
   if (date == undefined) {