From c9022795fdfcda166a79bef51dfeab29c1f7c191 Mon Sep 17 00:00:00 2001 From: Brandon Casey Date: Fri, 2 Dec 2016 15:20:41 -0500 Subject: [PATCH] docs(jsdoc): Update the jsdoc comments to modern syntax - Part 6 (#3771) Files in this PR: * src/js/control-bar/audio-track-controls/audio-track-button.js * src/js/control-bar/audio-track-controls/audio-track-menu-item.js * src/js/control-bar/control-bar.js * src/js/control-bar/fullscreen-toggle.js * src/js/control-bar/live-display.js * src/js/control-bar/mute-toggle.js * src/js/control-bar/play-toggle.js * src/js/control-bar/playback-rate-menu/playback-rate-menu-button.js * src/js/control-bar/playback-rate-menu/playback-rate-menu-item.js * src/js/control-bar/progress-control/load-progress-bar.js * src/js/control-bar/progress-control/mouse-time-display.js * src/js/control-bar/progress-control/play-progress-bar.js * src/js/control-bar/progress-control/progress-control.js * src/js/control-bar/progress-control/seek-bar.js * src/js/control-bar/progress-control/tooltip-progress-bar.js * src/js/control-bar/spacer-controls/custom-control-spacer.js * src/js/control-bar/spacer-controls/spacer.js * src/js/control-bar/text-track-controls/caption-settings-menu-item.js * src/js/control-bar/text-track-controls/captions-button.js * src/js/control-bar/text-track-controls/chapters-button.js * src/js/control-bar/text-track-controls/chapters-track-menu-item.js * src/js/control-bar/text-track-controls/descriptions-button.js * src/js/control-bar/text-track-controls/off-text-track-menu-item.js * src/js/control-bar/text-track-controls/subtitles-button.js * src/js/control-bar/text-track-controls/text-track-button.js * src/js/control-bar/text-track-controls/text-track-menu-item.js * src/js/control-bar/time-controls/current-time-display.js * src/js/control-bar/time-controls/duration-display.js * src/js/control-bar/time-controls/remaining-time-display.js * src/js/control-bar/time-controls/time-divider.js * src/js/control-bar/track-button.js * src/js/control-bar/volume-control/volume-bar.js * src/js/control-bar/volume-control/volume-control.js * src/js/control-bar/volume-control/volume-level.js * src/js/control-bar/volume-menu-button.js * src/js/utils/dom.js * src/js/utils/events.js * src/js/utils/log.js * src/js/utils/merge-options.js * src/js/utils/url.js * src/js/video.js --- .../audio-track-button.js | 35 +- .../audio-track-menu-item.js | 32 +- src/js/control-bar/control-bar.js | 13 +- src/js/control-bar/fullscreen-toggle.js | 46 ++- src/js/control-bar/live-display.js | 30 +- src/js/control-bar/mute-toggle.js | 48 ++- src/js/control-bar/play-toggle.js | 56 ++- .../playback-rate-menu-button.js | 70 ++-- .../playback-rate-menu-item.js | 41 +- .../progress-control/load-progress-bar.js | 25 +- .../progress-control/mouse-time-display.js | 53 ++- .../progress-control/play-progress-bar.js | 26 +- .../progress-control/progress-control.js | 15 +- .../control-bar/progress-control/seek-bar.js | 64 ++- .../progress-control/tooltip-progress-bar.js | 26 +- .../spacer-controls/custom-control-spacer.js | 11 +- src/js/control-bar/spacer-controls/spacer.js | 17 +- .../caption-settings-menu-item.js | 24 +- .../text-track-controls/captions-button.js | 48 ++- .../text-track-controls/chapters-button.js | 75 +++- .../chapters-track-menu-item.js | 31 +- .../descriptions-button.js | 40 +- .../off-text-track-menu-item.js | 16 +- .../text-track-controls/subtitles-button.js | 35 +- .../text-track-controls/text-track-button.js | 19 +- .../text-track-menu-item.js | 29 +- .../time-controls/current-time-display.js | 23 +- .../time-controls/duration-display.js | 28 +- .../time-controls/remaining-time-display.js | 26 +- .../control-bar/time-controls/time-divider.js | 5 +- src/js/control-bar/track-button.js | 14 +- .../control-bar/volume-control/volume-bar.js | 52 ++- .../volume-control/volume-control.js | 22 +- .../volume-control/volume-level.js | 7 +- src/js/control-bar/volume-menu-button.js | 66 ++- src/js/utils/dom.js | 377 ++++++++++++------ src/js/utils/events.js | 90 +++-- src/js/utils/log.js | 16 +- src/js/utils/merge-options.js | 27 +- src/js/utils/url.js | 69 +++- src/js/video.js | 293 ++++++-------- 41 files changed, 1383 insertions(+), 657 deletions(-) diff --git a/src/js/control-bar/audio-track-controls/audio-track-button.js b/src/js/control-bar/audio-track-controls/audio-track-button.js index a49998b9ec..2a58746023 100644 --- a/src/js/control-bar/audio-track-controls/audio-track-button.js +++ b/src/js/control-bar/audio-track-controls/audio-track-button.js @@ -6,14 +6,21 @@ import Component from '../../component.js'; import AudioTrackMenuItem from './audio-track-menu-item.js'; /** - * The base class for buttons that toggle specific text track types (e.g. subtitles) + * The base class for buttons that toggle specific {@link AudioTrack} types. * - * @param {Player|Object} player - * @param {Object=} options * @extends TrackButton - * @class AudioTrackButton */ class AudioTrackButton extends TrackButton { + + /** + * 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. + */ constructor(player, options = {}) { options.tracks = player.audioTracks && player.audioTracks(); @@ -23,10 +30,10 @@ class AudioTrackButton extends TrackButton { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-audio-button ${super.buildCSSClass()}`; @@ -35,8 +42,11 @@ class AudioTrackButton extends TrackButton { /** * Create a menu item for each audio track * - * @return {Array} Array of menu items - * @method createItems + * @param {AudioTrackMenuItem[]} [items=[]] + * An array of existing menu items to use. + * + * @return {AudioTrackMenuItem[]} + * An array of menu items */ createItems(items = []) { const tracks = this.player_.audioTracks && this.player_.audioTracks(); @@ -58,6 +68,13 @@ class AudioTrackButton extends TrackButton { return items; } } + +/** + * The text that should display over the `AudioTrackButton`s controls. Added for localization. + * + * @type {string} + * @private + */ AudioTrackButton.prototype.controlText_ = 'Audio Track'; Component.registerComponent('AudioTrackButton', AudioTrackButton); export default AudioTrackButton; 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 97ba5e16eb..e885ebbbdd 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 @@ -6,14 +6,21 @@ import Component from '../../component.js'; import * as Fn from '../../utils/fn.js'; /** - * The audio track menu item + * An {@link AudioTrack} {@link MenuItem} * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuItem - * @class AudioTrackMenuItem */ class AudioTrackMenuItem extends MenuItem { + + /** + * 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. + */ constructor(player, options) { const track = options.track; const tracks = player.audioTracks(); @@ -37,9 +44,15 @@ class AudioTrackMenuItem extends MenuItem { } /** - * Handle click on audio track + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ handleClick(event) { const tracks = this.player_.audioTracks(); @@ -58,9 +71,12 @@ class AudioTrackMenuItem extends MenuItem { } /** - * Handle audio track change + * Handle any {@link AudioTrack} change. + * + * @param {EventTarget~Event} [event] + * The {@link AudioTrackList#change} event that caused this to run. * - * @method handleTracksChange + * @listens AudioTrackList#change */ handleTracksChange(event) { this.selected(this.track.enabled); diff --git a/src/js/control-bar/control-bar.js b/src/js/control-bar/control-bar.js index 90d110f696..7321c57edb 100644 --- a/src/js/control-bar/control-bar.js +++ b/src/js/control-bar/control-bar.js @@ -24,18 +24,17 @@ import './playback-rate-menu/playback-rate-menu-button.js'; import './spacer-controls/custom-control-spacer.js'; /** - * Container of main controls + * Container of main controls. * * @extends Component - * @class ControlBar */ class ControlBar extends Component { /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -48,6 +47,12 @@ class ControlBar extends Component { } } +/** + * Default options for `ControlBar` + * + * @type {Object} + * @private + */ ControlBar.prototype.options_ = { children: [ 'playToggle', diff --git a/src/js/control-bar/fullscreen-toggle.js b/src/js/control-bar/fullscreen-toggle.js index 6994d69ee3..a565ee3695 100644 --- a/src/js/control-bar/fullscreen-toggle.js +++ b/src/js/control-bar/fullscreen-toggle.js @@ -8,42 +8,62 @@ import Component from '../component.js'; * Toggle fullscreen video * * @extends Button - * @class FullscreenToggle */ class FullscreenToggle extends Button { + /** + * 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. + */ constructor(player, options) { super(player, options); this.on(player, 'fullscreenchange', this.handleFullscreenChange); } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-fullscreen-control ${super.buildCSSClass()}`; } + /** - * Handles Fullscreenchange on the component and change control text accordingly + * Handles fullscreenchange on the player and change control text accordingly. + * + * @param {EventTarget~Event} [event] + * The {@link Player#fullscreenchange} event that caused this function to be + * called. * - * @method handleFullscreenChange + * @listens Player#fullscreenchange */ - handleFullscreenChange() { + handleFullscreenChange(event) { if (this.player_.isFullscreen()) { this.controlText('Non-Fullscreen'); } else { this.controlText('Fullscreen'); } } + /** - * Handles click for full screen + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { if (!this.player_.isFullscreen()) { this.player_.requestFullscreen(); } else { @@ -53,6 +73,12 @@ class FullscreenToggle extends Button { } +/** + * The text that should display over the `FullscreenToggle`s controls. Added for localization. + * + * @type {string} + * @private + */ FullscreenToggle.prototype.controlText_ = 'Fullscreen'; Component.registerComponent('FullscreenToggle', FullscreenToggle); diff --git a/src/js/control-bar/live-display.js b/src/js/control-bar/live-display.js index 017b5d0576..88c6a358e7 100644 --- a/src/js/control-bar/live-display.js +++ b/src/js/control-bar/live-display.js @@ -4,15 +4,24 @@ import Component from '../component'; import * as Dom from '../utils/dom.js'; +// TODO - Future make it click to snap to live + /** - * Displays the live indicator - * TODO - Future make it click to snap to live + * Displays the live indicator when duration is Infinity. * * @extends Component - * @class LiveDisplay */ class LiveDisplay extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -21,10 +30,10 @@ class LiveDisplay extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl('div', { @@ -42,7 +51,16 @@ class LiveDisplay extends Component { return el; } - updateShowing() { + /** + * Check the duration to see if the LiveDisplay should be showing or not. Then show/hide + * it accordingly + * + * @param {EventTarget~Event} [event] + * The {@link Player#durationchange} event that caused this function to run. + * + * @listens Player#durationchange + */ + updateShowing(event) { if (this.player().duration() === Infinity) { this.show(); } else { diff --git a/src/js/control-bar/mute-toggle.js b/src/js/control-bar/mute-toggle.js index 16adb66b1b..3d2467f76d 100644 --- a/src/js/control-bar/mute-toggle.js +++ b/src/js/control-bar/mute-toggle.js @@ -6,15 +6,21 @@ import Component from '../component'; import * as Dom from '../utils/dom.js'; /** - * A button component for muting the audio + * A button component for muting the audio. * - * @param {Player|Object} player - * @param {Object=} options * @extends Button - * @class MuteToggle */ class MuteToggle extends Button { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -38,30 +44,40 @@ class MuteToggle extends Button { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-mute-control ${super.buildCSSClass()}`; } /** - * Handle click on mute + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { this.player_.muted(this.player_.muted() ? false : true); } /** - * Update volume + * Update the state of volume. * - * @method update + * @param {EventTarget~Event} [event] + * The {@link Player#loadstart} event if this function was called through an + * event. + * + * @listens Player#loadstart */ - update() { + update(event) { const vol = this.player_.volume(); let level = 3; @@ -91,6 +107,12 @@ class MuteToggle extends Button { } +/** + * The text that should display over the `MuteToggle`s controls. Added for localization. + * + * @type {string} + * @private + */ MuteToggle.prototype.controlText_ = 'Mute'; Component.registerComponent('MuteToggle', MuteToggle); diff --git a/src/js/control-bar/play-toggle.js b/src/js/control-bar/play-toggle.js index 3781d135d4..e20894cef0 100644 --- a/src/js/control-bar/play-toggle.js +++ b/src/js/control-bar/play-toggle.js @@ -5,15 +5,21 @@ import Button from '../button.js'; import Component from '../component.js'; /** - * Button to toggle between play and pause + * Button to toggle between play and pause. * - * @param {Player|Object} player - * @param {Object=} options * @extends Button - * @class PlayToggle */ class PlayToggle extends Button { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -22,21 +28,27 @@ class PlayToggle extends Button { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-play-control ${super.buildCSSClass()}`; } /** - * Handle click to toggle between play and pause + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { if (this.player_.paused()) { this.player_.play(); } else { @@ -45,11 +57,14 @@ class PlayToggle extends Button { } /** - * Add the vjs-playing class to the element so it can change appearance + * Add the vjs-playing class to the element so it can change appearance. * - * @method handlePlay + * @param {EventTarget~Event} [event] + * The event that caused this function to run. + * + * @listens Player#play */ - handlePlay() { + handlePlay(event) { this.removeClass('vjs-paused'); this.addClass('vjs-playing'); // change the button text to "Pause" @@ -57,11 +72,14 @@ class PlayToggle extends Button { } /** - * Add the vjs-paused class to the element so it can change appearance + * Add the vjs-paused class to the element so it can change appearance. + * + * @param {EventTarget~Event} [event] + * The event that caused this function to run. * - * @method handlePause + * @listens Player#pause */ - handlePause() { + handlePause(event) { this.removeClass('vjs-playing'); this.addClass('vjs-paused'); // change the button text to "Play" @@ -70,6 +88,12 @@ class PlayToggle extends Button { } +/** + * The text that should display over the `PlayToggle`s controls. Added for localization. + * + * @type {string} + * @private + */ PlayToggle.prototype.controlText_ = 'Play'; Component.registerComponent('PlayToggle', PlayToggle); 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 993e94fdf2..a446208b08 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 @@ -8,15 +8,21 @@ import Component from '../../component.js'; import * as Dom from '../../utils/dom.js'; /** - * The component for controlling the playback rate + * The component for controlling the playback rate. * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuButton - * @class PlaybackRateMenuButton */ class PlaybackRateMenuButton extends MenuButton { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -28,10 +34,10 @@ class PlaybackRateMenuButton extends MenuButton { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl(); @@ -47,10 +53,10 @@ class PlaybackRateMenuButton extends MenuButton { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-playback-rate ${super.buildCSSClass()}`; @@ -59,8 +65,8 @@ class PlaybackRateMenuButton extends MenuButton { /** * Create the playback rate menu * - * @return {Menu} Menu object populated with items - * @method createMenu + * @return {Menu} + * Menu object populated with {@link PlaybackRateMenuItem}s */ createMenu() { const menu = new Menu(this.player()); @@ -79,8 +85,6 @@ class PlaybackRateMenuButton extends MenuButton { /** * Updates ARIA accessibility attributes - * - * @method updateARIAAttributes */ updateARIAAttributes() { // Current playback rate @@ -88,11 +92,17 @@ class PlaybackRateMenuButton extends MenuButton { } /** - * Handle menu item click + * This gets called when an `PlaybackRateMenuButton` is "clicked". See + * {@link ClickableComponent} for more detailed information on what a click can be. + * + * @param {EventTarget~Event} [event] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { // select next rate option const currentRate = this.player().playbackRate(); const rates = this.playbackRates(); @@ -112,8 +122,8 @@ class PlaybackRateMenuButton extends MenuButton { /** * Get possible playback rates * - * @return {Array} Possible playback rates - * @method playbackRates + * @return {Array} + * All possible playback rates */ playbackRates() { return this.options_.playbackRates || (this.options_.playerOptions && this.options_.playerOptions.playbackRates); @@ -123,8 +133,8 @@ class PlaybackRateMenuButton extends MenuButton { * Get whether playback rates is supported by the tech * and an array of playback rates exists * - * @return {Boolean} Whether changing playback rate is supported - * @method playbackRateSupported + * @return {boolean} + * Whether changing playback rate is supported */ playbackRateSupported() { return this.player().tech_ && @@ -137,9 +147,12 @@ class PlaybackRateMenuButton extends MenuButton { /** * Hide playback rate controls when they're no playback rate options to select * - * @method updateVisibility + * @param {EventTarget~Event} [event] + * The event that caused this function to run. + * + * @listens Player#loadstart */ - updateVisibility() { + updateVisibility(event) { if (this.playbackRateSupported()) { this.removeClass('vjs-hidden'); } else { @@ -150,9 +163,12 @@ class PlaybackRateMenuButton extends MenuButton { /** * Update button label when rate changed * - * @method updateLabel + * @param {EventTarget~Event} [event] + * The event that caused this function to run. + * + * @listens Player#ratechange */ - updateLabel() { + updateLabel(event) { if (this.playbackRateSupported()) { this.labelEl_.innerHTML = this.player().playbackRate() + 'x'; } @@ -160,6 +176,12 @@ class PlaybackRateMenuButton extends MenuButton { } +/** + * The text that should display over the `FullscreenToggle`s controls. Added for localization. + * + * @type {string} + * @private + */ PlaybackRateMenuButton.prototype.controlText_ = 'Playback Rate'; Component.registerComponent('PlaybackRateMenuButton', PlaybackRateMenuButton); 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 6ec35dac4f..91f32c0670 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 @@ -5,15 +5,21 @@ import MenuItem from '../../menu/menu-item.js'; import Component from '../../component.js'; /** - * The specific menu item type for selecting a playback rate + * The specific menu item type for selecting a playback rate. * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuItem - * @class PlaybackRateMenuItem */ class PlaybackRateMenuItem extends MenuItem { + /** + * 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. + */ constructor(player, options) { const label = options.rate; const rate = parseFloat(label, 10); @@ -30,26 +36,41 @@ class PlaybackRateMenuItem extends MenuItem { } /** - * Handle click on menu item + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { super.handleClick(); this.player().playbackRate(this.rate); } /** - * Update playback rate with selected rate + * Update the PlaybackRateMenuItem when the playbackrate changes. * - * @method update + * @param {EventTarget~Event} [event] + * The `ratechange` event that caused this function to run. + * + * @listens Player#ratechange */ - update() { + update(event) { this.selected(this.player().playbackRate() === this.rate); } } +/** + * The text that should display over the `PlaybackRateMenuItem`s controls. Added for localization. + * + * @type {string} + * @private + */ PlaybackRateMenuItem.prototype.contentElType = 'button'; Component.registerComponent('PlaybackRateMenuItem', PlaybackRateMenuItem); 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 5ffa636b30..c94f5ced3e 100644 --- a/src/js/control-bar/progress-control/load-progress-bar.js +++ b/src/js/control-bar/progress-control/load-progress-bar.js @@ -5,15 +5,21 @@ import Component from '../../component.js'; import * as Dom from '../../utils/dom.js'; /** - * Shows load progress + * Shows loading progress * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class LoadProgressBar */ class LoadProgressBar extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); this.partEls_ = []; @@ -21,10 +27,10 @@ class LoadProgressBar extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -36,9 +42,12 @@ class LoadProgressBar extends Component { /** * Update progress bar * - * @method update + * @param {EventTarget~Event} [event] + * The `progress` event that caused this function to run. + * + * @listens Player#progress */ - update() { + update(event) { const buffered = this.player_.buffered(); const duration = this.player_.duration(); const bufferedEnd = this.player_.bufferedEnd(); 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 129a2b8603..158cbc300c 100644 --- a/src/js/control-bar/progress-control/mouse-time-display.js +++ b/src/js/control-bar/progress-control/mouse-time-display.js @@ -12,13 +12,19 @@ import computedStyle from '../../utils/computed-style.js'; * The Mouse Time Display component shows the time you will seek to * when hovering over the progress bar * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class MouseTimeDisplay */ class MouseTimeDisplay extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -43,10 +49,10 @@ class MouseTimeDisplay extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -54,6 +60,14 @@ class MouseTimeDisplay extends Component { }); } + /** + * Handle the mouse move event on the `MouseTimeDisplay`. + * + * @param {EventTarget~Event} event + * The `mousemove` event that caused this to event to run. + * + * @listen mousemove + */ handleMouseMove(event) { const duration = this.player_.duration(); const newTime = this.calculateDistance(event) * duration; @@ -62,6 +76,15 @@ class MouseTimeDisplay extends Component { this.update(newTime, position); } + /** + * Update the time and posistion of the `MouseTimeDisplay`. + * + * @param {number} newTime + * Time to change the `MouseTimeDisplay` to. + * + * @param {nubmer} position + * Postion from the left of the in pixels. + */ update(newTime, position) { const time = formatTime(newTime, this.player_.duration()); @@ -79,6 +102,16 @@ class MouseTimeDisplay extends Component { } } + /** + * Get the mouse pointers x coordinate in pixels. + * + * @param {EventTarget~Event} [event] + * The `mousemove` event that was passed to this function by + * {@link MouseTimeDisplay#handleMouseMove} + * + * @return {number} + * THe x position in pixels of the mouse pointer. + */ calculateDistance(event) { return Dom.getPointerPosition(this.el().parentNode, event).x; } @@ -89,9 +122,13 @@ class MouseTimeDisplay extends Component { * of the tooltip and smaller than the player width minus half the width o the tooltip. * It will only clamp the position if `keepTooltipsInside` option is set. * - * @param {Number} position the position the bar wants to be - * @return {Number} newPosition the (potentially) clamped position - * @method clampPosition_ + * @param {number} position + * The position the bar wants to be + * + * @return {number} + * The (potentially) new clamped position. + * + * @private */ clampPosition_(position) { if (!this.keepTooltipsInside) { 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 5b29ba862a..b523a07d8d 100644 --- a/src/js/control-bar/progress-control/play-progress-bar.js +++ b/src/js/control-bar/progress-control/play-progress-bar.js @@ -8,13 +8,19 @@ import formatTime from '../../utils/format-time.js'; /** * Shows play progress * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class PlayProgressBar */ class PlayProgressBar extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); this.updateDataAttr(); @@ -34,10 +40,10 @@ class PlayProgressBar extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -46,7 +52,15 @@ class PlayProgressBar extends Component { }); } - updateDataAttr() { + /** + * Update the data-current-time attribute on the `PlayProgressBar`. + * + * @param {EventTarget~Event} [event] + * The `timeupdate` event that caused this to run. + * + * @listens Player#timeupdate + */ + updateDataAttr(event) { const time = (this.player_.scrubbing()) ? this.player_.getCache().currentTime : this.player_.currentTime(); this.el_.setAttribute('data-current-time', formatTime(time, this.player_.duration())); diff --git a/src/js/control-bar/progress-control/progress-control.js b/src/js/control-bar/progress-control/progress-control.js index e142f42e3d..b251d868fa 100644 --- a/src/js/control-bar/progress-control/progress-control.js +++ b/src/js/control-bar/progress-control/progress-control.js @@ -8,20 +8,17 @@ import './mouse-time-display.js'; /** * The Progress Control component contains the seek bar, load progress, - * and play progress + * and play progress. * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class ProgressControl */ class ProgressControl extends Component { /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -30,6 +27,12 @@ class ProgressControl extends Component { } } +/** + * Default options for `ProgressControl` + * + * @type {Object} + * @private + */ ProgressControl.prototype.options_ = { children: [ 'seekBar' diff --git a/src/js/control-bar/progress-control/seek-bar.js b/src/js/control-bar/progress-control/seek-bar.js index b46e4189cb..74145c61df 100644 --- a/src/js/control-bar/progress-control/seek-bar.js +++ b/src/js/control-bar/progress-control/seek-bar.js @@ -14,13 +14,19 @@ import './tooltip-progress-bar.js'; /** * Seek Bar and holder for the progress bars * - * @param {Player|Object} player - * @param {Object=} options * @extends Slider - * @class SeekBar */ class SeekBar extends Slider { + /** + * 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. + */ constructor(player, options) { super(player, options); this.on(player, 'timeupdate', this.updateProgress); @@ -40,10 +46,10 @@ class SeekBar extends Slider { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -54,11 +60,15 @@ class SeekBar extends Slider { } /** - * Update ARIA accessibility attributes + * Update the seek bars tooltip and width. + * + * @param {EventTarget~Event} [event] + * The `timeupdate` or `ended` event that caused this to run. * - * @method updateARIAAttributes + * @listens Player#timeupdate + * @listens Player#ended */ - updateProgress() { + updateProgress(event) { this.updateAriaAttributes(this.el_); if (this.keepTooltipsInside) { @@ -75,6 +85,12 @@ class SeekBar extends Slider { } } + /** + * Update ARIA accessibility attributes + * + * @param {Element} el + * The element to update with aria accessibility attributes. + */ updateAriaAttributes(el) { // Allows for smooth scrubbing, when player can't keep up. const time = (this.player_.scrubbing()) ? this.player_.getCache().currentTime : this.player_.currentTime(); @@ -88,8 +104,8 @@ class SeekBar extends Slider { /** * Get percentage of video played * + * @return {Number} Percentage played - * @method getPercent */ getPercent() { const percent = this.player_.currentTime() / this.player_.duration(); @@ -100,7 +116,10 @@ class SeekBar extends Slider { /** * Handle mouse down on seek bar * - * @method handleMouseDown + * @param {EventTarget~Event} event + * The `mousedown` event that caused this to run. + * + * @listens mousedown */ handleMouseDown(event) { super.handleMouseDown(event); @@ -114,7 +133,10 @@ class SeekBar extends Slider { /** * Handle mouse move on seek bar * - * @method handleMouseMove + * @param {EventTarget~Event} event + * The `mousemove` event that caused this to run. + * + * @listens mousemove */ handleMouseMove(event) { let newTime = this.calculateDistance(event) * this.player_.duration(); @@ -131,7 +153,10 @@ class SeekBar extends Slider { /** * Handle mouse up on seek bar * - * @method handleMouseUp + * @param {EventTarget~Event} event + * The `mouseup` event that caused this to run. + * + * @listens mouseup */ handleMouseUp(event) { super.handleMouseUp(event); @@ -144,8 +169,6 @@ class SeekBar extends Slider { /** * Move more quickly fast forward for keyboard-only users - * - * @method stepForward */ stepForward() { // more quickly fast forward for keyboard-only users @@ -154,8 +177,6 @@ class SeekBar extends Slider { /** * Move more quickly rewind for keyboard-only users - * - * @method stepBack */ stepBack() { // more quickly rewind for keyboard-only users @@ -164,6 +185,12 @@ class SeekBar extends Slider { } +/** + * Default options for the `SeekBar` + * + * @type {Object} + * @private + */ SeekBar.prototype.options_ = { children: [ 'loadProgressBar', @@ -173,6 +200,11 @@ SeekBar.prototype.options_ = { barName: 'playProgressBar' }; +/** + * Call the update event for this Slider when this event happens on the player. + * + * @type {string} + */ SeekBar.prototype.playerEvent = 'timeupdate'; Component.registerComponent('SeekBar', SeekBar); diff --git a/src/js/control-bar/progress-control/tooltip-progress-bar.js b/src/js/control-bar/progress-control/tooltip-progress-bar.js index 4a6db351ba..e97d4c5b36 100644 --- a/src/js/control-bar/progress-control/tooltip-progress-bar.js +++ b/src/js/control-bar/progress-control/tooltip-progress-bar.js @@ -8,13 +8,19 @@ import formatTime from '../../utils/format-time.js'; /** * Shows play progress * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class PlayProgressBar */ class TooltipProgressBar extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); this.updateDataAttr(); @@ -23,10 +29,10 @@ class TooltipProgressBar extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl('div', { @@ -40,7 +46,15 @@ class TooltipProgressBar extends Component { return el; } - updateDataAttr() { + /** + * Updatet the data-current-time attribute for TooltipProgressBar + * + * @param {EventTarget~Event} [event] + * The `timeupdate` event that caused this function to run. + * + * @listens Player#timeupdate + */ + updateDataAttr(event) { const time = (this.player_.scrubbing()) ? this.player_.getCache().currentTime : this.player_.currentTime(); const formattedTime = formatTime(time, this.player_.duration()); diff --git a/src/js/control-bar/spacer-controls/custom-control-spacer.js b/src/js/control-bar/spacer-controls/custom-control-spacer.js index a5c5a21f34..a1303e2a35 100644 --- a/src/js/control-bar/spacer-controls/custom-control-spacer.js +++ b/src/js/control-bar/spacer-controls/custom-control-spacer.js @@ -8,25 +8,24 @@ import Component from '../../component.js'; * Spacer specifically meant to be used as an insertion point for new plugins, etc. * * @extends Spacer - * @class CustomControlSpacer */ class CustomControlSpacer extends Spacer { /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-custom-control-spacer ${super.buildCSSClass()}`; } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl({ diff --git a/src/js/control-bar/spacer-controls/spacer.js b/src/js/control-bar/spacer-controls/spacer.js index 66b179f1ba..e175abbfae 100644 --- a/src/js/control-bar/spacer-controls/spacer.js +++ b/src/js/control-bar/spacer-controls/spacer.js @@ -8,25 +8,24 @@ import Component from '../../component.js'; * Also can be used to create space between elements when necessary. * * @extends Component - * @class Spacer */ class Spacer extends Component { - /** - * Allow sub components to stack CSS class names - * - * @return {String} The constructed class name - * @method buildCSSClass - */ + /** + * Builds the default DOM `className`. + * + * @return {string} + * The DOM `className` for this object. + */ buildCSSClass() { return `vjs-spacer ${super.buildCSSClass()}`; } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { 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 7632802cb8..e41c979315 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 @@ -7,13 +7,19 @@ import Component from '../../component.js'; /** * The menu item for caption track settings menu * - * @param {Player|Object} player - * @param {Object=} options * @extends TextTrackMenuItem - * @class CaptionSettingsMenuItem */ class CaptionSettingsMenuItem extends TextTrackMenuItem { + /** + * 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. + */ constructor(player, options) { options.track = { player, @@ -33,11 +39,17 @@ class CaptionSettingsMenuItem extends TextTrackMenuItem { } /** - * Handle click on menu item + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { this.player().getChild('textTrackSettings').show(); this.player().getChild('textTrackSettings').el_.focus(); } 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 929c841022..03171ede92 100644 --- a/src/js/control-bar/text-track-controls/captions-button.js +++ b/src/js/control-bar/text-track-controls/captions-button.js @@ -8,24 +8,32 @@ import CaptionSettingsMenuItem from './caption-settings-menu-item.js'; /** * The button component for toggling and selecting captions * - * @param {Object} player Player object - * @param {Object=} options Object of option names and values - * @param {Function=} ready Ready callback function * @extends TextTrackButton - * @class CaptionsButton */ class CaptionsButton 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 {Component~ReadyCallback} [ready] + * The function to call when this component is ready. + */ constructor(player, options, ready) { super(player, options, ready); this.el_.setAttribute('aria-label', 'Captions Menu'); } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-captions-button ${super.buildCSSClass()}`; @@ -34,9 +42,14 @@ class CaptionsButton extends TextTrackButton { /** * Update caption menu items * - * @method update + * @param {EventTarget~Event} [event] + * The `addtrack` or `removetrack` event that caused this function to be + * called. + * + * @listens TextTrackList#addtrack + * @listens TextTrackList#removetrack */ - update() { + update(event) { let threshold = 2; super.update(); @@ -56,8 +69,8 @@ class CaptionsButton extends TextTrackButton { /** * Create caption menu items * - * @return {Array} Array of menu items - * @method createItems + * @return {CaptionSettingsMenuItem[]} + * The array of current menu items. */ createItems() { const items = []; @@ -71,7 +84,20 @@ class CaptionsButton extends TextTrackButton { } +/** + * `kind` of TextTrack to look for to associate it with this menu. + * + * @type {string} + * @private + */ CaptionsButton.prototype.kind_ = 'captions'; + +/** + * The text that should display over the `CaptionsButton`s controls. Added for localization. + * + * @type {string} + * @private + */ CaptionsButton.prototype.controlText_ = 'Captions'; Component.registerComponent('CaptionsButton', CaptionsButton); 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 a6e1b4da33..2f65d55d0d 100644 --- a/src/js/control-bar/text-track-controls/chapters-button.js +++ b/src/js/control-bar/text-track-controls/chapters-button.js @@ -11,29 +11,47 @@ import toTitleCase from '../../utils/to-title-case.js'; * Chapters act much differently than other text tracks * Cues are navigation vs. other tracks of alternative languages * - * @param {Object} player Player object - * @param {Object=} options Object of option names and values - * @param {Function=} ready Ready callback function * @extends TextTrackButton - * @class ChaptersButton */ class ChaptersButton 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 {Component~ReadyCallback} [ready] + * The function to call when this function is ready. + */ constructor(player, options, ready) { super(player, options, ready); this.el_.setAttribute('aria-label', 'Chapters Menu'); } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-chapters-button ${super.buildCSSClass()}`; } + /** + * Update the menu based on the current state of its items. + * + * @param {EventTarget~Event} [event] + * An event that triggered this function to run. + * + * @listens TextTrackList#addtrack + * @listens TextTrackList#removetrack + * @listens TextTrackList#change + */ update(event) { if (!this.track_ || (event && (event.type === 'addtrack' || event.type === 'removetrack'))) { this.setTrack(this.findChaptersTrack()); @@ -41,6 +59,13 @@ class ChaptersButton extends TextTrackButton { super.update(); } + /** + * Set the currently selected track for the chapters button. + * + * @param {TextTrack} track + * The new track to select. Nothing will change if this is the currently selected + * track. + */ setTrack(track) { if (this.track_ === track) { return; @@ -75,6 +100,12 @@ class ChaptersButton extends TextTrackButton { } } + /** + * Find the track object that is currently in use by this ChaptersButton + * + * @return {TextTrack|undefined} + * The current track or undefined if none was found. + */ findChaptersTrack() { const tracks = this.player_.textTracks() || []; @@ -88,6 +119,13 @@ class ChaptersButton extends TextTrackButton { } } + /** + * Get the caption for the ChaptersButton based on the track label. This will also + * use the current tracks localized kind as a fallback if a label does not exist. + * + * @return {string} + * The tracks current label or the localized track kind. + */ getMenuCaption() { if (this.track_ && this.track_.label) { return this.track_.label; @@ -98,8 +136,8 @@ class ChaptersButton extends TextTrackButton { /** * Create menu from chapter track * - * @return {Menu} Menu of chapter buttons - * @method createMenu + * @return {Menu} + * New menu for the chapter buttons */ createMenu() { this.options_.title = this.getMenuCaption(); @@ -107,10 +145,10 @@ class ChaptersButton extends TextTrackButton { } /** - * Create a menu item for each chapter cue + * Create a menu item for each text track * - * @return {Array} Array of menu items - * @method createItems + * @return {TextTrackMenuItem[]} + * Array of menu items */ createItems() { const items = []; @@ -136,7 +174,20 @@ class ChaptersButton extends TextTrackButton { } } +/** + * `kind` of TextTrack to look for to associate it with this menu. + * + * @type {string} + * @private + */ ChaptersButton.prototype.kind_ = 'chapters'; + +/** + * The text that should display over the `ChaptersButton`s controls. Added for localization. + * + * @type {string} + * @private + */ ChaptersButton.prototype.controlText_ = 'Chapters'; Component.registerComponent('ChaptersButton', ChaptersButton); 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 b2b509f139..1faeb252bb 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 @@ -8,13 +8,19 @@ import * as Fn from '../../utils/fn.js'; /** * The chapter track menu item * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuItem - * @class ChaptersTrackMenuItem */ class ChaptersTrackMenuItem extends MenuItem { + /** + * 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. + */ constructor(player, options) { const track = options.track; const cue = options.cue; @@ -32,11 +38,17 @@ class ChaptersTrackMenuItem extends MenuItem { } /** - * Handle click on menu item + * 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] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { super.handleClick(); this.player_.currentTime(this.cue.startTime); this.update(this.cue.startTime); @@ -45,9 +57,12 @@ class ChaptersTrackMenuItem extends MenuItem { /** * Update chapter menu item * - * @method update + * @param {EventTarget~Event} [event] + * The `cuechange` event that caused this function to run. + * + * @listens TextTrack#cuechange */ - update() { + update(event) { const cue = this.cue; const currentTime = this.player_.currentTime(); 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 0b7bd02b45..1f74af933d 100644 --- a/src/js/control-bar/text-track-controls/descriptions-button.js +++ b/src/js/control-bar/text-track-controls/descriptions-button.js @@ -8,14 +8,22 @@ import * as Fn from '../../utils/fn.js'; /** * The button component for toggling and selecting descriptions * - * @param {Object} player Player object - * @param {Object=} options Object of option names and values - * @param {Function=} ready Ready callback function * @extends TextTrackButton - * @class DescriptionsButton */ class DescriptionsButton 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 {Component~ReadyCallback} [ready] + * The function to call when this component is ready. + */ constructor(player, options, ready) { super(player, options, ready); this.el_.setAttribute('aria-label', 'Descriptions Menu'); @@ -35,7 +43,10 @@ class DescriptionsButton extends TextTrackButton { /** * Handle text track change * - * @method handleTracksChange + * @param {EventTarget~Event} event + * The event that caused this function to run + * + * @listens TextTrackList#change */ handleTracksChange(event) { const tracks = this.player().textTracks(); @@ -60,10 +71,10 @@ class DescriptionsButton extends TextTrackButton { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-descriptions-button ${super.buildCSSClass()}`; @@ -71,7 +82,20 @@ class DescriptionsButton extends TextTrackButton { } +/** + * `kind` of TextTrack to look for to associate it with this menu. + * + * @type {string} + * @private + */ DescriptionsButton.prototype.kind_ = 'descriptions'; + +/** + * The text that should display over the `DescriptionsButton`s controls. Added for localization. + * + * @type {string} + * @private + */ DescriptionsButton.prototype.controlText_ = 'Descriptions'; Component.registerComponent('DescriptionsButton', DescriptionsButton); 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 a23b82bd4d..98e9caa81a 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 @@ -7,13 +7,19 @@ import Component from '../../component.js'; /** * A special menu item for turning of a specific type of text track * - * @param {Player|Object} player - * @param {Object=} options * @extends TextTrackMenuItem - * @class OffTextTrackMenuItem */ class OffTextTrackMenuItem extends TextTrackMenuItem { + /** + * 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. + */ constructor(player, options) { // Create pseudo track info // Requires options['kind'] @@ -35,8 +41,8 @@ class OffTextTrackMenuItem extends TextTrackMenuItem { /** * Handle text track change * - * @param {Object} event Event object - * @method handleTracksChange + * @param {EventTarget~Event} event + * The event that caused this function to run */ handleTracksChange(event) { const tracks = this.player().textTracks(); 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 207e8179d2..02c565575b 100644 --- a/src/js/control-bar/text-track-controls/subtitles-button.js +++ b/src/js/control-bar/text-track-controls/subtitles-button.js @@ -7,24 +7,32 @@ import Component from '../../component.js'; /** * The button component for toggling and selecting subtitles * - * @param {Object} player Player object - * @param {Object=} options Object of option names and values - * @param {Function=} ready Ready callback function * @extends TextTrackButton - * @class SubtitlesButton */ class SubtitlesButton 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 {Component~ReadyCallback} [ready] + * The function to call when this component is ready. + */ constructor(player, options, ready) { super(player, options, ready); this.el_.setAttribute('aria-label', 'Subtitles Menu'); } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { return `vjs-subtitles-button ${super.buildCSSClass()}`; @@ -32,7 +40,20 @@ class SubtitlesButton extends TextTrackButton { } +/** + * `kind` of TextTrack to look for to associate it with this menu. + * + * @type {string} + * @private + */ SubtitlesButton.prototype.kind_ = 'subtitles'; + +/** + * The text that should display over the `SubtitlesButton`s controls. Added for localization. + * + * @type {string} + * @private + */ SubtitlesButton.prototype.controlText_ = 'Subtitles'; Component.registerComponent('SubtitlesButton', SubtitlesButton); 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 fced8fb3ce..bc2d36c772 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 @@ -9,13 +9,19 @@ import OffTextTrackMenuItem from './off-text-track-menu-item.js'; /** * The base class for buttons that toggle specific text track types (e.g. subtitles) * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuButton - * @class TextTrackButton */ class TextTrackButton extends TrackButton { + /** + * 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. + */ constructor(player, options = {}) { options.tracks = player.textTracks(); @@ -25,8 +31,11 @@ class TextTrackButton extends TrackButton { /** * Create a menu item for each text track * - * @return {Array} Array of menu items - * @method createItems + * @param {TextTrackMenuItem[]} [items=[]] + * Existing array of items to use during creation + * + * @return {TextTrackMenuItem[]} + * Array of menu items that were created */ createItems(items = []) { // Add an OFF menu item to turn all tracks off 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 ccb5b02010..82e96a83bf 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 @@ -10,13 +10,19 @@ import document from 'global/document'; /** * The specific menu item type for selecting a language within a text track kind * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuItem - * @class TextTrackMenuItem */ class TextTrackMenuItem extends MenuItem { + /** + * 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. + */ constructor(player, options) { const track = options.track; const tracks = player.textTracks(); @@ -68,9 +74,15 @@ class TextTrackMenuItem extends MenuItem { } /** - * Handle click on text track + * 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 + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ handleClick(event) { const kind = this.track.kind; @@ -98,9 +110,12 @@ class TextTrackMenuItem extends MenuItem { } /** - * Handle text track change + * Handle text track list change + * + * @param {EventTarget~Event} event + * The `change` event that caused this function to be called. * - * @method handleTracksChange + * @listens TextTrackList#change */ handleTracksChange(event) { this.selected(this.track.mode === 'showing'); 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 66a102aeea..ba2cf4494e 100644 --- a/src/js/control-bar/time-controls/current-time-display.js +++ b/src/js/control-bar/time-controls/current-time-display.js @@ -8,13 +8,19 @@ import formatTime from '../../utils/format-time.js'; /** * Displays the current time * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class CurrentTimeDisplay */ class CurrentTimeDisplay extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -22,10 +28,10 @@ class CurrentTimeDisplay extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl('div', { @@ -48,9 +54,12 @@ class CurrentTimeDisplay extends Component { /** * Update current time display * - * @method updateContent + * @param {EventTarget~Event} [event] + * The `timeupdate` event that caused this function to run. + * + * @listens Player#timeupdate */ - updateContent() { + updateContent(event) { // Allows for smooth scrubbing, when player can't keep up. const time = (this.player_.scrubbing()) ? this.player_.getCache().currentTime : this.player_.currentTime(); const localizedText = this.localize('Current Time'); diff --git a/src/js/control-bar/time-controls/duration-display.js b/src/js/control-bar/time-controls/duration-display.js index 00cfcd9ae6..82385fa4f7 100644 --- a/src/js/control-bar/time-controls/duration-display.js +++ b/src/js/control-bar/time-controls/duration-display.js @@ -8,13 +8,19 @@ import formatTime from '../../utils/format-time.js'; /** * Displays the duration * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class DurationDisplay */ class DurationDisplay extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -28,10 +34,10 @@ class DurationDisplay extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl('div', { @@ -52,11 +58,17 @@ class DurationDisplay extends Component { } /** - * Update duration time display + * Update duration time display. + * + * @param {EventTarget~Event} [event] + * The `durationchange`, `timeupdate`, or `loadedmetadata` event that caused + * this function to be called. * - * @method updateContent + * @listens Player#durationchange + * @listens Player#timeupdate + * @listens Player#loadedmetadata */ - updateContent() { + updateContent(event) { const duration = this.player_.duration(); if (duration && this.duration_ !== duration) { 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 40914b7cd1..fcd3b49912 100644 --- a/src/js/control-bar/time-controls/remaining-time-display.js +++ b/src/js/control-bar/time-controls/remaining-time-display.js @@ -8,13 +8,19 @@ import formatTime from '../../utils/format-time.js'; /** * Displays the time left in the video * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class RemainingTimeDisplay */ class RemainingTimeDisplay extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -23,10 +29,10 @@ class RemainingTimeDisplay extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { const el = super.createEl('div', { @@ -47,11 +53,15 @@ class RemainingTimeDisplay extends Component { } /** - * Update remaining time display + * Update remaining time display. + * + * @param {EventTarget~Event} [event] + * The `timeupdate` or `durationchange` event that caused this to run. * - * @method updateContent + * @listens Player#timeupdate + * @listens Player#durationchange */ - updateContent() { + updateContent(event) { if (this.player_.duration()) { const localizedText = this.localize('Remaining Time'); const formattedTime = formatTime(this.player_.remainingTime()); diff --git a/src/js/control-bar/time-controls/time-divider.js b/src/js/control-bar/time-controls/time-divider.js index 7ae6f416ef..cd4ee558f2 100644 --- a/src/js/control-bar/time-controls/time-divider.js +++ b/src/js/control-bar/time-controls/time-divider.js @@ -7,10 +7,7 @@ import Component from '../../component.js'; * The separator between the current time and duration. * Can be hidden if it's not needed in the design. * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class TimeDivider */ class TimeDivider extends Component { @@ -18,7 +15,7 @@ class TimeDivider extends Component { * Create the component's DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { diff --git a/src/js/control-bar/track-button.js b/src/js/control-bar/track-button.js index 4b3056b1a8..e9df0aea4c 100644 --- a/src/js/control-bar/track-button.js +++ b/src/js/control-bar/track-button.js @@ -6,15 +6,21 @@ import Component from '../component.js'; import * as Fn from '../utils/fn.js'; /** - * The base class for buttons that toggle specific text track types (e.g. subtitles) + * The base class for buttons that toggle specific track types (e.g. subtitles). * - * @param {Player|Object} player - * @param {Object=} options * @extends MenuButton - * @class TrackButton */ class TrackButton extends MenuButton { + /** + * 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. + */ constructor(player, options) { const tracks = options.tracks; diff --git a/src/js/control-bar/volume-control/volume-bar.js b/src/js/control-bar/volume-control/volume-bar.js index db44eb9e59..261b9b4b9b 100644 --- a/src/js/control-bar/volume-control/volume-bar.js +++ b/src/js/control-bar/volume-control/volume-bar.js @@ -11,13 +11,19 @@ import './volume-level.js'; /** * The bar that contains the volume level and can be clicked on to adjust the level * - * @param {Player|Object} player - * @param {Object=} options * @extends Slider - * @class VolumeBar */ class VolumeBar extends Slider { + /** + * 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. + */ constructor(player, options) { super(player, options); this.on(player, 'volumechange', this.updateARIAAttributes); @@ -25,10 +31,10 @@ class VolumeBar extends Slider { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -39,15 +45,21 @@ class VolumeBar extends Slider { } /** - * Handle mouse move on volume bar + * Handle movement events on the {@link VolumeMenuButton}. * - * @method handleMouseMove + * @param {EventTarget~Event} event + * The event that caused this function to run. + * + * @listens mousemove */ handleMouseMove(event) { this.checkMuted(); this.player_.volume(this.calculateDistance(event)); } + /** + * If the player is muted unmute it. + */ checkMuted() { if (this.player_.muted()) { this.player_.muted(false); @@ -57,8 +69,8 @@ class VolumeBar extends Slider { /** * Get percent of volume level * - * @retun {Number} Volume level percent - * @method getPercent + * @return {number} + * Volume level percent as a decimal number. */ getPercent() { if (this.player_.muted()) { @@ -69,8 +81,6 @@ class VolumeBar extends Slider { /** * Increase volume level for keyboard users - * - * @method stepForward */ stepForward() { this.checkMuted(); @@ -79,8 +89,6 @@ class VolumeBar extends Slider { /** * Decrease volume level for keyboard users - * - * @method stepBack */ stepBack() { this.checkMuted(); @@ -90,9 +98,12 @@ class VolumeBar extends Slider { /** * Update ARIA accessibility attributes * - * @method updateARIAAttributes + * @param {EventTarget~Event} [event] + * The `volumechange` event that caused this function to run. + * + * @listens Player#volumechange */ - updateARIAAttributes() { + updateARIAAttributes(event) { // Current value of volume bar as a percentage const volume = (this.player_.volume() * 100).toFixed(2); @@ -102,6 +113,12 @@ class VolumeBar extends Slider { } +/** + * Default options for the `VolumeBar` + * + * @type {Object} + * @private + */ VolumeBar.prototype.options_ = { children: [ 'volumeLevel' @@ -109,6 +126,11 @@ VolumeBar.prototype.options_ = { barName: 'volumeLevel' }; +/** + * Call the update event for this Slider when this event happens on the player. + * + * @type {string} + */ VolumeBar.prototype.playerEvent = 'volumechange'; Component.registerComponent('VolumeBar', VolumeBar); diff --git a/src/js/control-bar/volume-control/volume-control.js b/src/js/control-bar/volume-control/volume-control.js index 741b403c17..b3caf6bacf 100644 --- a/src/js/control-bar/volume-control/volume-control.js +++ b/src/js/control-bar/volume-control/volume-control.js @@ -9,13 +9,19 @@ import './volume-bar.js'; /** * The component for controlling the volume level * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class VolumeControl */ class VolumeControl extends Component { + /** + * 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. + */ constructor(player, options) { super(player, options); @@ -33,10 +39,10 @@ class VolumeControl extends Component { } /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { @@ -46,6 +52,12 @@ class VolumeControl extends Component { } +/** + * Default options for the `VolumeControl` + * + * @type {Object} + * @private + */ VolumeControl.prototype.options_ = { children: [ 'volumeBar' diff --git a/src/js/control-bar/volume-control/volume-level.js b/src/js/control-bar/volume-control/volume-level.js index 26a422694d..88bb0fe448 100644 --- a/src/js/control-bar/volume-control/volume-level.js +++ b/src/js/control-bar/volume-control/volume-level.js @@ -6,18 +6,15 @@ import Component from '../../component.js'; /** * Shows volume level * - * @param {Player|Object} player - * @param {Object=} options * @extends Component - * @class VolumeLevel */ class VolumeLevel extends Component { /** - * Create the component's DOM element + * Create the `Component`'s DOM element * * @return {Element} - * @method createEl + * The element that was created. */ createEl() { return super.createEl('div', { diff --git a/src/js/control-bar/volume-menu-button.js b/src/js/control-bar/volume-menu-button.js index d650a245e4..6f71510c76 100644 --- a/src/js/control-bar/volume-menu-button.js +++ b/src/js/control-bar/volume-menu-button.js @@ -11,13 +11,19 @@ import VolumeBar from './volume-control/volume-bar.js'; /** * Button for volume popup * - * @param {Player|Object} player - * @param {Object=} options * @extends PopupButton - * @class VolumeMenuButton */ class VolumeMenuButton extends PopupButton { + /** + * 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. + */ constructor(player, options = {}) { // Default to inline if (options.inline === undefined) { @@ -76,10 +82,10 @@ class VolumeMenuButton extends PopupButton { } /** - * Allow sub components to stack CSS class names + * Builds the default DOM `className`. * - * @return {String} The constructed class name - * @method buildCSSClass + * @return {string} + * The DOM `className` for this object. */ buildCSSClass() { let orientationClass = ''; @@ -94,10 +100,7 @@ class VolumeMenuButton extends PopupButton { } /** - * Allow sub components to stack CSS class names - * - * @return {Popup} The volume popup button - * @method createPopup + * Create the VolumeMenuButton popup */ createPopup() { const popup = new Popup(this.player_, { @@ -117,30 +120,67 @@ class VolumeMenuButton extends PopupButton { } /** - * Handle click on volume popup and calls super + * This gets called when an `VolumeMenuButton` is "clicked". See + * {@link ClickableComponent} for more detailed information on what a click can be. + * + * @param {EventTarget~Event} [event] + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @listens tap + * @listens click */ - handleClick() { + handleClick(event) { MuteToggle.prototype.handleClick.call(this); super.handleClick(); } + /** + * Add events listeners to the created `VolumeBar`. + */ attachVolumeBarEvents() { this.menuContent.on(['mousedown', 'touchdown'], Fn.bind(this, this.handleMouseDown)); } + /** + * Handle the `mousedown` and `touchdown` events on the `VolumeBar` + * + * @param {EventTarget~Event} [event] + * The `mousedown` or `touchdown` event that caused this to run. + * + * @listens mousedown + * @listens touchdown + */ handleMouseDown(event) { this.on(['mousemove', 'touchmove'], Fn.bind(this.volumeBar, this.volumeBar.handleMouseMove)); this.on(this.el_.ownerDocument, ['mouseup', 'touchend'], this.handleMouseUp); } + /** + * Handle the `mouseup` and `touchend` events on the `VolumeBar` + * + * @param {EventTarget~Event} [event] + * The `mouseup` or `touchend` event that caused this to run. + * + * @listens mouseup + * @listens touchend + */ handleMouseUp(event) { this.off(['mousemove', 'touchmove'], Fn.bind(this.volumeBar, this.volumeBar.handleMouseMove)); } } +/** + * @borrows MuteToggle#update as VolumeMenuButton#volumeUpdate + */ VolumeMenuButton.prototype.volumeUpdate = MuteToggle.prototype.update; + +/** + * The text that should display over the `VolumeMenuButton`s controls. Added for localization. + * + * @type {string} + * @private + */ VolumeMenuButton.prototype.controlText_ = 'Mute'; Component.registerComponent('VolumeMenuButton', VolumeMenuButton); diff --git a/src/js/utils/dom.js b/src/js/utils/dom.js index 4ad1bbd1d0..125a0308f3 100644 --- a/src/js/utils/dom.js +++ b/src/js/utils/dom.js @@ -1,5 +1,6 @@ /** * @file dom.js + * @module dom */ import document from 'global/document'; import window from 'global/window'; @@ -10,8 +11,13 @@ import tsml from 'tsml'; /** * Detect if a value is a string with any non-whitespace characters. * - * @param {String} str - * @return {Boolean} + * @param {string} str + * The string to check + * + * @return {boolean} + * - True if the string is non-blank + * - False otherwise + * */ function isNonBlankString(str) { return typeof str === 'string' && (/\S/).test(str); @@ -21,8 +27,12 @@ function isNonBlankString(str) { * Throws an error if the passed string has whitespace. This is used by * class methods to be relatively consistent with the classList API. * - * @param {String} str - * @return {Boolean} + * @param {string} str + * The string to check for whitespace. + * + * @throws {Error} + * Throws an error if there is whitespace in the string. + * */ function throwIfWhitespace(str) { if ((/\s/).test(str)) { @@ -31,10 +41,14 @@ function throwIfWhitespace(str) { } /** - * Produce a regular expression for matching a class name. + * Produce a regular expression for matching a className within an elements className. + * + * @param {string} className + * The className to generate the RegExp for. * - * @param {String} className * @return {RegExp} + * The RegExp that will check for a specific `className` in an elements + * className. */ function classRegExp(className) { return new RegExp('(^|\\s)' + className + '($|\\s)'); @@ -43,9 +57,12 @@ function classRegExp(className) { /** * Determines, via duck typing, whether or not a value is a DOM element. * - * @function isEl - * @param {Mixed} value - * @return {Boolean} + * @param {Mixed} value + * The thing to check + * + * @return {boolean} + * - True if it is a DOM element + * - False otherwise */ export function isEl(value) { return !!value && typeof value === 'object' && value.nodeType === 1; @@ -54,10 +71,11 @@ export function isEl(value) { /** * Creates functions to query the DOM using a given method. * - * @function createQuerier - * @private - * @param {String} method + * @param {string} method + * The method to create the query with. + * * @return {Function} + * The query method */ function createQuerier(method) { return function(selector, context) { @@ -78,9 +96,11 @@ function createQuerier(method) { * Shorthand for document.getElementById() * Also allows for CSS (jQuery) ID syntax. But nothing other than IDs. * - * @param {String} id Element ID - * @return {Element} Element with supplied ID - * @function getEl + * @param {string} id + * The id of the element to get + * + * @return {Element|null} + * Element with supplied ID or null if there wasn't one. */ export function getEl(id) { if (id.indexOf('#') === 0) { @@ -93,12 +113,20 @@ export function getEl(id) { /** * Creates an element and applies properties. * - * @param {String} [tagName='div'] Name of tag to be created. - * @param {Object} [properties={}] Element properties to be applied. - * @param {Object} [attributes={}] Element attributes to be applied. - * @param {String|Element|TextNode|Array|Function} [content] Contents for the element (see: `normalizeContent`) + * @param {string} [tagName='div'] + * Name of tag to be created. + * + * @param {Object} [properties={}] + * Element properties to be applied. + * + * @param {Object} [attributes={}] + * Element attributes to be applied. + * + * @param {String|Element|TextNode|Array|Function} [content] + * Contents for the element (see: {@link dom:normalizeContent}) + * * @return {Element} - * @function createEl + * The element that was created. */ export function createEl(tagName = 'div', properties = {}, attributes = {}, content) { const el = document.createElement(tagName); @@ -138,10 +166,14 @@ export function createEl(tagName = 'div', properties = {}, attributes = {}, cont /** * Injects text into an element, replacing any existing contents entirely. * - * @param {Element} el - * @param {String} text + * @param {Element} el + * The element to add text content into + * + * @param {string} text + * The text content to add. + * * @return {Element} - * @function textContent + * The element with added text content. */ export function textContent(el, text) { if (typeof el.textContent === 'undefined') { @@ -155,10 +187,12 @@ export function textContent(el, text) { /** * Insert an element as the first child node of another * - * @param {Element} child Element to insert - * @param {Element} parent Element to insert child into - * @private - * @function insertElFirst + * @param {Element} child + * Element to insert + * + * @param {Element} parent + * Element to insert child into + * */ export function insertElFirst(child, parent) { if (parent.firstChild) { @@ -181,7 +215,7 @@ const elData = {}; /* * Unique attribute name to store an element's guid in * - * @type {String} + * @type {string} * @constant * @private */ @@ -190,9 +224,11 @@ const elIdAttr = 'vdata' + (new Date()).getTime(); /** * Returns the cache object where data for an element is stored * - * @param {Element} el Element to store data for. + * @param {Element} el + * Element to store data for. + * * @return {Object} - * @function getElData + * The cache object for that el that was passed in. */ export function getElData(el) { let id = el[elIdAttr]; @@ -211,10 +247,12 @@ export function getElData(el) { /** * Returns whether or not an element has cached data * - * @param {Element} el A dom element - * @return {Boolean} - * @private - * @function hasElData + * @param {Element} el + * Check if this element has cached data. + * + * @return {boolean} + * - True if the DOM element has cached data. + * - False otherwise. */ export function hasElData(el) { const id = el[elIdAttr]; @@ -229,9 +267,8 @@ export function hasElData(el) { /** * Delete data for the element from the cache and the guid attr from getElementById * - * @param {Element} el Remove data for an element - * @private - * @function removeElData + * @param {Element} el + * Remove cached data for this element. */ export function removeElData(el) { const id = el[elIdAttr]; @@ -259,9 +296,18 @@ export function removeElData(el) { /** * Check if an element has a CSS class * - * @function hasElClass - * @param {Element} element Element to check - * @param {String} classToCheck Classname to check + * @param {Element} element + * Element to check + * + * @param {string} classToCheck + * Class name to check for + * + * @return {boolean} + * - True if the element had the class + * - False otherwise. + * + * @throws {Error} + * Throws an error if `classToCheck` has white space. */ export function hasElClass(element, classToCheck) { throwIfWhitespace(classToCheck); @@ -274,9 +320,14 @@ export function hasElClass(element, classToCheck) { /** * Add a CSS class name to an element * - * @function addElClass - * @param {Element} element Element to add class name to - * @param {String} classToAdd Classname to add + * @param {Element} element + * Element to add class name to. + * + * @param {string} classToAdd + * Class name to add. + * + * @return {Element} + * The dom element with the added class name. */ export function addElClass(element, classToAdd) { if (element.classList) { @@ -294,9 +345,14 @@ export function addElClass(element, classToAdd) { /** * Remove a CSS class name from an element * - * @function removeElClass - * @param {Element} element Element to remove from class name - * @param {String} classToRemove Classname to remove + * @param {Element} element + * Element to remove a class name from. + * + * @param {string} classToRemove + * Class name to remove + * + * @return {Element} + * The dom element with class name removed. */ export function removeElClass(element, classToRemove) { if (element.classList) { @@ -311,17 +367,37 @@ export function removeElClass(element, classToRemove) { return element; } +/** + * The callback definition for toggleElClass. + * + * @callback Dom~PredicateCallback + * @param {Element} element + * The DOM element of the Component. + * + * @param {string} classToToggle + * The `className` that wants to be toggled + * + * @return {boolean|undefined} + * - If true the `classToToggle` will get added to `element`. + * - If false the `classToToggle` will get removed from `element`. + * - If undefined this callback will be ignored + */ + /** * Adds or removes a CSS class name on an element depending on an optional * condition or the presence/absence of the class name. * - * @function toggleElClass - * @param {Element} element - * @param {String} classToToggle - * @param {Boolean|Function} [predicate] - * Can be a function that returns a Boolean. If `true`, the class - * will be added; if `false`, the class will be removed. If not - * given, the class will be added if not present and vice versa. + * @param {Element} element + * The element to toggle a class name on. + * + * @param {string} classToToggle + * The class that should be toggled + * + * @param {boolean|PredicateCallback} [predicate] + * See the return value for {@link Dom~PredicateCallback} + * + * @return {Element} + * The element with a class that has been toggled. */ export function toggleElClass(element, classToToggle, predicate) { @@ -356,10 +432,11 @@ export function toggleElClass(element, classToToggle, predicate) { /** * Apply attributes to an HTML element. * - * @param {Element} el Target element. - * @param {Object=} attributes Element attributes to be applied. - * @private - * @function setElAttributes + * @param {Element} el + * Element to add attributes to. + * + * @param {Object} [attributes] + * Attributes to be applied. */ export function setElAttributes(el, attributes) { Object.getOwnPropertyNames(attributes).forEach(function(attrName) { @@ -379,10 +456,11 @@ export function setElAttributes(el, attributes) { * or with setAttribute (which shouldn't be used with HTML) * This will return true or false for boolean attributes. * - * @param {Element} tag Element from which to get tag attributes + * @param {Element} tag + * Element from which to get tag attributes. + * * @return {Object} - * @private - * @function getElAttributes + * All attributes of the element. */ export function getElAttributes(tag) { const obj = {}; @@ -419,9 +497,13 @@ export function getElAttributes(tag) { * Get the value of an element's attribute * * @param {Element} el - * @param {String} attribute Attribute to get - * @return {String} value of the attribute - * @method getAttribute + * A DOM element + * + * @param {string} attribute + * Attribute to get the value of + * + * @return {string} + * value of the attribute */ export function getAttribute(el, attribute) { return el.getAttribute(attribute); @@ -431,9 +513,13 @@ export function getAttribute(el, attribute) { * Set the value of an element's attribute * * @param {Element} el - * @param {String} attribute Attribute to set - * @param {String} value Value to set the attribute to - * @method setAttribute + * A DOM element + * + * @param {string} attribute + * Attribute to set + * + * @param {string} value + * Value to set the attribute to */ export function setAttribute(el, attribute, value) { el.setAttribute(attribute, value); @@ -443,8 +529,10 @@ export function setAttribute(el, attribute, value) { * Remove an element's attribute * * @param {Element} el - * @param {String} attribute Attribute to remove - * @method removeAttribute + * A DOM element + * + * @param {string} attribute + * Attribute to remove */ export function removeAttribute(el, attribute) { el.removeAttribute(attribute); @@ -452,9 +540,6 @@ export function removeAttribute(el, attribute) { /** * Attempt to block the ability to select text while dragging controls - * - * @return {Boolean} - * @function blockTextSelection */ export function blockTextSelection() { document.body.focus(); @@ -465,9 +550,6 @@ export function blockTextSelection() { /** * Turn off text selection blocking - * - * @return {Boolean} - * @function unblockTextSelection */ export function unblockTextSelection() { document.onselectstart = function() { @@ -476,13 +558,29 @@ export function unblockTextSelection() { } /** - * Offset Left + * The postion of a DOM element on the page. + * + * @typedef {Object} Dom~Position + * + * @property {number} left + * Pixels to the left + * + * @property {number} top + * Pixels on top + */ + +/** + * Offset Left. * getBoundingClientRect technique from - * John Resig http://ejohn.org/blog/getboundingclientrect-is-awesome/ + * John Resig * - * @function findElPosition - * @param {Element} el Element from which to get offset - * @return {Object} + * @see http://ejohn.org/blog/getboundingclientrect-is-awesome/ + * + * @param {Element} el + * Element from which to get offset + * + * @return {Dom~Position} + * The position of the element that was passed in. */ export function findElPosition(el) { let box; @@ -516,15 +614,32 @@ export function findElPosition(el) { }; } +/** + * x and y coordinates for a dom element or mouse pointer + * + * @typedef {Object} Dom~Coordinates + * + * @property {number} x + * x coordinate in pixels + * + * @property {number} y + * y coordinate in pixels + */ + /** * Get pointer position in element * Returns an object with x and y coordinates. * The base on the coordinates are the bottom left of the element. * - * @function getPointerPosition - * @param {Element} el Element on which to get the pointer position on - * @param {Event} event Event object - * @return {Object} This object will have x and y coordinates corresponding to the mouse position + * @param {Element} el + * Element on which to get the pointer position on + * + * @param {EventTarget~Event} event + * Event object + * + * @return {Dom~Coordinates} + * A Coordinates object corresponding to the mouse position. + * */ export function getPointerPosition(el, event) { const position = {}; @@ -551,8 +666,12 @@ export function getPointerPosition(el, event) { /** * Determines, via duck typing, whether or not a value is a text node. * - * @param {Mixed} value - * @return {Boolean} + * @param {Mixed} value + * Check if this value is a text node. + * + * @return {boolean} + * - True if it is a text node + * - False otherwise */ export function isTextNode(value) { return !!value && typeof value === 'object' && value.nodeType === 3; @@ -561,9 +680,11 @@ export function isTextNode(value) { /** * Empties the contents of an element. * - * @function emptyEl - * @param {Element} el - * @return {Element} + * @param {Element} el + * The element to empty children from + * + * @return {Element} + * The element with no children */ export function emptyEl(el) { while (el.firstChild) { @@ -582,23 +703,16 @@ export function emptyEl(el) { * The content for an element can be passed in multiple types and * combinations, whose behavior is as follows: * - * - String - * Normalized into a text node. + * @param {String|Element|TextNode|Array|Function} content + * - String: Normalized into a text node. + * - Element/TextNode: Passed through. + * - Array: A one-dimensional array of strings, elements, nodes, or functions + * (which return single strings, elements, or nodes). + * - Function: If the sole argument, is expected to produce a string, element, + * node, or array as defined above. * - * - Element, TextNode - * Passed through. - * - * - Array - * A one-dimensional array of strings, elements, nodes, or functions (which - * return single strings, elements, or nodes). - * - * - Function - * If the sole argument, is expected to produce a string, element, - * node, or array. - * - * @function normalizeContent - * @param {String|Element|TextNode|Array|Function} content - * @return {Array} + * @return {Array} + * All of the content that was passed in normalized. */ export function normalizeContent(content) { @@ -631,11 +745,15 @@ export function normalizeContent(content) { /** * Normalizes and appends content to an element. * - * @function appendContent - * @param {Element} el - * @param {String|Element|TextNode|Array|Function} content - * See: `normalizeContent` - * @return {Element} + * @param {Element} el + * Element to append normalized content to. + * + * + * @param {String|Element|TextNode|Array|Function} content + * See the `content` argument of {@link dom:normalizeContent} + * + * @return {Element} + * The element with appended normalized content. */ export function appendContent(el, content) { normalizeContent(content).forEach(node => el.appendChild(node)); @@ -646,11 +764,15 @@ export function appendContent(el, content) { * Normalizes and inserts content into an element; this is identical to * `appendContent()`, except it empties the element first. * - * @function insertContent - * @param {Element} el - * @param {String|Element|TextNode|Array|Function} content - * See: `normalizeContent` - * @return {Element} + * @param {Element} el + * Element to insert normalized content into. + * + * @param {String|Element|TextNode|Array|Function} content + * See the `content` argument of {@link dom:normalizeContent} + * + * @return {Element} + * The element with inserted normalized content. + * */ export function insertContent(el, content) { return appendContent(emptyEl(el), content); @@ -660,17 +782,17 @@ export function insertContent(el, content) { * Finds a single DOM element matching `selector` within the optional * `context` of another DOM element (defaulting to `document`). * - * @function $ - * @param {String} selector - * A valid CSS selector, which will be passed to `querySelector`. + * @param {string} selector + * A valid CSS selector, which will be passed to `querySelector`. * - * @param {Element|String} [context=document] - * A DOM element within which to query. Can also be a selector - * string in which case the first matching element will be used - * as context. If missing (or no element matches selector), falls - * back to `document`. + * @param {Element|String} [context=document] + * A DOM element within which to query. Can also be a selector + * string in which case the first matching element will be used + * as context. If missing (or no element matches selector), falls + * back to `document`. * - * @return {Element|null} + * @return {Element|null} + * The element that was found or null. */ export const $ = createQuerier('querySelector'); @@ -678,16 +800,17 @@ export const $ = createQuerier('querySelector'); * Finds a all DOM elements matching `selector` within the optional * `context` of another DOM element (defaulting to `document`). * - * @function $$ - * @param {String} selector + * @param {string} selector * A valid CSS selector, which will be passed to `querySelectorAll`. * - * @param {Element|String} [context=document] + * @param {Element|String} [context=document] * A DOM element within which to query. Can also be a selector * string in which case the first matching element will be used * as context. If missing (or no element matches selector), falls * back to `document`. * - * @return {NodeList} + * @return {NodeList} + * A element list of elements that were found. Will be empty if none were found. + * */ export const $$ = createQuerier('querySelectorAll'); diff --git a/src/js/utils/events.js b/src/js/utils/events.js index d75b96ba0a..38abf18220 100644 --- a/src/js/utils/events.js +++ b/src/js/utils/events.js @@ -1,5 +1,6 @@ /** * @file events.js + * @module events * * Event System (John Resig - Secrets of a JS Ninja http://jsninja.com/) * (Original book version wasn't completely usable, so fixed some things and made Closure Compiler compatible) @@ -15,11 +16,12 @@ import document from 'global/document'; /** * Clean up the listener cache and dispatchers -* - * @param {Element|Object} elem Element to clean up - * @param {String} type Type of event to clean up - * @private - * @method _cleanUpEvents + * + * @param {Element|Object} elem + * Element to clean up + * + * @param {string} type + * Type of event to clean up */ function _cleanUpEvents(elem, type) { const data = Dom.getElData(elem); @@ -54,12 +56,17 @@ function _cleanUpEvents(elem, type) { /** * Loops through an array of event types and calls the requested method for each type. * - * @param {Function} fn The event method we want to use. - * @param {Element|Object} elem Element or object to bind listeners to - * @param {String} type Type of event to bind to. - * @param {Function} callback Event listener. - * @private - * @function _handleMultipleEvents + * @param {Function} fn + * The event method we want to use. + * + * @param {Element|Object} elem + * Element or object to bind listeners to + * + * @param {string} type + * Type of event to bind to. + * + * @param {EventTarget~EventListener} callback + * Event listener. */ function _handleMultipleEvents(fn, elem, types, callback) { types.forEach(function(type) { @@ -71,10 +78,11 @@ function _handleMultipleEvents(fn, elem, types, callback) { /** * Fix a native event to have standard property values * - * @param {Object} event Event object to fix + * @param {Object} event + * Event object to fix. + * * @return {Object} - * @private - * @method fixEvent + * Fixed event object. */ export function fixEvent(event) { @@ -201,10 +209,14 @@ export function fixEvent(event) { * and adds a generic handler to the element's event, * along with a unique id (guid) to the element. * - * @param {Element|Object} elem Element or object to bind listeners to - * @param {String|Array} type Type of event to bind to. - * @param {Function} fn Event listener. - * @method on + * @param {Element|Object} elem + * Element or object to bind listeners to + * + * @param {string|string[]} type + * Type of event to bind to. + * + * @param {EventTarget~EventListener} fn + * Event listener. */ export function on(elem, type, fn) { if (Array.isArray(type)) { @@ -272,10 +284,15 @@ export function on(elem, type, fn) { /** * Removes event listeners from an element * - * @param {Element|Object} elem Object to remove listeners from - * @param {String|Array=} type Type of listener to remove. Don't include to remove all events from element. - * @param {Function} fn Specific listener to remove. Don't include to remove listeners for an event type. - * @method off + * @param {Element|Object} elem + * Object to remove listeners from. + * + * @param {string|string[]} [type] + * Type of listener to remove. Don't include to remove all events from element. + * + * @param {EventTarget~EventListener} [fn] + * Specific listener to remove. Don't include to remove listeners for an event + * type. */ export function off(elem, type, fn) { // Don't want to add a cache object through getElData if not needed @@ -336,11 +353,18 @@ export function off(elem, type, fn) { /** * Trigger an event for an element * - * @param {Element|Object} elem Element to trigger an event on - * @param {Event|Object|String} event A string (the type) or an event object with a type attribute - * @param {Object} [hash] data hash to pass along with the event - * @return {Boolean=} Returned only if default was prevented - * @method trigger + * @param {Element|Object} elem + * Element to trigger an event on + * + * @param {EventTarget~Event|string} event + * A string (the type) or an event object with a type attribute + * + * @param {Object} [hash] + * data hash to pass along with the event + * + * @return {boolean|undefined} + * - Returns the opposite of `defaultPrevented` if default was prevented + * - Otherwise returns undefined */ export function trigger(elem, event, hash) { // Fetches element data and a reference to the parent (for bubbling). @@ -392,10 +416,14 @@ export function trigger(elem, event, hash) { /** * Trigger a listener only once for an event * - * @param {Element|Object} elem Element or object to - * @param {String|Array} type Name/type of event - * @param {Function} fn Event handler function - * @method one + * @param {Element|Object} elem + * Element or object to bind to. + * + * @param {string|string[]} type + * Name/type of event + * + * @param {Event~EventListener} fn + * Event Listener function */ export function one(elem, type, fn) { if (Array.isArray(type)) { diff --git a/src/js/utils/log.js b/src/js/utils/log.js index 85e5f7b575..f9c8972ea5 100644 --- a/src/js/utils/log.js +++ b/src/js/utils/log.js @@ -1,5 +1,6 @@ /** * @file log.js + * @module log */ import window from 'global/window'; import {IE_VERSION} from './browser'; @@ -9,11 +10,13 @@ let log; /** * Log messages to the console and history based on the type of message * - * @param {String} type + * @param {string} type * The name of the console method to use. + * * @param {Array} args * The arguments to be passed to the matching console method. - * @param {Boolean} [stringify] + * + * @param {boolean} [stringify] * By default, only old IEs should get console argument stringification, * but this is exposed as a parameter to facilitate testing. */ @@ -74,7 +77,8 @@ export const logByType = (type, args, stringify = !!IE_VERSION && IE_VERSION < 1 /** * Log plain debug messages * - * @function log + * @param {Mixed[]} args + * One or more messages or objects that should be logged. */ log = function(...args) { logByType('log', args); @@ -90,14 +94,16 @@ log.history = []; /** * Log error messages * - * @method error + * @param {Mixed[]} args + * One or more messages or objects that should be logged as an error */ log.error = (...args) => logByType('error', args); /** * Log warning messages * - * @method warn + * @param {Mixed[]} args + * One or more messages or objects that should be logged as a warning. */ log.warn = (...args) => logByType('warn', args); diff --git a/src/js/utils/merge-options.js b/src/js/utils/merge-options.js index 2a1849d647..b5b2d19128 100644 --- a/src/js/utils/merge-options.js +++ b/src/js/utils/merge-options.js @@ -1,8 +1,16 @@ /** * @file merge-options.js + * @module merge-options */ import merge from 'lodash-compat/object/merge'; +/** + * Check if an object direct descentant of Object and + * not of Array or RegExp. + * + * @param {Mixed} obj + * The object to check + */ function isPlain(obj) { return !!obj && typeof obj === 'object' && @@ -13,6 +21,16 @@ function isPlain(obj) { /** * Merge customizer. video.js simply overwrites non-simple objects * (like arrays) instead of attempting to overlay them. + * + * @param {Mixed} destination + * The merge destination + * + * @param {Mixed} source + * A merge source. + * + * @retun {Mixed} + * The source and destination merged. + * * @see https://lodash.com/docs#merge */ function customizer(destination, source) { @@ -36,10 +54,11 @@ function customizer(destination, source) { * Merge one or more options objects, recursively merging **only** * plain object properties. Previously `deepMerge`. * - * @param {...Object} source One or more objects to merge - * @returns {Object} a new object that is the union of all - * provided objects - * @function mergeOptions + * @param {Object[]} source + * One or more objects to merge + * + * @returns {Object} + * a new object that is the union of all */ export default function mergeOptions(...objects) { diff --git a/src/js/utils/url.js b/src/js/utils/url.js index d294273583..0136cec45c 100644 --- a/src/js/utils/url.js +++ b/src/js/utils/url.js @@ -1,15 +1,43 @@ /** * @file url.js + * @module url */ import document from 'global/document'; import window from 'global/window'; /** - * Resolve and parse the elements of a URL + * @typedef {Object} url:URLObject * - * @param {String} url The url to parse - * @return {Object} An object of url details - * @method parseUrl + * @property {string} protocol + * The protocol of the url that was parsed. + * + * @property {string} hostname + * The hostname of the url that was parsed. + * + * @property {string} port + * The port of the url that was parsed. + * + * @property {string} pathname + * The pathname of the url that was parsed. + * + * @property {string} search + * The search query of the url that was parsed. + * + * @property {string} hash + * The hash of the url that was parsed. + * + * @property {string} host + * The host of the url that was parsed. + */ + +/** + * Resolve and parse the elements of a URL. + * + * @param {String} url + * The url to parse + * + * @return {url:URLObject} + * An object of url details */ export const parseUrl = function(url) { const props = ['protocol', 'hostname', 'port', 'pathname', 'search', 'hash', 'host']; @@ -62,12 +90,15 @@ export const parseUrl = function(url) { /** * Get absolute version of relative URL. Used to tell flash correct URL. - * http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue * - * @param {String} url URL to make absolute - * @return {String} Absolute URL - * @private - * @method getAbsoluteURL + * + * @param {string} url + * URL to make absolute + * + * @return {string} + * Absolute URL + * + * @see http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue */ export const getAbsoluteURL = function(url) { // Check if absolute URL @@ -83,11 +114,15 @@ export const getAbsoluteURL = function(url) { }; /** - * Returns the extension of the passed file name. It will return an empty string if you pass an invalid path + * Returns the extension of the passed file name. It will return an empty string + * if passed an invalid path. * - * @param {String} path The fileName path like '/path/to/file.mp4' - * @returns {String} The extension in lower case or an empty string if no extension could be found. - * @method getFileExtension + * @param {string} path + * The fileName path like '/path/to/file.mp4' + * + * @returns {string} + * The extension in lower case or an empty string if no + * extension could be found. */ export const getFileExtension = function(path) { if (typeof path === 'string') { @@ -105,9 +140,11 @@ export const getFileExtension = function(path) { /** * Returns whether the url passed is a cross domain request or not. * - * @param {String} url The url to check - * @return {Boolean} Whether it is a cross domain request or not - * @method isCrossOrigin + * @param {string} url + * The url to check. + * + * @return {boolean} + * Whether it is a cross domain request or not. */ export const isCrossOrigin = function(url) { const winLoc = window.location; diff --git a/src/js/video.js b/src/js/video.js index 4ceb7c8888..b25bec4be4 100644 --- a/src/js/video.js +++ b/src/js/video.js @@ -1,5 +1,6 @@ /** * @file video.js + * @module videojs */ /* global define */ @@ -47,15 +48,22 @@ if (typeof HTMLVideoElement === 'undefined' && * the main library object. * The `videojs` function can be used to initialize or retrieve a player. * ```js - * var myPlayer = videojs('my_video_id'); + * var myPlayer = videojs('my_video_id'); * ``` * - * @param {String|Element} id Video element or video element ID - * @param {Object=} options Optional options object for config/settings - * @param {Function=} ready Optional ready callback - * @return {Player} A player instance + * @param {string|Element} id + * Video element or video element ID + * + * @param {Object} [options] + * Optional options object for config/settings + * + * @param {Component~ReadyCallback} [ready] + * Optional ready callback + * + * @return {Player} + * A player instance + * * @mixes videojs - * @method videojs */ function videojs(id, options, ready) { let tag; @@ -135,9 +143,14 @@ videojs.hooks_ = {}; /** * Get a list of hooks for a specific lifecycle * - * @param {String} type the lifecyle to get hooks from - * @param {Function=} optionally add a hook to the lifecycle that your are getting - * @return {Array} an array of hooks, or an empty array if there are none + * @param {string} type + * the lifecyle to get hooks from + * + * @param {Function} [fn] + * Optionally add a hook to the lifecycle that your are getting. + * + * @return {Array} + * an array of hooks, or an empty array if there are none. */ videojs.hooks = function(type, fn) { videojs.hooks_[type] = videojs.hooks_[type] || []; @@ -148,21 +161,29 @@ videojs.hooks = function(type, fn) { }; /** - * Add a function hook to a specific videojs lifecycle + * Add a function hook to a specific videojs lifecycle. + * + * @param {string} type + * the lifecycle to hook the function to. * - * @param {String} type the lifecycle to hook the function to - * @param {Function|Array} fn the function to attach + * @param {Function|Function[]} + * The function or array of functions to attach. */ videojs.hook = function(type, fn) { videojs.hooks(type, fn); }; /** - * Remove a hook from a specific videojs lifecycle + * Remove a hook from a specific videojs lifecycle. + * + * @param {string} type + * the lifecycle that the function hooked to * - * @param {String} type the lifecycle that the function hooked to - * @param {Function} fn the hooked function to remove - * @return {Boolean} the function that was removed or undef + * @param {Function} fn + * The hooked function to remove + * + * @return {boolean} + * The function that was removed or undef */ videojs.removeHook = function(type, fn) { const index = videojs.hooks(type).indexOf(fn); @@ -206,10 +227,10 @@ if (window.VIDEOJS_NO_DYNAMIC_STYLE !== true) { // video in the DOM (weird behavior only with minified version) setup.autoSetupTimeout(1, videojs); -/* - * Current software version (semver) +/** + * Current software version. Follows semver. * - * @type {String} + * @type {string} */ videojs.VERSION = require('../../package.json').version; @@ -229,9 +250,8 @@ videojs.options = Player.prototype.options_; /** * Get an object with the currently created players, keyed by player ID * - * @return {Object} The created players - * @mixes videojs - * @method getPlayers + * @return {Object} + * The created players */ videojs.getPlayers = () => Player.players; @@ -251,9 +271,7 @@ videojs.players = Player.players; * var myButton = new VjsButton(myPlayer); * ``` * - * @return {Component} Component identified by name - * @mixes videojs - * @method getComponent + * @borrows Component.getComponent as videojs.getComponent */ videojs.getComponent = Component.getComponent; @@ -265,23 +283,26 @@ videojs.getComponent = Component.getComponent; * or through default children options * `{ children: ['myComponent'] }`. * ```js - * // Get a component to subclass - * var VjsButton = videojs.getComponent('Button'); - * // Subclass the component (see 'extend' doc for more info) - * var MySpecialButton = videojs.extend(VjsButton, {}); - * // Register the new component - * VjsButton.registerComponent('MySepcialButton', MySepcialButton); - * // (optionally) add the new component as a default player child - * myPlayer.addChild('MySepcialButton'); + * // Get a component to subclass + * var VjsButton = videojs.getComponent('Button'); + * // Subclass the component (see 'extend' doc for more info) + * var MySpecialButton = videojs.extend(VjsButton, {}); + * // Register the new component + * VjsButton.registerComponent('MySepcialButton', MySepcialButton); + * // (optionally) add the new component as a default player child + * myPlayer.addChild('MySepcialButton'); * ``` - * NOTE: You could also just initialize the component before adding. + * > NOTE: You could also just initialize the component before adding. * `component.addChild(new MyComponent());` * - * @param {String} The class name of the component - * @param {Component} The component class - * @return {Component} The newly registered component - * @mixes videojs - * @method registerComponent + * @param {string} name + * The class name of the component + * + * @param {Component} comp + * The component class + * + * @return {Component} + * The newly registered component */ videojs.registerComponent = (name, comp) => { if (Tech.isTech(comp)) { @@ -294,14 +315,12 @@ videojs.registerComponent = (name, comp) => { /** * Get a Tech class object by name * ```js - * var Html5 = videojs.getTech('Html5'); - * // Create a new instance of the component - * var html5 = new Html5(options); + * var Html5 = videojs.getTech('Html5'); + * // Create a new instance of the component + * var html5 = new Html5(options); * ``` * - * @return {Tech} Tech identified by name - * @mixes videojs - * @method getComponent + * @borrows Tech.getTech as videojs.getTech */ videojs.getTech = Tech.getTech; @@ -320,16 +339,12 @@ videojs.getTech = Tech.getTech; * }); * ``` * - * @param {String} The class name of the tech - * @param {Tech} The tech class - * @return {Tech} The newly registered Tech - * @mixes videojs - * @method registerTech + * @borrows Tech.registerTech as videojs.registerTech */ videojs.registerTech = Tech.registerTech; /** - * A suite of browser and device tests + * A suite of browser and device tests from {@link browser}. * * @type {Object} * @private @@ -341,8 +356,8 @@ videojs.browser = browser; * compatibility with 4.x, but deprecated. Use `videojs.browser.TOUCH_ENABLED` * instead going forward. * - * @deprecated - * @type {Boolean} + * @deprecated since version 5.0 + * @type {boolean} */ videojs.TOUCH_ENABLED = browser.TOUCH_ENABLED; @@ -372,12 +387,7 @@ videojs.TOUCH_ENABLED = browser.TOUCH_ENABLED; * myInstance.sayMyName(); // -> should alert "John" * ``` * - * @param {Function} The Class to subclass - * @param {Object} An object including instace methods for the new class - * Optionally including a `constructor` function - * @return {Function} The newly created subclass - * @mixes videojs - * @method extend + * @borrows extend:extendFn as videojs.extend */ videojs.extend = extendFn; @@ -406,35 +416,28 @@ videojs.extend = extendFn; * // result.bar.b = [4,5,6]; * ``` * - * @param {Object} defaults The options object whose values will be overriden - * @param {Object} overrides The options object with values to override the first - * @param {Object} etc Any number of additional options objects - * - * @return {Object} a new object with the merged values - * @mixes videojs - * @method mergeOptions + * @borrows merge-options:mergeOptions as videojs.mergeOptions */ videojs.mergeOptions = mergeOptions; /** * Change the context (this) of a function * + * ``` js * videojs.bind(newContext, function() { * this === newContext * }); + * ``` * - * NOTE: as of v5.0 we require an ES5 shim, so you should use the native + * > NOTE: as of v5.0 we require an ES5 shim, so you should use the native * `function() {}.bind(newContext);` instead of this. * - * @param {*} context The object to bind as scope - * @param {Function} fn The function to be bound to a scope - * @param {Number=} uid An optional unique ID for the function to be set - * @return {Function} + * @borrows fn:bind as videojs.bind */ videojs.bind = Fn.bind; /** - * Create a Video.js player plugin + * Create a Video.js player plugin. * Plugins are only initialized when options for the plugin are included * in the player options, or the plugin function on the player instance is * called. @@ -473,24 +476,24 @@ videojs.bind = Fn.bind; * // --> Should alert 'Plugin added later!' * ``` * - * @param {String} name The plugin name - * @param {Function} fn The plugin function that will be called with options - * @mixes videojs - * @method plugin + * @borrows plugin:plugin as videojs.plugin */ videojs.plugin = plugin; /** * Adding languages so that they're available to all players. * ```js - * videojs.addLanguage('es', { 'Hello': 'Hola' }); + * videojs.addLanguage('es', { 'Hello': 'Hola' }); * ``` * - * @param {String} code The language code or dictionary property - * @param {Object} data The data values to be translated - * @return {Object} The resulting language dictionary object - * @mixes videojs - * @method addLanguage + * @param {string} code + * The language code or dictionary property + * + * @param {Object} data + * The data values to be translated + * + * @return {Object} + * The resulting language dictionary object */ videojs.addLanguage = function(code, data) { code = ('' + code).toLowerCase(); @@ -498,19 +501,19 @@ videojs.addLanguage = function(code, data) { }; /** - * Log debug messages. + * Log messages * - * @param {...Object} messages One or more messages to log + * @borrows log:log as videojs.log */ videojs.log = log; /** * Creates an emulated TimeRange object. * - * @param {Number|Array} start Start time in seconds or an array of ranges - * @param {Number} end End time in seconds - * @return {Object} Fake TimeRange object - * @method createTimeRange + * @borrows time-ranges:createTimeRanges as videojs.createTimeRange + */ +/** + * @borrows time-ranges:createTimeRanges as videojs.createTimeRanges */ videojs.createTimeRange = videojs.createTimeRanges = createTimeRanges; @@ -519,35 +522,28 @@ videojs.createTimeRange = videojs.createTimeRanges = createTimeRanges; * Supplying a guide (in seconds) will force a number of leading zeros * to cover the length of the guide * - * @param {Number} seconds Number of seconds to be turned into a string - * @param {Number} guide Number (in seconds) to model the string after - * @return {String} Time formatted as H:MM:SS or M:SS - * @method formatTime + * @borrows format-time:formatTime as videojs.formatTime */ videojs.formatTime = formatTime; /** * Resolve and parse the elements of a URL * - * @param {String} url The url to parse - * @return {Object} An object of url details - * @method parseUrl + * @borrows url:parseUrl as videojs.parseUrl */ videojs.parseUrl = Url.parseUrl; /** * Returns whether the url passed is a cross domain request or not. * - * @param {String} url The url to check - * @return {Boolean} Whether it is a cross domain request or not - * @method isCrossOrigin + * @borrows url:isCrossOrigin as videojs.isCrossOrigin */ videojs.isCrossOrigin = Url.isCrossOrigin; /** * Event target class. * - * @type {Function} + * @borrows EventTarget as videojs.EventTarget */ videojs.EventTarget = EventTarget; @@ -557,47 +553,35 @@ videojs.EventTarget = EventTarget; * and adds a generic handler to the element's event, * along with a unique id (guid) to the element. * - * @param {Element|Object} elem Element or object to bind listeners to - * @param {String|Array} type Type of event to bind to. - * @param {Function} fn Event listener. - * @method on + * @borrows events:on as videojs.on */ videojs.on = Events.on; /** * Trigger a listener only once for an event * - * @param {Element|Object} elem Element or object to - * @param {String|Array} type Name/type of event - * @param {Function} fn Event handler function - * @method one + * @borrows events:one as videojs.one */ videojs.one = Events.one; /** * Removes event listeners from an element * - * @param {Element|Object} elem Object to remove listeners from - * @param {String|Array=} type Type of listener to remove. Don't include to remove all events from element. - * @param {Function} fn Specific listener to remove. Don't include to remove listeners for an event type. - * @method off + * @borrows events:off as videojs.off */ videojs.off = Events.off; /** * Trigger an event for an element * - * @param {Element|Object} elem Element to trigger an event on - * @param {Event|Object|String} event A string (the type) or an event object with a type attribute - * @param {Object} [hash] data hash to pass along with the event - * @return {Boolean=} Returned only if default was prevented - * @method trigger + * @borrows events:trigger as videojs.trigger */ videojs.trigger = Events.trigger; /** * A cross-browser XMLHttpRequest wrapper. Here's a simple example: * + * ```js * videojs.xhr({ * body: someJSONString, * uri: "/foo", @@ -607,13 +591,14 @@ videojs.trigger = Events.trigger; * }, function (err, resp, body) { * // check resp.statusCode * }); + * ``` * - * Check out the [full - * documentation](https://github.com/Raynos/xhr/blob/v2.1.0/README.md) - * for more options. + * @param {Object} options + * settings for the request. + * + * @return {XMLHttpRequest|XDomainRequest} + * The request object. * - * @param {Object} options settings for the request. - * @return {XMLHttpRequest|XDomainRequest} the request object. * @see https://github.com/Raynos/xhr */ videojs.xhr = xhr; @@ -621,7 +606,7 @@ videojs.xhr = xhr; /** * TextTrack class * - * @type {Function} + * @borrows TextTrack as videojs.TextTrack */ videojs.TextTrack = TextTrack; @@ -629,7 +614,7 @@ videojs.TextTrack = TextTrack; * export the AudioTrack class so that source handlers can create * AudioTracks and then add them to the players AudioTrackList * - * @type {Function} + * @borrows AudioTrack as videojs.AudioTrack */ videojs.AudioTrack = AudioTrack; @@ -637,63 +622,49 @@ videojs.AudioTrack = AudioTrack; * export the VideoTrack class so that source handlers can create * VideoTracks and then add them to the players VideoTrackList * - * @type {Function} + * @borrows VideoTrack as videojs.VideoTrack */ videojs.VideoTrack = VideoTrack; /** * Determines, via duck typing, whether or not a value is a DOM element. * - * @method isEl - * @param {Mixed} value - * @return {Boolean} + * @borrows dom:isEl as videojs.isEl */ videojs.isEl = Dom.isEl; /** * Determines, via duck typing, whether or not a value is a text node. * - * @method isTextNode - * @param {Mixed} value - * @return {Boolean} + * @borrows dom:isTextNode as videojs.isTextNode */ videojs.isTextNode = Dom.isTextNode; /** * Creates an element and applies properties. * - * @method createEl - * @param {String} [tagName='div'] Name of tag to be created. - * @param {Object} [properties={}] Element properties to be applied. - * @param {Object} [attributes={}] Element attributes to be applied. - * @return {Element} + * @borrows dom:createEl as videojs.createEl */ videojs.createEl = Dom.createEl; /** * Check if an element has a CSS class * - * @method hasClass - * @param {Element} element Element to check - * @param {String} classToCheck Classname to check + * @borrows dom:hasElClass as videojs.hasClass */ videojs.hasClass = Dom.hasElClass; /** * Add a CSS class name to an element * - * @method addClass - * @param {Element} element Element to add class name to - * @param {String} classToAdd Classname to add + * @borrows dom:addElClass as videojs.addClass */ videojs.addClass = Dom.addElClass; /** * Remove a CSS class name from an element * - * @method removeClass - * @param {Element} element Element to remove from class name - * @param {String} classToRemove Classname to remove + * @borrows dom:removeElClass as videojs.removeClass */ videojs.removeClass = Dom.removeElClass; @@ -701,22 +672,14 @@ videojs.removeClass = Dom.removeElClass; * Adds or removes a CSS class name on an element depending on an optional * condition or the presence/absence of the class name. * - * @method toggleElClass - * @param {Element} element - * @param {String} classToToggle - * @param {Boolean|Function} [predicate] - * Can be a function that returns a Boolean. If `true`, the class - * will be added; if `false`, the class will be removed. If not - * given, the class will be added if not present and vice versa. + * @borrows dom:toggleElClass as videojs.toggleClass */ videojs.toggleClass = Dom.toggleElClass; /** * Apply attributes to an HTML element. * - * @method setAttributes - * @param {Element} el Target element. - * @param {Object=} attributes Element attributes to be applied. + * @borrows dom:setElAttributes as videojs.setAttribute */ videojs.setAttributes = Dom.setElAttributes; @@ -726,18 +689,14 @@ videojs.setAttributes = Dom.setElAttributes; * or with setAttribute (which shouldn't be used with HTML) * This will return true or false for boolean attributes. * - * @method getAttributes - * @param {Element} tag Element from which to get tag attributes - * @return {Object} + * @borrows dom:getElAttributes as videojs.getAttributes */ videojs.getAttributes = Dom.getElAttributes; /** * Empties the contents of an element. * - * @method emptyEl - * @param {Element} el - * @return {Element} + * @borrows dom:emptyEl as videojs.emptyEl */ videojs.emptyEl = Dom.emptyEl; @@ -761,10 +720,7 @@ videojs.emptyEl = Dom.emptyEl; * If the sole argument, is expected to produce a string, element, * node, or array. * - * @method appendContent - * @param {Element} el - * @param {String|Element|TextNode|Array|Function} content - * @return {Element} + * @borrows dom:appendContents as videojs.appendContet */ videojs.appendContent = Dom.appendContent; @@ -789,10 +745,7 @@ videojs.appendContent = Dom.appendContent; * If the sole argument, is expected to produce a string, element, * node, or array. * - * @method insertContent - * @param {Element} el - * @param {String|Element|TextNode|Array|Function} content - * @return {Element} + * @borrows dom:insertContent as videojs.insertContent */ videojs.insertContent = Dom.insertContent; @@ -804,9 +757,7 @@ videojs.insertContent = Dom.insertContent; * that the player doesn't break in these cases. * See https://bugzilla.mozilla.org/show_bug.cgi?id=548397 for more details. * - * @function computedStyle - * @param el the element you want the computed style of - * @param prop the property name you want + * @borrows computed-style:computedStyle as videojs.computedStyle */ videojs.computedStyle = computedStyle;