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
videojs · Dec 2, 2016 · c902279 · c902279
1 parent ba3cf17
commit c902279
Show file tree

Hide file tree

Showing 41 changed files with 1,383 additions and 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);