From 1c18a74ea08f02160d1e4ce823a5cde1e2e49a2f Mon Sep 17 00:00:00 2001
From: Ben McCann <322311+benmccann@users.noreply.github.com>
Date: Mon, 3 Feb 2020 04:52:55 -0800
Subject: [PATCH] Fix some JSDoc errors (#7026)

* Fix some JSDoc errors

* Fix helpers.dom JSDoc errors

* Add scale JSDoc errors

* Address review comment

* Fix additional errors

* Document optional parameters

* JSDoc fixes for datasetController

* Remove undefined
---
 src/core/core.controller.js        |  2 +-
 src/core/core.datasetController.js |  8 ++++++--
 src/core/core.interaction.js       | 10 +++++-----
 src/core/core.scale.js             | 11 ++++++-----
 src/helpers/helpers.dom.js         |  7 +++----
 src/platform/platform.base.js      |  8 ++++----
 src/plugins/plugin.filler.js       |  2 +-
 src/plugins/plugin.legend.js       |  4 ++--
 src/plugins/plugin.tooltip.js      |  4 ++--
 src/scales/scale.linearbase.js     |  2 +-
 src/scales/scale.logarithmic.js    |  2 +-
 src/scales/scale.time.js           |  6 +++---
 12 files changed, 35 insertions(+), 31 deletions(-)

diff --git a/src/core/core.controller.js b/src/core/core.controller.js
index 3b98da087..ccae7a044 100644
--- a/src/core/core.controller.js
+++ b/src/core/core.controller.js
@@ -981,7 +981,7 @@ class Chart {
 	/**
 	 * Handle an event
 	 * @private
-	 * @param {IEvent} event the event to handle
+	 * @param {IEvent} e the event to handle
 	 * @return {boolean} true if the chart needs to re-render
 	 */
 	handleEvent(e) {
diff --git a/src/core/core.datasetController.js b/src/core/core.datasetController.js
index 2e1b31fb4..1f8a6e7d3 100644
--- a/src/core/core.datasetController.js
+++ b/src/core/core.datasetController.js
@@ -461,7 +461,7 @@ helpers.extend(DatasetController.prototype, {
 
 		// Re-sync meta data in case the user replaced the data array or if we missed
 		// any updates and so make sure that we handle number of datapoints changing.
-		me.resyncElements(dataChanged | labelsChanged | scaleChanged | stackChanged);
+		me.resyncElements(dataChanged || labelsChanged || scaleChanged || stackChanged);
 
 		// if stack changed, update stack values for the whole dataset
 		if (stackChanged) {
@@ -783,7 +783,10 @@ helpers.extend(DatasetController.prototype, {
 		me._cacheScaleStackStatus();
 	},
 
-	update: helpers.noop,
+	/**
+	 * @param {string} mode
+	 */
+	update: function(mode) {}, // eslint-disable-line no-unused-vars
 
 	draw: function() {
 		const ctx = this._ctx;
@@ -820,6 +823,7 @@ helpers.extend(DatasetController.prototype, {
 	 * Returns a set of predefined style properties that should be used to represent the dataset
 	 * or the data if the index is specified
 	 * @param {number} index - data index
+	 * @param {boolean} [active] - true if hover
 	 * @return {IStyleInterface} style object
 	 */
 	getStyle: function(index, active) {
diff --git a/src/core/core.interaction.js b/src/core/core.interaction.js
index 797dca4cd..8927636ec 100644
--- a/src/core/core.interaction.js
+++ b/src/core/core.interaction.js
@@ -6,7 +6,7 @@ import {_lookup, _rlookup} from '../helpers/helpers.collection';
 
 /**
  * Helper function to get relative position for an event
- * @param {Event|IEvent} event - The event to get the position for
+ * @param {Event|IEvent} e - The event to get the position for
  * @param {Chart} chart - The chart
  * @returns {object} the event position
  */
@@ -47,7 +47,7 @@ function evaluateAllVisibleItems(chart, handler) {
  * @param {string} axis - the axis mide. x|y|xy
  * @param {number} value - the value to find
  * @param {boolean} intersect - should the element intersect
- * @returns {lo, hi} indices to search data array between
+ * @returns {{lo:number, hi:number}} indices to search data array between
  */
 function binarySearch(metaset, axis, value, intersect) {
 	const {controller, data, _sorted} = metaset;
@@ -79,7 +79,7 @@ function binarySearch(metaset, axis, value, intersect) {
  * @param {string} axis - the axis mode. x|y|xy
  * @param {object} position - the point to be nearest to
  * @param {function} handler - the callback to execute for each visible item
- * @param {boolean} intersect - consider intersecting items
+ * @param {boolean} [intersect] - consider intersecting items
  */
 function optimizedEvaluateItems(chart, axis, position, handler, intersect) {
 	const metasets = chart._getSortedVisibleDatasetMetas();
@@ -140,8 +140,8 @@ function getIntersectItems(chart, position, axis) {
  * Helper function to get the items nearest to the event position considering all visible items in the chart
  * @param {Chart} chart - the chart to look at elements from
  * @param {object} position - the point to be nearest to
- * @param {function} axis - the axes along which to measure distance
- * @param {boolean} intersect - if true, only consider items that intersect the position
+ * @param {string} axis - the axes along which to measure distance
+ * @param {boolean} [intersect] - if true, only consider items that intersect the position
  * @return {ChartElement[]} the nearest items
  */
 function getNearestItems(chart, position, axis, intersect) {
diff --git a/src/core/core.scale.js b/src/core/core.scale.js
index 9cd20d1c1..92e6d7089 100644
--- a/src/core/core.scale.js
+++ b/src/core/core.scale.js
@@ -299,7 +299,7 @@ class Scale extends Element {
 	 * Get the padding needed for the scale
 	 * @method getPadding
 	 * @private
-	 * @returns {Padding} the necessary padding
+	 * @returns {object} the necessary padding
 	 */
 	getPadding() {
 		const me = this;
@@ -491,6 +491,9 @@ class Scale extends Element {
 	beforeBuildTicks() {
 		call(this.options.beforeBuildTicks, [this]);
 	}
+	/**
+	 * @return {object[]} the ticks
+	 */
 	buildTicks() {}
 	afterBuildTicks() {
 		call(this.options.afterBuildTicks, [this]);
@@ -800,17 +803,15 @@ class Scale extends Element {
 	 * Returns the location of the given data point. Value can either be an index or a numerical value
 	 * The coordinate (0, 0) is at the upper-left corner of the canvas
 	 * @param value
-	 * @param index
-	 * @param datasetIndex
 	 */
-	getPixelForValue() {}
+	getPixelForValue(value) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * Used to get the data value from a given pixel. This is the inverse of getPixelForValue
 	 * The coordinate (0, 0) is at the upper-left corner of the canvas
 	 * @param pixel
 	 */
-	getValueForPixel() {}
+	getValueForPixel(pixel) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * Returns the location of the tick at the given index
diff --git a/src/helpers/helpers.dom.js b/src/helpers/helpers.dom.js
index 4db17b6dc..899dc086b 100644
--- a/src/helpers/helpers.dom.js
+++ b/src/helpers/helpers.dom.js
@@ -39,6 +39,7 @@ function parseMaxStyle(styleValue, node, parentProperty) {
  * @param {HTMLElement} domNode - the node to check the constraint on
  * @param {string} maxStyle - the style that defines the maximum for the direction we are using ('max-width' / 'max-height')
  * @param {string} percentageProperty - property of parent to use when calculating width as a percentage
+ * @return {number|undefined} number or undefined if no constraint
  * @see {@link https://www.nathanaeljones.com/blog/2013/reading-max-width-cross-browser}
  */
 function getConstraintDimension(domNode, maxStyle, percentageProperty) {
@@ -55,8 +56,6 @@ function getConstraintDimension(domNode, maxStyle, percentageProperty) {
 			hasCNode ? parseMaxStyle(constrainedNode, domNode, percentageProperty) : infinity,
 			hasCContainer ? parseMaxStyle(constrainedContainer, parentNode, percentageProperty) : infinity);
 	}
-
-	return 'none';
 }
 
 export function getStyle(el, property) {
@@ -65,12 +64,12 @@ export function getStyle(el, property) {
 		document.defaultView.getComputedStyle(el, null).getPropertyValue(property);
 }
 
-// returns Number or undefined if no constraint
+/** @return {number|undefined} number or undefined if no constraint */
 function getConstraintWidth(domNode) {
 	return getConstraintDimension(domNode, 'max-width', 'clientWidth');
 }
 
-// returns Number or undefined if no constraint
+/** @return {number|undefined} number or undefined if no constraint */
 function getConstraintHeight(domNode) {
 	return getConstraintDimension(domNode, 'max-height', 'clientHeight');
 }
diff --git a/src/platform/platform.base.js b/src/platform/platform.base.js
index 5ef81f744..3a62403ef 100644
--- a/src/platform/platform.base.js
+++ b/src/platform/platform.base.js
@@ -16,7 +16,7 @@ export default class BasePlatform {
 	 * @param {object} options - The chart options
 	 * @returns {CanvasRenderingContext2D} context2d instance
 	 */
-	acquireContext() {}
+	acquireContext(canvas, options) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * Called at chart destruction time, releases any resources associated to the context
@@ -24,7 +24,7 @@ export default class BasePlatform {
 	 * @param {CanvasRenderingContext2D} context - The context2d instance
 	 * @returns {boolean} true if the method succeeded, else false
 	 */
-	releaseContext() {}
+	releaseContext(context) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * Registers the specified listener on the given chart.
@@ -33,7 +33,7 @@ export default class BasePlatform {
 	 * @param {function} listener - Receives a notification (an object that implements
 	 * the {@link IEvent} interface) when an event of the specified type occurs.
 	 */
-	addEventListener() {}
+	addEventListener(chart, type, listener) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * Removes the specified listener previously registered with addEventListener.
@@ -41,7 +41,7 @@ export default class BasePlatform {
 	 * @param {string} type - The ({@link IEvent}) type to remove
 	 * @param {function} listener - The listener function to remove from the event target.
 	 */
-	removeEventListener() {}
+	removeEventListener(chart, type, listener) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * @returns {number} the current devicePixelRatio of the device this platform is connected to.
diff --git a/src/plugins/plugin.filler.js b/src/plugins/plugin.filler.js
index 03ea9dcaa..f9343c655 100644
--- a/src/plugins/plugin.filler.js
+++ b/src/plugins/plugin.filler.js
@@ -47,7 +47,7 @@ function parseFillOption(line) {
 // @todo if (fill[0] === '#')
 function decodeFill(line, index, count) {
 	const fill = parseFillOption(line);
-	let target = parseFloat(fill, 10);
+	let target = parseFloat(fill);
 
 	if (isFinite(target) && Math.floor(target) === target) {
 		if (fill[0] === '-' || fill[0] === '+') {
diff --git a/src/plugins/plugin.legend.js b/src/plugins/plugin.legend.js
index 62c13efe1..4c0ebb4d3 100644
--- a/src/plugins/plugin.legend.js
+++ b/src/plugins/plugin.legend.js
@@ -83,7 +83,7 @@ defaults._set('legend', {
 
 /**
  * Helper function to get the box width based on the usePointStyle option
- * @param {object} labelopts - the label options on the legend
+ * @param {object} labelOpts - the label options on the legend
  * @param {number} fontSize - the label font size
  * @return {number} width of the color box area
  */
@@ -616,8 +616,8 @@ class Legend extends Element {
 
 	/**
 	 * Handle an event
+	 * @param {IEvent} e - The event to handle
 	 * @private
-	 * @param {IEvent} event - The event to handle
 	 */
 	handleEvent(e) {
 		var me = this;
diff --git a/src/plugins/plugin.tooltip.js b/src/plugins/plugin.tooltip.js
index a1ef6f181..4659ded29 100644
--- a/src/plugins/plugin.tooltip.js
+++ b/src/plugins/plugin.tooltip.js
@@ -199,7 +199,7 @@ function pushOrConcat(base, toPush) {
 
 /**
  * Returns array of strings split by newline
- * @param {string} value - The value to split by newline.
+ * @param {string} str - The value to split by newline.
  * @returns {string[]} value if newline present - Returned from String split() method
  * @function
  */
@@ -959,7 +959,7 @@ class Tooltip extends Element {
 	/**
 	 * Handle an event
 	 * @private
-	 * @param {IEvent} event - The event to handle
+	 * @param {IEvent} e - The event to handle
 	 * @returns {boolean} true if the tooltip changed
 	 */
 	handleEvent(e) {
diff --git a/src/scales/scale.linearbase.js b/src/scales/scale.linearbase.js
index 0932642dd..7ebbec014 100644
--- a/src/scales/scale.linearbase.js
+++ b/src/scales/scale.linearbase.js
@@ -37,7 +37,7 @@ function niceNum(range, round) {
  * Generate a set of linear ticks
  * @param generationOptions the options used to generate the ticks
  * @param dataRange the range of the data
- * @returns {number[]} array of tick values
+ * @returns {object[]} array of tick objects
  */
 function generateTicks(generationOptions, dataRange) {
 	const ticks = [];
diff --git a/src/scales/scale.logarithmic.js b/src/scales/scale.logarithmic.js
index 33de08c9b..2cd0d9f4a 100644
--- a/src/scales/scale.logarithmic.js
+++ b/src/scales/scale.logarithmic.js
@@ -19,7 +19,7 @@ function finiteOrDefault(value, def) {
  * Generate a set of logarithmic ticks
  * @param generationOptions the options used to generate the ticks
  * @param dataRange the range of the data
- * @returns {number[]} array of tick values
+ * @returns {object[]} array of tick objects
  */
 function generateTicks(generationOptions, dataRange) {
 	const endExp = Math.floor(log10(dataRange.max));
diff --git a/src/scales/scale.time.js b/src/scales/scale.time.js
index 8a3f20a07..d93b190db 100644
--- a/src/scales/scale.time.js
+++ b/src/scales/scale.time.js
@@ -430,9 +430,9 @@ function getLabelBounds(scale) {
 /**
  * Return subset of `timestamps` between `min` and `max`.
  * Timestamps are assumend to be in sorted order.
- * @param {int[]} timestamps - array of timestamps
- * @param {int} min - min value (timestamp)
- * @param {int} max - max value (timestamp)
+ * @param {number[]} timestamps - array of timestamps
+ * @param {number} min - min value (timestamp)
+ * @param {number} max - max value (timestamp)
  */
 function filterBetween(timestamps, min, max) {
 	let start = 0;
-- 
2.47.2