From cfc3ed7f0fef4f0bef44eff62d69e168491e5cc2 Mon Sep 17 00:00:00 2001
From: Brandon Casey <BrandonOCasey@users.noreply.github.com>
Date: Fri, 2 Dec 2016 15:12:01 -0500
Subject: [PATCH] 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 | 14 +--
src/js/loading-spinner.js | 10 +-
src/js/media-error.js | 161 +++++++++++++++++++++++++++-----
src/js/menu/menu-button.js | 96 ++++++++++---------
src/js/menu/menu-item.js | 48 +++++++---
src/js/menu/menu.js | 48 ++++++----
src/js/modal-dialog.js | 172 ++++++++++++++++++++++++-----------
src/js/plugins.js | 14 ++-
src/js/popup/popup-button.js | 34 +++----
src/js/popup/popup.js | 10 +-
10 files changed, 416 insertions(+), 191 deletions(-)
diff --git a/src/js/fullscreen-api.js b/src/js/fullscreen-api.js
index cd15def3d..b87bd87d0 100644
--- a/src/js/fullscreen-api.js
+++ b/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
- * @type {Object|undefined}
- * @private
+/**
+ * Store the browser-specific methods for the fullscreen API.
+ *
+ * @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',
diff --git a/src/js/loading-spinner.js b/src/js/loading-spinner.js
index d170049eb..02e1b0d02 100644
--- a/src/js/loading-spinner.js
+++ b/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', {
diff --git a/src/js/media-error.js b/src/js/media-error.js
index 957871ec1..42709b2b4 100644
--- a/src/js/media-error.js
+++ b/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
- * - String: an error message (the code will be 0)
+ * - number: should be a standard error code
+ * - string: an error message (the code will be 0)
* - Object: arbitrary properties
- * - MediaError (native): used to populate a video.js MediaError object
- * - MediaError (video.js): will return itself if it's already 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
+ * 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
- * MediaError types
+/**
+ * The error code that refers two one of the defined `MediaError` types
*
* @type {Number}
*/
MediaError.prototype.code = 0;
-/*
- * An optional message to be shown with the error.
- * Message is not part of the HTML5 video spec
- * but allows for more informative custom errors.
+/**
+ * An optional message that to show with the error. Message is not part of the HTML5
+ * video spec but allows for more informative custom errors.
*
* @type {String}
*/
MediaError.prototype.message = '';
-/*
- * An optional status code that can be set by plugins
- * to allow even more detail about the error.
- * For example the HLS plugin might provide the specific
- * HTTP status code that was returned when the error
- * occurred, then allowing a custom error overlay
- * to display more information.
+/**
+ * An optional status code that can be set by plugins to allow even more detail about
+ * the error. For example a plugin might provide a specific HTTP status code and an
+ * error message for that code. Then when the plugin gets that error this class will
+ * know how to display an error message for it. This allows a custom message to show
+ * up on the `Player` error overlay.
*
* @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;
diff --git a/src/js/menu/menu-button.js b/src/js/menu/menu-button.js
index 4d6f8d779..093652091 100644
--- a/src/js/menu/menu-button.js
+++ b/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
- * @param {Object=} options
- * @extends Button
- * @class MenuButton
+ * @extends ClickableComponent
*/
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
- *
- * @method update
+ * Update the menu based on the current state of its items.
*/
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
- * @method createMenu
+ * @return {Menu}
+ * 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
- * @method buildCSSClass
+ * @return {string}
+ * 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
- * will show the menu indefinitely.
- * 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
+ * Handle a click on a `MenuButton`.
+ * 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) {
+ // 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
- * @method handleKeyPress
+ * @param {EventTarget~Event} event
+ * 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
- * @method handleSubmenuKeyPress
+ * @param {EventTarget~Event} event
+ * Key press event
+ *
+ * @listens keydown
*/
handleSubmenuKeyPress(event) {
@@ -202,9 +218,7 @@ class MenuButton extends ClickableComponent {
}
/**
- * Makes changes based on button pressed
- *
- * @method pressButton
+ * Put the current `MenuButton` into a pressed state.
*/
pressButton() {
if (this.enabled_) {
@@ -217,9 +231,7 @@ class MenuButton extends ClickableComponent {
}
/**
- * Makes changes based on button unpressed
- *
- * @method unpressButton
+ * Take the current `MenuButton` out of a pressed state.
*/
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}
- * @method disable
+ * @return {MenuButton}
+ * 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}
- * @method disable
+ * @return {MenuButton}
+ * Returns itself; method can be chained.
*/
enable() {
this.enabled_ = true;
diff --git a/src/js/menu/menu-item.js b/src/js/menu/menu-item.js
index 0ebe2f0e3..eb322ae9f 100644
--- a/src/js/menu/menu-item.js
+++ b/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
- * @param {Object=} options
- * @extends Button
- * @class MenuItem
+ * @extends ClickableComponent
*/
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
- * @method selected
+ * @param {boolean} selected
+ * if the menu item is selected or not
*/
selected(selected) {
if (this.selectable) {
diff --git a/src/js/menu/menu.js b/src/js/menu/menu.js
index 5044b9767..44a9a316e 100644
--- a/src/js/menu/menu.js
+++ b/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
- * @method handleKeyPress
+ * @param {EventTarget~Event} event
+ * 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
- *
- * @method stepForward
+ * Move to next (lower) menu item for keyboard users.
*/
stepForward() {
let stepChild = 0;
@@ -104,9 +114,7 @@ class Menu extends Component {
}
/**
- * Move to previous (higher) menu item for keyboard users
- *
- * @method stepBack
+ * Move to previous (higher) menu item for keyboard users.
*/
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
- * @method focus
+ * @param {Object|string} [item=0]
+ * Index of child item set focus on.
*/
focus(item = 0) {
const children = this.children().slice();
diff --git a/src/js/modal-dialog.js b/src/js/modal-dialog.js
index 06b06dd84..598ac6a71 100644
--- a/src/js/modal-dialog.js
+++ b/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
- * @param {Object} [options]
- * @param {Mixed} [options.content=undefined]
- * Provide customized content for this modal.
+ * @param {Player} player
+ * The `Player` that this class should be attached to.
*
- * @param {String} [options.description]
- * A text description for the modal, primarily for accessibility.
+ * @param {Object} [options]
+ * The key/value store of player options.
*
- * @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 {Mixed} [options.content=undefined]
+ * Provide customized content for this modal.
*
- * @param {String} [options.label]
- * A text label for the modal, primarily for accessibility.
+ * @param {string} [options.description]
+ * A text description for the modal, primarily for accessibility.
*
- * @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.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 {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.
+ * @param {string} [options.label]
+ * A text label for the modal, primarily for accessibility.
*
+ * @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]
+ * 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 {Event} e
+ * @param {EventTarget~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]
- * If given as a Boolean, it will set the `closeable` option.
+ * @param {boolean} [value]
+ * 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
diff --git a/src/js/plugins.js b/src/js/plugins.js
index faf809e62..394099025 100644
--- a/src/js/plugins.js
+++ b/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;
diff --git a/src/js/popup/popup-button.js b/src/js/popup/popup-button.js
index fbd941f08..da6593c4f 100644
--- a/src/js/popup/popup-button.js
+++ b/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
- *
- * @method update
+ * Update the `Popup` that this button is attached to.
*/
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
- * @method createPopup
+ * @abstract
*/
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
- * @method buildCSSClass
+ * @return {string}
+ * 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);
diff --git a/src/js/popup/popup.js b/src/js/popup/popup.js
index ab22cc536..5a5d5833f 100644
--- a/src/js/popup/popup.js
+++ b/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
- * @method addItem
+ * @param {Object|string} component
+ * 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';