docs(jsdoc): Update the jsdoc comments to modern syntax - Part 2 (#3698)

Files updates:
* src/js/fullscreen-api.js
* src/js/loading-spinner.js
* src/js/media-error.js
* src/js/menu/menu-button.js
* src/js/menu/menu-item.js
* src/js/menu/menu.js
* src/js/modal-dialog.js
* src/js/plugins.js
* src/js/popup/popup-button.js
* src/js/popup/popup.js

src/js/fullscreen-api.js

@@ -1,19 +1,21 @@
 /**
  * @file fullscreen-api.js
+ * @module fullscreen-api
+ * @private
  */
 import document from 'global/document';
 
-/*
+/**
- * Store the browser-specific methods for the fullscreen API
+ * Store the browser-specific methods for the fullscreen API.
- * @type {Object|undefined}
+ *
- * @private
+ * @type {Object}
+ * @see [Specification]{@link https://fullscreen.spec.whatwg.org}
+ * @see [Map Approach From Screenfull.js]{@link https://github.com/sindresorhus/screenfull.js}
  */
 const FullscreenApi = {};
 
 // browser API methods
-// map approach from Screenful.js - https://github.com/sindresorhus/screenfull.js
 const apiMap = [
-  // Spec: https://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html
   [
     'requestFullscreen',
     'exitFullscreen',

src/js/loading-spinner.js

@@ -3,20 +3,18 @@
  */
 import Component from './component';
 
-/* Loading Spinner
-================================================================================ */
 /**
- * Loading spinner for waiting events
+ * A loading spinner for use during waiting/loading events.
  *
  * @extends Component
- * @class LoadingSpinner
  */
 class LoadingSpinner extends Component {
 
   /**
-   * Create the component's DOM element
+   * Create the `LoadingSpinner`s DOM element.
    *
-   * @method createEl
+   * @return {Element}
+   *         The dom element that gets created.
    */
   createEl() {
     return super.createEl('div', {

src/js/media-error.js

@@ -3,17 +3,22 @@
  */
 import assign from 'object.assign';
 
-/*
+/**
- * Custom MediaError class which mimics the standard HTML5 MediaError class.
+ * A Custom `MediaError` class which mimics the standard HTML5 `MediaError` class.
  *
- * @param {Number|String|Object|MediaError} value
+ * @param {number|string|Object|MediaError} value
  *        This can be of multiple types:
- *        - Number: should be a standard error code
+ *        - number: should be a standard error code
- *        - String: an error message (the code will be 0)
+ *        - string: an error message (the code will be 0)
  *        - Object: arbitrary properties
- *        - MediaError (native): used to populate a video.js MediaError object
+ *        - `MediaError` (native): used to populate a video.js `MediaError` object
- *        - MediaError (video.js): will return itself if it's already a
+ *        - `MediaError` (video.js): will return itself if it's already a
- *          video.js MediaError object.
+ *          video.js `MediaError` object.
+ *
+ * @see [MediaError Spec]{@link https://dev.w3.org/html5/spec-author-view/video.html#mediaerror}
+ * @see [Encrypted MediaError Spec]{@link https://www.w3.org/TR/2013/WD-encrypted-media-20130510/#error-codes}
+ *
+ * @class MediaError
  */
 function MediaError(value) {
 
@@ -30,7 +35,7 @@ function MediaError(value) {
     this.message = value;
   } else if (typeof value === 'object') {
 
-    // We assign the `code` property manually because native MediaError objects
+    // We assign the `code` property manually because native `MediaError` objects
     // do not expose it as an own/enumerable property of the object.
     if (typeof value.code === 'number') {
       this.code = value.code;
@@ -44,37 +49,45 @@ function MediaError(value) {
   }
 }
 
-/*
+/**
- * The error code that refers two one of the defined
+ * The error code that refers two one of the defined `MediaError` types
- * MediaError types
  *
  * @type {Number}
  */
 MediaError.prototype.code = 0;
 
-/*
+/**
- * An optional message to be shown with the error.
+ * An optional message that to show with the error. Message is not part of the HTML5
- * Message is not part of the HTML5 video spec
+ * video spec but allows for more informative custom errors.
- * but allows for more informative custom errors.
  *
  * @type {String}
  */
 MediaError.prototype.message = '';
 
-/*
+/**
- * An optional status code that can be set by plugins
+ * An optional status code that can be set by plugins to allow even more detail about
- * to allow even more detail about the error.
+ * the error. For example a plugin might provide a specific HTTP status code and an
- * For example the HLS plugin might provide the specific
+ * error message for that code. Then when the plugin gets that error this class will
- * HTTP status code that was returned when the error
+ * know how to display an error message for it. This allows a custom message to show
- * occurred, then allowing a custom error overlay
+ * up on the `Player` error overlay.
- * to display more information.
  *
  * @type {Array}
  */
 MediaError.prototype.status = null;
 
-// These errors are indexed by the W3C standard numeric value. The order
+/**
-// should not be changed!
+ * Errors indexed by the W3C standard. The order **CANNOT CHANGE**! See the
+ * specification listed under {@link MediaError} for more information.
+ *
+ * @enum {array}
+ * @readonly
+ * @property {string} 0 - MEDIA_ERR_CUSTOM
+ * @property {string} 1 - MEDIA_ERR_CUSTOM
+ * @property {string} 2 - MEDIA_ERR_ABORTED
+ * @property {string} 3 - MEDIA_ERR_NETWORK
+ * @property {string} 4 - MEDIA_ERR_SRC_NOT_SUPPORTED
+ * @property {string} 5 - MEDIA_ERR_ENCRYPTED
+ */
 MediaError.errorTypes = [
   'MEDIA_ERR_CUSTOM',
   'MEDIA_ERR_ABORTED',
@@ -84,6 +97,12 @@ MediaError.errorTypes = [
   'MEDIA_ERR_ENCRYPTED'
 ];
 
+/**
+ * The default `MediaError` messages based on the {@link MediaError.errorTypes}.
+ *
+ * @type {Array}
+ * @constant
+ */
 MediaError.defaultMessages = {
   1: 'You aborted the media playback',
   2: 'A network error caused the media download to fail part-way.',
@@ -100,4 +119,96 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
   MediaError.prototype[MediaError.errorTypes[errNum]] = errNum;
 }
 
+// jsdocs for instance/static members added above
+// instance methods use `#` and static methods use `.`
+/**
+ * W3C error code for any custom error.
+ *
+ * @member MediaError#MEDIA_ERR_CUSTOM
+ * @constant {number}
+ * @default 0
+ */
+/**
+ * W3C error code for any custom error.
+ *
+ * @member MediaError.MEDIA_ERR_CUSTOM
+ * @constant {number}
+ * @default 0
+ */
+
+/**
+ * W3C error code for media error aborted.
+ *
+ * @member MediaError#MEDIA_ERR_ABORTED
+ * @constant {number}
+ * @default 1
+ */
+/**
+ * W3C error code for media error aborted.
+ *
+ * @member MediaError.MEDIA_ERR_ABORTED
+ * @constant {number}
+ * @default 1
+ */
+
+/**
+ * W3C error code for any network error.
+ *
+ * @member MediaError#MEDIA_ERR_NETWORK
+ * @constant {number}
+ * @default 2
+ */
+/**
+ * W3C error code for any network error.
+ *
+ * @member MediaError.MEDIA_ERR_NETWORK
+ * @constant {number}
+ * @default 2
+ */
+
+/**
+ * W3C error code for any decoding error.
+ *
+ * @member MediaError#MEDIA_ERR_DECODE
+ * @constant {number}
+ * @default 3
+ */
+/**
+ * W3C error code for any decoding error.
+ *
+ * @member MediaError.MEDIA_ERR_DECODE
+ * @constant {number}
+ * @default 3
+ */
+
+/**
+ * W3C error code for any time that a source is not supported.
+ *
+ * @member MediaError#MEDIA_ERR_SRC_NOT_SUPPORTED
+ * @constant {number}
+ * @default 4
+ */
+/**
+ * W3C error code for any time that a source is not supported.
+ *
+ * @member MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED
+ * @constant {number}
+ * @default 4
+ */
+
+/**
+ * W3C error code for any time that a source is encrypted.
+ *
+ * @member MediaError#MEDIA_ERR_ENCRYPTED
+ * @constant {number}
+ * @default 5
+ */
+/**
+ * W3C error code for any time that a source is encrypted.
+ *
+ * @member MediaError.MEDIA_ERR_ENCRYPTED
+ * @constant {number}
+ * @default 5
+ */
+
 export default MediaError;

src/js/menu/menu-button.js

@@ -9,15 +9,21 @@ import * as Fn from '../utils/fn.js';
 import toTitleCase from '../utils/to-title-case.js';
 
 /**
- * A button class with a popup menu
+ * A `MenuButton` class for any popup {@link Menu}.
  *
- * @param {Player|Object} player
+ * @extends ClickableComponent
- * @param {Object=} options
- * @extends Button
- * @class MenuButton
  */
 class MenuButton extends ClickableComponent {
 
+  /**
+   * 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);
 
@@ -31,9 +37,7 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Update menu
+   * Update the menu based on the current state of its items.
-   *
-   * @method update
    */
   update() {
     const menu = this.createMenu();
@@ -62,10 +66,10 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Create menu
+   * Create the menu and add all items to it.
    *
-   * @return {Menu} The constructed menu
+   * @return {Menu}
-   * @method createMenu
+   *         The constructed menu
    */
   createMenu() {
     const menu = new Menu(this.player_);
@@ -97,15 +101,15 @@ class MenuButton extends ClickableComponent {
   /**
    * Create the list of menu items. Specific to each subclass.
    *
-   * @method createItems
+   * @abstract
    */
   createItems() {}
 
   /**
-   * Create the component's DOM element
+   * Create the `MenuButtons`s DOM element.
    *
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl() {
     return super.createEl('div', {
@@ -114,10 +118,10 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Allow sub components to stack CSS class names
+   * Builds the default DOM `className`.
    *
-   * @return {String} The constructed class name
+   * @return {string}
-   * @method buildCSSClass
+   *         The DOM `className` for this object.
    */
   buildCSSClass() {
     let menuButtonClass = 'vjs-menu-button';
@@ -133,15 +137,21 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * When you click the button it adds focus, which
+   * Handle a click on a `MenuButton`.
-   * will show the menu indefinitely.
+   * See {@link ClickableComponent#handleClick} for instances where this is called.
-   * So we'll remove focus when the mouse leaves the button.
-   * Focus is needed for tab navigation.
-   * Allow sub components to stack CSS class names
    *
-   * @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) {
+    // When you click the button it adds focus, which will show the menu.
+    // So we'll remove focus when the mouse leaves the button. Focus is needed
+    // for tab navigation.
+
     this.one(this.menu.contentEl(), 'mouseleave', Fn.bind(this, function(e) {
       this.unpressButton();
       this.el_.blur();
@@ -154,10 +164,13 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Handle key press on menu
+   * Handle tab, escape, down arrow, and up arrow keys for `MenuButton`. See
+   * {@link ClickableComponent#handleKeyPress} for instances where this is called.
    *
-   * @param {Object} event Key press event
+   * @param {EventTarget~Event} event
-   * @method handleKeyPress
+   *        The `keydown` event that caused this function to be called.
+   *
+   * @listens keydown
    */
   handleKeyPress(event) {
 
@@ -182,10 +195,13 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Handle key press on submenu
+   * Handle a `keydown` event on a sub-menu. The listener for this is added in
+   * the constructor.
    *
-   * @param {Object} event Key press event
+   * @param {EventTarget~Event} event
-   * @method handleSubmenuKeyPress
+   *        Key press event
+   *
+   * @listens keydown
    */
   handleSubmenuKeyPress(event) {
 
@@ -202,9 +218,7 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Makes changes based on button pressed
+   * Put the current `MenuButton` into a pressed state.
-   *
-   * @method pressButton
    */
   pressButton() {
     if (this.enabled_) {
@@ -217,9 +231,7 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Makes changes based on button unpressed
+   * Take the current `MenuButton` out of a pressed state.
-   *
-   * @method unpressButton
    */
   unpressButton() {
     if (this.enabled_) {
@@ -232,10 +244,10 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Disable the menu button
+   * Disable the `MenuButton`. Don't allow it to be clicked.
    *
-   * @return {Component}
+   * @return {MenuButton}
-   * @method disable
+   *         Returns itself; method can be chained.
    */
   disable() {
     // Unpress, but don't force focus on this button
@@ -249,10 +261,10 @@ class MenuButton extends ClickableComponent {
   }
 
   /**
-   * Enable the menu button
+   * Enable the `MenuButton`. Allow it to be clicked.
    *
-   * @return {Component}
+   * @return {MenuButton}
-   * @method disable
+   *         Returns itself; method can be chained.
    */
   enable() {
     this.enabled_ = true;

src/js/menu/menu-item.js

@@ -8,13 +8,20 @@ import assign from 'object.assign';
 /**
  * The component for a menu item. `<li>`
  *
- * @param {Player|Object} player
+ * @extends ClickableComponent
- * @param {Object=} options
- * @extends Button
- * @class MenuItem
  */
 class MenuItem extends ClickableComponent {
 
+  /**
+   * Creates an instance of the 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);
 
@@ -32,12 +39,19 @@ class MenuItem extends ClickableComponent {
   }
 
   /**
-   * Create the component's DOM element
+   * Create the `MenuItem's DOM element
+   *
+   * @param {string} [type=li]
+   *        Element's node type, not actually used, always set to `li`.
+   *
+   * @param {Object} [props={}]
+   *        An object of properties that should be set on the element
+   *
+   * @param {Object} [attrs={}]
+   *        An object of attributes that should be set on the element
    *
-   * @param {String=} type Desc
-   * @param {Object=} props Desc
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl(type, props, attrs) {
     return super.createEl('li', assign({
@@ -48,19 +62,25 @@ class MenuItem extends ClickableComponent {
   }
 
   /**
-   * Handle a click on the menu item, and set it to selected
+   * Any click on a `MenuItem` puts int into the selected state.
+   * See {@link ClickableComponent#handleClick} for instances where this is called.
    *
-   * @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.selected(true);
   }
 
   /**
-   * Set this menu item as selected or not
+   * Set the state for this menu item as selected or not.
    *
-   * @param  {Boolean} selected
+   * @param {boolean} selected
-   * @method selected
+   *        if the menu item is selected or not
    */
   selected(selected) {
     if (this.selectable) {

src/js/menu/menu.js

@@ -7,14 +7,23 @@ import * as Fn from '../utils/fn.js';
 import * as Events from '../utils/events.js';
 
 /**
- * The Menu component is used to build pop up menus, including subtitle and
+ * The Menu component is used to build popup menus, including subtitle and
  * captions selection menus.
  *
  * @extends Component
- * @class Menu
  */
 class Menu extends Component {
 
+  /**
+   * Create an instance of this class.
+   *
+   * @param {Player} player
+   *        the player that this component should attach to
+   *
+   * @param {Object} [options]
+   *        Object of option names and values
+   *
+   */
   constructor(player, options) {
     super(player, options);
 
@@ -24,24 +33,25 @@ class Menu extends Component {
   }
 
   /**
-   * Add a menu item to the menu
+   * Add a {@link MenuItem} to the menu.
+   *
+   * @param {Object|string} component
+   *        The name or instance of the `MenuItem` to add.
    *
-   * @param {Object|String} component Component or component type to add
-   * @method addItem
    */
   addItem(component) {
     this.addChild(component);
-    component.on('click', Fn.bind(this, function() {
+    component.on('click', Fn.bind(this, function(event) {
       this.unlockShowing();
       // TODO: Need to set keyboard focus back to the menuButton
     }));
   }
 
   /**
-   * Create the component's DOM element
+   * Create the `Menu`s DOM element.
    *
    * @return {Element}
-   * @method createEl
+   *         the element that was created
    */
   createEl() {
     const contentElType = this.options_.contentElType || 'ul';
@@ -71,10 +81,12 @@ class Menu extends Component {
   }
 
   /**
-   * Handle key press for menu
+   * Handle a `keydown` event on this menu. This listener is added in the constructor.
    *
-   * @param {Object} event Event object
+   * @param {EventTarget~Event} event
-   * @method handleKeyPress
+   *        A `keydown` event that happened on the menu.
+   *
+   * @listens keydown
    */
   handleKeyPress(event) {
     // Left and Down Arrows
@@ -90,9 +102,7 @@ class Menu extends Component {
   }
 
   /**
-   * Move to next (lower) menu item for keyboard users
+   * Move to next (lower) menu item for keyboard users.
-   *
-   * @method stepForward
    */
   stepForward() {
     let stepChild = 0;
@@ -104,9 +114,7 @@ class Menu extends Component {
   }
 
   /**
-   * Move to previous (higher) menu item for keyboard users
+   * Move to previous (higher) menu item for keyboard users.
-   *
-   * @method stepBack
    */
   stepBack() {
     let stepChild = 0;
@@ -118,10 +126,10 @@ class Menu extends Component {
   }
 
   /**
-   * Set focus on a menu item in the menu
+   * Set focus on a {@link MenuItem} in the `Menu`.
    *
-   * @param {Object|String} item Index of child item set focus on
+   * @param {Object|string} [item=0]
-   * @method focus
+   *        Index of child item set focus on.
    */
   focus(item = 0) {
     const children = this.children().slice();

src/js/modal-dialog.js

@@ -16,38 +16,40 @@ const ESC = 27;
  * is activated - or when ESC is pressed anywhere.
  *
  * @extends Component
- * @class ModalDialog
  */
 class ModalDialog extends Component {
 
   /**
-   * Constructor for modals.
+   * 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.
+   *
    * @param {Mixed} [options.content=undefined]
    *        Provide customized content for this modal.
    *
-   * @param  {String} [options.description]
+   * @param {string} [options.description]
    *        A text description for the modal, primarily for accessibility.
    *
-   * @param  {Boolean} [options.fillAlways=false]
+   * @param {boolean} [options.fillAlways=false]
    *        Normally, modals are automatically filled only the first time
    *        they open. This tells the modal to refresh its content
    *        every time it opens.
    *
-   * @param  {String} [options.label]
+   * @param {string} [options.label]
    *        A text label for the modal, primarily for accessibility.
    *
-   * @param  {Boolean} [options.temporary=true]
+   * @param {boolean} [options.temporary=true]
    *        If `true`, the modal can only be opened once; it will be
    *        disposed as soon as it's closed.
    *
-   * @param  {Boolean} [options.uncloseable=false]
+   * @param {boolean} [options.uncloseable=false]
    *        If `true`, the user will not be able to close the modal
    *        through the UI in the normal ways. Programmatic closing is
    *        still possible.
-   *
    */
   constructor(player, options) {
     super(player, options);
@@ -76,10 +78,10 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Create the modal's DOM element
+   * Create the `ModalDialog`'s DOM element
    *
-   * @method createEl
    * @return {Element}
+   *         The DOM element that gets created.
    */
   createEl() {
     return super.createEl('div', {
@@ -94,21 +96,23 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Build the modal's CSS class.
+   * Builds the default DOM `className`.
    *
-   * @method buildCSSClass
+   * @return {string}
-   * @return {String}
+   *         The DOM `className` for this object.
    */
   buildCSSClass() {
     return `${MODAL_CLASS_NAME} vjs-hidden ${super.buildCSSClass()}`;
   }
 
   /**
-   * Handles key presses on the document, looking for ESC, which closes
+   * Handles `keydown` events on the document, looking for ESC, which closes
    * the modal.
    *
-   * @method handleKeyPress
+   * @param {EventTarget~Event} e
-   * @param  {Event} e
+   *        The keypress that triggered this event.
+   *
+   * @listens keydown
    */
   handleKeyPress(e) {
     if (e.which === ESC && this.closeable()) {
@@ -119,7 +123,8 @@ class ModalDialog extends Component {
   /**
    * Returns the label string for this modal. Primarily used for accessibility.
    *
-   * @return {String}
+   * @return {string}
+   *         the localized or raw label of this modal.
    */
   label() {
     return this.options_.label || this.localize('Modal Window');
@@ -129,7 +134,8 @@ class ModalDialog extends Component {
    * Returns the description string for this modal. Primarily used for
    * accessibility.
    *
-   * @return {String}
+   * @return {string}
+   *         The localized or raw description of this modal.
    */
   description() {
     let desc = this.options_.description || this.localize('This is a modal window.');
@@ -145,13 +151,22 @@ class ModalDialog extends Component {
   /**
    * Opens the modal.
    *
-   * @method open
+   * @fires ModalDialog#beforemodalopen
+   * @fires ModalDialog#modalopen
+   *
    * @return {ModalDialog}
+   *         Returns itself; method can be chained.
    */
   open() {
     if (!this.opened_) {
       const player = this.player();
 
+      /**
+       * Fired just before a `ModalDialog` is opened.
+       *
+       * @event ModalDialog#beforemodalopen
+       * @type {EventTarget~Event}
+       */
       this.trigger('beforemodalopen');
       this.opened_ = true;
 
@@ -176,6 +191,13 @@ class ModalDialog extends Component {
       player.controls(false);
       this.show();
       this.el().setAttribute('aria-hidden', 'false');
+
+      /**
+       * Fired just after a `ModalDialog` is opened.
+       *
+       * @event ModalDialog#modalopen
+       * @type {EventTarget~Event}
+       */
       this.trigger('modalopen');
       this.hasBeenOpened_ = true;
     }
@@ -183,13 +205,13 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Whether or not the modal is opened currently.
+   * If the `ModalDialog` is currently open or closed.
    *
-   * @method opened
+   * @param  {boolean} [value]
-   * @param  {Boolean} [value]
    *         If given, it will open (`true`) or close (`false`) the modal.
    *
-   * @return {Boolean}
+   * @return {boolean}
+   *         the current open state of the modaldialog
    */
   opened(value) {
     if (typeof value === 'boolean') {
@@ -199,15 +221,25 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Closes the modal.
+   * Closes the modal, does nothing if the `ModalDialog` is
+   * not open.
+   *
+   * @fires ModalDialog#beforemodalclose
+   * @fires ModalDialog#modalclose
    *
-   * @method close
    * @return {ModalDialog}
+   *         Returns itself; method can be chained.
    */
   close() {
     if (this.opened_) {
       const player = this.player();
 
+      /**
+       * Fired just before a `ModalDialog` is closed.
+       *
+       * @event ModalDialog#beforemodalclose
+       * @type {EventTarget~Event}
+       */
       this.trigger('beforemodalclose');
       this.opened_ = false;
 
@@ -222,6 +254,13 @@ class ModalDialog extends Component {
       player.controls(true);
       this.hide();
       this.el().setAttribute('aria-hidden', 'true');
+
+      /**
+       * Fired just after a `ModalDialog` is closed.
+       *
+       * @event ModalDialog#modalclose
+       * @type {EventTarget~Event}
+       */
       this.trigger('modalclose');
 
       if (this.options_.temporary) {
@@ -232,13 +271,13 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Whether or not the modal is closeable via the UI.
+   * Check to see if the `ModalDialog` is closeable via the UI.
    *
-   * @method closeable
+   * @param  {boolean} [value]
-   * @param  {Boolean} [value]
+   *         If given as a boolean, it will set the `closeable` option.
-   *         If given as a Boolean, it will set the `closeable` option.
    *
-   * @return {Boolean}
+   * @return {boolean}
+   *         Returns the final value of the closable option.
    */
   closeable(value) {
     if (typeof value === 'boolean') {
@@ -270,11 +309,10 @@ class ModalDialog extends Component {
 
   /**
    * Fill the modal's content element with the modal's "content" option.
-   *
    * The content element will be emptied before this change takes place.
    *
-   * @method fill
    * @return {ModalDialog}
+   *         Returns itself; method can be chained.
    */
   fill() {
     return this.fillWith(this.content());
@@ -282,20 +320,28 @@ class ModalDialog extends Component {
 
   /**
    * Fill the modal's content element with arbitrary content.
-   *
    * The content element will be emptied before this change takes place.
    *
-   * @method fillWith
+   * @fires ModalDialog#beforemodalfill
+   * @fires ModalDialog#modalfill
+   *
    * @param  {Mixed} [content]
    *         The same rules apply to this as apply to the `content` option.
    *
    * @return {ModalDialog}
+   *         Returns itself; method can be chained.
    */
   fillWith(content) {
     const contentEl = this.contentEl();
     const parentEl = contentEl.parentNode;
     const nextSiblingEl = contentEl.nextSibling;
 
+     /**
+      * Fired just before a `ModalDialog` is filled with content.
+      *
+      * @event ModalDialog#beforemodalfill
+      * @type {EventTarget~Event}
+      */
     this.trigger('beforemodalfill');
     this.hasBeenFilled_ = true;
 
@@ -304,6 +350,12 @@ class ModalDialog extends Component {
     parentEl.removeChild(contentEl);
     this.empty();
     Dom.insertContent(contentEl, content);
+    /**
+     * Fired just after a `ModalDialog` is filled with content.
+     *
+     * @event ModalDialog#modalfill
+     * @type {EventTarget~Event}
+     */
     this.trigger('modalfill');
 
     // Re-inject the re-filled content element.
@@ -317,16 +369,30 @@ class ModalDialog extends Component {
   }
 
   /**
-   * Empties the content element.
+   * Empties the content element. This happens anytime the modal is filled.
    *
-   * This happens automatically anytime the modal is filled.
+   * @fires ModalDialog#beforemodalempty
+   * @fires ModalDialog#modalempty
    *
-   * @method empty
    * @return {ModalDialog}
+   *         Returns itself; method can be chained.
    */
   empty() {
+   /**
+    * Fired just before a `ModalDialog` is emptied.
+    *
+    * @event ModalDialog#beforemodalempty
+    * @type {EventTarget~Event}
+    */
     this.trigger('beforemodalempty');
     Dom.emptyEl(this.contentEl());
+
+   /**
+    * Fired just after a `ModalDialog` is emptied.
+    *
+    * @event ModalDialog#modalempty
+    * @type {EventTarget~Event}
+    */
     this.trigger('modalempty');
     return this;
   }
@@ -338,13 +404,13 @@ class ModalDialog extends Component {
    * This does not update the DOM or fill the modal, but it is called during
    * that process.
    *
-   * @method content
    * @param  {Mixed} [value]
    *         If defined, sets the internal content value to be used on the
    *         next call(s) to `fill`. This value is normalized before being
    *         inserted. To "clear" the internal content value, pass `null`.
    *
    * @return {Mixed}
+   *         The current content of the modal dialog
    */
   content(value) {
     if (typeof value !== 'undefined') {
@@ -354,8 +420,8 @@ class ModalDialog extends Component {
   }
 }
 
-/*
+/**
- * Modal dialog default options.
+ * Default options for `ModalDialog` default options.
  *
  * @type {Object}
  * @private

src/js/plugins.js

@@ -1,14 +1,20 @@
 /**
  * @file plugins.js
+ * @module plugins
  */
 import Player from './player.js';
 
 /**
- * The method for registering a video.js plugin
  *
- * @param  {String} name The name of the plugin
+ */
- * @param  {Function} init The function that is run when the player inits
+/**
- * @method plugin
+ * The method for registering a video.js plugin. {@link videojs:videojs.registerPlugin].
+ *
+ * @param {string} name
+ *        The name of the plugin that is being registered
+ *
+ * @param {plugins:PluginFn} init
+ *        The function that gets run when a `Player` initializes.
  */
 const plugin = function(name, init) {
   Player.prototype[name] = init;

src/js/popup/popup-button.js

@@ -5,15 +5,21 @@ import ClickableComponent from '../clickable-component.js';
 import Component from '../component.js';
 
 /**
- * A button class with a popup control
+ * A button class for use with {@link Popup} controls
  *
- * @param {Player|Object} player
- * @param {Object=} options
  * @extends ClickableComponent
- * @class PopupButton
  */
 class PopupButton extends ClickableComponent {
 
+  /**
+   * 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);
 
@@ -21,9 +27,7 @@ class PopupButton extends ClickableComponent {
   }
 
   /**
-   * Update popup
+   * Update the `Popup` that this button is attached to.
-   *
-   * @method update
    */
   update() {
     const popup = this.createPopup();
@@ -43,18 +47,17 @@ class PopupButton extends ClickableComponent {
   }
 
   /**
-   * Create popup - Override with specific functionality for component
+   * Create a `Popup`. - Override with specific functionality for component
    *
-   * @return {Popup} The constructed popup
+   * @abstract
-   * @method createPopup
    */
   createPopup() {}
 
   /**
-   * Create the component's DOM element
+   * Create the `PopupButton`s DOM element.
    *
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl() {
     return super.createEl('div', {
@@ -63,10 +66,10 @@ class PopupButton extends ClickableComponent {
   }
 
   /**
-   * Allow sub components to stack CSS class names
+   * Builds the default DOM `className`.
    *
-   * @return {String} The constructed class name
+   * @return {string}
-   * @method buildCSSClass
+   *         The DOM `className` for this object.
    */
   buildCSSClass() {
     let menuButtonClass = 'vjs-menu-button';
@@ -80,7 +83,6 @@ class PopupButton extends ClickableComponent {
 
     return `vjs-menu-button ${menuButtonClass} ${super.buildCSSClass()}`;
   }
-
 }
 
 Component.registerComponent('PopupButton', PopupButton);

src/js/popup/popup.js

@@ -10,15 +10,15 @@ import * as Events from '../utils/events.js';
  * The Popup component is used to build pop up controls.
  *
  * @extends Component
- * @class Popup
  */
 class Popup extends Component {
 
   /**
    * Add a popup item to the popup
    *
-   * @param {Object|String} component Component or component type to add
+   * @param {Object|string} component
-   * @method addItem
+   *        Component or component type to add
+   *
    */
   addItem(component) {
     this.addChild(component);
@@ -28,10 +28,10 @@ class Popup extends Component {
   }
 
   /**
-   * Create the component's DOM element
+   * Create the `PopupButton`s DOM element.
    *
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl() {
     const contentElType = this.options_.contentElType || 'ul';