From 19beef7ec017563f7b46180cd2ee32fb5ffef749 Mon Sep 17 00:00:00 2001 From: macleodbroad-wf Date: Wed, 16 Aug 2017 16:42:27 -0400 Subject: [PATCH] Tightens up jsdoc lint rules on timeline (#3362) * Tightens up jsdoc lint rules on timeline * Adds missing options param --- lib/timeline/.eslintrc | 39 ++++++++++ lib/timeline/Core.js | 27 +++---- lib/timeline/DateUtil.js | 78 ++++++++++--------- lib/timeline/Graph2d.js | 12 +-- lib/timeline/Range.js | 9 ++- lib/timeline/Stack.js | 11 +-- lib/timeline/TimeStep.js | 10 ++- lib/timeline/Timeline.js | 6 +- lib/timeline/component/DataAxis.js | 34 ++++---- lib/timeline/component/GraphGroup.js | 17 ++-- lib/timeline/component/Group.js | 19 +++-- lib/timeline/component/ItemSet.js | 16 ++-- lib/timeline/component/Legend.js | 11 ++- lib/timeline/component/LineGraph.js | 39 +++++----- lib/timeline/component/graph2d_types/bar.js | 22 +++--- lib/timeline/component/graph2d_types/line.js | 19 ++--- lib/timeline/component/item/BackgroundItem.js | 2 +- lib/timeline/component/item/Item.js | 4 +- lib/timeline/component/item/RangeItem.js | 4 +- 19 files changed, 229 insertions(+), 150 deletions(-) create mode 100644 lib/timeline/.eslintrc diff --git a/lib/timeline/.eslintrc b/lib/timeline/.eslintrc new file mode 100644 index 00000000..5990d5f6 --- /dev/null +++ b/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"] }], +} diff --git a/lib/timeline/Core.js b/lib/timeline/Core.js index 7ccdfbcf..d54c2e5f 100644 --- a/lib/timeline/Core.js +++ b/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 () { diff --git a/lib/timeline/DateUtil.js b/lib/timeline/DateUtil.js index 43afb935..c163183a 100644 --- a/lib/timeline/DateUtil.js +++ b/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) { diff --git a/lib/timeline/Graph2d.js b/lib/timeline/Graph2d.js index 237abd07..d7908b76 100644 --- a/lib/timeline/Graph2d.js +++ b/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) { diff --git a/lib/timeline/Range.js b/lib/timeline/Range.js index 74e1be5b..550a3798 100644 --- a/lib/timeline/Range.js +++ b/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 diff --git a/lib/timeline/Stack.js b/lib/timeline/Stack.js index 2d96c70c..0535aea4 100644 --- a/lib/timeline/Stack.js +++ b/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} 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 diff --git a/lib/timeline/TimeStep.js b/lib/timeline/TimeStep.js index 6f7ccae5..c2bfbb62 100644 --- a/lib/timeline/TimeStep.js +++ b/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} [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) { diff --git a/lib/timeline/Timeline.js b/lib/timeline/Timeline.js index 8dcb9b2e..c731deb6 100644 --- a/lib/timeline/Timeline.js +++ b/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; diff --git a/lib/timeline/component/DataAxis.js b/lib/timeline/component/DataAxis.js index e2cc569b..d1dd69f1 100644 --- a/lib/timeline/component/DataAxis.js +++ b/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); diff --git a/lib/timeline/component/GraphGroup.js b/lib/timeline/component/GraphGroup.js index 25dda8bc..6b5eab27 100644 --- a/lib/timeline/component/GraphGroup.js +++ b/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}} 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) { diff --git a/lib/timeline/component/Group.js b/lib/timeline/component/Group.js index f817e87a..502a0036 100644 --- a/lib/timeline/component/Group.js +++ b/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} visibleItems + * @param {Object} visibleItemsLookup * @param {{start:number, end:number}} range * @private */ diff --git a/lib/timeline/component/ItemSet.js b/lib/timeline/component/ItemSet.js index 3d6e4000..a1e0382e 100644 --- a/lib/timeline/component/ItemSet.js +++ b/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} groupIds + * @returns {Array} * @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} 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) { diff --git a/lib/timeline/component/Legend.js b/lib/timeline/component/Legend.js index c1eefde6..578e2e76 100644 --- a/lib/timeline/component/Legend.js +++ b/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 diff --git a/lib/timeline/component/LineGraph.js b/lib/timeline/component/LineGraph.js index 00bae06f..dc3980bb 100644 --- a/lib/timeline/component/LineGraph.js +++ b/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} 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} 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} 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} 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} datapoints + * @param {vis.GraphGroup} group * @private */ LineGraph.prototype._convertYcoordinates = function (datapoints, group) { diff --git a/lib/timeline/component/graph2d_types/bar.js b/lib/timeline/component/graph2d_types/bar.js index 7f66828d..2cefb5b7 100644 --- a/lib/timeline/component/graph2d_types/bar.js +++ b/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} groupIds + * @param {Object} processedGroupData + * @param {{svg: Object, svgElements: Array, options: Object, groups: Array}} 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} 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; diff --git a/lib/timeline/component/graph2d_types/line.js b/lib/timeline/component/graph2d_types/line.js index 9cccef8e..d6155054 100644 --- a/lib/timeline/component/graph2d_types/line.js +++ b/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} pathArray + * @param {vis.Group} group + * @param {{svg: Object, svgElements: Array, options: Object, groups: Array}} 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} 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} 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} data * @returns {string} * @private */ diff --git a/lib/timeline/component/item/BackgroundItem.js b/lib/timeline/component/item/BackgroundItem.js index 2d8f07d4..9e1e3b19 100644 --- a/lib/timeline/component/item/BackgroundItem.js +++ b/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) { diff --git a/lib/timeline/component/item/Item.js b/lib/timeline/component/item/Item.js index 551ffc35..6c5d7d3a 100644 --- a/lib/timeline/component/item/Item.js +++ b/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) { diff --git a/lib/timeline/component/item/RangeItem.js b/lib/timeline/component/item/RangeItem.js index 485df4b5..e1dbef4f 100644 --- a/lib/timeline/component/item/RangeItem.js +++ b/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) {