docs(jsdoc): Update the jsdoc comments to modern syntax - Part 5 (#3766)

Files in this PR:
* src/js/tracks/audio-track-list.js
* src/js/tracks/audio-track.js
* src/js/tracks/html-track-element-list.js
* src/js/tracks/html-track-element.js
* src/js/tracks/text-track-cue-list.js
* src/js/tracks/text-track-display.js
* src/js/tracks/text-track-list-converter.js
* src/js/tracks/text-track-list.js
* src/js/tracks/text-track-settings.js
* src/js/tracks/text-track.js
* src/js/tracks/track-enums.js
* src/js/tracks/track-list.js
* src/js/tracks/track.js
* src/js/tracks/video-track-list.js
* src/js/tracks/video-track.js
* src/js/utils/browser.js
* src/js/utils/buffer.js
* src/js/utils/computed-style.js
* src/js/utils/fn.js
* src/js/utils/format-time.js
* src/js/utils/guid.js
* src/js/utils/obj.js
* src/js/utils/stylesheet.js
* src/js/utils/time-ranges.js
* src/js/utils/to-title-case.js

src/js/tracks/audio-track-list.js

@@ -6,11 +6,16 @@ import * as browser from '../utils/browser.js';
 import document from 'global/document';
 
 /**
- * anywhere we call this function we diverge from the spec
+ * Anywhere we call this function we diverge from the spec
  * as we only support one enabled audiotrack at a time
  *
- * @param {Array|AudioTrackList} list list to work on
- * @param {AudioTrack} track the track to skip
+ * @param {AudioTrackList} list
+ *        list to work on
+ *
+ * @param {AudioTrack} track
+ *        The track to skip
+ *
+ * @private
  */
 const disableOthers = function(list, track) {
   for (let i = 0; i < list.length; i++) {
@@ -23,25 +28,19 @@ const disableOthers = function(list, track) {
 };
 
 /**
- * A list of possible audio tracks. All functionality is in the
- * base class Tracklist and the spec for AudioTrackList is located at:
- * @link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotracklist
- *
- * interface AudioTrackList : EventTarget {
- *   readonly attribute unsigned long length;
- *   getter AudioTrack (unsigned long index);
- *   AudioTrack? getTrackById(DOMString id);
+ * The current list of {@link AudioTrack} for a media file.
  *
- *   attribute EventHandler onchange;
- *   attribute EventHandler onaddtrack;
- *   attribute EventHandler onremovetrack;
- * };
- *
- * @param {AudioTrack[]} tracks a list of audio tracks to instantiate the list with
+ * @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotracklist}
  * @extends TrackList
- * @class AudioTrackList
  */
 class AudioTrackList extends TrackList {
+
+  /**
+   * Create an instance of this class.
+   *
+   * @param {AudioTrack[]} [tracks=[]]
+   *        A list of `AudioTrack` to instantiate the list with.
+   */
   constructor(tracks = []) {
     let list;
 
@@ -76,6 +75,15 @@ class AudioTrackList extends TrackList {
     return list;
   }
 
+  /**
+   * Add an {@link AudioTrack} to the `AudioTrackList`.
+   *
+   * @param {AudioTrack} track
+   *        The AudioTrack to add to the list
+   *
+   * @fires Track#addtrack
+   * @private
+   */
   addTrack_(track) {
     if (track.enabled) {
       disableOthers(this, track);
@@ -87,6 +95,10 @@ class AudioTrackList extends TrackList {
       return;
     }
 
+    /**
+     * @listens AudioTrack#enabledchange
+     * @fires TrackList#change
+     */
     track.addEventListener('enabledchange', () => {
       // when we are disabling other tracks (since we don't support
       // more than one track at a time) we will set changing_
@@ -101,10 +113,26 @@ class AudioTrackList extends TrackList {
     });
   }
 
+  /**
+   * Add an {@link AudioTrack} to the `AudioTrackList`.
+   *
+   * @param {AudioTrack} track
+   *        The AudioTrack to add to the list
+   *
+   * @fires Track#addtrack
+   */
   addTrack(track) {
     this.addTrack_(track);
   }
 
+  /**
+   * Remove an {@link AudioTrack} from the `AudioTrackList`.
+   *
+   * @param {AudioTrack} track
+   *        The AudioTrack to remove from the list
+   *
+   * @fires Track#removetrack
+   */
   removeTrack(track) {
     super.removeTrack_(track);
   }

src/js/tracks/audio-track.js

@@ -4,21 +4,36 @@ import merge from '../utils/merge-options';
 import * as browser from '../utils/browser.js';
 
 /**
- * A single audio text track as defined in:
- * @link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack
+ * A representation of a single `AudioTrack`. If it is part of an {@link AudioTrackList}
+ * only one `AudioTrack` in the list will be enabled at a time.
  *
- * interface AudioTrack {
- *   readonly attribute DOMString id;
- *   readonly attribute DOMString kind;
- *   readonly attribute DOMString label;
- *   readonly attribute DOMString language;
- *   attribute boolean enabled;
- * };
- *
- * @param {Object=} options Object of option names and values
- * @class AudioTrack
+ * @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack}
+ * @extends Track
  */
 class AudioTrack extends Track {
+
+  /**
+   * Create an instance of this class.
+   *
+   * @param {Object} [options={}]
+   *        Object of option names and values
+   *
+   * @param {AudioTrack~Kind} [options.kind='']
+   *        A valid audio track kind
+   *
+   * @param {string} [options.id='vjs_track_' + Guid.newGUID()]
+   *        A unique id for this AudioTrack.
+   *
+   * @param {string} [options.label='']
+   *        The menu label for this track.
+   *
+   * @param {string} [options.language='']
+   *        A valid two character language code.
+   *
+   * @param {boolean} [options.enabled]
+   *        If this track is the one that is currently playing. If this track is part of
+   *        an {@link AudioTrackList}, only one {@link AudioTrack} will be enabled.
+   */
   constructor(options = {}) {
     const settings = merge(options, {
       kind: AudioTrackKind[options.kind] || ''
@@ -35,7 +50,13 @@ class AudioTrack extends Track {
         }
       }
     }
-
+    /**
+     * @member {boolean} enabled
+     *         If this `AudioTrack` is enabled or not. When setting this will
+     *         fire {@link AudioTrack#enabledchange} if the state of enabled is changed.
+     *
+     * @fires VideoTrack#selectedchange
+     */
     Object.defineProperty(track, 'enabled', {
       get() {
         return enabled;
@@ -46,6 +67,17 @@ class AudioTrack extends Track {
           return;
         }
         enabled = newEnabled;
+
+        /**
+         * An event that fires when enabled changes on this track. This allows
+         * the AudioTrackList that holds this track to act accordingly.
+         *
+         * > Note: This is not part of the spec! Native tracks will do
+         *         this internally without an event.
+         *
+         * @event AudioTrack#enabledchange
+         * @type {EventTarget~Event}
+         */
         this.trigger('enabledchange');
       }
     });

src/js/tracks/html-track-element-list.js

@@ -5,7 +5,17 @@
 import * as browser from '../utils/browser.js';
 import document from 'global/document';
 
+/**
+ * The current list of {@link HtmlTrackElement}s.
+ */
 class HtmlTrackElementList {
+
+  /**
+   * Create an instance of this class.
+   *
+   * @param {HtmlTrackElement[]} [tracks=[]]
+   *        A list of `HtmlTrackElement` to instantiate the list with.
+   */
   constructor(trackElements = []) {
     let list = this; // eslint-disable-line
 
@@ -21,6 +31,10 @@ class HtmlTrackElementList {
 
     list.trackElements_ = [];
 
+    /**
+     * @member {number} length
+     *         The current number of `Track`s in the this Trackist.
+     */
     Object.defineProperty(list, 'length', {
       get() {
         return this.trackElements_.length;
@@ -36,6 +50,14 @@ class HtmlTrackElementList {
     }
   }
 
+  /**
+   * Add an {@link HtmlTrackElement} to the `HtmlTrackElementList`
+   *
+   * @param {HtmlTrackElement} trackElement
+   *        The track element to add to the list.
+   *
+   * @private
+   */
   addTrackElement_(trackElement) {
     const index = this.trackElements_.length;
 
@@ -53,6 +75,18 @@ class HtmlTrackElementList {
     }
   }
 
+  /**
+   * Get an {@link HtmlTrackElement} from the `HtmlTrackElementList` given an
+   * {@link TextTrack}.
+   *
+   * @param {TextTrack} track
+   *        The track associated with a track element.
+   *
+   * @return {HtmlTrackElement|undefined}
+   *         The track element that was found or undefined.
+   *
+   * @private
+   */
   getTrackElementByTrack_(track) {
     let trackElement_;
 
@@ -67,6 +101,14 @@ class HtmlTrackElementList {
     return trackElement_;
   }
 
+  /**
+   * Remove a {@link HtmlTrackElement} from the `HtmlTrackElementList`
+   *
+   * @param {HtmlTrackElement} trackElement
+   *        The track element to remove from the list.
+   *
+   * @private
+   */
   removeTrackElement_(trackElement) {
     for (let i = 0, length = this.trackElements_.length; i < length; i++) {
       if (trackElement === this.trackElements_[i]) {

src/js/tracks/html-track-element.js

@@ -7,35 +7,57 @@ import document from 'global/document';
 import EventTarget from '../event-target';
 import TextTrack from '../tracks/text-track';
 
+/**
+ * @typedef {HTMLTrackElement~ReadyState}
+ * @enum {number}
+ */
 const NONE = 0;
 const LOADING = 1;
 const LOADED = 2;
 const ERROR = 3;
 
 /**
- * https://html.spec.whatwg.org/multipage/embedded-content.html#htmltrackelement
- *
- * interface HTMLTrackElement : HTMLElement {
- *   attribute DOMString kind;
- *   attribute DOMString src;
- *   attribute DOMString srclang;
- *   attribute DOMString label;
- *   attribute boolean default;
- *
- *   const unsigned short NONE = 0;
- *   const unsigned short LOADING = 1;
- *   const unsigned short LOADED = 2;
- *   const unsigned short ERROR = 3;
- *   readonly attribute unsigned short readyState;
+ * A single track represented in the DOM.
  *
- *   readonly attribute TextTrack track;
- * };
- *
- * @param {Object} options TextTrack configuration
- * @class HTMLTrackElement
+ * @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#htmltrackelement}
+ * @extends EventTarget
  */
-
 class HTMLTrackElement extends EventTarget {
+
+  /**
+   * Create an instance of this class.
+   *
+   * @param {Object} options={}
+   *        Object of option names and values
+   *
+   * @param {Tech} options.tech
+   *        A reference to the tech that owns this HTMLTrackElement.
+   *
+   * @param {TextTrack~Kind} [options.kind='subtitles']
+   *        A valid text track kind.
+   *
+   * @param {TextTrack~Mode} [options.mode='disabled']
+   *        A valid text track mode.
+   *
+   * @param {string} [options.id='vjs_track_' + Guid.newGUID()]
+   *        A unique id for this TextTrack.
+   *
+   * @param {string} [options.label='']
+   *        The menu label for this track.
+   *
+   * @param {string} [options.language='']
+   *        A valid two character language code.
+   *
+   * @param {string} [options.srclang='']
+   *        A valid two character language code. An alternative, but deprioritized
+   *        vesion of `options.language`
+   *
+   * @param {string} [options.src]
+   *        A url to TextTrack cues.
+   *
+   * @param {boolean} [options.default]
+   *        If this track should default to on or off.
+   */
   constructor(options = {}) {
     super();
 
@@ -60,12 +82,20 @@ class HTMLTrackElement extends EventTarget {
     trackElement.label = track.label;
     trackElement.default = track.default;
 
+    /**
+     * @member {HTMLTrackElement~ReadyState} readyState
+     *         The current ready state of the track element.
+     */
     Object.defineProperty(trackElement, 'readyState', {
       get() {
         return readyState;
       }
     });
 
+    /**
+     * @member {TextTrack} track
+     *         The underlying TextTrack object.
+     */
     Object.defineProperty(trackElement, 'track', {
       get() {
         return track;
@@ -74,6 +104,10 @@ class HTMLTrackElement extends EventTarget {
 
     readyState = NONE;
 
+    /**
+     * @listens TextTrack#loadeddata
+     * @fires HTMLTrackElement#load
+     */
     track.addEventListener('loadeddata', function() {
       readyState = LOADED;