Tightens up jsdoc lint rules on timeline (#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/Core.js

@@ -559,6 +559,7 @@ Core.prototype.getCustomTime = function(id) {
  * Set a custom title for the custom time bar.
  * @param {String} [title] Custom title
  * @param {number} [id=undefined]    Id of the custom time bar.
+ * @returns {*}
  */
 Core.prototype.setCustomTimeTitle = function(title, id) {
   var customTimes = this.customTimes.filter(function (component) {
@@ -620,7 +621,7 @@ Core.prototype.addCustomTime = function (time, id) {
 /**
  * Remove previously added custom bar
  * @param {int} id ID of the custom bar to be removed
- * @return {boolean} True if the bar exists and is removed, false otherwise
+ * [at]returns {boolean} True if the bar exists and is removed, false otherwise
  */
 Core.prototype.removeCustomTime = function (id) {
   var customTimes = this.customTimes.filter(function (bar) {
@@ -656,7 +657,7 @@ Core.prototype.getVisibleItems = function() {
  *                                    provided to specify duration and easing function.
  *                                    Default duration is 500 ms, and default easing
  *                                    function is 'easeInOutQuad'.
- * @param {Function} a callback funtion to be executed at the end of this function 
+ * @param {function} [callback] a callback funtion to be executed at the end of this function
  */
 Core.prototype.fit = function(options, callback) {
   var range = this.getDataRange();
@@ -676,7 +677,7 @@ Core.prototype.fit = function(options, callback) {
 
 /**
  * Calculate the data range of the items start and end dates
- * @returns {{min: Date | null, max: Date | null}}
+ * [at]returns {{min: [Date], max: [Date]}}
  * @protected
  */
 Core.prototype.getDataRange = function() {
@@ -704,11 +705,11 @@ Core.prototype.getDataRange = function() {
  *                                    provided to specify duration and easing function.
  *                                    Default duration is 500 ms, and default easing
  *                                    function is 'easeInOutQuad'.
- * @param {Function} a callback funtion to be executed at the end of this function 
+ * @param {function} [callback] a callback funtion to be executed at the end of this function
  */
 Core.prototype.setWindow = function(start, end, options, callback) {
   if (typeof arguments[2] == "function") {
-    callback = arguments[2]
+    callback = arguments[2];
     options = {};
   }
   var animation;
@@ -740,11 +741,11 @@ Core.prototype.setWindow = function(start, end, options, callback) {
  *                                    provided to specify duration and easing function.
  *                                    Default duration is 500 ms, and default easing
  *                                    function is 'easeInOutQuad'.
- * @param {Function} a callback funtion to be executed at the end of this function 
+ * @param {function} [callback] a callback funtion to be executed at the end of this function
  */
 Core.prototype.moveTo = function(time, options, callback) {
   if (typeof arguments[1] == "function") {
-    callback = arguments[1]
+    callback = arguments[1];
     options = {};
   }
   var interval = this.range.end - this.range.start;
@@ -779,12 +780,12 @@ Core.prototype.getWindow = function() {
  *                                    provided to specify duration and easing function.
  *                                    Default duration is 500 ms, and default easing
  *                                    function is 'easeInOutQuad'.
- * @param {Function} a callback funtion to be executed at the end of this function 
+ * @param {function} [callback] a callback funtion to be executed at the end of this function
  */
 Core.prototype.zoomIn = function(percentage, options, callback) {
-  if (!percentage || percentage < 0 || percentage > 1) return
+  if (!percentage || percentage < 0 || percentage > 1) return;
   if (typeof arguments[1] == "function") {
-    callback = arguments[1]
+    callback = arguments[1];
     options = {};
   }
   var range = this.getWindow();
@@ -809,12 +810,12 @@ Core.prototype.zoomIn = function(percentage, options, callback) {
  *                                    provided to specify duration and easing function.
  *                                    Default duration is 500 ms, and default easing
  *                                    function is 'easeInOutQuad'.
- * @param {Function} a callback funtion to be executed at the end of this function 
+ * @param {function} [callback] a callback funtion to be executed at the end of this function
  */
 Core.prototype.zoomOut = function(percentage, options, callback) {
   if (!percentage || percentage < 0 || percentage > 1) return
   if (typeof arguments[1] == "function") {
-    callback = arguments[1]
+    callback = arguments[1];
     options = {};
   }
   var range = this.getWindow();
@@ -1314,7 +1315,7 @@ Core.prototype._getScrollTop = function () {
 
 /**
  * Load a configurator
- * @return {Object}
+ * [at]returns {Object}
  * @private
  */
 Core.prototype._createConfigurator = function () {

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,8 +344,7 @@ 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);
   }
 };
 
@@ -347,8 +352,9 @@ exports.toTime = function(Core, x, width) {
 /**
  * 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) {

lib/timeline/Timeline.js

@@ -306,7 +306,7 @@ Timeline.prototype.setGroups = function(groups) {
 
 /**
  * Set both items and groups in one go
- * @param {{items: Array | vis.DataSet, groups: Array | vis.DataSet}} data
+ * @param {{items: (Array | vis.DataSet), groups: (Array | vis.DataSet)}} data
  */
 Timeline.prototype.setData = function (data) {
   if (data && data.groups) {
@@ -451,7 +451,7 @@ function getEnd(item) {
 /**
  * Determine the range of the items, taking into account their actual width
  * and a margin of 10 pixels on both sides.
- * @return {{min: Date | null, max: Date | null}}
+ * @returns {{min: [Date], max: [Date]}}
  */
 Timeline.prototype.getItemRange = function () {
   // get a rough approximation for the range based on the items start and end dates
@@ -524,7 +524,7 @@ Timeline.prototype.getItemRange = function () {
 
 /**
  * Calculate the data range of the items start and end dates
- * @returns {{min: Date | null, max: Date | null}}
+ * @returns {{min: [Date], max: [Date]}}
  */
 Timeline.prototype.getDataRange = function() {
   var min = null;

lib/timeline/component/DataAxis.js

@@ -4,11 +4,13 @@ var Component = require('./Component');
 var DataScale = require('./DataScale');
 /**
  * A horizontal time axis
+ * @param {Object} body
  * @param {Object} [options]        See DataAxis.setOptions for the available
  *                                  options.
+ * @param {SVGElement} svg
+ * @param {vis.LineGraph.options} linegraphOptions
  * @constructor DataAxis
  * @extends Component
- * @param body
  */
 function DataAxis(body, options, svg, linegraphOptions) {
   this.id = util.randomUUID();
@@ -245,9 +247,8 @@ DataAxis.prototype.hide = function () {
 
 /**
  * Set a range (start and end)
- * @param end
- * @param start
- * @param end
+ * @param {number} start
+ * @param {number} end
  */
 DataAxis.prototype.setRange = function (start, end) {
   this.range.start = start;
@@ -342,6 +343,8 @@ DataAxis.prototype.redraw = function () {
 
 /**
  * Repaint major and minor text labels and vertical grid lines
+ *
+ * @returns {boolean}
  * @private
  */
 DataAxis.prototype._redrawLabels = function () {
@@ -448,12 +451,13 @@ DataAxis.prototype.screenToValue = function (x) {
 
 /**
  * Create a label for the axis at position x
+ *
+ * @param {number} y
+ * @param {string} text
+ * @param {'top'|'right'|'bottom'|'left'} orientation
+ * @param {string} className
+ * @param {number} characterHeight
  * @private
- * @param y
- * @param text
- * @param orientation
- * @param className
- * @param characterHeight
  */
 DataAxis.prototype._redrawLabel = function (y, text, orientation, className, characterHeight) {
   // reuse redundant label
@@ -481,11 +485,11 @@ DataAxis.prototype._redrawLabel = function (y, text, orientation, className, cha
 
 /**
  * Create a minor line for the axis at position y
- * @param y
- * @param orientation
- * @param className
- * @param offset
- * @param width
+ * @param {number} y
+ * @param {'top'|'right'|'bottom'|'left'} orientation
+ * @param {string} className
+ * @param {number} offset
+ * @param {number} width
  */
 DataAxis.prototype._redrawLine = function (y, orientation, className, offset, width) {
   if (this.master === true) {
@@ -508,7 +512,7 @@ DataAxis.prototype._redrawLine = function (y, orientation, className, offset, wi
 /**
  * Create a title for the axis
  * @private
- * @param orientation
+ * @param {'top'|'right'|'bottom'|'left'} orientation
  */
 DataAxis.prototype._redrawTitle = function (orientation) {
   DOMutil.prepareElements(this.DOMelements.title);

lib/timeline/component/GraphGroup.js

@@ -48,11 +48,11 @@ GraphGroup.prototype.setItems = function (items) {
 
 GraphGroup.prototype.getItems = function () {
   return this.itemsData;
-}
+};
 
 /**
  * this is used for barcharts and shading, this way, we only have to calculate it once.
- * @param pos
+ * @param {number} pos
  */
 GraphGroup.prototype.setZeroPosition = function (pos) {
   this.zeroPosition = pos;
@@ -60,7 +60,7 @@ GraphGroup.prototype.setZeroPosition = function (pos) {
 
 /**
  * set the options of the graph group over the default options.
- * @param options
+ * @param {Object} options
  */
 GraphGroup.prototype.setOptions = function (options) {
   if (options !== undefined) {
@@ -100,7 +100,7 @@ GraphGroup.prototype.setOptions = function (options) {
 
 /**
  * this updates the current group class with the latest group dataset entree, used in _updateGroup in linegraph
- * @param group
+ * @param {vis.Group} group
  */
 GraphGroup.prototype.update = function (group) {
   this.group = group;
@@ -114,9 +114,12 @@ GraphGroup.prototype.update = function (group) {
 /**
  * return the legend entree for this group.
  *
- * @param iconWidth
- * @param iconHeight
- * @returns {{icon: HTMLElement, label: (group.content|*|string), orientation: (.options.yAxisOrientation|*)}}
+ * @param {number} iconWidth
+ * @param {number} iconHeight
+ * @param {{svg: (*|Element), svgElements: Object, options: Object, groups: Array<Object>}} framework
+ * @param {number} x
+ * @param {number} y
+ * @returns {{icon: (*|Element), label: (*|string), orientation: *}}
  */
 GraphGroup.prototype.getLegend = function (iconWidth, iconHeight, framework, x, y) {
   if (framework == undefined || framework == null) {

lib/timeline/component/Group.js

@@ -320,6 +320,8 @@ Group.prototype.redraw = function(range, margin, forceRestack) {
 
 /**
  * recalculate the height of the subgroups
+ *
+ * @param {{item: vis.Item}} margin
  * @private
  */
 Group.prototype._calculateSubGroupHeights = function (margin) {
@@ -339,14 +341,16 @@ Group.prototype._calculateSubGroupHeights = function (margin) {
 
 /**
  * check if group is visible
+ *
+ * @param {vis.Range} range
+ * @param {{axis: vis.DataAxis}} margin
+ * @returns {boolean} is visible
  * @private
-  */
+ */
 Group.prototype._isGroupVisible = function (range, margin) {
-  var isVisible = 
-  (this.top <= range.body.domProps.centerContainer.height - range.body.domProps.scrollTop + margin.axis) 
+  return (this.top <= range.body.domProps.centerContainer.height - range.body.domProps.scrollTop + margin.axis)
   && (this.top + this.height + margin.axis >= - range.body.domProps.scrollTop);
-  return isVisible;
-}
+};
 
 /**
  * recalculate the height of the group
@@ -610,7 +614,7 @@ Group.prototype.order = function() {
 /**
  * Update the visible items
  * @param {{byStart: Item[], byEnd: Item[]}} orderedItems   All items ordered by start date and by end date
- * @param {Item[]} visibleItems                             The previously visible items.
+ * @param {Item[]} oldVisibleItems                          The previously visible items.
  * @param {{start: number, end: number}} range              Visible range
  * @return {Item[]} visibleItems                            The new visible items.
  * @private
@@ -739,7 +743,8 @@ Group.prototype._checkIfVisible = function(item, visibleItems, range) {
  * this one is for brute forcing and hiding.
  *
  * @param {Item} item
- * @param {Array} visibleItems
+ * @param {Array<vis.Item>} visibleItems
+ * @param {Object<number, boolean>} visibleItemsLookup
  * @param {{start:number, end:number}} range
  * @private
  */

lib/timeline/component/ItemSet.js

@@ -503,7 +503,6 @@ ItemSet.prototype.hide = function() {
 
 /**
  * Show the component in the DOM (when not already visible).
- * @return {Boolean} changed
  */
 ItemSet.prototype.show = function() {
   // show frame containing the items
@@ -1181,7 +1180,9 @@ ItemSet.prototype._orderGroups = function () {
 
 /**
  * Reorder the nested groups
- * @return {boolean} changed
+ *
+ * @param {Array<number>} groupIds
+ * @returns {Array<number>}
  * @private
  */
 ItemSet.prototype._orderNestedGroups = function(groupIds) {
@@ -1270,7 +1271,7 @@ ItemSet.prototype._removeItem = function(item) {
 
 /**
  * Create an array containing all items being a range (having an end date)
- * @param array
+ * @param {Array<Object>} array
  * @returns {Array}
  * @private
  */
@@ -1307,7 +1308,8 @@ ItemSet.prototype._onTouch = function (event) {
 /**
  * Given an group id, returns the index it has.
  *
- * @param {Number} groupID
+ * @param {number} groupId
+ * @returns {number} index / groupId
  * @private
  */
 ItemSet.prototype._getGroupIndex = function(groupId) {
@@ -2001,7 +2003,7 @@ ItemSet.prototype._onMouseMove = function (event) {
 
 /**
  * Handle mousewheel
- * @param event
+ * @param {Event}  event   The event
  * @private
  */
 ItemSet.prototype._onMouseWheel = function(event) {
@@ -2012,7 +2014,7 @@ ItemSet.prototype._onMouseWheel = function(event) {
 
 /**
  * Handle updates of an item on double tap
- * @param event
+ * @param {vis.Item}  item   The item
  * @private
  */
 ItemSet.prototype._onUpdateItem = function (item) {
@@ -2034,7 +2036,7 @@ ItemSet.prototype._onUpdateItem = function (item) {
 
 /**
  * Handle creation of an item on double tap
- * @param event
+ * @param {Event} event   The event
  * @private
  */
 ItemSet.prototype._onAddItem = function (event) {

lib/timeline/component/Legend.js

@@ -4,6 +4,12 @@ var Component = require('./Component');
 
 /**
  * Legend for Graph2d
+ *
+ * @param {vis.Graph2d.body} body
+ * @param {vis.Graph2d.options} options
+ * @param {number} side
+ * @param {vis.LineGraph.options} linegraphOptions
+ * @constructor
  */
 function Legend(body, options, side, linegraphOptions) {
   this.body = body;
@@ -20,10 +26,10 @@ function Legend(body, options, side, linegraphOptions) {
       visible: true,
       position: 'top-right' // top/bottom - left,center,right
     }
-  }
+  };
 
   this.side = side;
-  this.options = util.extend({},this.defaultOptions);
+  this.options = util.extend({}, this.defaultOptions);
   this.linegraphOptions = linegraphOptions;
 
   this.svgElements = {};
@@ -99,7 +105,6 @@ Legend.prototype.hide = function() {
 
 /**
  * Show the component in the DOM (when not already visible).
- * @return {Boolean} changed
  */
 Legend.prototype.show = function() {
   // show frame containing the items

lib/timeline/component/LineGraph.js

@@ -15,8 +15,8 @@ var UNGROUPED = '__ungrouped__'; // reserved group id for ungrouped items
 /**
  * This is the constructor of the LineGraph. It requires a Timeline body and options.
  *
- * @param body
- * @param options
+ * @param {vis.Timeline.body} body
+ * @param {Object} options
  * @constructor
  */
 function LineGraph(body, options) {
@@ -230,7 +230,6 @@ LineGraph.prototype.hide = function () {
 
 /**
  * Show the component in the DOM (when not already visible).
- * @return {Boolean} changed
  */
 LineGraph.prototype.show = function () {
   // show frame containing the items
@@ -362,7 +361,7 @@ LineGraph.prototype._onRemoveGroups = function (groupIds) {
 
 /**
  * this cleans the group out off the legends and the dataaxis
- * @param groupId
+ * @param {vis.GraphGroup.id} groupId
  * @private
  */
 LineGraph.prototype._removeGroup = function (groupId) {
@@ -379,13 +378,13 @@ LineGraph.prototype._removeGroup = function (groupId) {
     }
     delete this.groups[groupId];
   }
-}
+};
 
 /**
  * update a group object with the group dataset entree
  *
- * @param group
- * @param groupId
+ * @param {vis.GraphGroup} group
+ * @param {vis.GraphGroup.id} groupId
  * @private
  */
 LineGraph.prototype._updateGroup = function (group, groupId) {
@@ -624,11 +623,13 @@ LineGraph.prototype._getSortedGroupIds = function(){
     groupIds[i] = grouplist[i].id;
   }
   return groupIds;
-}
+};
 
 /**
  * Update and redraw the graph.
  *
+ * @returns {boolean}
+ * @private
  */
 LineGraph.prototype._updateGraph = function () {
   // reset the svg elements
@@ -854,8 +855,8 @@ LineGraph.prototype._getRelevantData = function (groupIds, groupsData, minDate,
 
 /**
  *
- * @param groupIds
- * @param groupsData
+ * @param {Array<vis.GraphGroup.id>} groupIds
+ * @param {vis.DataSet} groupsData
  * @private
  */
 LineGraph.prototype._applySampling = function (groupIds, groupsData) {
@@ -891,9 +892,8 @@ LineGraph.prototype._applySampling = function (groupIds, groupsData) {
 
 /**
  *
- *
- * @param {array}  groupIds
- * @param {object} groupsData
+ * @param {Array<vis.GraphGroup.id>} groupIds
+ * @param {vis.DataSet} groupsData
  * @param {object} groupRanges  | this is being filled here
  * @private
  */
@@ -932,8 +932,9 @@ LineGraph.prototype._getYRanges = function (groupIds, groupsData, groupRanges) {
 
 /**
  * this sets the Y ranges for the Y axis. It also determines which of the axis should be shown or hidden.
- * @param {Array} groupIds
+ * @param {Array<vis.GraphGroup.id>} groupIds
  * @param {Object} groupRanges
+ * @returns {boolean} resized
  * @private
  */
 LineGraph.prototype._updateYAxis = function (groupIds, groupRanges) {
@@ -1031,9 +1032,9 @@ LineGraph.prototype._updateYAxis = function (groupIds, groupRanges) {
  * This shows or hides the Y axis if needed. If there is a change, the changed event is emitted by the updateYAxis function
  *
  * @param {boolean} axisUsed
+ * @param {vis.DataAxis}  axis
  * @returns {boolean}
  * @private
- * @param axis
  */
 LineGraph.prototype._toggleAxisVisiblity = function (axisUsed, axis) {
   var changed = false;
@@ -1058,8 +1059,7 @@ LineGraph.prototype._toggleAxisVisiblity = function (axisUsed, axis) {
  * util function toScreen to get the x coordinate from the timestamp. It also pre-filters the data and get the minMax ranges for
  * the yAxis.
  *
- * @param datapoints
- * @returns {Array}
+ * @param {Array<Object>} datapoints
  * @private
  */
 LineGraph.prototype._convertXcoordinates = function (datapoints) {
@@ -1082,9 +1082,8 @@ LineGraph.prototype._convertXcoordinates = function (datapoints) {
  * util function toScreen to get the x coordinate from the timestamp. It also pre-filters the data and get the minMax ranges for
  * the yAxis.
  *
- * @param datapoints
- * @param group
- * @returns {Array}
+ * @param {Array<Object>} datapoints
+ * @param {vis.GraphGroup} group
  * @private
  */
 LineGraph.prototype._convertYcoordinates = function (datapoints, group) {

lib/timeline/component/graph2d_types/bar.js

@@ -3,7 +3,7 @@ var Points = require('./points');
 
 /**
  *
- * @param {vis.Group.id} groupId
+ * @param {vis.GraphGroup.id} groupId
  * @param {Object} options   // TODO: Describe options
  * @constructor
  */
@@ -40,14 +40,14 @@ Bargraph.drawIcon = function (group, x, y, iconWidth, iconHeight, framework) {
     DOMutil.drawPoint(x + 0.5 * barWidth + offset, y + fillHeight - bar1Height - 1, groupTemplate, framework.svgElements, framework.svg);
     DOMutil.drawPoint(x + 1.5 * barWidth + offset + 2, y + fillHeight - bar2Height - 1, groupTemplate, framework.svgElements, framework.svg);
   }
-
-}
+};
 
 /**
  * draw a bar graph
  *
- * @param groupIds
- * @param processedGroupData
+ * @param {Array<vis.GraphGroup.id>} groupIds
+ * @param {Object} processedGroupData
+ * @param {{svg: Object, svgElements: Array<Object>, options: Object, groups: Array<vis.Group>}} framework
  */
 Bargraph.draw = function (groupIds, processedGroupData, framework) {
   var combinedData = [];
@@ -167,8 +167,8 @@ Bargraph.draw = function (groupIds, processedGroupData, framework) {
 
 /**
  * Fill the intersections object with counters of how many datapoints share the same x coordinates
- * @param intersections
- * @param combinedData
+ * @param {Object} intersections
+ * @param {Array<Object>} combinedData
  * @private
  */
 Bargraph._getDataIntersections = function (intersections, combinedData) {
@@ -199,9 +199,9 @@ Bargraph._getDataIntersections = function (intersections, combinedData) {
 /**
  * Get the width and offset for bargraphs based on the coredistance between datapoints
  *
- * @param coreDistance
- * @param group
- * @param minWidth
+ * @param {number} coreDistance
+ * @param {vis.Group} group
+ * @param {number} minWidth
  * @returns {{width: Number, offset: Number}}
  * @private
  */
@@ -251,7 +251,7 @@ Bargraph.getStackedYRange = function (combinedData, groupRanges, groupIds, group
     groupRanges[groupLabel].yAxisOrientation = orientation;
     groupIds.push(groupLabel);
   }
-}
+};
 
 Bargraph._getStackedYRange = function (intersections, combinedData) {
   var key;

lib/timeline/component/graph2d_types/line.js

@@ -2,7 +2,7 @@ var DOMutil = require('../../../DOMutil');
 
 /**
  *
- * @param {Number | String} groupId
+ * @param {vis.GraphGroup.id} groupId
  * @param {Object} options   // TODO: Describe options
  * @constructor
  */
@@ -71,7 +71,7 @@ Line.drawIcon = function (group, x, y, iconWidth, iconHeight, framework) {
         };
         DOMutil.drawPoint(x + 0.5 * iconWidth, y, groupTemplate, framework.svgElements, framework.svg);
     }
-}
+};
 
 Line.drawShading = function (pathArray, group, subPathArray, framework) {
     // append shading to the path
@@ -112,13 +112,14 @@ Line.drawShading = function (pathArray, group, subPathArray, framework) {
         }
         fillPath.setAttributeNS(null, 'd', dFill);
     }
-}
+};
 
 /**
  * draw a line graph
  *
- * @param dataset
- * @param group
+ * @param {Array<Object>} pathArray
+ * @param {vis.Group} group
+ * @param {{svg: Object, svgElements: Array<Object>, options: Object, groups: Array<vis.Group>}} framework
  */
 Line.draw = function (pathArray, group, framework) {
     if (pathArray != null && pathArray != undefined) {
@@ -160,7 +161,7 @@ Line.serializePath = function(pathArray,type,inverse){
 /**
  * This uses an uniform parametrization of the interpolation algorithm:
  * 'On the Parameterization of Catmull-Rom Curves' by Cem Yuksel et al.
- * @param data
+ * @param {Array<Object>} data
  * @returns {string}
  * @private
  */
@@ -210,8 +211,8 @@ Line._catmullRomUniform = function (data) {
  * These parameterizations are relatively heavy because the distance between 4 points have to be calculated.
  *
  * One optimization can be used to reuse distances since this is a sliding window approach.
- * @param data
- * @param group
+ * @param {Array<Object>} data
+ * @param {vis.GraphGroup} group
  * @returns {string}
  * @private
  */
@@ -292,7 +293,7 @@ Line._catmullRom = function (data, group) {
 
 /**
  * this generates the SVG path for a linear drawing between datapoints.
- * @param data
+ * @param {Array<Object>} data
  * @returns {string}
  * @private
  */

lib/timeline/component/item/BackgroundItem.js

@@ -41,7 +41,7 @@ BackgroundItem.prototype.stack = false;
 
 /**
  * Check whether this item is visible inside given range
- * @returns {{start: Number, end: Number}} range with a timestamp for start and end
+ * @param {vis.Range} range with a timestamp for start and end
  * @returns {boolean} True if visible
  */
 BackgroundItem.prototype.isVisible = function(range) {

lib/timeline/component/item/Item.js

@@ -99,7 +99,7 @@ Item.prototype.setParent = function(parent) {
 
 /**
  * Check whether this item is visible inside given range
- * @returns {{start: Number, end: Number}} range with a timestamp for start and end
+ * @param {vis.Range} range with a timestamp for start and end
  * @returns {boolean} True if visible
  */
 Item.prototype.isVisible = function(range) {  // eslint-disable-line no-unused-vars
@@ -427,7 +427,7 @@ Item.prototype._updateContents = function (element) {
 
 /**
  * Update custom styles of the element
- * @param element
+ * @param {Element} element
  * @private
  */
 Item.prototype._updateStyle = function(element) {

lib/timeline/component/item/RangeItem.js

@@ -37,7 +37,8 @@ RangeItem.prototype.baseClassName = 'vis-item vis-range';
 
 /**
  * Check whether this item is visible inside given range
- * @returns {{start: Number, end: Number}} range with a timestamp for start and end
+ *
+ * @param {vis.Range} range with a timestamp for start and end
  * @returns {boolean} True if visible
  */
 RangeItem.prototype.isVisible = function(range) {
@@ -143,7 +144,6 @@ RangeItem.prototype.show = function() {
 
 /**
  * Hide the item from the DOM (when visible)
- * @return {Boolean} changed
  */
 RangeItem.prototype.hide = function() {
   if (this.displayed) {