docs(jsdoc): Update the jsdoc comments to modern syntax - Part 1 (#3694)

Add jsdoc npm script.
Update JSDoc comments for the following files:
* src/js/big-play-button.js
* src/js/button.js
* src/js/clickable-component.js
* src/js/close-button.js
* src/js/component.js
* src/js/error-display.js
* src/js/event-target.js

.jsdoc.json

@@ -0,0 +1,6 @@
+{
+  "plugins": ["plugins/markdown"],
+  "markdown": {
+    "tags": ["example"]
+  }
+}

package.json

@@ -24,7 +24,8 @@
     "lint": "vjsstandard",
     "start": "grunt watchAll",
     "test": "grunt test",
-    "toc": "doctoc"
+    "toc": "doctoc",
+    "docs": "jsdoc -r src/js -d docs/api -c .jsdoc.json"
   },
   "repository": {
     "type": "git",
@@ -87,6 +88,7 @@
     "grunt-version": "~0.3.0",
     "grunt-videojs-languages": "0.0.4",
     "grunt-zip": "0.10.2",
+    "jsdoc": "^3.4.2",
     "karma": "^1.2.0",
     "karma-browserify": "^5.1.0",
     "karma-browserstack-launcher": "^1.0.1",

src/js/big-play-button.js

@@ -5,37 +5,45 @@ import Button from './button.js';
 import Component from './component.js';
 
 /**
- * Initial play button. Shows before the video has played. The hiding of the
- * big play button is done via CSS and player states.
+ * The initial play button that shows before the video has played. The hiding of the
+ * `BigPlayButton` get done via CSS and `Player` states.
  *
- * @param {Object} player  Main Player
- * @param {Object=} options Object of option names and values
  * @extends Button
- * @class BigPlayButton
  */
 class BigPlayButton 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. Always returns 'vjs-big-play-button'.
    */
   buildCSSClass() {
     return 'vjs-big-play-button';
   }
 
   /**
-   * Handles click for play
+   * This gets called when a `BigPlayButton` "clicked". See {@link ClickableComponent}
+   * for more detailed information on what a click can be.
    *
-   * @method handleClick
+   * @param {EventTarget~Event} event
+   *        The `keydown`, `tap`, or `click` event that caused this function to be
+   *        called.
+   *
+   * @listens tap
+   * @listens click
    */
-  handleClick() {
+  handleClick(event) {
     this.player_.play();
   }
-
 }
 
+/**
+ * The text that should display over the `BigPlayButton`s controls. Added to for localization.
+ *
+ * @type {string}
+ * @private
+ */
 BigPlayButton.prototype.controlText_ = 'Play Video';
 
 Component.registerComponent('BigPlayButton', BigPlayButton);

src/js/button.js

@@ -7,23 +7,26 @@ import log from './utils/log.js';
 import assign from 'object.assign';
 
 /**
- * Base class for all buttons
+ * Base class for all buttons.
  *
- * @param {Object} player  Main Player
- * @param {Object=} options Object of option names and values
  * @extends ClickableComponent
- * @class Button
  */
 class Button extends ClickableComponent {
 
   /**
-   * Create the component's DOM element
+   * Create the `Button`s DOM element.
+   *
+   * @param {string} [tag=button]
+   *        Element's node type. e.g. 'button'
+   *
+   * @param {Object} [props={}]
+   *        An object of properties that should be set on the element.
+   *
+   * @param {Object} [attributes={}]
+   *        An object of attributes that should be set on the element.
    *
-   * @param {String=} type Element's node type. e.g. 'div'
-   * @param {Object=} props An object of properties that should be set on the element
-   * @param {Object=} attributes An object of attributes that should be set on the element
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl(tag = 'button', props = {}, attributes = {}) {
     props = assign({
@@ -62,13 +65,20 @@ class Button extends ClickableComponent {
   }
 
   /**
-   * Adds a child component inside this button
+   * Add a child `Component` inside of this `Button`.
+   *
+   * @param {string|Component} child
+   *        The name or instance of a child to add.
    *
-   * @param {String|Component} child The class name or instance of a child to add
-   * @param {Object=} options Options, including options to be passed to children of the child.
-   * @return {Component} The child component (created by this process if a string was used)
-   * @deprecated
-   * @method addChild
+   * @param {Object} [options={}]
+   *        The key/value store of options that will get passed to children of
+   *        the child.
+   *
+   * @return {Component}
+   *         The `Component` that gets added as a child. When using a string the
+   *         `Component` will get created by this process.
+   *
+   * @deprecated since version 5
    */
   addChild(child, options = {}) {
     const className = this.constructor.name;
@@ -80,31 +90,37 @@ class Button extends ClickableComponent {
   }
 
   /**
-   * Enable the button element
+   * Enable the `Button` element so that it can be activated or clicked. Use this with
+   * {@link Button#disable}.
    *
    * @return {Component}
-   * @method enable
+   *         Returns itself; method is chainable.
    */
   enable() {
     super.enable();
     this.el_.removeAttribute('disabled');
   }
 
   /**
-   * Disable the button element
+   * Enable the `Button` element so that it cannot be activated or clicked. Use this with
+   * {@link Button#enable}.
    *
    * @return {Component}
-   * @method disable
+   *         Returns itself; method is chainable.
    */
   disable() {
     super.disable();
     this.el_.setAttribute('disabled', 'disabled');
   }
 
   /**
-   * Handle KeyPress (document level) - Extend with specific functionality for button
+   * This gets called when a `Button` has focus and `keydown` is triggered via a key
+   * press.
+   *
+   * @param {EventTarget~Event} event
+   *        The event that caused this function to get called.
    *
-   * @method handleKeyPress
+   * @listens keydown
    */
   handleKeyPress(event) {