docs(jsdoc): Update the jsdoc comments to modern syntax - Part 3 (#3708)

files in this change:
* src/js/player.js
* src/js/setup.js
* src/js/slider/slider.js

src/js/setup.js

@@ -1,8 +1,9 @@
 /**
- * @file setup.js
+ * Functions for setting up a player without user insteraction based on the data-setup
+ * `attribute` of the video tag.
  *
- * Functions for automatically setting up a player
- * based on the data-setup attribute of the video tag
+ * @file setup.js
+ * @module setup
  */
 import * as Events from './utils/events.js';
 import document from 'global/document';
@@ -11,7 +12,9 @@ import window from 'global/window';
 let _windowLoaded = false;
 let videojs;
 
-// Automatically set up any tags that have a data-setup attribute
+/**
+ * Set up any tags that have a data-setup `attribute` when the player is started.
+ */
 const autoSetup = function() {
   // One day, when we stop supporting IE8, go back to this, but in the meantime...*hack hack hack*
   // var vids = Array.prototype.slice.call(document.getElementsByTagName('video'));
@@ -72,7 +75,10 @@ const autoSetup = function() {
   }
 };
 
-// Pause to let the DOM keep processing
+/**
+ * Wait until the page is loaded before running autoSetup. This will be called in
+ * autoSetup if `hasLoaded` returns false.
+ */
 function autoSetupTimeout(wait, vjs) {
   if (vjs) {
     videojs = vjs;
@@ -84,13 +90,21 @@ function autoSetupTimeout(wait, vjs) {
 if (document.readyState === 'complete') {
   _windowLoaded = true;
 } else {
+  /**
+   * Listen for the load event on window, and set _windowLoaded to true.
+   *
+   * @listens load
+   */
   Events.one(window, 'load', function() {
     _windowLoaded = true;
   });
 }
 
+/**
+ * check if the document has been loaded
+ */
 const hasLoaded = function() {
   return _windowLoaded;
 };
 
-export { autoSetup, autoSetupTimeout, hasLoaded };
+export {autoSetup, autoSetupTimeout, hasLoaded};

src/js/slider/slider.js

@@ -6,15 +6,22 @@ import * as Dom from '../utils/dom.js';
 import assign from 'object.assign';
 
 /**
- * The base functionality for sliders like the volume bar and seek bar
+ * The base functionality for a slider. Can be vertical or horizontal.
+ * For instance the volume bar or the seek bar on a video is a slider.
  *
- * @param {Player|Object} player
- * @param {Object=} options
  * @extends Component
- * @class Slider
  */
 class Slider extends Component {
 
+/**
+ * Create 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);
 
@@ -35,12 +42,19 @@ class Slider extends Component {
   }
 
   /**
-   * Create the component's DOM element
+   * Create the `Button`s DOM element.
+   *
+   * @param {string} type
+   *        Type of element to create.
+   *
+   * @param {Object} [props={}]
+   *        List of properties in Object form.
+   *
+   * @param {Object} [attributes={}]
+   *        list of attributes in Object form.
    *
-   * @param {String} type Type of element to create
-   * @param {Object=} props List of properties in Object form
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl(type, props = {}, attributes = {}) {
     // Add the slider element class to all sub classes
@@ -61,10 +75,14 @@ class Slider extends Component {
   }
 
   /**
-   * Handle mouse down on slider
+   * Handle `mousedown` or `touchstart` events on the `Slider`.
    *
-   * @param {Object} event Mouse down event object
-   * @method handleMouseDown
+   * @param {EventTarget~Event} event
+   *        `mousedown` or `touchstart` event that triggered this function
+   *
+   * @listens mousedown
+   * @listens touchstart
+   * @fires Slider#slideractive
    */
   handleMouseDown(event) {
     const doc = this.bar.el_.ownerDocument;
@@ -73,6 +91,12 @@ class Slider extends Component {
     Dom.blockTextSelection();
 
     this.addClass('vjs-sliding');
+    /**
+     * Triggered when the slider is in an active state
+     *
+     * @event Slider#slideractive
+     * @type {EventTarget~Event}
+     */
     this.trigger('slideractive');
 
     this.on(doc, 'mousemove', this.handleMouseMove);
@@ -84,16 +108,29 @@ class Slider extends Component {
   }
 
   /**
-   * To be overridden by a subclass
+   * Handle the `mousemove`, `touchmove`, and `mousedown` events on this `Slider`.
+   * The `mousemove` and `touchmove` events will only only trigger this function during
+   * `mousedown` and `touchstart`. This is due to {@link Slider#handleMouseDown} and
+   * {@link Slider#handleMouseUp}.
    *
-   * @method handleMouseMove
+   * @param {EventTarget~Event} event
+   *        `mousedown`, `mousemove`, `touchstart`, or `touchmove` event that triggered
+   *        this function
+   *
+   * @listens mousemove
+   * @listens touchmove
    */
-  handleMouseMove() {}
+  handleMouseMove(event) {}
 
   /**
-   * Handle mouse up on Slider
+   * Handle `mouseup` or `touchend` events on the `Slider`.
    *
-   * @method handleMouseUp
+   * @param {EventTarget~Event} event
+   *        `mouseup` or `touchend` event that triggered this function.
+   *
+   * @listens touchend
+   * @listens mouseup
+   * @fires Slider#sliderinactive
    */
   handleMouseUp() {
     const doc = this.bar.el_.ownerDocument;
@@ -101,6 +138,12 @@ class Slider extends Component {
     Dom.unblockTextSelection();
 
     this.removeClass('vjs-sliding');
+    /**
+     * Triggered when the slider is no longer in an active state.
+     *
+     * @event Slider#sliderinactive
+     * @type {EventTarget~Event}
+     */
     this.trigger('sliderinactive');
 
     this.off(doc, 'mousemove', this.handleMouseMove);
@@ -112,9 +155,7 @@ class Slider extends Component {
   }
 
   /**
-   * Update slider
-   *
-   * @method update
+   * Update the progress bar of the `Slider`.
    */
   update() {
     // In VolumeBar init we have a setTimeout for update that pops and update to the end of the
@@ -156,8 +197,13 @@ class Slider extends Component {
   /**
    * Calculate distance for slider
    *
-   * @param {Object} event Event object
-   * @method calculateDistance
+   * @param {EventTarget~Event} event
+   *        The event that caused this function to run.
+   *
+   * @return {number}
+   *         The current position of the Slider.
+   *         - postition.x for vertical `Slider`s
+   *         - postition.y for horizontal `Slider`s
    */
   calculateDistance(event) {
     const position = Dom.getPointerPosition(this.el_, event);
@@ -169,19 +215,26 @@ class Slider extends Component {
   }
 
   /**
-   * Handle on focus for slider
+   * Handle a `focus` event on this `Slider`.
    *
-   * @method handleFocus
+   * @param {EventTarget~Event} event
+   *        The `focus` event that caused this function to run.
+   *
+   * @listens focus
    */
   handleFocus() {
     this.on(this.bar.el_.ownerDocument, 'keydown', this.handleKeyPress);
   }
 
   /**
-   * Handle key press for slider
+   * Handle a `keydown` event on the `Slider`. Watches for left, rigth, up, and down
+   * arrow keys. This function will only be called when the slider has focus. See
+   * {@link Slider#handleFocus} and {@link Slider#handleBlur}.
    *
-   * @param {Object} event Event object
-   * @method handleKeyPress
+   * @param {EventTarget~Event} event
+   *        the `keydown` event that caused this function to run.
+   *
+   * @listens keydown
    */
   handleKeyPress(event) {
     // Left and Down Arrows
@@ -197,10 +250,14 @@ class Slider extends Component {
   }
 
   /**
-   * Handle on blur for slider
+   * Handle a `blur` event on this `Slider`.
    *
-   * @method handleBlur
+   * @param {EventTarget~Event} event
+   *        The `blur` event that caused this function to run.
+   *
+   * @listens blur
    */
+
   handleBlur() {
     this.off(this.bar.el_.ownerDocument, 'keydown', this.handleKeyPress);
   }
@@ -209,8 +266,8 @@ class Slider extends Component {
    * Listener for click events on slider, used to prevent clicks
    *   from bubbling up to parent elements like button menus.
    *
-   * @param {Object} event Event object
-   * @method handleClick
+   * @param {Object} event
+   *        Event that caused this object to run
    */
   handleClick(event) {
     event.stopImmediatePropagation();
@@ -220,9 +277,14 @@ class Slider extends Component {
   /**
    * Get/set if slider is horizontal for vertical
    *
-   * @param {Boolean} bool True if slider is vertical, false is horizontal
-   * @return {Boolean} True if slider is vertical, false is horizontal
-   * @method vertical
+   * @param {boolean} [bool]
+   *        - true if slider is vertical,
+   *        - false is horizontal
+   *
+   * @return {boolean|Slider}
+   *         - true if slider is vertical, and getting
+   *         - false is horizontal, and getting
+   *         - a reference to this object when setting
    */
   vertical(bool) {
     if (bool === undefined) {
@@ -239,7 +301,6 @@ class Slider extends Component {
 
     return this;
   }
-
 }
 
 Component.registerComponent('Slider', Slider);