From 679f00746622a547626a293501e87582b49f57c0 Mon Sep 17 00:00:00 2001 From: mister-ben Date: Mon, 20 Feb 2023 10:05:20 +0100 Subject: [PATCH] fix(types): Improve Typescript coverage --- src/js/big-play-button.js | 6 +- src/js/button.js | 2 +- src/js/clickable-component.js | 8 +- src/js/close-button.js | 10 +- src/js/component.js | 102 ++++++++++++++-- .../audio-track-menu-item.js | 8 +- src/js/control-bar/fullscreen-toggle.js | 8 +- src/js/control-bar/live-display.js | 6 +- src/js/control-bar/mute-toggle.js | 8 +- .../control-bar/picture-in-picture-toggle.js | 8 +- src/js/control-bar/play-toggle.js | 14 ++- .../playback-rate-menu-button.js | 8 +- .../playback-rate-menu-item.js | 8 +- .../progress-control/load-progress-bar.js | 6 +- .../progress-control/mouse-time-display.js | 4 + .../progress-control/play-progress-bar.js | 4 + .../progress-control/progress-control.js | 14 ++- .../control-bar/progress-control/seek-bar.js | 19 +-- .../progress-control/time-tooltip.js | 4 + src/js/control-bar/seek-to-live.js | 4 + .../caption-settings-menu-item.js | 6 +- .../text-track-controls/captions-button.js | 6 +- .../text-track-controls/chapters-button.js | 10 +- .../chapters-track-menu-item.js | 6 +- .../descriptions-button.js | 8 +- .../off-text-track-menu-item.js | 6 +- .../text-track-controls/subs-caps-button.js | 17 +++ .../text-track-controls/subtitles-button.js | 6 +- .../text-track-controls/text-track-button.js | 4 + .../text-track-menu-item.js | 8 +- .../time-controls/current-time-display.js | 2 +- .../time-controls/duration-display.js | 6 +- .../time-controls/remaining-time-display.js | 6 +- .../control-bar/time-controls/time-display.js | 6 +- src/js/control-bar/track-button.js | 4 + .../volume-control/check-mute-support.js | 5 + .../volume-control/check-volume-support.js | 5 + .../mouse-volume-level-display.js | 4 + .../control-bar/volume-control/volume-bar.js | 11 +- .../volume-control/volume-control.js | 10 +- .../volume-control/volume-level-tooltip.js | 4 + src/js/control-bar/volume-panel.js | 12 +- src/js/error-display.js | 4 + src/js/event-target.js | 22 +++- src/js/live-tracker.js | 4 + src/js/menu/menu-button.js | 16 ++- src/js/menu/menu-item.js | 8 +- src/js/menu/menu.js | 10 +- src/js/modal-dialog.js | 29 +++-- src/js/player.js | 109 ++++++++++-------- src/js/plugin.js | 2 +- src/js/poster-image.js | 8 +- src/js/resize-manager.js | 2 +- src/js/slider/slider.js | 21 ++-- src/js/tech/html5.js | 6 +- src/js/tech/loader.js | 6 +- src/js/tech/middleware.js | 15 ++- src/js/tech/setup-sourceset.js | 4 + src/js/tech/tech.js | 53 +++++---- src/js/tracks/audio-track-list.js | 4 + src/js/tracks/audio-track.js | 2 +- src/js/tracks/html-track-element.js | 4 + src/js/tracks/text-track-display.js | 7 +- src/js/tracks/text-track-list-converter.js | 4 + src/js/tracks/text-track-list.js | 4 + src/js/tracks/text-track-settings.js | 8 +- src/js/tracks/text-track.js | 6 +- src/js/tracks/track-list.js | 12 +- src/js/tracks/track.js | 2 +- src/js/tracks/video-track-list.js | 4 + src/js/tracks/video-track.js | 2 +- src/js/types.js | 0 src/js/utils/buffer.js | 6 +- src/js/utils/create-logger.js | 10 +- src/js/utils/dom.js | 20 ++-- src/js/utils/events.js | 6 +- src/js/utils/filter-source.js | 4 + src/js/utils/fn.js | 2 +- src/js/utils/mimetypes.js | 4 + src/js/utils/obj.js | 12 +- src/js/utils/time.js | 6 +- 81 files changed, 619 insertions(+), 232 deletions(-) create mode 100644 src/js/types.js diff --git a/src/js/big-play-button.js b/src/js/big-play-button.js index c35b50a6ca..8e5ba9dafc 100644 --- a/src/js/big-play-button.js +++ b/src/js/big-play-button.js @@ -5,6 +5,10 @@ import Button from './button.js'; import Component from './component.js'; import {isPromise, silencePromise} from './utils/promise'; +/** + * @typedef {import('../event-target').Event} Event + */ + /** * The initial play button that shows before the video has played. The hiding of the * `BigPlayButton` get done via CSS and `Player` states. @@ -34,7 +38,7 @@ class BigPlayButton extends Button { * This gets called when a `BigPlayButton` "clicked". See {@link ClickableComponent} * for more detailed information on what a click can be. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/button.js b/src/js/button.js index b5e5f5dc1f..e2175733d8 100644 --- a/src/js/button.js +++ b/src/js/button.js @@ -104,7 +104,7 @@ class Button extends ClickableComponent { * This gets called when a `Button` has focus and `keydown` is triggered via a key * press. * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to get called. * * @listens keydown diff --git a/src/js/clickable-component.js b/src/js/clickable-component.js index da6229c3a2..031fb89c1a 100644 --- a/src/js/clickable-component.js +++ b/src/js/clickable-component.js @@ -6,6 +6,10 @@ import * as Dom from './utils/dom.js'; import log from './utils/log.js'; import keycode from 'keycode'; +/** + * @typedef { import('./player').default } Player + */ + /** * Component which is clickable or keyboard actionable, but is not a * native HTML button. @@ -212,7 +216,7 @@ class ClickableComponent extends Component { * Event handler that is called when a `ClickableComponent` receives a * `click` or `tap` event. * - * @param {EventTarget~Event} event + * @param {Event} event * The `tap` or `click` event that caused this function to be called. * * @listens tap @@ -231,7 +235,7 @@ class ClickableComponent extends Component { * * By default, if the key is Space or Enter, it will trigger a `click` event. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown diff --git a/src/js/close-button.js b/src/js/close-button.js index 89af076f9e..22179dc66e 100644 --- a/src/js/close-button.js +++ b/src/js/close-button.js @@ -5,6 +5,10 @@ import Button from './button'; import Component from './component'; import keycode from 'keycode'; +/** + * @typedef { import('./player').default } Player + */ + /** * The `CloseButton` is a `{@link Button}` that fires a `close` event when * it gets clicked. @@ -42,7 +46,7 @@ class CloseButton extends Button { * {@link ClickableComponent#handleClick} for more information on when * this will be triggered * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -56,7 +60,7 @@ class CloseButton extends Button { * Triggered when the a `CloseButton` is clicked. * * @event CloseButton#close - * @type {EventTarget~Event} + * @type {Event} * * @property {boolean} [bubbles=false] * set to false so that the close event does not @@ -70,7 +74,7 @@ class CloseButton extends Button { * * By default, if the key is Esc, it will trigger a `click` event. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown diff --git a/src/js/component.js b/src/js/component.js index 10bc7cc3be..48a67d06bd 100644 --- a/src/js/component.js +++ b/src/js/component.js @@ -13,6 +13,11 @@ import {toTitleCase, toLowerCase} from './utils/str.js'; import {merge} from './utils/obj.js'; import keycode from 'keycode'; +/** + * @typedef { import('./player').default } Player + * @typedef { import('./event-target').Event} Event +*/ + /** * Base class for all UI Components. * Components are UI objects which represent both a javascript object and an element @@ -27,7 +32,7 @@ class Component { * A callback that is called when a component is ready. Does not have any * parameters and any callback value will be ignored. * - * @callback Component~ReadyCallback + * @callback ReadyCallback * @this Component */ @@ -48,7 +53,7 @@ class Component { * @param {string} [options.className] * A class or space separated list of classes to add the component * - * @param {Component~ReadyCallback} [ready] + * @param {ReadyCallback} [ready] * Function that gets called when the `Component` is ready. */ constructor(player, options, ready) { @@ -95,6 +100,12 @@ class Component { options.className.split(' ').forEach(c => this.addClass(c)); } + // Remove the placeholder event methods. If the component is evented, the + // real methods are added next + ['on', 'off', 'one', 'any', 'trigger'].forEach(fn => { + this[fn] = undefined; + }); + // if evented is anything except false, we want to mixin in evented if (options.evented !== false) { // Make this an evented object and use `el_`, if available, as its event bus @@ -130,6 +141,79 @@ class Component { } + // `on`, `off`, `one`, `any` and `trigger` are here so tsc includes them in definitions. + // They are replaced or removed in the constructor + + /** + * Adds an `event listener` to an instance of an `EventTarget`. An `event listener` is a + * function that will get called when an event with a certain name gets triggered. + * + * @param {string|string[]} type + * An event name or an array of event names. + * + * @param {Function} fn + * The function to call with `EventTarget`s + */ + on(type, fn) {} + + /** + * Removes an `event listener` for a specific event from an instance of `EventTarget`. + * This makes it so that the `event listener` will no longer get called when the + * named event happens. + * + * @param {string|string[]} type + * An event name or an array of event names. + * + * @param {Function} fn + * The function to remove. + */ + off(type, fn) {} + + /** + * This function will add an `event listener` that gets triggered only once. After the + * first trigger it will get removed. This is like adding an `event listener` + * with {@link EventTarget#on} that calls {@link EventTarget#off} on itself. + * + * @param {string|string[]} type + * An event name or an array of event names. + * + * @param {Function} fn + * The function to be called once for each event name. + */ + one(type, fn) {} + + /** + * This function will add an `event listener` that gets triggered only once and is + * removed from all events. This is like adding an array of `event listener`s + * with {@link EventTarget#on} that calls {@link EventTarget#off} on all events the + * first time it is triggered. + * + * @param {string|string[]} type + * An event name or an array of event names. + * + * @param {Function} fn + * The function to be called once for each event name. + */ + any(type, fn) {} + + /** + * This function causes an event to happen. This will then cause any `event listeners` + * that are waiting for that event, to get called. If there are no `event listeners` + * for an event then nothing will happen. + * + * If the name of the `Event` that is being triggered is in `EventTarget.allowedEvents_`. + * Trigger will also call the `on` + `uppercaseEventName` function. + * + * Example: + * 'click' is in `EventTarget.allowedEvents_`, so, trigger will attempt to call + * `onClick` if it exists. + * + * @param {string|Event|Object} event + * The name of the event, an `Event`, or an object with a key of type set to + * an event name. + */ + trigger(event) {} + /** * Dispose of the `Component` and all child components. * @@ -153,7 +237,7 @@ class Component { * Triggered when a `Component` is disposed. * * @event Component#dispose - * @type {EventTarget~Event} + * @type {Event} * * @property {boolean} [bubbles=false] * set to false so that the dispose event does not @@ -700,7 +784,7 @@ class Component { * Different from event listeners in that if the ready event has already happened * it will trigger the function immediately. * - * @param {Component~ReadyCallback} fn + * @param {ReadyCallback} fn * Function that gets called when the `Component` is ready. * * @return {Component} @@ -751,7 +835,7 @@ class Component { * Triggered when a `Component` is ready. * * @event Component#ready - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('ready'); }, 1); @@ -1033,7 +1117,7 @@ class Component { * Triggered when a component is resized. * * @event Component#componentresize - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('componentresize'); } @@ -1169,7 +1253,7 @@ class Component { * When this Component receives a `keydown` event which it does not process, * it passes the event to the Player for handling. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. */ handleKeyDown(event) { @@ -1190,7 +1274,7 @@ class Component { * delegates to `handleKeyDown`. This means anyone calling `handleKeyPress` * will not see their method calls stop working. * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to be called. */ handleKeyPress(event) { @@ -1283,7 +1367,7 @@ class Component { * Triggered when a `Component` is tapped. * * @event Component#tap - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('tap'); // It may be good to copy the touchend event object and change the diff --git a/src/js/control-bar/audio-track-controls/audio-track-menu-item.js b/src/js/control-bar/audio-track-controls/audio-track-menu-item.js index c8dc28aa4b..4180435e62 100644 --- a/src/js/control-bar/audio-track-controls/audio-track-menu-item.js +++ b/src/js/control-bar/audio-track-controls/audio-track-menu-item.js @@ -5,6 +5,10 @@ import MenuItem from '../../menu/menu-item.js'; import Component from '../../component.js'; import * as Dom from '../../utils/dom.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * An {@link AudioTrack} {@link MenuItem} * @@ -68,7 +72,7 @@ class AudioTrackMenuItem extends MenuItem { * This gets called when an `AudioTrackMenuItem is "clicked". See {@link ClickableComponent} * for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -102,7 +106,7 @@ class AudioTrackMenuItem extends MenuItem { /** * Handle any {@link AudioTrack} change. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The {@link AudioTrackList#change} event that caused this to run. * * @listens AudioTrackList#change diff --git a/src/js/control-bar/fullscreen-toggle.js b/src/js/control-bar/fullscreen-toggle.js index 2a060a9ee2..ff4808af75 100644 --- a/src/js/control-bar/fullscreen-toggle.js +++ b/src/js/control-bar/fullscreen-toggle.js @@ -5,6 +5,10 @@ import Button from '../button.js'; import Component from '../component.js'; import document from 'global/document'; +/** + * @typedef { import('./player').default } Player + */ + /** * Toggle fullscreen video * @@ -43,7 +47,7 @@ class FullscreenToggle extends Button { /** * Handles fullscreenchange on the player and change control text accordingly. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The {@link Player#fullscreenchange} event that caused this function to be * called. * @@ -61,7 +65,7 @@ class FullscreenToggle extends Button { * This gets called when an `FullscreenToggle` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/control-bar/live-display.js b/src/js/control-bar/live-display.js index bf0a9c9408..34d377326b 100644 --- a/src/js/control-bar/live-display.js +++ b/src/js/control-bar/live-display.js @@ -5,6 +5,10 @@ import Component from '../component'; import * as Dom from '../utils/dom.js'; import document from 'global/document'; +/** + * @typedef { import('./player').default } Player + */ + // TODO - Future make it click to snap to live /** @@ -67,7 +71,7 @@ class LiveDisplay extends Component { * Check the duration to see if the LiveDisplay should be showing or not. Then show/hide * it accordingly * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The {@link Player#durationchange} event that caused this function to run. * * @listens Player#durationchange diff --git a/src/js/control-bar/mute-toggle.js b/src/js/control-bar/mute-toggle.js index 8e06e2c12f..562351ea23 100644 --- a/src/js/control-bar/mute-toggle.js +++ b/src/js/control-bar/mute-toggle.js @@ -7,6 +7,10 @@ import * as Dom from '../utils/dom.js'; import checkMuteSupport from './volume-control/check-mute-support'; import * as browser from '../utils/browser.js'; +/** + * @typedef { import('./player').default } Player + */ + /** * A button component for muting the audio. * @@ -46,7 +50,7 @@ class MuteToggle extends Button { * This gets called when an `MuteToggle` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -71,7 +75,7 @@ class MuteToggle extends Button { * Update the `MuteToggle` button based on the state of `volume` and `muted` * on the player. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The {@link Player#loadstart} event if this function was called * through an event. * diff --git a/src/js/control-bar/picture-in-picture-toggle.js b/src/js/control-bar/picture-in-picture-toggle.js index cadafbe041..7fb9745b3d 100644 --- a/src/js/control-bar/picture-in-picture-toggle.js +++ b/src/js/control-bar/picture-in-picture-toggle.js @@ -5,6 +5,10 @@ import Button from '../button.js'; import Component from '../component.js'; import document from 'global/document'; +/** + * @typedef { import('./player').default } Player + */ + /** * Toggle Picture-in-Picture mode * @@ -73,7 +77,7 @@ class PictureInPictureToggle extends Button { /** * Handles enterpictureinpicture and leavepictureinpicture on the player and change control text accordingly. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The {@link Player#enterpictureinpicture} or {@link Player#leavepictureinpicture} event that caused this function to be * called. * @@ -93,7 +97,7 @@ class PictureInPictureToggle extends Button { * This gets called when an `PictureInPictureToggle` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/control-bar/play-toggle.js b/src/js/control-bar/play-toggle.js index 8c79393068..d60a15d2c4 100644 --- a/src/js/control-bar/play-toggle.js +++ b/src/js/control-bar/play-toggle.js @@ -5,6 +5,10 @@ import Button from '../button.js'; import Component from '../component.js'; import {silencePromise} from '../utils/promise'; +/** + * @typedef { import('./player').default } Player + */ + /** * Button to toggle between play and pause. * @@ -49,7 +53,7 @@ class PlayToggle extends Button { * This gets called when an `PlayToggle` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -68,7 +72,7 @@ class PlayToggle extends Button { * This gets called once after the video has ended and the user seeks so that * we can change the replay button back to a play button. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#seeked @@ -86,7 +90,7 @@ class PlayToggle extends Button { /** * Add the vjs-playing class to the element so it can change appearance. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#play @@ -101,7 +105,7 @@ class PlayToggle extends Button { /** * Add the vjs-paused class to the element so it can change appearance. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#pause @@ -116,7 +120,7 @@ class PlayToggle extends Button { /** * Add the vjs-ended class to the element so it can change appearance * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#ended diff --git a/src/js/control-bar/playback-rate-menu/playback-rate-menu-button.js b/src/js/control-bar/playback-rate-menu/playback-rate-menu-button.js index 8a4c4a3d65..5c7a4fe0d9 100644 --- a/src/js/control-bar/playback-rate-menu/playback-rate-menu-button.js +++ b/src/js/control-bar/playback-rate-menu/playback-rate-menu-button.js @@ -6,6 +6,10 @@ import PlaybackRateMenuItem from './playback-rate-menu-item.js'; import Component from '../../component.js'; import * as Dom from '../../utils/dom.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The component for controlling the playback rate. * @@ -131,7 +135,7 @@ class PlaybackRateMenuButton extends MenuButton { /** * Hide playback rate controls when they're no playback rate options to select * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#loadstart @@ -147,7 +151,7 @@ class PlaybackRateMenuButton extends MenuButton { /** * Update button label when rate changed * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The event that caused this function to run. * * @listens Player#ratechange diff --git a/src/js/control-bar/playback-rate-menu/playback-rate-menu-item.js b/src/js/control-bar/playback-rate-menu/playback-rate-menu-item.js index 2fb31a9cf4..4fee03a00f 100644 --- a/src/js/control-bar/playback-rate-menu/playback-rate-menu-item.js +++ b/src/js/control-bar/playback-rate-menu/playback-rate-menu-item.js @@ -4,6 +4,10 @@ import MenuItem from '../../menu/menu-item.js'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The specific menu item type for selecting a playback rate. * @@ -42,7 +46,7 @@ class PlaybackRateMenuItem extends MenuItem { * This gets called when an `PlaybackRateMenuItem` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -57,7 +61,7 @@ class PlaybackRateMenuItem extends MenuItem { /** * Update the PlaybackRateMenuItem when the playbackrate changes. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `ratechange` event that caused this function to run. * * @listens Player#ratechange diff --git a/src/js/control-bar/progress-control/load-progress-bar.js b/src/js/control-bar/progress-control/load-progress-bar.js index 31d108eb30..50ae1fdfdd 100644 --- a/src/js/control-bar/progress-control/load-progress-bar.js +++ b/src/js/control-bar/progress-control/load-progress-bar.js @@ -6,6 +6,10 @@ import * as Dom from '../../utils/dom.js'; import {clamp} from '../../utils/num'; import document from 'global/document'; +/** + * @typedef { import('../../player').default } Player + */ + // get the percent width of a time compared to the total end const percentify = (time, end) => clamp((time / end) * 100, 0, 100).toFixed(2) + '%'; @@ -66,7 +70,7 @@ class LoadProgressBar extends Component { /** * Update progress bar * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `progress` event that caused this function to run. * * @listens Player#progress diff --git a/src/js/control-bar/progress-control/mouse-time-display.js b/src/js/control-bar/progress-control/mouse-time-display.js index 2b9140dc67..93a3526522 100644 --- a/src/js/control-bar/progress-control/mouse-time-display.js +++ b/src/js/control-bar/progress-control/mouse-time-display.js @@ -6,6 +6,10 @@ import * as Fn from '../../utils/fn.js'; import './time-tooltip'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The {@link MouseTimeDisplay} component tracks mouse movement over the * {@link ProgressControl}. It displays an indicator and a {@link TimeTooltip} diff --git a/src/js/control-bar/progress-control/play-progress-bar.js b/src/js/control-bar/progress-control/play-progress-bar.js index 08adb584de..ffa602309c 100644 --- a/src/js/control-bar/progress-control/play-progress-bar.js +++ b/src/js/control-bar/progress-control/play-progress-bar.js @@ -7,6 +7,10 @@ import * as Fn from '../../utils/fn.js'; import './time-tooltip'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Used by {@link SeekBar} to display media playback progress as part of the * {@link ProgressControl}. diff --git a/src/js/control-bar/progress-control/progress-control.js b/src/js/control-bar/progress-control/progress-control.js index 013ef5a0a3..75037af9c7 100644 --- a/src/js/control-bar/progress-control/progress-control.js +++ b/src/js/control-bar/progress-control/progress-control.js @@ -9,6 +9,10 @@ import {silencePromise} from '../../utils/promise'; import './seek-bar.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The Progress Control component contains the seek bar, load progress, * and play progress. @@ -52,7 +56,7 @@ class ProgressControl extends Component { * When the mouse moves over the `ProgressControl`, the pointer position * gets passed down to the `MouseTimeDisplay` component. * - * @param {EventTarget~Event} event + * @param {Event} event * The `mousemove` event that caused this function to run. * * @listen mousemove @@ -94,7 +98,7 @@ class ProgressControl extends Component { * A throttled version of the {@link ProgressControl#handleMouseSeek} listener. * * @method ProgressControl#throttledHandleMouseSeek - * @param {EventTarget~Event} event + * @param {Event} event * The `mousemove` event that caused this function to run. * * @listen mousemove @@ -104,7 +108,7 @@ class ProgressControl extends Component { /** * Handle `mousemove` or `touchmove` events on the `ProgressControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown` or `touchstart` event that triggered this function * * @listens mousemove @@ -191,7 +195,7 @@ class ProgressControl extends Component { /** * Handle `mousedown` or `touchstart` events on the `ProgressControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown` or `touchstart` event that triggered this function * * @listens mousedown @@ -214,7 +218,7 @@ class ProgressControl extends Component { /** * Handle `mouseup` or `touchend` events on the `ProgressControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mouseup` or `touchend` event that triggered this function. * * @listens touchend diff --git a/src/js/control-bar/progress-control/seek-bar.js b/src/js/control-bar/progress-control/seek-bar.js index 7c5e1fbc5f..b38f81fd50 100644 --- a/src/js/control-bar/progress-control/seek-bar.js +++ b/src/js/control-bar/progress-control/seek-bar.js @@ -15,6 +15,11 @@ import './load-progress-bar.js'; import './play-progress-bar.js'; import './mouse-time-display.js'; +/** + * @typedef { import('../../player').default } Player + * @typedef {import('../event-target').Event} Event + */ + // The number of seconds the `step*` functions move the timeline. const STEP_SECONDS = 5; @@ -129,7 +134,7 @@ class SeekBar extends Slider { * This function updates the play progress bar and accessibility * attributes to whatever is passed in. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `timeupdate` or `ended` event that caused this to run. * * @listens Player#timeupdate @@ -244,7 +249,7 @@ class SeekBar extends Slider { /** * Handle mouse down on seek bar * - * @param {EventTarget~Event} event + * @param {Event} event * The `mousedown` event that caused this to run. * * @listens mousedown @@ -266,7 +271,7 @@ class SeekBar extends Slider { /** * Handle mouse move on seek bar * - * @param {EventTarget~Event} event + * @param {Event} event * The `mousemove` event that caused this to run. * @param {boolean} mouseDown this is a flag that should be set to true if `handleMouseMove` is called directly. It allows us to skip things that should not happen if coming from mouse down but should happen on regular mouse move handler. Defaults to false * @@ -351,7 +356,7 @@ class SeekBar extends Slider { /** * Handle mouse up on seek bar * - * @param {EventTarget~Event} event + * @param {Event} event * The `mouseup` event that caused this to run. * * @listens mouseup @@ -370,7 +375,7 @@ class SeekBar extends Slider { * This is particularly useful for if the player is paused to time the time displays. * * @event Tech#timeupdate - * @type {EventTarget~Event} + * @type {Event} */ this.player_.trigger({ type: 'timeupdate', target: this, manuallyTriggered: true }); if (this.videoWasPlaying) { @@ -400,7 +405,7 @@ class SeekBar extends Slider { * Toggles the playback state of the player * This gets called when enter or space is used on the seekbar * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called * */ @@ -423,7 +428,7 @@ class SeekBar extends Slider { * PageDown key moves back a larger step than ArrowDown * PageUp key moves forward a large step * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown diff --git a/src/js/control-bar/progress-control/time-tooltip.js b/src/js/control-bar/progress-control/time-tooltip.js index c1cc863403..07bee63e61 100644 --- a/src/js/control-bar/progress-control/time-tooltip.js +++ b/src/js/control-bar/progress-control/time-tooltip.js @@ -6,6 +6,10 @@ import * as Dom from '../../utils/dom.js'; import {formatTime} from '../../utils/time.js'; import * as Fn from '../../utils/fn.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Time tooltips display a time above the progress bar. * diff --git a/src/js/control-bar/seek-to-live.js b/src/js/control-bar/seek-to-live.js index c6769fdec3..8ff5a4e7b1 100644 --- a/src/js/control-bar/seek-to-live.js +++ b/src/js/control-bar/seek-to-live.js @@ -5,6 +5,10 @@ import Button from '../button'; import Component from '../component'; import * as Dom from '../utils/dom.js'; +/** + * @typedef { import('./player').default } Player + */ + /** * Displays the live indicator when duration is Infinity. * diff --git a/src/js/control-bar/text-track-controls/caption-settings-menu-item.js b/src/js/control-bar/text-track-controls/caption-settings-menu-item.js index 095d8895a7..a41494f6f4 100644 --- a/src/js/control-bar/text-track-controls/caption-settings-menu-item.js +++ b/src/js/control-bar/text-track-controls/caption-settings-menu-item.js @@ -4,6 +4,10 @@ import TextTrackMenuItem from './text-track-menu-item.js'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The menu item for caption track settings menu * @@ -44,7 +48,7 @@ class CaptionSettingsMenuItem extends TextTrackMenuItem { * This gets called when an `CaptionSettingsMenuItem` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/control-bar/text-track-controls/captions-button.js b/src/js/control-bar/text-track-controls/captions-button.js index c03f1c8e04..11c2e90e71 100644 --- a/src/js/control-bar/text-track-controls/captions-button.js +++ b/src/js/control-bar/text-track-controls/captions-button.js @@ -5,6 +5,10 @@ import TextTrackButton from './text-track-button.js'; import Component from '../../component.js'; import CaptionSettingsMenuItem from './caption-settings-menu-item.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The button component for toggling and selecting captions * @@ -21,7 +25,7 @@ class CaptionsButton extends TextTrackButton { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function to call when this component is ready. */ constructor(player, options, ready) { diff --git a/src/js/control-bar/text-track-controls/chapters-button.js b/src/js/control-bar/text-track-controls/chapters-button.js index be047c774c..a002d25bda 100644 --- a/src/js/control-bar/text-track-controls/chapters-button.js +++ b/src/js/control-bar/text-track-controls/chapters-button.js @@ -6,6 +6,12 @@ import Component from '../../component.js'; import ChaptersTrackMenuItem from './chapters-track-menu-item.js'; import {toTitleCase} from '../../utils/str.js'; +/** + * @typedef { import('../../player').default } Player + * @typedef { import('../../menu/menu').default } Menu + * @typedef { import('../text-track-menu-item/menu/').default } TextTrackMenuItem + */ + /** * The button component for toggling and selecting chapters * Chapters act much differently than other text tracks @@ -24,7 +30,7 @@ class ChaptersButton extends TextTrackButton { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function to call when this function is ready. */ constructor(player, options, ready) { @@ -54,7 +60,7 @@ class ChaptersButton extends TextTrackButton { /** * Update the menu based on the current state of its items. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * An event that triggered this function to run. * * @listens TextTrackList#addtrack diff --git a/src/js/control-bar/text-track-controls/chapters-track-menu-item.js b/src/js/control-bar/text-track-controls/chapters-track-menu-item.js index 69ecb5ea93..da5a83f77f 100644 --- a/src/js/control-bar/text-track-controls/chapters-track-menu-item.js +++ b/src/js/control-bar/text-track-controls/chapters-track-menu-item.js @@ -4,6 +4,10 @@ import MenuItem from '../../menu/menu-item.js'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The chapter track menu item * @@ -40,7 +44,7 @@ class ChaptersTrackMenuItem extends MenuItem { * This gets called when an `ChaptersTrackMenuItem` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/control-bar/text-track-controls/descriptions-button.js b/src/js/control-bar/text-track-controls/descriptions-button.js index 6f67a70912..c2f8744033 100644 --- a/src/js/control-bar/text-track-controls/descriptions-button.js +++ b/src/js/control-bar/text-track-controls/descriptions-button.js @@ -5,6 +5,10 @@ import TextTrackButton from './text-track-button.js'; import Component from '../../component.js'; import * as Fn from '../../utils/fn.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The button component for toggling and selecting descriptions * @@ -21,7 +25,7 @@ class DescriptionsButton extends TextTrackButton { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function to call when this component is ready. */ constructor(player, options, ready) { @@ -39,7 +43,7 @@ class DescriptionsButton extends TextTrackButton { /** * Handle text track change * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to run * * @listens TextTrackList#change diff --git a/src/js/control-bar/text-track-controls/off-text-track-menu-item.js b/src/js/control-bar/text-track-controls/off-text-track-menu-item.js index ee0c6e6ed4..e862b8ff7b 100644 --- a/src/js/control-bar/text-track-controls/off-text-track-menu-item.js +++ b/src/js/control-bar/text-track-controls/off-text-track-menu-item.js @@ -4,6 +4,10 @@ import TextTrackMenuItem from './text-track-menu-item.js'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * A special menu item for turning of a specific type of text track * @@ -55,7 +59,7 @@ class OffTextTrackMenuItem extends TextTrackMenuItem { /** * Handle text track change * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to run */ handleTracksChange(event) { diff --git a/src/js/control-bar/text-track-controls/subs-caps-button.js b/src/js/control-bar/text-track-controls/subs-caps-button.js index 146f35a326..48ad1ac22f 100644 --- a/src/js/control-bar/text-track-controls/subs-caps-button.js +++ b/src/js/control-bar/text-track-controls/subs-caps-button.js @@ -6,6 +6,11 @@ import Component from '../../component.js'; import CaptionSettingsMenuItem from './caption-settings-menu-item.js'; import SubsCapsMenuItem from './subs-caps-menu-item.js'; import {toTitleCase} from '../../utils/str.js'; + +/** + * @typedef { import('../../player').default } Player + */ + /** * The button component for toggling and selecting captions and/or subtitles * @@ -13,6 +18,18 @@ import {toTitleCase} from '../../utils/str.js'; */ class SubsCapsButton extends TextTrackButton { + /** + * Creates an instance of this class. + * + * @param {Player} player + * The `Player` that this class should be attached to. + * + * @param {Object} [options] + * The key/value store of player options. + * + * @param {Function} [ready] + * The function to call when this component is ready. + */ constructor(player, options = {}) { super(player, options); diff --git a/src/js/control-bar/text-track-controls/subtitles-button.js b/src/js/control-bar/text-track-controls/subtitles-button.js index 4b6abdfb67..fe2666a43c 100644 --- a/src/js/control-bar/text-track-controls/subtitles-button.js +++ b/src/js/control-bar/text-track-controls/subtitles-button.js @@ -4,6 +4,10 @@ import TextTrackButton from './text-track-button.js'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The button component for toggling and selecting subtitles * @@ -20,7 +24,7 @@ class SubtitlesButton extends TextTrackButton { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function to call when this component is ready. */ constructor(player, options, ready) { diff --git a/src/js/control-bar/text-track-controls/text-track-button.js b/src/js/control-bar/text-track-controls/text-track-button.js index 181be2b8f9..2ab9d51747 100644 --- a/src/js/control-bar/text-track-controls/text-track-button.js +++ b/src/js/control-bar/text-track-controls/text-track-button.js @@ -6,6 +6,10 @@ import Component from '../../component.js'; import TextTrackMenuItem from './text-track-menu-item.js'; import OffTextTrackMenuItem from './off-text-track-menu-item.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The base class for buttons that toggle specific text track types (e.g. subtitles) * diff --git a/src/js/control-bar/text-track-controls/text-track-menu-item.js b/src/js/control-bar/text-track-controls/text-track-menu-item.js index 781d22a2e4..ef8a4120d2 100644 --- a/src/js/control-bar/text-track-controls/text-track-menu-item.js +++ b/src/js/control-bar/text-track-controls/text-track-menu-item.js @@ -6,6 +6,10 @@ import Component from '../../component.js'; import window from 'global/window'; import document from 'global/document'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The specific menu item type for selecting a language within a text track kind * @@ -89,7 +93,7 @@ class TextTrackMenuItem extends MenuItem { * This gets called when an `TextTrackMenuItem` is "clicked". See * {@link ClickableComponent} for more detailed information on what a click can be. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -133,7 +137,7 @@ class TextTrackMenuItem extends MenuItem { /** * Handle text track list change * - * @param {EventTarget~Event} event + * @param {Event} event * The `change` event that caused this function to be called. * * @listens TextTrackList#change diff --git a/src/js/control-bar/time-controls/current-time-display.js b/src/js/control-bar/time-controls/current-time-display.js index 02affe8cd4..34bfa3868b 100644 --- a/src/js/control-bar/time-controls/current-time-display.js +++ b/src/js/control-bar/time-controls/current-time-display.js @@ -24,7 +24,7 @@ class CurrentTimeDisplay extends TimeDisplay { /** * Update current time display * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `timeupdate` event that caused this function to run. * * @listens Player#timeupdate diff --git a/src/js/control-bar/time-controls/duration-display.js b/src/js/control-bar/time-controls/duration-display.js index bb73873b94..9f2f8e3d03 100644 --- a/src/js/control-bar/time-controls/duration-display.js +++ b/src/js/control-bar/time-controls/duration-display.js @@ -4,6 +4,10 @@ import TimeDisplay from './time-display'; import Component from '../../component.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Displays the duration * @@ -54,7 +58,7 @@ class DurationDisplay extends TimeDisplay { /** * Update duration time display. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `durationchange`, `timeupdate`, or `loadedmetadata` event that caused * this function to be called. * diff --git a/src/js/control-bar/time-controls/remaining-time-display.js b/src/js/control-bar/time-controls/remaining-time-display.js index e7a9d6fb74..5fa8fedaf3 100644 --- a/src/js/control-bar/time-controls/remaining-time-display.js +++ b/src/js/control-bar/time-controls/remaining-time-display.js @@ -5,6 +5,10 @@ import TimeDisplay from './time-display'; import Component from '../../component.js'; import * as Dom from '../../utils/dom.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Displays the time left in the video * @@ -54,7 +58,7 @@ class RemainingTimeDisplay extends TimeDisplay { /** * Update remaining time display. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `timeupdate` or `durationchange` event that caused this to run. * * @listens Player#timeupdate diff --git a/src/js/control-bar/time-controls/time-display.js b/src/js/control-bar/time-controls/time-display.js index d30284f398..0488150c2e 100644 --- a/src/js/control-bar/time-controls/time-display.js +++ b/src/js/control-bar/time-controls/time-display.js @@ -7,6 +7,10 @@ import * as Dom from '../../utils/dom.js'; import {formatTime} from '../../utils/time.js'; import log from '../../utils/log.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Displays time information about the video * @@ -120,7 +124,7 @@ class TimeDisplay extends Component { * To be filled out in the child class, should update the displayed time * in accordance with the fact that the current time has changed. * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `timeupdate` event that caused this to run. * * @listens Player#timeupdate diff --git a/src/js/control-bar/track-button.js b/src/js/control-bar/track-button.js index 3452f71ec6..8f74c7b56a 100644 --- a/src/js/control-bar/track-button.js +++ b/src/js/control-bar/track-button.js @@ -5,6 +5,10 @@ import MenuButton from '../menu/menu-button.js'; import Component from '../component.js'; import * as Fn from '../utils/fn.js'; +/** + * @typedef { import('./player').default } Player + */ + /** * The base class for buttons that toggle specific track types (e.g. subtitles). * diff --git a/src/js/control-bar/volume-control/check-mute-support.js b/src/js/control-bar/volume-control/check-mute-support.js index f5a6e1fbcf..7876f91bf2 100644 --- a/src/js/control-bar/volume-control/check-mute-support.js +++ b/src/js/control-bar/volume-control/check-mute-support.js @@ -1,3 +1,8 @@ +/** + * @typedef { import('../../player').default } Player + * @typedef { import('../../component').default } Component + */ + /** * Check if muting volume is supported and if it isn't hide the mute toggle * button. diff --git a/src/js/control-bar/volume-control/check-volume-support.js b/src/js/control-bar/volume-control/check-volume-support.js index df4a3c1e94..5d6cfa28ac 100644 --- a/src/js/control-bar/volume-control/check-volume-support.js +++ b/src/js/control-bar/volume-control/check-volume-support.js @@ -1,3 +1,8 @@ +/** + * @typedef { import('../../player').default } Player + * @typedef { import('../../component').default } Component + */ + /** * Check if volume control is supported and if it isn't hide the * `Component` that was passed using the `vjs-hidden` class. diff --git a/src/js/control-bar/volume-control/mouse-volume-level-display.js b/src/js/control-bar/volume-control/mouse-volume-level-display.js index 617693bd0b..f9b5d50d6e 100644 --- a/src/js/control-bar/volume-control/mouse-volume-level-display.js +++ b/src/js/control-bar/volume-control/mouse-volume-level-display.js @@ -1,3 +1,7 @@ +/** + * @typedef { import('../../player').default } Player + */ + /** * @file mouse-volume-level-display.js */ diff --git a/src/js/control-bar/volume-control/volume-bar.js b/src/js/control-bar/volume-control/volume-bar.js index 9824c1482c..46aac589f1 100644 --- a/src/js/control-bar/volume-control/volume-bar.js +++ b/src/js/control-bar/volume-control/volume-bar.js @@ -11,6 +11,11 @@ import {IS_IOS, IS_ANDROID} from '../../utils/browser.js'; import './volume-level.js'; import './mouse-volume-level-display.js'; +/** + * @typedef { import('../../player').default } Player + * @typedef {import('../../event-target').Event} Event + */ + /** * The bar that contains the volume level and can be clicked on to adjust the level * @@ -52,7 +57,7 @@ class VolumeBar extends Slider { /** * Handle mouse down on volume bar * - * @param {EventTarget~Event} event + * @param {Event} event * The `mousedown` event that caused this to run. * * @listens mousedown @@ -68,7 +73,7 @@ class VolumeBar extends Slider { /** * Handle movement events on the {@link VolumeMenuButton}. * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to run. * * @listens mousemove @@ -140,7 +145,7 @@ class VolumeBar extends Slider { /** * Update ARIA accessibility attributes * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `volumechange` event that caused this function to run. * * @listens Player#volumechange diff --git a/src/js/control-bar/volume-control/volume-control.js b/src/js/control-bar/volume-control/volume-control.js index 61ff1c4b91..889249a404 100644 --- a/src/js/control-bar/volume-control/volume-control.js +++ b/src/js/control-bar/volume-control/volume-control.js @@ -9,6 +9,10 @@ import {throttle, bind_, UPDATE_REFRESH_INTERVAL} from '../../utils/fn.js'; // Required children import './volume-bar.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * The component for controlling the volume level * @@ -83,7 +87,7 @@ class VolumeControl extends Component { /** * Handle `mousedown` or `touchstart` events on the `VolumeControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown` or `touchstart` event that triggered this function * * @listens mousedown @@ -101,7 +105,7 @@ class VolumeControl extends Component { /** * Handle `mouseup` or `touchend` events on the `VolumeControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mouseup` or `touchend` event that triggered this function. * * @listens touchend @@ -119,7 +123,7 @@ class VolumeControl extends Component { /** * Handle `mousedown` or `touchstart` events on the `VolumeControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown` or `touchstart` event that triggered this function * * @listens mousedown diff --git a/src/js/control-bar/volume-control/volume-level-tooltip.js b/src/js/control-bar/volume-control/volume-level-tooltip.js index 3fc35c343e..12310ef673 100644 --- a/src/js/control-bar/volume-control/volume-level-tooltip.js +++ b/src/js/control-bar/volume-control/volume-level-tooltip.js @@ -5,6 +5,10 @@ import Component from '../../component'; import * as Dom from '../../utils/dom.js'; import * as Fn from '../../utils/fn.js'; +/** + * @typedef { import('../../player').default } Player + */ + /** * Volume level tooltips display a volume above or side by side the volume bar. * diff --git a/src/js/control-bar/volume-panel.js b/src/js/control-bar/volume-panel.js index b51a1db62a..e1eb9c84bd 100644 --- a/src/js/control-bar/volume-panel.js +++ b/src/js/control-bar/volume-panel.js @@ -7,6 +7,10 @@ import * as Events from '../utils/events.js'; import keycode from 'keycode'; import document from 'global/document'; +/** + * @typedef { import('./player').default } Player + */ + // Required children import './volume-control/volume-control.js'; import './mute-toggle.js'; @@ -132,7 +136,7 @@ class VolumePanel extends Component { * Handles `keyup` events on the `VolumeControl`, looking for ESC, which closes * the volume panel and sets focus on `MuteToggle`. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keyup` event that caused this function to be called. * * @listens keyup @@ -148,7 +152,7 @@ class VolumePanel extends Component { * Turns on listening for `mouseover` event. When they happen it * calls `this.handleMouseOver`. * - * @param {EventTarget~Event} event + * @param {Event} event * The `mouseover` event that caused this function to be called. * * @listens mouseover @@ -163,7 +167,7 @@ class VolumePanel extends Component { * Turns on listening for `mouseout` event. When they happen it * calls `this.handleMouseOut`. * - * @param {EventTarget~Event} event + * @param {Event} event * The `mouseout` event that caused this function to be called. * * @listens mouseout @@ -177,7 +181,7 @@ class VolumePanel extends Component { * Handles `keyup` event on the document or `keydown` event on the `VolumePanel`, * looking for ESC, which hides the `VolumeControl`. * - * @param {EventTarget~Event} event + * @param {Event} event * The keypress that triggered this event. * * @listens keydown | keyup diff --git a/src/js/error-display.js b/src/js/error-display.js index 69767ecb4e..676bf24454 100644 --- a/src/js/error-display.js +++ b/src/js/error-display.js @@ -4,6 +4,10 @@ import Component from './component'; import ModalDialog from './modal-dialog'; +/** + * @typedef { import('./player').default } Player + */ + /** * A display that indicates an error has occurred. This means that the video * is unplayable. diff --git a/src/js/event-target.js b/src/js/event-target.js index edd5b197bf..c76769c697 100644 --- a/src/js/event-target.js +++ b/src/js/event-target.js @@ -22,7 +22,7 @@ class EventTarget { * @param {string|string[]} type * An event name or an array of event names. * - * @param {EventTarget~EventListener} fn + * @param {Function} fn * The function to call with `EventTarget`s */ on(type, fn) { @@ -42,7 +42,7 @@ class EventTarget { * @param {string|string[]} type * An event name or an array of event names. * - * @param {EventTarget~EventListener} fn + * @param {Function} fn * The function to remove. */ off(type, fn) { @@ -56,7 +56,7 @@ class EventTarget { * @param {string|string[]} type * An event name or an array of event names. * - * @param {EventTarget~EventListener} fn + * @param {Function} fn * The function to be called once for each event name. */ one(type, fn) { @@ -68,6 +68,18 @@ class EventTarget { Events.one(this, type, fn); this.addEventListener = ael; } + /** + * This function will add an `event listener` that gets triggered only once and is + * removed from all events. This is like adding an array of `event listener`s + * with {@link EventTarget#on} that calls {@link EventTarget#off} on all events the + * first time it is triggered. + * + * @param {string|string[]} type + * An event name or an array of event names. + * + * @param {Function} fn + * The function to be called once for each event name. + */ any(type, fn) { // Remove the addEventListener aliasing Events.on // so we don't get into an infinite type loop @@ -149,7 +161,7 @@ class EventTarget { /** * A Custom DOM event. * - * @typedef {EventTarget} Event + * @typedef {CustomEvent} Event * @see [Properties]{@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent} */ @@ -159,7 +171,7 @@ class EventTarget { * @callback EventTarget~EventListener * @this {EventTarget} * - * @param {EventTarget~Event} event + * @param {Event} event * the event that triggered this function * * @param {Object} [hash] diff --git a/src/js/live-tracker.js b/src/js/live-tracker.js index 256234bbe3..c90bf8dbfe 100644 --- a/src/js/live-tracker.js +++ b/src/js/live-tracker.js @@ -3,6 +3,10 @@ import {merge} from './utils/obj.js'; import window from 'global/window'; import * as Fn from './utils/fn.js'; +/** + * @typedef { import('./player').default } Player + */ + const defaults = { trackingThreshold: 20, liveTolerance: 15 diff --git a/src/js/menu/menu-button.js b/src/js/menu/menu-button.js index 0a101ee3e1..7b8ad9aa3f 100644 --- a/src/js/menu/menu-button.js +++ b/src/js/menu/menu-button.js @@ -11,6 +11,10 @@ import { IS_IOS } from '../utils/browser.js'; import document from 'global/document'; import keycode from 'keycode'; +/** + * @typedef { import('../player').default } Player + */ + /** * A `MenuButton` class for any popup {@link Menu}. * @@ -231,7 +235,7 @@ class MenuButton extends Component { * Handle a click on a `MenuButton`. * See {@link ClickableComponent#handleClick} for instances where this is called. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown`, `tap`, or `click` event that caused this function to be * called. * @@ -249,7 +253,7 @@ class MenuButton extends Component { /** * Handle `mouseleave` for `MenuButton`. * - * @param {EventTarget~Event} event + * @param {Event} event * The `mouseleave` event that caused this function to be called. * * @listens mouseleave @@ -277,7 +281,7 @@ class MenuButton extends Component { * Handle tab, escape, down arrow, and up arrow keys for `MenuButton`. See * {@link ClickableComponent#handleKeyDown} for instances where this is called. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown @@ -309,7 +313,7 @@ class MenuButton extends Component { * Handle a `keyup` event on a `MenuButton`. The listener for this is added in * the constructor. * - * @param {EventTarget~Event} event + * @param {Event} event * Key press event * * @listens keyup @@ -326,7 +330,7 @@ class MenuButton extends Component { * anyone calling `handleSubmenuKeyPress` will not see their method calls * stop working. * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to be called. */ handleSubmenuKeyPress(event) { @@ -337,7 +341,7 @@ class MenuButton extends Component { * Handle a `keydown` event on a sub-menu. The listener for this is added in * the constructor. * - * @param {EventTarget~Event} event + * @param {Event} event * Key press event * * @listens keydown diff --git a/src/js/menu/menu-item.js b/src/js/menu/menu-item.js index 7a95e19a52..ce961185a0 100644 --- a/src/js/menu/menu-item.js +++ b/src/js/menu/menu-item.js @@ -7,6 +7,10 @@ import {MenuKeys} from './menu-keys.js'; import keycode from 'keycode'; import {createEl} from '../utils/dom.js'; +/** + * @typedef { import('../player').default } Player + */ + /** * The component for a menu item. `
  • ` * @@ -81,7 +85,7 @@ class MenuItem extends ClickableComponent { * Ignore keys which are used by the menu, but pass any other ones up. See * {@link ClickableComponent#handleKeyDown} for instances where this is called. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown @@ -97,7 +101,7 @@ class MenuItem extends ClickableComponent { * Any click on a `MenuItem` puts it into the selected state. * See {@link ClickableComponent#handleClick} for instances where this is called. * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown`, `tap`, or `click` event that caused this function to be * called. * diff --git a/src/js/menu/menu.js b/src/js/menu/menu.js index b0d05c1469..8b471d34a4 100644 --- a/src/js/menu/menu.js +++ b/src/js/menu/menu.js @@ -7,6 +7,10 @@ import * as Dom from '../utils/dom.js'; import * as Events from '../utils/events.js'; import keycode from 'keycode'; +/** + * @typedef { import('../player').default } Player + */ + /** * The Menu component is used to build popup menus, including subtitle and * captions selection menus. @@ -149,7 +153,7 @@ class Menu extends Component { /** * Called when a `MenuItem` loses focus. * - * @param {EventTarget~Event} event + * @param {Event} event * The `blur` event that caused this function to be called. * * @listens blur @@ -172,7 +176,7 @@ class Menu extends Component { /** * Called when a `MenuItem` gets clicked or tapped. * - * @param {EventTarget~Event} event + * @param {Event} event * The `click` or `tap` event that caused this function to be called. * * @listens click,tap @@ -205,7 +209,7 @@ class Menu extends Component { /** * Handle a `keydown` event on this menu. This listener is added in the constructor. * - * @param {EventTarget~Event} event + * @param {Event} event * A `keydown` event that happened on the menu. * * @listens keydown diff --git a/src/js/modal-dialog.js b/src/js/modal-dialog.js index 1f825f1c48..e3560f96dd 100644 --- a/src/js/modal-dialog.js +++ b/src/js/modal-dialog.js @@ -7,6 +7,11 @@ import window from 'global/window'; import document from 'global/document'; import keycode from 'keycode'; +/** + * @typedef { import('./player').default } Player + * @typedef { import('./utils/dom').ContentDescriptor} ContentDescriptor + */ + const MODAL_CLASS_NAME = 'vjs-modal-dialog'; /** @@ -29,7 +34,7 @@ class ModalDialog extends Component { * @param {Object} [options] * The key/value store of player options. * - * @param {Mixed} [options.content=undefined] + * @param {ContentDescriptor} [options.content=undefined] * Provide customized content for this modal. * * @param {string} [options.description] @@ -163,7 +168,7 @@ class ModalDialog extends Component { * Fired just before a `ModalDialog` is opened. * * @event ModalDialog#beforemodalopen - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('beforemodalopen'); this.opened_ = true; @@ -196,7 +201,7 @@ class ModalDialog extends Component { * Fired just after a `ModalDialog` is opened. * * @event ModalDialog#modalopen - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('modalopen'); this.hasBeenOpened_ = true; @@ -236,7 +241,7 @@ class ModalDialog extends Component { * Fired just before a `ModalDialog` is closed. * * @event ModalDialog#beforemodalclose - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('beforemodalclose'); this.opened_ = false; @@ -258,7 +263,7 @@ class ModalDialog extends Component { * Fired just after a `ModalDialog` is closed. * * @event ModalDialog#modalclose - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('modalclose'); this.conditionalBlur_(); @@ -320,7 +325,7 @@ class ModalDialog extends Component { * @fires ModalDialog#beforemodalfill * @fires ModalDialog#modalfill * - * @param {Mixed} [content] + * @param {ContentDescriptor} [content] * The same rules apply to this as apply to the `content` option. */ fillWith(content) { @@ -332,7 +337,7 @@ class ModalDialog extends Component { * Fired just before a `ModalDialog` is filled with content. * * @event ModalDialog#beforemodalfill - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('beforemodalfill'); this.hasBeenFilled_ = true; @@ -346,7 +351,7 @@ class ModalDialog extends Component { * Fired just after a `ModalDialog` is filled with content. * * @event ModalDialog#modalfill - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('modalfill'); @@ -376,7 +381,7 @@ class ModalDialog extends Component { * Fired just before a `ModalDialog` is emptied. * * @event ModalDialog#beforemodalempty - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('beforemodalempty'); Dom.emptyEl(this.contentEl()); @@ -385,7 +390,7 @@ class ModalDialog extends Component { * Fired just after a `ModalDialog` is emptied. * * @event ModalDialog#modalempty - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('modalempty'); } @@ -397,12 +402,12 @@ class ModalDialog extends Component { * This does not update the DOM or fill the modal, but it is called during * that process. * - * @param {Mixed} [value] + * @param {ContentDescriptor} [value] * If defined, sets the internal content value to be used on the * next call(s) to `fill`. This value is normalized before being * inserted. To "clear" the internal content value, pass `null`. * - * @return {Mixed} + * @return {ContentDescriptor} * The current content of the modal dialog */ content(value) { diff --git a/src/js/player.js b/src/js/player.js index cc886944e4..da9f126d7a 100644 --- a/src/js/player.js +++ b/src/js/player.js @@ -55,6 +55,11 @@ import './title-bar.js'; // Import Html5 tech, at least for disposing the original video tag. import './tech/html5.js'; +/** + * @typedef { import('./tracks/html-track-element').default } HtmlTrackElement + * @typedef { import('./utils/time').TimeRange } TimeRange + */ + // The following tech events are simply re-triggered // on the player when they happen const TECH_EVENTS_RETRIGGER = [ @@ -62,7 +67,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fired while the user agent is downloading media data. * * @event Player#progress - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `progress` event that was triggered by the {@link Tech}. @@ -78,7 +83,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fires when the loading of an audio/video is aborted. * * @event Player#abort - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `abort` event that was triggered by the {@link Tech}. @@ -94,7 +99,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fires when the browser is intentionally not getting media data. * * @event Player#suspend - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `suspend` event that was triggered by the {@link Tech}. @@ -110,7 +115,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fires when the current playlist is empty. * * @event Player#emptied - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `emptied` event that was triggered by the {@link Tech}. @@ -125,7 +130,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fires when the browser is trying to get media data, but data is not available. * * @event Player#stalled - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `stalled` event that was triggered by the {@link Tech}. @@ -141,7 +146,7 @@ const TECH_EVENTS_RETRIGGER = [ * Fires when the browser has loaded meta data for the audio/video. * * @event Player#loadedmetadata - * @type {EventTarget~Event} + * @type {Event} */ /** * Retrigger the `loadedmetadata` event that was triggered by the {@link Tech}. @@ -283,11 +288,13 @@ const DEFAULT_BREAKPOINTS = { * An instance of the `Player` class is created when any of the Video.js setup methods * are used to initialize a video. * - * After an instance has been created it can be accessed globally in two ways: - * 1. By calling `videojs('example_video_1');` + * After an instance has been created it can be accessed globally in three ways: + * 1. By calling `videojs.getPlayer('example_video_1');` + * 2. By calling `videojs('example_video_1');` (not recomended) * 2. By using it directly via `videojs.players.example_video_1;` * * @extends Component + * @global */ class Player extends Component { @@ -300,7 +307,7 @@ class Player extends Component { * @param {Object} [options] * Object of option names and values. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * Ready callback function. */ constructor(tag, options, ready) { @@ -593,7 +600,7 @@ class Player extends Component { * Called when the player is being disposed of. * * @event Player#dispose - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('dispose'); // prevent dispose from being called twice @@ -1401,7 +1408,7 @@ class Player extends Component { * Fired when the user agent begins looking for media data * * @event Player#loadstart - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('loadstart'); } else { @@ -1564,7 +1571,7 @@ class Player extends Component { * __To use this, pass `enableSourceset` option to the player.__ * * @event Player#sourceset - * @type {EventTarget~Event} + * @type {Event} * @prop {string} src * The source url available when the `sourceset` was triggered. * It will be an empty string if we cannot know what the source is @@ -1675,7 +1682,7 @@ class Player extends Component { * playback has started or resumed. * * @event Player#play - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('play'); } @@ -1719,7 +1726,7 @@ class Player extends Component { * A readyState change on the DOM element has caused playback to stop. * * @event Player#waiting - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('waiting'); @@ -1750,7 +1757,7 @@ class Player extends Component { * The media has a readyState of HAVE_FUTURE_DATA or greater. * * @event Player#canplay - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('canplay'); } @@ -1769,7 +1776,7 @@ class Player extends Component { * entire media file can be played without buffering. * * @event Player#canplaythrough - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('canplaythrough'); } @@ -1787,7 +1794,7 @@ class Player extends Component { * The media is no longer blocked from playback, and has started playing. * * @event Player#playing - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('playing'); } @@ -1805,7 +1812,7 @@ class Player extends Component { * Fired whenever the player is jumping to a new time * * @event Player#seeking - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('seeking'); } @@ -1823,7 +1830,7 @@ class Player extends Component { * Fired when the player has finished jumping to a new time * * @event Player#seeked - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('seeked'); } @@ -1842,7 +1849,7 @@ class Player extends Component { * Fired whenever the media has been paused * * @event Player#pause - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('pause'); } @@ -1868,7 +1875,7 @@ class Player extends Component { * Fired when the end of the media resource is reached (currentTime == duration) * * @event Player#ended - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('ended'); } @@ -1886,7 +1893,7 @@ class Player extends Component { /** * Handle a click on the media element to play/pause * - * @param {EventTarget~Event} event + * @param {Event} event * the event that caused this function to trigger * * @listens Tech#click @@ -1925,7 +1932,7 @@ class Player extends Component { /** * Handle a double-click on the media element to enter/exit fullscreen * - * @param {EventTarget~Event} event + * @param {Event} event * the event that caused this function to trigger * * @listens Tech#dblclick @@ -2011,7 +2018,7 @@ class Player extends Component { /** * Handle touch to end * - * @param {EventTarget~Event} event + * @param {Event} event * the touchend event that triggered * this function * @@ -2063,7 +2070,7 @@ class Player extends Component { /** * Handle Tech Fullscreen Change * - * @param {EventTarget~Event} event + * @param {Event} event * the fullscreenchange event that triggered this function * * @param {Object} data @@ -2103,7 +2110,7 @@ class Player extends Component { /** * Handle Tech Enter Picture-in-Picture. * - * @param {EventTarget~Event} event + * @param {Event} event * the enterpictureinpicture event that triggered this function * * @private @@ -2116,7 +2123,7 @@ class Player extends Component { /** * Handle Tech Leave Picture-in-Picture. * - * @param {EventTarget~Event} event + * @param {Event} event * the leavepictureinpicture event that triggered this function * * @private @@ -2156,7 +2163,7 @@ class Player extends Component { * Fires when we get a textdata event from tech * * @event Player#textdata - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('textdata', data); } @@ -2530,7 +2537,7 @@ class Player extends Component { /** * @event Player#durationchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('durationchange'); } @@ -2570,7 +2577,7 @@ class Player extends Component { * @see [Buffered Spec]{@link http://dev.w3.org/html5/spec/video.html#dom-media-buffered} * * @return {TimeRange} - * A mock TimeRange object (following HTML spec) + * A mock {@link TimeRanges} object (following HTML spec) */ buffered() { let buffered = this.techGet_('buffered'); @@ -2758,7 +2765,7 @@ class Player extends Component { if (this.isFullscreen_ !== oldValue && this.fsApi_.prefixed) { /** * @event Player#fullscreenchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('fullscreenchange'); } @@ -2933,7 +2940,7 @@ class Player extends Component { /** * @event Player#enterFullWindow - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('enterFullWindow'); } @@ -2977,7 +2984,7 @@ class Player extends Component { // this.positionAll(); /** * @event Player#exitFullWindow - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('exitFullWindow'); } @@ -3036,7 +3043,7 @@ class Player extends Component { * This event fires when the player enters picture in picture mode * * @event Player#enterpictureinpicture - * @type {EventTarget~Event} + * @type {Event} */ return this.techGet_('requestPictureInPicture'); } @@ -3058,7 +3065,7 @@ class Player extends Component { * This event fires when the player leaves picture in picture mode * * @event Player#leavepictureinpicture - * @type {EventTarget~Event} + * @type {Event} */ return document.exitPictureInPicture(); } @@ -3070,7 +3077,7 @@ class Player extends Component { * This allows player-wide hotkeys (either as defined below, or optionally * by an external function). * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. * * @listens keydown @@ -3134,7 +3141,7 @@ class Player extends Component { * m - toggle mute * k or Space - toggle play/pause * - * @param {EventTarget~Event} event + * @param {Event} event * The `keydown` event that caused this function to be called. */ handleHotkeys(event) { @@ -3752,7 +3759,7 @@ class Player extends Component { * This event fires when the poster image is changed on the player. * * @event Player#posterchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('posterchange'); } @@ -3818,7 +3825,7 @@ class Player extends Component { this.addClass('vjs-controls-enabled'); /** * @event Player#controlsenabled - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('controlsenabled'); if (!this.usingNativeControls()) { @@ -3829,7 +3836,7 @@ class Player extends Component { this.addClass('vjs-controls-disabled'); /** * @event Player#controlsdisabled - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('controlsdisabled'); if (!this.usingNativeControls()) { @@ -3876,7 +3883,7 @@ class Player extends Component { * player is using the native device controls * * @event Player#usingnativecontrols - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('usingnativecontrols'); } else { @@ -3886,7 +3893,7 @@ class Player extends Component { * player is using the custom HTML controls * * @event Player#usingcustomcontrols - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('usingcustomcontrols'); } @@ -3964,7 +3971,7 @@ class Player extends Component { /** * @event Player#error - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('error'); @@ -4016,7 +4023,7 @@ class Player extends Component { this.addClass('vjs-user-active'); /** * @event Player#useractive - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('useractive'); return; @@ -4042,7 +4049,7 @@ class Player extends Component { this.addClass('vjs-user-inactive'); /** * @event Player#userinactive - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('userinactive'); } @@ -4513,7 +4520,7 @@ class Player extends Component { * fires when the player language change * * @event Player#languagechange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('languagechange'); } @@ -5010,7 +5017,7 @@ class Player extends Component { * fires when the playback rates in a player are changed * * @event Player#playbackrateschange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('playbackrateschange'); } @@ -5258,14 +5265,14 @@ TECH_EVENTS_RETRIGGER.forEach(function(event) { * Fired when the player has initial duration and dimension information * * @event Player#loadedmetadata - * @type {EventTarget~Event} + * @type {Event} */ /** * Fired when the player has downloaded data at the current playback position * * @event Player#loadeddata - * @type {EventTarget~Event} + * @type {Event} */ /** @@ -5274,14 +5281,14 @@ TECH_EVENTS_RETRIGGER.forEach(function(event) { * playback technology in use. * * @event Player#timeupdate - * @type {EventTarget~Event} + * @type {Event} */ /** * Fired when the volume changes * * @event Player#volumechange - * @type {EventTarget~Event} + * @type {Event} */ /** diff --git a/src/js/plugin.js b/src/js/plugin.js index d55698ad3c..53df33f573 100644 --- a/src/js/plugin.js +++ b/src/js/plugin.js @@ -295,7 +295,7 @@ class Plugin { * Signals that a advanced plugin is about to be disposed. * * @event Plugin#dispose - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('dispose'); this.off(); diff --git a/src/js/poster-image.js b/src/js/poster-image.js index 62b79d86da..3f7e9422a6 100644 --- a/src/js/poster-image.js +++ b/src/js/poster-image.js @@ -6,6 +6,10 @@ import Component from './component.js'; import * as Dom from './utils/dom.js'; import {silencePromise} from './utils/promise'; +/** + * @typedef { import('./player').default } Player + */ + /** * A `ClickableComponent` that handles showing the poster image for the player. * @@ -95,7 +99,7 @@ class PosterImage extends ClickableComponent { * * @listens Player#posterchange * - * @param {EventTarget~Event} [event] + * @param {Event} [event] * The `Player#posterchange` event that triggered this function. */ update(event) { @@ -155,7 +159,7 @@ class PosterImage extends ClickableComponent { * @listens click * @listens keydown * - * @param {EventTarget~Event} event + * @param {Event} event + The `click`, `tap` or `keydown` event that caused this function to be called. */ handleClick(event) { diff --git a/src/js/resize-manager.js b/src/js/resize-manager.js index 9d5949109a..e95a68de29 100644 --- a/src/js/resize-manager.js +++ b/src/js/resize-manager.js @@ -110,7 +110,7 @@ class ResizeManager extends Component { * Called when the player size has changed * * @event Player#playerresize - * @type {EventTarget~Event} + * @type {Event} */ // make sure player is still around to trigger // prevents this from causing an error after dispose diff --git a/src/js/slider/slider.js b/src/js/slider/slider.js index 5644a0a1f2..f05e1fff1f 100644 --- a/src/js/slider/slider.js +++ b/src/js/slider/slider.js @@ -7,6 +7,11 @@ import {IS_CHROME} from '../utils/browser.js'; import {clamp} from '../utils/num.js'; import keycode from 'keycode'; +/** + * @typedef { import('../player').default } Player + * @typedef {import('../event-target').Event} Event + */ + /** * The base functionality for a slider. Can be vertical or horizontal. * For instance the volume bar or the seek bar on a video is a slider. @@ -142,7 +147,7 @@ class Slider extends Component { /** * Handle `mousedown` or `touchstart` events on the `Slider`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown` or `touchstart` event that triggered this function * * @listens mousedown @@ -169,7 +174,7 @@ class Slider extends Component { * Triggered when the slider is in an active state * * @event Slider#slideractive - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('slideractive'); @@ -187,7 +192,7 @@ class Slider extends Component { * `mousedown` and `touchstart`. This is due to {@link Slider#handleMouseDown} and * {@link Slider#handleMouseUp}. * - * @param {EventTarget~Event} event + * @param {Event} event * `mousedown`, `mousemove`, `touchstart`, or `touchmove` event that triggered * this function * @param {boolean} mouseDown this is a flag that should be set to true if `handleMouseMove` is called directly. It allows us to skip things that should not happen if coming from mouse down but should happen on regular mouse move handler. Defaults to false. @@ -200,14 +205,14 @@ class Slider extends Component { /** * Handle `mouseup` or `touchend` events on the `Slider`. * - * @param {EventTarget~Event} event + * @param {Event} event * `mouseup` or `touchend` event that triggered this function. * * @listens touchend * @listens mouseup * @fires Slider#sliderinactive */ - handleMouseUp() { + handleMouseUp(event) { const doc = this.bar.el_.ownerDocument; Dom.unblockTextSelection(); @@ -217,7 +222,7 @@ class Slider extends Component { * Triggered when the slider is no longer in an active state. * * @event Slider#sliderinactive - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('sliderinactive'); @@ -280,7 +285,7 @@ class Slider extends Component { /** * Calculate distance for slider * - * @param {EventTarget~Event} event + * @param {Event} event * The event that caused this function to run. * * @return {number} @@ -302,7 +307,7 @@ class Slider extends Component { * arrow keys. This function will only be called when the slider has focus. See * {@link Slider#handleFocus} and {@link Slider#handleBlur}. * - * @param {EventTarget~Event} event + * @param {Event} event * the `keydown` event that caused this function to run. * * @listens keydown diff --git a/src/js/tech/html5.js b/src/js/tech/html5.js index 3201d15603..544f2415f6 100644 --- a/src/js/tech/html5.js +++ b/src/js/tech/html5.js @@ -28,7 +28,7 @@ class Html5 extends Tech { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * Callback function to call when the `HTML5` Tech is ready. */ constructor(options, ready) { @@ -1080,7 +1080,7 @@ Html5.canControlVolume = function() { * Some devices, e.g. iOS, don't allow changing volume * but permits muting/unmuting. * - * @return {bolean} + * @return {boolean} * - True if volume can be muted * - False otherwise */ @@ -1225,7 +1225,7 @@ Html5.Events = [ /** * Boolean indicating whether the `Tech` supports muting volume. * - * @type {bolean} + * @type {boolean} * @default {@link Html5.canMuteVolume} */ diff --git a/src/js/tech/loader.js b/src/js/tech/loader.js index b7beb64d14..c5a99ed9ce 100644 --- a/src/js/tech/loader.js +++ b/src/js/tech/loader.js @@ -6,6 +6,10 @@ import Tech from './tech.js'; import {toTitleCase} from '../utils/str.js'; import {merge} from '../utils/obj.js'; +/** + * @typedef { import('../player').default } Player + */ + /** * The `MediaLoader` is the `Component` that decides which playback technology to load * when a player is initialized. @@ -23,7 +27,7 @@ class MediaLoader extends Component { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function that is run when this component is ready. */ constructor(player, options, ready) { diff --git a/src/js/tech/middleware.js b/src/js/tech/middleware.js index bb7f3ad94a..2f18a58eda 100644 --- a/src/js/tech/middleware.js +++ b/src/js/tech/middleware.js @@ -4,6 +4,11 @@ */ import {toTitleCase} from '../utils/str.js'; +/** + * @typedef { import('../player').default } Player + * @typedef { import('../tech/tech').default } Tech + */ + const middlewares = {}; const middlewareInstances = {}; @@ -108,7 +113,7 @@ export function setTech(middleware, tech) { * @param {string} method * A method name. * - * @return {Mixed} + * @return {*} * The final value from the tech after middleware has intercepted it. */ export function get(middleware, tech, method) { @@ -128,10 +133,10 @@ export function get(middleware, tech, method) { * @param {string} method * A method name. * - * @param {Mixed} arg + * @param {*} arg * The value to set on the tech. * - * @return {Mixed} + * @return {*} * The return value of the `method` of the `tech`. */ export function set(middleware, tech, method, arg) { @@ -154,10 +159,10 @@ export function set(middleware, tech, method, arg) { * @param {string} method * A method name. * - * @param {Mixed} arg + * @param {*} arg * The value to set on the tech. * - * @return {Mixed} + * @return {*} * The return value of the `method` of the `tech`, regardless of the * return values of middlewares. */ diff --git a/src/js/tech/setup-sourceset.js b/src/js/tech/setup-sourceset.js index 6c15ff0698..3431bdee03 100644 --- a/src/js/tech/setup-sourceset.js +++ b/src/js/tech/setup-sourceset.js @@ -3,6 +3,10 @@ import document from 'global/document'; import {merge} from '../utils/obj'; import {getAbsoluteURL} from '../utils/url'; +/** + * @typedef { import('./html5').default } Html5 + */ + /** * This function is used to fire a sourceset when there is something * similar to `mediaEl.load()` being called. It will try to find the source via diff --git a/src/js/tech/tech.js b/src/js/tech/tech.js index ff2ae9fc6e..c48b4df571 100644 --- a/src/js/tech/tech.js +++ b/src/js/tech/tech.js @@ -16,6 +16,10 @@ import {toTitleCase, toLowerCase} from '../utils/str.js'; import vtt from 'videojs-vtt.js'; import * as Guid from '../utils/guid.js'; +/** + * @typedef { import('../utils/time').TimeRange } TimeRange + */ + /** * An Object containing a structure like: `{src: 'url', type: 'mimetype'}` or string * that just contains the src url alone. @@ -88,7 +92,7 @@ class Tech extends Component { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * Callback function to call when the `HTML5` Tech is ready. */ constructor(options = {}, ready = function() {}) { @@ -185,7 +189,7 @@ class Tech extends Component { * * @see {@link Player#event:sourceset} * @event Tech#sourceset - * @type {EventTarget~Event} + * @type {Event} */ this.trigger({ src, @@ -228,7 +232,7 @@ class Tech extends Component { * * > This function is called by {@link Tech#manualProgressOn} * - * @param {EventTarget~Event} event + * @param {Event} event * The `ready` event that caused this to run. * * @listens Tech#ready @@ -246,7 +250,7 @@ class Tech extends Component { * See {@link Player#progress} * * @event Tech#progress - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('progress'); } @@ -263,7 +267,7 @@ class Tech extends Component { * Update our internal duration on a `durationchange` event by calling * {@link Tech#duration}. * - * @param {EventTarget~Event} event + * @param {Event} event * The `durationchange` event that caused this to run. * * @listens Tech#durationchange @@ -343,7 +347,7 @@ class Tech extends Component { * Triggered at an interval of 250ms to indicated that time is passing in the video. * * @event Tech#timeupdate - * @type {EventTarget~Event} + * @type {Event} */ this.trigger({ type: 'timeupdate', target: this, manuallyTriggered: true }); @@ -504,10 +508,13 @@ class Tech extends Component { * Set whether we are scrubbing or not * * @abstract + * @param {boolean} _isScrubbing + * - true for we are currently scrubbing + * - false for we are no longer scrubbing * * @see {Html5#setScrubbing} */ - setScrubbing() {} + setScrubbing(_isScrubbing) {} /** * Get whether we are scrubbing or not @@ -522,16 +529,18 @@ class Tech extends Component { * Causes a manual time update to occur if {@link Tech#manualTimeUpdatesOn} was * previously called. * + * @param {number} _seconds + * Set the current time of the media to this. * @fires Tech#timeupdate */ - setCurrentTime() { + setCurrentTime(_seconds) { // improve the accuracy of manual timeupdates if (this.manualTimeUpdates) { /** * A manual `timeupdate` event. * * @event Tech#timeupdate - * @type {EventTarget~Event} + * @type {Event} */ this.trigger({ type: 'timeupdate', target: this, manuallyTriggered: true }); } @@ -552,21 +561,21 @@ class Tech extends Component { * Triggered when tracks are added or removed on the Tech {@link AudioTrackList} * * @event Tech#audiotrackchange - * @type {EventTarget~Event} + * @type {Event} */ /** * Triggered when tracks are added or removed on the Tech {@link VideoTrackList} * * @event Tech#videotrackchange - * @type {EventTarget~Event} + * @type {Event} */ /** * Triggered when tracks are added or removed on the Tech {@link TextTrackList} * * @event Tech#texttrackchange - * @type {EventTarget~Event} + * @type {Event} */ TRACK_TYPES.NORMAL.names.forEach((name) => { const props = TRACK_TYPES.NORMAL[name]; @@ -620,7 +629,7 @@ class Tech extends Component { * Fired when vtt.js is loaded. * * @event Tech#vttjsloaded - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('vttjsloaded'); }; @@ -629,7 +638,7 @@ class Tech extends Component { * Fired when vtt.js was not loaded due to an error * * @event Tech#vttjsloaded - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('vttjserror'); }; @@ -916,7 +925,7 @@ class Tech extends Component { * * @abstract */ - overrideNativeAudioTracks() {} + overrideNativeAudioTracks(override) {} /** * Attempt to force override of native video tracks. @@ -926,15 +935,15 @@ class Tech extends Component { * * @abstract */ - overrideNativeVideoTracks() {} + overrideNativeVideoTracks(override) {} - /* + /** * Check if the tech can support the given mime-type. * * The base tech does not support any type, but source handlers might * overwrite this. * - * @param {string} type + * @param {string} _type * The mimetype to check for support * * @return {string} @@ -944,7 +953,7 @@ class Tech extends Component { * * @abstract */ - canPlayType() { + canPlayType(_type) { return ''; } @@ -954,11 +963,11 @@ class Tech extends Component { * The base tech does not support any type, but source handlers might * overwrite this. * - * @param {string} type + * @param {string} _type * The media type to check * @return {string} Returns the native video element's response */ - static canPlayType() { + static canPlayType(_type) { return ''; } @@ -1135,7 +1144,7 @@ Tech.prototype.featuresVolumeControl = true; /** * Boolean indicating whether the `Tech` supports muting volume. * - * @type {bolean} + * @type {boolean} * @default */ Tech.prototype.featuresMuteControl = true; diff --git a/src/js/tracks/audio-track-list.js b/src/js/tracks/audio-track-list.js index 0a64d94777..61f21f1b1c 100644 --- a/src/js/tracks/audio-track-list.js +++ b/src/js/tracks/audio-track-list.js @@ -3,6 +3,10 @@ */ import TrackList from './track-list'; +/** + * @typedef { import('./audio-track').default } AudioTrack + */ + /** * Anywhere we call this function we diverge from the spec * as we only support one enabled audiotrack at a time diff --git a/src/js/tracks/audio-track.js b/src/js/tracks/audio-track.js index 3eb9c7d5c7..b3d55eb506 100644 --- a/src/js/tracks/audio-track.js +++ b/src/js/tracks/audio-track.js @@ -70,7 +70,7 @@ class AudioTrack extends Track { * this internally without an event. * * @event AudioTrack#enabledchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('enabledchange'); } diff --git a/src/js/tracks/html-track-element.js b/src/js/tracks/html-track-element.js index 0064fb5166..6d5fdf21b6 100644 --- a/src/js/tracks/html-track-element.js +++ b/src/js/tracks/html-track-element.js @@ -5,6 +5,10 @@ import EventTarget from '../event-target'; import TextTrack from '../tracks/text-track'; +/** + * @typedef { import('../tech/tech').default } Tech + */ + /** * A single track represented in the DOM. * diff --git a/src/js/tracks/text-track-display.js b/src/js/tracks/text-track-display.js index b205d99737..b271eb1686 100644 --- a/src/js/tracks/text-track-display.js +++ b/src/js/tracks/text-track-display.js @@ -6,6 +6,11 @@ import * as Fn from '../utils/fn.js'; import * as Dom from '../utils/dom.js'; import window from 'global/window'; +/** + * @typedef { import('./player').default } Player + * @typedef { import('./tech/tech').default } Tech + */ + const darkGray = '#222'; const lightGray = '#ccc'; const fontMap = { @@ -93,7 +98,7 @@ class TextTrackDisplay extends Component { * @param {Object} [options] * The key/value store of player options. * - * @param {Component~ReadyCallback} [ready] + * @param {Function} [ready] * The function to call when `TextTrackDisplay` is ready. */ constructor(player, options, ready) { diff --git a/src/js/tracks/text-track-list-converter.js b/src/js/tracks/text-track-list-converter.js index 49bd3763a9..e6dc96db79 100644 --- a/src/js/tracks/text-track-list-converter.js +++ b/src/js/tracks/text-track-list-converter.js @@ -5,6 +5,10 @@ * @module text-track-list-converter */ +/** + * @typedef { import('../tech/tech').default } Tech + */ + /** * Examine a single {@link TextTrack} and return a JSON-compatible javascript object that * represents the {@link TextTrack}'s state. diff --git a/src/js/tracks/text-track-list.js b/src/js/tracks/text-track-list.js index ac89664631..f9edc076ae 100644 --- a/src/js/tracks/text-track-list.js +++ b/src/js/tracks/text-track-list.js @@ -3,6 +3,10 @@ */ import TrackList from './track-list'; +/** + * @typedef { import('./text-track').default } TextTrack + */ + /** * The current list of {@link TextTrack} for a media file. * diff --git a/src/js/tracks/text-track-settings.js b/src/js/tracks/text-track-settings.js index d866e0c2e1..c7b13b856e 100644 --- a/src/js/tracks/text-track-settings.js +++ b/src/js/tracks/text-track-settings.js @@ -8,6 +8,10 @@ import {createEl} from '../utils/dom'; import * as Obj from '../utils/obj'; import log from '../utils/log'; +/** + * @typedef { import('../player').default } Player + */ + const LOCAL_STORAGE_KEY = 'vjs-text-track-settings'; const COLOR_BLACK = ['#000', 'Black']; @@ -166,7 +170,7 @@ selectConfigs.windowColor.options = selectConfigs.backgroundColor.options; * @param {Function} [parser] * Optional function to adjust the value. * - * @return {Mixed} + * @return {*} * - Will be `undefined` if no value exists * - Will be `undefined` if the given value is "none". * - Will be the actual value otherwise. @@ -192,7 +196,7 @@ function parseOptionValue(value, parser) { * @param {Function} [parser] * Optional function to adjust the value. * - * @return {Mixed} + * @return {*} * - Will be `undefined` if no value exists * - Will be `undefined` if the given value is "none". * - Will be the actual value otherwise. diff --git a/src/js/tracks/text-track.js b/src/js/tracks/text-track.js index c41df8e651..73eb6cde1b 100644 --- a/src/js/tracks/text-track.js +++ b/src/js/tracks/text-track.js @@ -11,6 +11,10 @@ import { isCrossOrigin } from '../utils/url.js'; import XHR from '@videojs/xhr'; import {merge} from '../utils/obj'; +/** + * @typedef { import('../tech/tech').default } Tech + */ + /** * Takes a webvtt file contents and parses it into cues * @@ -277,7 +281,7 @@ class TextTrack extends Track { * > Note: This is not part of the spec! * * @event TextTrack#modechange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('modechange'); diff --git a/src/js/tracks/track-list.js b/src/js/tracks/track-list.js index 7f224d2742..371a955afc 100644 --- a/src/js/tracks/track-list.js +++ b/src/js/tracks/track-list.js @@ -4,6 +4,10 @@ import EventTarget from '../event-target'; import {isEvented} from '../mixins/evented'; +/** + * @typedef { import('./track').default } Track + */ + /** * Common functionaliy between {@link TextTrackList}, {@link AudioTrackList}, and * {@link VideoTrackList} @@ -67,7 +71,7 @@ class TrackList extends EventTarget { * Triggered when a track is added to a track list. * * @event TrackList#addtrack - * @type {EventTarget~Event} + * @type {Event} * @property {Track} track * A reference to track that was added. */ @@ -82,7 +86,7 @@ class TrackList extends EventTarget { * Triggered when a track label is changed. * * @event TrackList#addtrack - * @type {EventTarget~Event} + * @type {Event} * @property {Track} track * A reference to track that was added. */ @@ -131,7 +135,7 @@ class TrackList extends EventTarget { * Triggered when a track is removed from track list. * * @event TrackList#removetrack - * @type {EventTarget~Event} + * @type {Event} * @property {Track} track * A reference to track that was removed. */ @@ -170,7 +174,7 @@ class TrackList extends EventTarget { * Triggered when a different track is selected/enabled. * * @event TrackList#change - * @type {EventTarget~Event} + * @type {Event} */ /** diff --git a/src/js/tracks/track.js b/src/js/tracks/track.js index 88630450e7..5e5a10083f 100644 --- a/src/js/tracks/track.js +++ b/src/js/tracks/track.js @@ -106,7 +106,7 @@ class Track extends EventTarget { * > Note: This is not part of the spec! * * @event Track#labelchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('labelchange'); } diff --git a/src/js/tracks/video-track-list.js b/src/js/tracks/video-track-list.js index 4240ab6d7d..7d46a16c90 100644 --- a/src/js/tracks/video-track-list.js +++ b/src/js/tracks/video-track-list.js @@ -3,6 +3,10 @@ */ import TrackList from './track-list'; +/** + * @typedef { import('./video-track').default } VideoTrack + */ + /** * Un-select all other {@link VideoTrack}s that are selected. * diff --git a/src/js/tracks/video-track.js b/src/js/tracks/video-track.js index 0e156f3c3b..b9166bcf4d 100644 --- a/src/js/tracks/video-track.js +++ b/src/js/tracks/video-track.js @@ -68,7 +68,7 @@ class VideoTrack extends Track { * this internally without an event. * * @event VideoTrack#selectedchange - * @type {EventTarget~Event} + * @type {Event} */ this.trigger('selectedchange'); } diff --git a/src/js/types.js b/src/js/types.js new file mode 100644 index 0000000000..e69de29bb2 diff --git a/src/js/utils/buffer.js b/src/js/utils/buffer.js index fa312b680e..f147e92273 100644 --- a/src/js/utils/buffer.js +++ b/src/js/utils/buffer.js @@ -4,11 +4,15 @@ */ import { createTimeRange } from './time.js'; +/** + * @typedef { import('./time').TimeRange } TimeRange + */ + /** * Compute the percentage of the media that has been buffered. * * @param {TimeRange} buffered - * The current `TimeRange` object representing buffered time ranges + * The current `TimeRanges` object representing buffered time ranges * * @param {number} duration * Total duration of the media diff --git a/src/js/utils/create-logger.js b/src/js/utils/create-logger.js index 33f89d8f92..d742398a99 100644 --- a/src/js/utils/create-logger.js +++ b/src/js/utils/create-logger.js @@ -82,7 +82,7 @@ export default function createLogger(name) { * * #### Arguments * ##### *args - * Mixed[] + * *[] * * Any combination of values that could be passed to `console.log()`. * @@ -91,7 +91,7 @@ export default function createLogger(name) { * `undefined` * * @namespace - * @param {Mixed[]} args + * @param {(*|*[])} args * One or more messages or objects that should be logged. */ const log = function(...args) { @@ -226,7 +226,7 @@ export default function createLogger(name) { /** * Logs error messages. Similar to `console.error`. * - * @param {Mixed[]} args + * @param {(*|*[])} args * One or more messages or objects that should be logged as an error */ log.error = (...args) => logByType('error', level, args); @@ -234,7 +234,7 @@ export default function createLogger(name) { /** * Logs warning messages. Similar to `console.warn`. * - * @param {Mixed[]} args + * @param {(*|*[])} args * One or more messages or objects that should be logged as a warning. */ log.warn = (...args) => logByType('warn', level, args); @@ -243,7 +243,7 @@ export default function createLogger(name) { * Logs debug messages. Similar to `console.debug`, but may also act as a comparable * log if `console.debug` is not available * - * @param {Mixed[]} args + * @param {(*|*[])} args * One or more messages or objects that should be logged as debug. */ log.debug = (...args) => logByType('debug', level, args); diff --git a/src/js/utils/dom.js b/src/js/utils/dom.js index d86700f6ec..f47d35af5f 100644 --- a/src/js/utils/dom.js +++ b/src/js/utils/dom.js @@ -61,7 +61,7 @@ export function isReal() { /** * Determines, via duck typing, whether or not a value is a DOM element. * - * @param {Mixed} value + * @param {*} value * The value to check. * * @return {boolean} @@ -126,7 +126,7 @@ function createQuerier(method) { * @param {Object} [attributes={}] * Element attributes to be applied. * - * @param {module:dom~ContentDescriptor} content + * @param {ContentDescriptor} [content] * A content descriptor object. * * @return {Element} @@ -547,7 +547,7 @@ export function findPosition(el) { * @param {Element} el * Element on which to get the pointer position on. * - * @param {EventTarget~Event} event + * @param {Event} event * Event object. * * @return {module:dom~Coordinates} @@ -607,7 +607,7 @@ export function getPointerPosition(el, event) { /** * Determines, via duck typing, whether or not a value is a text node. * - * @param {Mixed} value + * @param {*} value * Check if this value is a text node. * * @return {boolean} @@ -641,11 +641,11 @@ export function emptyEl(el) { * -----------|------------- * `string` | The value will be normalized into a text node. * `Element` | The value will be accepted as-is. - * `TextNode` | The value will be accepted as-is. + * `Text` | A TextNode. The value will be accepted as-is. * `Array` | A one-dimensional array of strings, elements, text nodes, or functions. These functions should return a string, element, or text node (any other return value, like an array, will be ignored). * `Function` | A function, which is expected to return a string, element, text node, or array - any of the other possible values described above. This means that a content descriptor could be a function that returns an array of functions, but those second-level functions must return strings, elements, or text nodes. * - * @typedef {string|Element|TextNode|Array|Function} module:dom~ContentDescriptor + * @typedef {string|Element|Text|Array|Function} ContentDescriptor */ /** @@ -658,7 +658,7 @@ export function emptyEl(el) { * The content for an element can be passed in multiple types and * combinations, whose behavior is as follows: * - * @param {module:dom~ContentDescriptor} content + * @param {ContentDescriptor} content * A content descriptor value. * * @return {Array} @@ -699,7 +699,7 @@ export function normalizeContent(content) { * @param {Element} el * Element to append normalized content to. * - * @param {module:dom~ContentDescriptor} content + * @param {ContentDescriptor} content * A content descriptor value. * * @return {Element} @@ -717,7 +717,7 @@ export function appendContent(el, content) { * @param {Element} el * Element to insert normalized content into. * - * @param {module:dom~ContentDescriptor} content + * @param {ContentDescriptor} content * A content descriptor value. * * @return {Element} @@ -730,7 +730,7 @@ export function insertContent(el, content) { /** * Check if an event was a single left click. * - * @param {EventTarget~Event} event + * @param {Event} event * Event object. * * @return {boolean} diff --git a/src/js/utils/events.js b/src/js/utils/events.js index 36afd652d9..4945c236b0 100644 --- a/src/js/utils/events.js +++ b/src/js/utils/events.js @@ -67,7 +67,7 @@ function _cleanUpEvents(elem, type) { * @param {string} type * Type of event to bind to. * - * @param {EventTarget~EventListener} callback + * @param {Function} callback * Event listener. */ function _handleMultipleEvents(fn, elem, types, callback) { @@ -256,7 +256,7 @@ const passiveEvents = [ * @param {string|string[]} type * Type of event to bind to. * - * @param {EventTarget~EventListener} fn + * @param {Function} fn * Event listener. */ export function on(elem, type, fn) { @@ -341,7 +341,7 @@ export function on(elem, type, fn) { * @param {string|string[]} [type] * Type of listener to remove. Don't include to remove all events from element. * - * @param {EventTarget~EventListener} [fn] + * @param {Function} [fn] * Specific listener to remove. Don't include to remove listeners for an event * type. */ diff --git a/src/js/utils/filter-source.js b/src/js/utils/filter-source.js index 7cfe021206..de77c54ee1 100644 --- a/src/js/utils/filter-source.js +++ b/src/js/utils/filter-source.js @@ -4,6 +4,10 @@ import {isObject} from './obj'; import {getMimetype} from './mimetypes'; +/** + * @typedef { import('../tech/tech').default } Tech + */ + /** * Filter out single bad source objects or multiple source objects in an * array. Also flattens nested source object arrays into a 1 dimensional diff --git a/src/js/utils/fn.js b/src/js/utils/fn.js index ef957f9497..cf7ba35ed4 100644 --- a/src/js/utils/fn.js +++ b/src/js/utils/fn.js @@ -15,7 +15,7 @@ export const UPDATE_REFRESH_INTERVAL = 30; * * @private * @function - * @param {Mixed} context + * @param {*} context * The object to bind as scope. * * @param {Function} fn diff --git a/src/js/utils/mimetypes.js b/src/js/utils/mimetypes.js index 8e0ba34879..2bf701279e 100644 --- a/src/js/utils/mimetypes.js +++ b/src/js/utils/mimetypes.js @@ -1,5 +1,9 @@ import * as Url from '../utils/url.js'; +/** + * @typedef { import('../player').default } Player + */ + /** * Mimetypes * diff --git a/src/js/utils/obj.js b/src/js/utils/obj.js index cadab67602..09a9d4fb45 100644 --- a/src/js/utils/obj.js +++ b/src/js/utils/obj.js @@ -6,7 +6,7 @@ /** * @callback obj:EachCallback * - * @param {Mixed} value + * @param {*} value * The current key for the object that is being iterated over. * * @param {string} key @@ -16,16 +16,16 @@ /** * @callback obj:ReduceCallback * - * @param {Mixed} accum + * @param {*} accum * The value that is accumulating over the reduce loop. * - * @param {Mixed} value + * @param {*} value * The current key for the object that is being iterated over. * * @param {string} key * The current key-value for object that is being iterated over * - * @return {Mixed} + * @return {*} * The new accumulated value. */ const toString = Object.prototype.toString; @@ -70,10 +70,10 @@ export function each(object, fn) { * receives the accumulated value and the per-iteration value and key * as arguments. * - * @param {Mixed} [initial = 0] + * @param {*} [initial = 0] * Starting value * - * @return {Mixed} + * @return {*} * The final accumulated value. */ export function reduce(object, fn, initial = 0) { diff --git a/src/js/utils/time.js b/src/js/utils/time.js index 4f0e8f7944..408bea08fb 100644 --- a/src/js/utils/time.js +++ b/src/js/utils/time.js @@ -21,7 +21,7 @@ import window from 'global/window'; */ /** - * An object that contains ranges of time. + * An object that contains ranges of time, which mimics {@link TimeRanges}. * * @typedef {Object} TimeRange * @@ -93,6 +93,8 @@ function getRange(fnName, valueIndex, ranges, rangeIndex) { * @private * @param {Array} [ranges] * An array of time ranges. + * + * @return {TimeRange} */ function createTimeRangesObj(ranges) { let timeRangesObj; @@ -133,6 +135,8 @@ function createTimeRangesObj(ranges) { * @param {number} end * The end of a single range. Cannot be used with the array form of * the `start` argument. + * + * @return {TimeRange} */ export function createTimeRanges(start, end) { if (Array.isArray(start)) {