From cfc3ed7f0fef4f0bef44eff62d69e168491e5cc2 Mon Sep 17 00:00:00 2001 From: Brandon Casey 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 cd15def3db..b87bd87d0e 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 d170049eb2..02e1b0d020 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 957871ec15..42709b2b40 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 4d6f8d7796..0936520915 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. + * + * @param {EventTarget~Event} event + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @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 {EventTarget~Event} event + * The `keydown` event that caused this function to be called. * - * @param {Object} event Key press event - * @method handleKeyPress + * @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 {EventTarget~Event} event + * Key press event * - * @param {Object} event Key press event - * @method handleSubmenuKeyPress + * @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 0ebe2f0e3a..eb322ae9fd 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. `
  • ` * - * @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. + * + * @param {EventTarget~Event} event + * The `keydown`, `tap`, or `click` event that caused this function to be + * called. * - * @method handleClick + * @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 5044b97675..44a9a316e7 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 {EventTarget~Event} event + * A `keydown` event that happened on the menu. * - * @param {Object} event Event object - * @method handleKeyPress + * @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 06b06dd844..598ac6a715 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 faf809e624..394099025b 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 fbd941f08e..da6593c4f1 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 ab22cc5360..5a5d5833fc 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';