web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2025-03-25 22:01:11 +02:00
Code Releases Activity

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

Browse Source 
Add jsdoc npm script.
Update JSDoc comments for the following files:
* src/js/big-play-button.js
* src/js/button.js
* src/js/clickable-component.js
* src/js/close-button.js
* src/js/component.js
* src/js/error-display.js
* src/js/event-target.js
This commit is contained in:
Brandon Casey 2016-12-02 15:07:19 -05:00 committed by Gary Katsevman
parent d24fe409e8
commit 1a0b2812ce
9 changed files with 1196 additions and 499 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.jsdoc.json Normal file
View File

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

4
package.json
View File

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

32
src/js/big-play-button.js
View File

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

58
src/js/button.js
View File

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

124
src/js/clickable-component.js
View File

@ -10,15 +10,22 @@ import document from 'global/document';
import assign from 'object.assign';
/**
* Clickable Component which is clickable or keyboard actionable, but is not a native HTML button
* Clickable Component which is clickable or keyboard actionable,
* but is not a native HTML button.
*
* @param {Object} player Main Player
* @param {Object=} options Object of option names and values
* @extends Component
* @class ClickableComponent
*/
class ClickableComponent extends Component {
/**
* 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);
@ -28,13 +35,19 @@ class ClickableComponent extends Component {
}
/**
* Create the component's DOM element
* Create the `Component`s DOM element.
*
* @param {string} [tag=div]
* The element's node type.
*
* @param {Object} [props={}]
* An object of properties that should be set on the element.
*
* @param {Object} [attributes={}]
* An object of attributes that should be set on the element.
*
* @param {String=} type Element's node type. e.g. 'div'
* @param {Object=} props An object of properties that should be set on the element
* @param {Object=} attributes An object of attributes that should be set on the element
* @return {Element}
* @method createEl
* The element that gets created.
*/
createEl(tag = 'div', props = {}, attributes = {}) {
props = assign({
@ -64,11 +77,13 @@ class ClickableComponent extends Component {
}
/**
* create control text
* Create a control text element on this `Component`
*
* @param {Element} [el]
* Parent element for the control text.
*
* @param {Element} el Parent element for the control text
* @return {Element}
* @method controlText
* The control text element that gets created.
*/
createControlTextEl(el) {
this.controlTextEl_ = Dom.createEl('span', {
@ -85,12 +100,17 @@ class ClickableComponent extends Component {
}
/**
* Controls text - both request and localize
* Get or set the localize text to use for the controls on the `Component`.
*
* @param {String} text Text for element
* @param {Element=} el Element to set the title on
* @return {String}
* @method controlText
* @param {string} [text]
* Control text for element.
*
* @param {Element} [el=this.el()]
* Element to set the title on.
*
* @return {string|ClickableComponent}
* - The control text when getting
* - Returns itself when setting; method can be chained.
*/
controlText(text, el = this.el()) {
if (!text) {
@ -107,20 +127,20 @@ class ClickableComponent extends Component {
}
/**
* Allows sub components to stack CSS class names
* Builds the default DOM `className`.
*
* @return {String}
* @method buildCSSClass
* @return {string}
* The DOM `className` for this object.
*/
buildCSSClass() {
return `vjs-control vjs-button ${super.buildCSSClass()}`;
}
/**
* Enable the component element
* Enable this `Component`s element.
*
* @return {Component}
* @method enable
* @return {ClickableComponent}
* Returns itself; method can be chained.
*/
enable() {
this.removeClass('vjs-disabled');
@ -136,10 +156,10 @@ class ClickableComponent extends Component {
}
/**
* Disable the component element
* Disable this `Component`s element.
*
* @return {Component}
* @method disable
* @return {ClickableComponent}
* Returns itself; method can be chained.
*/
disable() {
this.addClass('vjs-disabled');
@ -155,25 +175,51 @@ class ClickableComponent extends Component {
}
/**
* Handle Click - Override with specific functionality for component
* This gets called when a `ClickableComponent` gets:
* - Clicked (via the `click` event, listening starts in the constructor)
* - Tapped (via the `tap` event, listening starts in the constructor)
* - The following things happen in order:
* 1. {@link ClickableComponent#handleFocus} is called via a `focus` event on the
* `ClickableComponent`.
* 2. {@link ClickableComponent#handleFocus} adds a listener for `keydown` on using
* {@link ClickableComponent#handleKeyPress}.
* 3. `ClickableComponent` has not had a `blur` event (`blur` means that focus was lost). The user presses
* the space or enter key.
* 4. {@link ClickableComponent#handleKeyPress} calls this function with the `keydown`
* event as a parameter.
*
* @method handleClick
* @param {EventTarget~Event} event
* The `keydown`, `tap`, or `click` event that caused this function to be
* called.
*
* @listens tap
* @listens click
* @abstract
*/
handleClick() {}
handleClick(event) {}
/**
* Handle Focus - Add keyboard functionality to element
* This gets called when a `ClickableComponent` gains focus via a `focus` event.
* Turns on listening for `keydown` events. When they happen it
* calls `this.handleKeyPress`.
*
* @method handleFocus
* @param {EventTarget~Event} event
* The `focus` event that caused this function to be called.
*
* @listens focus
*/
handleFocus() {
handleFocus(event) {
Events.on(document, 'keydown', Fn.bind(this, this.handleKeyPress));
}
/**
* Handle KeyPress (document level) - Trigger click when Space or Enter key is pressed
* Called when this ClickableComponent has focus and a key gets pressed down. By
* default it will call `this.handleClick` when the key is space or enter.
*
* @method handleKeyPress
* @param {EventTarget~Event} event
* The `keydown` event that caused this function to be called.
*
* @listens keydown
*/
handleKeyPress(event) {
@ -189,11 +235,15 @@ class ClickableComponent extends Component {
}
/**
* Handle Blur - Remove keyboard triggers
* Called when a `ClickableComponent` loses focus. Turns off the listener for
* `keydown` events. Which Stops `this.handleKeyPress` from getting called.
*
* @method handleBlur
* @param {EventTarget~Event} event
* The `blur` event that caused this function to be called.
*
* @listens blur
*/
handleBlur() {
handleBlur(event) {
Events.off(document, 'keydown', Fn.bind(this, this.handleKeyPress));
}
}

49
src/js/close-button.js
View File

@ -1,25 +1,66 @@
/**
* @file close-button.js
*/
import Button from './button';
import Component from './component';
/**
* The `CloseButton` component is a button which fires a "close" event
* when it is activated.
* The `CloseButton` is a `{@link Button}` that fires a `close` event when
* it gets clicked.
*
* @extends Button
* @class CloseButton
*/
class CloseButton extends Button {
/**
* 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);
this.controlText(options && options.controlText || this.localize('Close'));
}
/**
* Builds the default DOM `className`.
*
* @return {string}
* The DOM `className` for this object.
*/
buildCSSClass() {
return `vjs-close-button ${super.buildCSSClass()}`;
}
handleClick() {
/**
* This gets called when a `CloseButton` gets clicked. See
* {@link ClickableComponent#handleClick} for more information on when this will be
* triggered
*
* @param {EventTarget~Event} event
* The `keydown`, `tap`, or `click` event that caused this function to be
* called.
*
* @listens tap
* @listens click
* @fires CloseButton#close
*/
handleClick(event) {
/**
* Triggered when the a `CloseButton` is clicked.
*
* @event CloseButton#close
* @type {EventTarget~Event}
*
* @property {boolean} [bubbles=false]
* set to false so that the close event does not
* bubble up to parents if there is no listener
*/
this.trigger({type: 'close', bubbles: false});
}
}

1199
src/js/component.js
View File

File diff suppressed because it is too large Load Diff

28
src/js/error-display.js
View File

@ -6,18 +6,21 @@ import ModalDialog from './modal-dialog';
import mergeOptions from './utils/merge-options';
/**
* Display that an error has occurred making the video unplayable.
* A display that indicates an error has occurred. This means that the video
* is unplayable.
*
* @extends ModalDialog
* @class ErrorDisplay
*/
class ErrorDisplay extends ModalDialog {
/**
* Constructor for error display modal.
* 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);
@ -25,22 +28,22 @@ class ErrorDisplay extends ModalDialog {
}
/**
* Include the old class for backward-compatibility.
* Builds the default DOM `className`.
*
* This can be removed in 6.0.
* @return {string}
* The DOM `className` for this object.
*
* @method buildCSSClass
* @deprecated
* @return {String}
* @deprecated Since version 5.
*/
buildCSSClass() {
return `vjs-error-display ${super.buildCSSClass()}`;
}
/**
* Generates the modal content based on the player error.
* Gets the localized error message based on the `Player`s error.
*
* @return {String|Null}
* @return {string}
* The `Player`s error message localized or an empty string.
*/
content() {
const error = this.player().error();
@ -49,6 +52,11 @@ class ErrorDisplay extends ModalDialog {
}
}
/**
* The default options for an `ErrorDisplay`.
*
* @private
*/
ErrorDisplay.prototype.options_ = mergeOptions(ModalDialog.prototype.options_, {
fillAlways: true,
temporary: false,

195
src/js/event-target.js
View File

@ -1,12 +1,73 @@
/**
* @file event-target.js
* @file src/js/event-target.js
*/
import * as Events from './utils/events.js';
/**
* `EventTarget` is a class that can have the same API as the DOM `EventTarget`. It
* adds shorthand functions that wrap around lengthy functions. For example:
* the `on` function is a wrapper around `addEventListener`.
*
* @see [EventTarget Spec]{@link https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventTarget}
* @class EventTarget
*/
const EventTarget = function() {};
/**
* A Custom DOM event.
*
* @typedef {Object} EventTarget~Event
* @see [Properties]{@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent}
*/
/**
* All event listeners should follow the following format.
*
* @callback EventTarget~EventListener
* @this {EventTarget}
*
* @param {EventTarget~Event} event
* the event that triggered this function
*
* @param {Object} [hash]
* hash of data sent during the event
*/
/**
* An object containing event names as keys and booleans as values.
*
* > NOTE: If an event name is set to a true value here {@link EventTarget#trigger}
* will have extra functionality. See that function for more information.
*
* @property EventTarget.prototype.allowedEvents_
* @private
*/
EventTarget.prototype.allowedEvents_ = {};
/**
* Adds an `event listener` to an instance of an `EventTarget`. An `event listener` is a
* function that will get called when an event with a certain name gets triggered.
*
* ```js
* var foo = new EventTarget();
* var handleBar = function() {
* console.log('bar was triggered');
* };
*
* foo.on('bar', handleBar);
*
* // This causes any `event listeners` for the `bar` event to get called
* // see {@link EventTarget#trigger} for more information
* foo.trigger('bar');
* // logs 'bar was triggered'
* ```
*
* @param {string|string[]} type
* An event name or an array of event names.
*
* @param {EventTarget~EventListener} fn
* The function to call with `EventTarget`s
*/
EventTarget.prototype.on = function(type, fn) {
// Remove the addEventListener alias before calling Events.on
// so we don't get into an infinite type loop
@ -17,16 +78,105 @@ EventTarget.prototype.on = function(type, fn) {
this.addEventListener = ael;
};
/**
* An alias of {@link EventTarget#on}. Allows `EventTarget` to mimic
* the standard DOM API.
*
* @function
* @see {@link EventTarget#on}
*/
EventTarget.prototype.addEventListener = EventTarget.prototype.on;
/**
* Removes an `event listener` for a specific event from an instance of `EventTarget`.
* This makes it so that the `event listener` will no longer get called when the
* named event happens.
*
* ```js
* var foo = new EventTarget();
* var handleBar = function() {
* console.log('bar was triggered');
* };
*
* // adds an `event listener` for the `bar` event
* // see {@link EventTarget#on} for more info
* foo.on('bar', handleBar);
*
* // runs all `event listeners` for the `bar` event
* // see {@link EventTarget#trigger} for more info
* foo.trigger('bar');
* // logs 'bar was triggered'
*
* foo.off('bar', handleBar);
* foo.trigger('bar');
* // does nothing
* ```
*
* @param {string|string[]} type
* An event name or an array of event names.
*
* @param {EventTarget~EventListener} fn
* The function to remove.
*/
EventTarget.prototype.off = function(type, fn) {
Events.off(this, type, fn);
};
/**
* An alias of {@link EventTarget#off}. Allows `EventTarget` to mimic
* the standard DOM API.
*
* @function
* @see {@link EventTarget#off}
*/
EventTarget.prototype.removeEventListener = EventTarget.prototype.off;
/**
* This function will add an `event listener` that gets triggered only once. After the
* first trigger it will get removed. This is like adding an `event listener`
* with {@link EventTarget#on} that calls {@link EventTarget#off} on itself.
*
* Using {@link EventTarget#on} and {@link EventTarget#off} to mimic {@link EventTarget#one}
* ```js
* var foo = new EventTarget();
* var handleBar = function() {
* console.log('bar was triggered');
* // after the first trigger remove this handler
* foo.off('bar', handleBar);
* };
*
* foo.on('bar', handleBar);
* foo.trigger('bar');
* // logs 'bar was triggered'
*
* foo.trigger('bar');
* // does nothing
* ```
*
* Using {@link EventTarget#one}
* ```js
* var foo = new EventTarget();
* var handleBar = function() {
* console.log('bar was triggered');
* };
*
* // removed after the first trigger
* foo.one('bar', handleBar);
* foo.trigger('bar');
* // logs 'bar was triggered'
*
* foo.trigger('bar');
* // does nothing
* ```
*
* @param {string|string[]} type
* An event name or an array of event names.
*
* @param {EventTarget~EventListener} fn
* The function to be called once for each event name.
*/
EventTarget.prototype.one = function(type, fn) {
// Remove the addEventListener alias before calling Events.on
// Remove the addEventListener alialing Events.on
// so we don't get into an infinite type loop
const ael = this.addEventListener;
@ -35,6 +185,39 @@ EventTarget.prototype.one = function(type, fn) {
this.addEventListener = ael;
};
/**
* This function causes an event to happen. This will then cause any `event listeners`
* that are waiting for that event, to get called. If there are no `event listeners`
* for an event then nothing will happen.
*
* If the name of the `Event` that is being triggered is in `EventTarget.allowedEvents_`.
* Trigger will also call the `on` + `uppercaseEventName` function.
*
* Example:
* 'click' is in `EventTarget.allowedEvents_`, so, trigger will attempt to call
* `onClick` if it exists.
*
* ```js
* var foo = new EventTarget();
* var handleBar = function() {
* console.log('bar was triggered');
* };
*
* foo.on('bar', handleBar);
* foo.trigger('bar');
* // logs 'bar was triggered'
*
* foo.trigger('bar');
* // logs 'bar was triggered'
*
* foo.trigger('foo');
* // does nothing
* ```
*
* @param {string|EventTarget~Event|Object} event
* The name of the event, an `Event`, or an object with a key of type set to
* an event name.
*/
EventTarget.prototype.trigger = function(event) {
const type = event.type || event;
@ -50,7 +233,13 @@ EventTarget.prototype.trigger = function(event) {
Events.trigger(this, event);
};
// The standard DOM EventTarget.dispatchEvent() is aliased to trigger()
/**
* An alias of {@link EventTarget#trigger}. Allows `EventTarget` to mimic
* the standard DOM API.
*
* @function
* @see {@link EventTarget#trigger}
*/
EventTarget.prototype.dispatchEvent = EventTarget.prototype.trigger;
export default EventTarget;