Review comments, additional fixes

Author: kurkle

docs/developers/plugins.md

@@ -104,6 +104,6 @@ var chart = new Chart(ctx, {
 });
 ```
 
- ## Plugin Core API
+## Plugin Core API
 
-Read more about the [existing plugin extension hooks](../jsdoc/IPlugin.html).
+Read more about the [existing plugin extension hooks](../typedoc/IPlugin.html).

docs/getting-started/v3-migration.md

@@ -93,6 +93,7 @@ Animation system was completely rewritten in Chart.js v3. Each property can now
 * `Chart.offsetY`
 * `Chart.outerRadius`
 * `Chart.prototype.generateLegend`
+* `Chart.radiusLength`
 * `Chart.types`
 * `Chart.Tooltip` is now provided by the tooltip plugin. The positioners can be accessed from `tooltipPlugin.positioners`
 * `DatasetController.addElementAndReset`

src/controllers/controller.doughnut.js

@@ -132,6 +132,10 @@ function getRatioAndOffset(rotation, circumference, cutout) {
 
 class DoughnutController extends DatasetController {
 
+	/**
+	 * @param {Chart} chart
+	 * @param {number} datasetIndex
+	 */
 	constructor(chart, datasetIndex) {
 		super(chart, datasetIndex);
 
@@ -145,6 +149,8 @@ class DoughnutController extends DatasetController {
 
 	/**
 	 * Override data parsing, since we are not using scales
+	 * @param {number} start
+	 * @param {number} count
 	 * @private
 	 */
 	_parse(start, count) {
@@ -156,7 +162,10 @@ class DoughnutController extends DatasetController {
 		}
 	}
 
-	// Get index of the dataset in relation to the visible datasets. This allows determining the inner and outer radius correctly
+	/**
+	 * Get index of the dataset in relation to the visible datasets. This allows determining the inner and outer radius correctly
+	 * @param {number} datasetIndex
+	 */
 	getRingIndex(datasetIndex) {
 		var ringIndex = 0;
 
@@ -174,7 +183,6 @@ class DoughnutController extends DatasetController {
 	 */
 	update(mode) {
 		const me = this;
-		/** @type {Chart} */
 		const chart = me.chart;
 		const {chartArea, options} = chart;
 		const meta = me._cachedMeta;
@@ -202,6 +210,9 @@ class DoughnutController extends DatasetController {
 
 	/**
 	 * @private
+	 * @param {number} i
+	 * @param {boolean} reset
+	 * @return {number}
 	 */
 	_circumference(i, reset) {
 		const me = this;
@@ -218,7 +229,6 @@ class DoughnutController extends DatasetController {
 	updateElements(arcs, start, mode) {
 		const me = this;
 		const reset = mode === 'reset';
-		/** @type {Chart} */
 		const chart = me.chart;
 		const chartArea = chart.chartArea;
 		const opts = chart.options;
@@ -260,6 +270,9 @@ class DoughnutController extends DatasetController {
 		me._updateSharedOptions(sharedOptions, mode);
 	}
 
+	/**
+	 * @return {number}
+	 */
 	calculateTotal() {
 		const meta = this._cachedMeta;
 		const metaData = meta.data;
@@ -278,6 +291,7 @@ class DoughnutController extends DatasetController {
 
 	/**
 	 * @param {number} value
+	 * @return {number}
 	 */
 	calculateCircumference(value) {
 		var total = this._cachedMeta.total;
@@ -288,8 +302,9 @@ class DoughnutController extends DatasetController {
 	}
 
 	/**
-	 * gets the max border or hover width to properly scale pie charts
+	 * Gets the max border or hover width to properly scale pie charts
 	 * @param {Arc[]} [arcs]
+	 * @return {number}
 	 */
 	getMaxBorderWidth(arcs) {
 		var me = this;
@@ -328,6 +343,7 @@ class DoughnutController extends DatasetController {
 	/**
 	 * Get radius length offset of the dataset in relation to the visible datasets weights. This allows determining the inner and outer radius correctly
 	 * @param {number} datasetIndex
+	 * @return {number}
 	 * @private
 	 */
 	_getRingWeightOffset(datasetIndex) {
@@ -344,6 +360,7 @@ class DoughnutController extends DatasetController {
 
 	/**
 	 * @param {number} datasetIndex
+	 * @return {number}
 	 * @private
 	 */
 	_getRingWeight(datasetIndex) {
@@ -352,6 +369,7 @@ class DoughnutController extends DatasetController {
 
 	/**
 	 * Returns the sum of all visibile data set weights.  This value can be 0.
+	 * @return {number}
 	 * @private
 	 */
 	_getVisibleDatasetWeightTotal() {

src/controllers/controller.polarArea.js

@@ -130,12 +130,12 @@ class PolarAreaController extends DatasetController {
 		var opts = chart.options;
 		var minSize = Math.min(chartArea.right - chartArea.left, chartArea.bottom - chartArea.top);
 
-		chart.outerRadius = Math.max(minSize / 2, 0);
-		chart.innerRadius = Math.max(opts.cutoutPercentage ? (chart.outerRadius / 100) * (opts.cutoutPercentage) : 1, 0);
-		chart.radiusLength = (chart.outerRadius - chart.innerRadius) / chart.getVisibleDatasetCount();
+		const outerRadius = Math.max(minSize / 2, 0);
+		const innerRadius = Math.max(opts.cutoutPercentage ? (outerRadius / 100) * (opts.cutoutPercentage) : 1, 0);
+		const radiusLength = (outerRadius - innerRadius) / chart.getVisibleDatasetCount();
 
-		me.outerRadius = chart.outerRadius - (chart.radiusLength * me.index);
-		me.innerRadius = me.outerRadius - chart.radiusLength;
+		me.outerRadius = outerRadius - (radiusLength * me.index);
+		me.innerRadius = me.outerRadius - radiusLength;
 	}
 
 	updateElements(arcs, start, mode) {

src/core/core.controller.js

@@ -12,6 +12,7 @@ import scaleService from '../core/core.scaleService';
 
 /**
  * @typedef { import("../platform/platform.base").IEvent } IEvent
+ * @typedef { import("./core.interaction").InteractionItem} InteractionItem
  */
 
 const valueOrDefault = helpers.valueOrDefault;
@@ -790,10 +791,11 @@ class Chart {
 	}
 
 	/**
-	 * @param {IEvent} e
-	 * @param {string} mode
-	 * @param {any} options
-	 * @param {boolean} [useFinalPosition]
+	 * @param {IEvent} e - the event
+	 * @param {string} mode - interaction mode
+	 * @param {import('./core.interaction').InteractionOptions} options - options
+	 * @param {boolean} [useFinalPosition] - evaluate elements by their final position (animation target)
+	 * @return {InteractionItem[]}
 	 */
 	getElementsAtEventForMode(e, mode, options, useFinalPosition) {
 		const method = Interaction.modes[mode];
@@ -969,7 +971,7 @@ class Chart {
 	}
 
 	/**
-	 * @param {{datasetIndex: number, index: number, element: Element}[]} items
+	 * @param {InteractionItem[]} items
 	 * @param {string} mode
 	 * @param {boolean} enabled
 	 */
@@ -1010,8 +1012,9 @@ class Chart {
 	}
 
 	/**
-	 * @param {IEvent} e
-	 * @param {boolean} [replay]
+	 * @param {IEvent} e - the event
+	 * @param {boolean} [replay] - true if the event was replayed by `update`
+	 * @return {Chart}
 	 * @private
 	 */
 	_eventHandler(e, replay) {
@@ -1033,22 +1036,23 @@ class Chart {
 	/**
 	 * Handle an event
 	 * @param {IEvent} e the event to handle
-	 * @param {boolean} [replay]
+	 * @param {boolean} [replay] - true if the event was replayed by `update`
 	 * @return {boolean} true if the chart needs to re-render
 	 * @private
 	 */
 	_handleEvent(e, replay) {
 		const me = this;
 		const options = me.options;
 		const hoverOptions = options.hover;
+		const useFinalPosition = replay;
 		let changed = false;
 
 		// Find Active Elements for hover and tooltips
 		if (e.type === 'mouseout') {
 			me.active = [];
 			me._lastEvent = null;
 		} else {
-			me.active = me.getElementsAtEventForMode(e, hoverOptions.mode, hoverOptions, replay);
+			me.active = me.getElementsAtEventForMode(e, hoverOptions.mode, hoverOptions, useFinalPosition);
 			me._lastEvent = e.type === 'click' ? me._lastEvent : e;
 		}
 

src/core/core.datasetController.js

@@ -5,6 +5,12 @@ import Animations from './core.animations';
 
 const resolve = helpers.options.resolve;
 
+/**
+ * @typedef { import("../core/core.controller").default } Chart
+ * @typedef { import("../core/core.element").default } Element
+ * @typedef {{ target: object, options: object }} SharedOptions
+ */
+
 const arrayEvents = ['push', 'pop', 'shift', 'splice', 'unshift'];
 
 /**
@@ -217,6 +223,10 @@ function getFirstScaleId(chart, axis) {
 
 class DatasetController {
 
+	/**
+	 * @param {Chart} chart
+	 * @param {number} datasetIndex
+	 */
 	constructor(chart, datasetIndex) {
 		this.chart = chart;
 		this._ctx = chart.ctx;
@@ -953,6 +963,10 @@ class DatasetController {
 
 	/**
 	 * Utility for checking if the options are shared and should be animated separately.
+	 * @param {string} mode
+	 * @param {Element} el
+	 * @param {{ $shared?: boolean }} options
+	 * @return {SharedOptions}
 	 * @private
 	 */
 	_getSharedOptions(mode, el, options) {
@@ -968,7 +982,8 @@ class DatasetController {
 	/**
 	 * Utility for determining if `options` should be included in the updated properties
 	 * @param {string} mode
-	 * @param {{ target: any; options: any; }} sharedOptions
+	 * @param {SharedOptions} sharedOptions
+	 * @return {boolean}
 	 * @private
 	 */
 	_includeOptions(mode, sharedOptions) {
@@ -980,7 +995,7 @@ class DatasetController {
 
 	/**
 	 * Utility for updating a element with new properties, using animations when appropriate.
-	 * @param {import("../core/core.element").default} element
+	 * @param {Element} element
 	 * @param {number} index
 	 * @param {object} properties
 	 * @param {string} mode
@@ -996,7 +1011,7 @@ class DatasetController {
 
 	/**
 	 * Utility to animate the shared options, that are potentially affecting multiple elements.
-	 * @param {{ target: any; options: any; }} sharedOptions
+	 * @param {SharedOptions} sharedOptions
 	 * @param {string} mode
 	 * @private
 	 */
@@ -1007,7 +1022,7 @@ class DatasetController {
 	}
 
 	/**
-	 * @param {import("../core/core.element").default} element
+	 * @param {Element} element
 	 * @param {number} index
 	 * @param {string} mode
 	 * @param {boolean} active
@@ -1019,7 +1034,7 @@ class DatasetController {
 	}
 
 	/**
-	 * @param {import("../core/core.element").default} element
+	 * @param {Element} element
 	 * @param {number} datasetIndex
 	 * @param {number} index
 	 */
@@ -1028,7 +1043,7 @@ class DatasetController {
 	}
 
 	/**
-	 * @param {import("../core/core.element").default} element
+	 * @param {Element} element
 	 * @param {number} datasetIndex
 	 * @param {number} index
 	 */
@@ -1105,7 +1120,12 @@ class DatasetController {
 		me.updateElements(elements, start, 'reset');
 	}
 
-	updateElements(element, start, mode) {} // eslint-disable-line no-unused-vars
+	/**
+	 * @param {Element[]} elements
+	 * @param {number} start
+	 * @param {string} mode
+	 */
+	updateElements(elements, start, mode) {} // eslint-disable-line no-unused-vars
 
 	/**
 	 * @private

src/core/core.element.js

@@ -3,16 +3,27 @@
 import {extend, inherits} from '../helpers/helpers.core';
 import {isNumber} from '../helpers/helpers.math';
 
+/**
+ * @typedef {import("./core.animation").default} Animation
+ */
+
 class Element {
 
 	/**
-	 * @param {object} [cfg] optional configuration
+	 * @param {{x?: number, y?: number, hidden?: boolean, active?: boolean, options?: object}} [cfg] optional configuration
 	 */
 	constructor(cfg) {
+		/** @type {number} */
 		this.x = undefined;
+		/** @type {number} */
 		this.y = undefined;
-		this.hidden = undefined;
-		this.active = undefined;
+		/** @type {boolean} */
+		this.hidden = false;
+		/** @type {boolean} */
+		this.active = false;
+		/** @type {object} */
+		this.options = undefined;
+		/** @type {Animation[]} */
 		this.$animations = undefined;
 
 		if (cfg) {