docs: Update JSDoc comments, so core API docs for the videojs function are accurate. (#5385)

src/js/extend.js

@@ -37,22 +37,27 @@ const _inherits = function(subClass, superClass) {
 };
 
 /**
- * Function for subclassing using the same inheritance that
+ * Used to subclass an existing class by emulating ES subclassing using the
- * videojs uses internally
+ * `extends` keyword.
  *
- * @static
+ * @function
- * @const
+ * @example
+ * var MyComponent = videojs.extend(videojs.getComponent('Component'), {
+ *   myCustomMethod: function() {
+ *     // Do things in my method.
+ *   }
+ * });
  *
- * @param {Object} superClass
+ * @param    {Function} superClass
- *        The class to inherit from
+ *           The class to inherit from
  *
- * @param {Object} [subClassMethods={}]
+ * @param    {Object}   [subClassMethods={}]
- *        The class to inherit to
+ *           Methods of the new class
  *
- * @return {Object}
+ * @return   {Function}
- *         The new object with subClassMethods that inherited superClass.
+ *           The new class with subClassMethods that inherited superClass.
  */
-const extendFn = function(superClass, subClassMethods = {}) {
+const extend = function(superClass, subClassMethods = {}) {
   let subClass = function() {
     superClass.apply(this, arguments);
   };
@@ -80,4 +85,4 @@ const extendFn = function(superClass, subClassMethods = {}) {
   return subClass;
 };
 
-export default extendFn;
+export default extend;

src/js/player.js

@@ -3779,7 +3779,10 @@ TRACK_TYPES.names.forEach(function(name) {
 });
 
 /**
- * Global player list
+ * Global enumeration of players.
+ *
+ * The keys are the player IDs and the values are either the {@link Player}
+ * instance or `null` for disposed players.
  *
  * @type {Object}
  */

src/js/plugin.js

@@ -373,8 +373,12 @@ class Plugin {
   /**
    * De-register a Video.js plugin.
    *
-   * @param {string} name
+   * @param  {string} name
-   *        The name of the plugin to be deregistered.
+   *         The name of the plugin to be de-registered. Must be a string that
+   *         matches an existing plugin.
+   *
+   * @throws {Error}
+   *         If an attempt is made to de-register the base plugin.
    */
   static deregisterPlugin(name) {
     if (name === BASE_PLUGIN_NAME) {

src/js/tech/middleware.js

@@ -1,3 +1,7 @@
+/**
+ * @file middleware.js
+ * @module middleware
+ */
 import { assign } from '../utils/obj.js';
 import toTitleCase from '../utils/to-title-case.js';
 
@@ -6,11 +10,53 @@ const middlewareInstances = {};
 
 export const TERMINATOR = {};
 
+/**
+ * A middleware object is a plain JavaScript object that has methods that
+ * match the {@link Tech} methods found in the lists of allowed
+ * {@link module:middleware.allowedGetters|getters},
+ * {@link module:middleware.allowedSetters|setters}, and
+ * {@link module:middleware.allowedMediators|mediators}.
+ *
+ * @typedef {Object} MiddlewareObject
+ */
+
+/**
+ * A middleware factory function that should return a
+ * {@link module:middleware~MiddlewareObject|MiddlewareObject}.
+ *
+ * This factory will be called for each player when needed, with the player
+ * passed in as an argument.
+ *
+ * @callback MiddlewareFactory
+ * @param {Player} player
+ *        A Video.js player.
+ */
+
+/**
+ * Define a middleware that the player should use by way of a factory function
+ * that returns a middleware object.
+ *
+ * @param  {string} type
+ *         The MIME type to match or `"*"` for all MIME types.
+ *
+ * @param  {MiddlewareFactory} middleware
+ *         A middleware factory function that will be executed for
+ *         matching types.
+ */
 export function use(type, middleware) {
   middlewares[type] = middlewares[type] || [];
   middlewares[type].push(middleware);
 }
 
+/**
+ * Gets middlewares by type (or all middlewares).
+ *
+ * @param  {string} type
+ *         The MIME type to match or `"*"` for all MIME types.
+ *
+ * @return {Function[]|undefined}
+ *         An array of middlewares or `undefined` if none exist.
+ */
 export function getMiddleware(type) {
   if (type) {
     return middlewares[type];
@@ -19,10 +65,33 @@ export function getMiddleware(type) {
   return middlewares;
 }
 
+/**
+ * Asynchronously sets a source using middleware by recursing through any
+ * matching middlewares and calling `setSource` on each, passing along the
+ * previous returned value each time.
+ *
+ * @param  {Player} player
+ *         A {@link Player} instance.
+ *
+ * @param  {Tech~SourceObject} src
+ *         A source object.
+ *
+ * @param  {Function}
+ *         The next middleware to run.
+ */
 export function setSource(player, src, next) {
   player.setTimeout(() => setSourceHelper(src, middlewares[src.type], next, player), 1);
 }
 
+/**
+ * When the tech is set, passes the tech to each middleware's `setTech` method.
+ *
+ * @param {Object[]} middleware
+ *        An array of middleware instances.
+ *
+ * @param {Tech} tech
+ *        A Video.js tech.
+ */
 export function setTech(middleware, tech) {
   middleware.forEach((mw) => mw.setTech && mw.setTech(tech));
 }
@@ -30,6 +99,18 @@ export function setTech(middleware, tech) {
 /**
  * Calls a getter on the tech first, through each middleware
  * from right to left to the player.
+ *
+ * @param  {Object[]} middleware
+ *         An array of middleware instances.
+ *
+ * @param  {Tech} tech
+ *         The current tech.
+ *
+ * @param  {string} method
+ *         A method name.
+ *
+ * @return {Mixed}
+ *         The final value from the tech after middleware has intercepted it.
  */
 export function get(middleware, tech, method) {
   return middleware.reduceRight(middlewareIterator(method), tech[method]());
@@ -38,16 +119,48 @@ export function get(middleware, tech, method) {
 /**
  * Takes the argument given to the player and calls the setter method on each
  * middleware from left to right to the tech.
+ *
+ * @param  {Object[]} middleware
+ *         An array of middleware instances.
+ *
+ * @param  {Tech} tech
+ *         The current tech.
+ *
+ * @param  {string} method
+ *         A method name.
+ *
+ * @param  {Mixed} arg
+ *         The value to set on the tech.
+ *
+ * @return {Mixed}
+ *         The return value of the `method` of the `tech`.
  */
 export function set(middleware, tech, method, arg) {
   return tech[method](middleware.reduce(middlewareIterator(method), arg));
 }
 
 /**
- * Takes the argument given to the player and calls the `call` version of the method
+ * Takes the argument given to the player and calls the `call` version of the
- * on each middleware from left to right.
+ * method on each middleware from left to right.
+ *
  * Then, call the passed in method on the tech and return the result unchanged
  * back to the player, through middleware, this time from right to left.
+ *
+ * @param  {Object[]} middleware
+ *         An array of middleware instances.
+ *
+ * @param  {Tech} tech
+ *         The current tech.
+ *
+ * @param  {string} method
+ *         A method name.
+ *
+ * @param  {Mixed} arg
+ *         The value to set on the tech.
+ *
+ * @return {Mixed}
+ *         The return value of the `method` of the `tech`, regardless of the
+ *         return values of middlewares.
  */
 export function mediate(middleware, tech, method, arg = null) {
   const callMethod = 'call' + toTitleCase(method);
@@ -60,6 +173,11 @@ export function mediate(middleware, tech, method, arg = null) {
   return returnValue;
 }
 
+/**
+ * Enumeration of allowed getters where the keys are method names.
+ *
+ * @type {Object}
+ */
 export const allowedGetters = {
   buffered: 1,
   currentTime: 1,
@@ -69,10 +187,20 @@ export const allowedGetters = {
   paused: 1
 };
 
+/**
+ * Enumeration of allowed setters where the keys are method names.
+ *
+ * @type {Object}
+ */
 export const allowedSetters = {
   setCurrentTime: 1
 };
 
+/**
+ * Enumeration of allowed mediators where the keys are method names.
+ *
+ * @type {Object}
+ */
 export const allowedMediators = {
   play: 1,
   pause: 1
@@ -103,6 +231,12 @@ function executeRight(mws, method, value, terminated) {
   }
 }
 
+/**
+ * Clear the middleware cache for a player.
+ *
+ * @param  {Player} player
+ *         A {@link Player} instance.
+ */
 export function clearCacheForPlayer(player) {
   middlewareInstances[player.id()] = null;
 }
@@ -111,6 +245,8 @@ export function clearCacheForPlayer(player) {
  * {
  *  [playerId]: [[mwFactory, mwInstance], ...]
  * }
+ *
+ * @private
  */
 function getOrCreateFactory(player, mwFactory) {
   const mws = middlewareInstances[player.id()];

src/js/utils/browser.js

@@ -9,22 +9,52 @@ const USER_AGENT = window.navigator && window.navigator.userAgent || '';
 const webkitVersionMap = (/AppleWebKit\/([\d.]+)/i).exec(USER_AGENT);
 const appleWebkitVersion = webkitVersionMap ? parseFloat(webkitVersionMap.pop()) : null;
 
-/*
+/**
- * Device is an iPhone
+ * Whether or not this device is an iPad.
  *
+ * @static
+ * @const
  * @type {Boolean}
- * @constant
- * @private
  */
 export const IS_IPAD = (/iPad/i).test(USER_AGENT);
 
+/**
+ * Whether or not this device is an iPhone.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 // The Facebook app's UIWebView identifies as both an iPhone and iPad, so
 // to identify iPhones, we need to exclude iPads.
 // http://artsy.github.io/blog/2012/10/18/the-perils-of-ios-user-agent-sniffing/
 export const IS_IPHONE = (/iPhone/i).test(USER_AGENT) && !IS_IPAD;
+
+/**
+ * Whether or not this device is an iPod.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_IPOD = (/iPod/i).test(USER_AGENT);
+
+/**
+ * Whether or not this is an iOS device.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_IOS = IS_IPHONE || IS_IPAD || IS_IPOD;
 
+/**
+ * The detected iOS version - or `null`.
+ *
+ * @static
+ * @const
+ * @type {string|null}
+ */
 export const IOS_VERSION = (function() {
   const match = USER_AGENT.match(/OS (\d+)_/i);
 
@@ -34,7 +64,22 @@ export const IOS_VERSION = (function() {
   return null;
 }());
 
+/**
+ * Whether or not this is an Android device.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_ANDROID = (/Android/i).test(USER_AGENT);
+
+/**
+ * The detected Android version - or `null`.
+ *
+ * @static
+ * @const
+ * @type {number|string|null}
+ */
 export const ANDROID_VERSION = (function() {
   // This matches Android Major.Minor.Patch versions
   // ANDROID_VERSION is Major.Minor as a Number, if Minor isn't available, then only Major is returned
@@ -55,11 +100,52 @@ export const ANDROID_VERSION = (function() {
   return null;
 }());
 
+/**
+ * Whether or not this is a native Android browser.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_NATIVE_ANDROID = IS_ANDROID && ANDROID_VERSION < 5 && appleWebkitVersion < 537;
 
+/**
+ * Whether or not this is Mozilla Firefox.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_FIREFOX = (/Firefox/i).test(USER_AGENT);
+
+/**
+ * Whether or not this is Microsoft Edge.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_EDGE = (/Edge/i).test(USER_AGENT);
+
+/**
+ * Whether or not this is Google Chrome.
+ *
+ * This will also be `true` for Chrome on iOS, which will have different support
+ * as it is actually Safari under the hood.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_CHROME = !IS_EDGE && ((/Chrome/i).test(USER_AGENT) || (/CriOS/i).test(USER_AGENT));
+
+/**
+ * The detected Google Chrome version - or `null`.
+ *
+ * @static
+ * @const
+ * @type {number|null}
+ */
 export const CHROME_VERSION = (function() {
   const match = USER_AGENT.match(/(Chrome|CriOS)\/(\d+)/);
 
@@ -68,6 +154,14 @@ export const CHROME_VERSION = (function() {
   }
   return null;
 }());
+
+/**
+ * The detected Internet Explorer version - or `null`.
+ *
+ * @static
+ * @const
+ * @type {number|null}
+ */
 export const IE_VERSION = (function() {
   const result = (/MSIE\s(\d+)\.\d/).exec(USER_AGENT);
   let version = result && parseFloat(result[1]);
@@ -80,9 +174,31 @@ export const IE_VERSION = (function() {
   return version;
 }());
 
+/**
+ * Whether or not this is desktop Safari.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_SAFARI = (/Safari/i).test(USER_AGENT) && !IS_CHROME && !IS_ANDROID && !IS_EDGE;
+
+/**
+ * Whether or not this is any flavor of Safari - including iOS.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const IS_ANY_SAFARI = (IS_SAFARI || IS_IOS) && !IS_CHROME;
 
+/**
+ * Whether or not this device is touch-enabled.
+ *
+ * @static
+ * @const
+ * @type {Boolean}
+ */
 export const TOUCH_ENABLED = Dom.isReal() && (
   'ontouchstart' in window ||
   window.navigator.maxTouchPoints ||

src/js/utils/computed-style.js

@@ -8,21 +8,19 @@ import window from 'global/window';
  * A safe getComputedStyle.
  *
  * This is needed because in Firefox, if the player is loaded in an iframe with
- * `display:none`, then `getComputedStyle` returns `null`, so, we do a null-check to
+ * `display:none`, then `getComputedStyle` returns `null`, so, we do a
- * make sure  that the player doesn't break in these cases.
+ * null-check to make sure that the player doesn't break in these cases.
  *
- * @param {Element} el
+ * @function
- *        The element you want the computed style of
+ * @param    {Element} el
+ *           The element you want the computed style of
  *
- * @param {string} prop
+ * @param    {string} prop
- *        The property name you want
+ *           The property name you want
  *
- * @see https://bugzilla.mozilla.org/show_bug.cgi?id=548397
+ * @see      https://bugzilla.mozilla.org/show_bug.cgi?id=548397
- *
- * @static
- * @const
  */
-export default function computedStyle(el, prop) {
+function computedStyle(el, prop) {
   if (!el || !prop) {
     return '';
   }
@@ -35,3 +33,5 @@ export default function computedStyle(el, prop) {
 
   return '';
 }
+
+export default computedStyle;

src/js/utils/dom.js

@@ -12,12 +12,12 @@ import computedStyle from './computed-style';
 /**
  * Detect if a value is a string with any non-whitespace characters.
  *
- * @param {string} str
+ * @private
- *        The string to check
+ * @param  {string} str
+ *         The string to check
  *
  * @return {boolean}
- *         - True if the string is non-blank
+ *         Will be `true` if the string is non-blank, `false` otherwise.
- *         - False otherwise
  *
  */
 function isNonBlankString(str) {
@@ -28,12 +28,12 @@ function isNonBlankString(str) {
  * Throws an error if the passed string has whitespace. This is used by
  * class methods to be relatively consistent with the classList API.
  *
- * @param {string} str
+ * @private
+ * @param  {string} str
  *         The string to check for whitespace.
  *
  * @throws {Error}
  *         Throws an error if there is whitespace in the string.
- *
  */
 function throwIfWhitespace(str) {
   if ((/\s/).test(str)) {
@@ -44,7 +44,8 @@ function throwIfWhitespace(str) {
 /**
  * Produce a regular expression for matching a className within an elements className.
  *
- * @param {string} className
+ * @private
+ * @param  {string} className
  *         The className to generate the RegExp for.
  *
  * @return {RegExp}
@@ -56,9 +57,10 @@ function classRegExp(className) {
 }
 
 /**
- * Whether the current DOM interface appears to be real.
+ * Whether the current DOM interface appears to be real (i.e. not simulated).
  *
  * @return {boolean}
+ *         Will be `true` if the DOM appears to be real, `false` otherwise.
  */
 export function isReal() {
   // Both document and window will never be undefined thanks to `global`.
@@ -68,12 +70,11 @@ export function isReal() {
 /**
  * Determines, via duck typing, whether or not a value is a DOM element.
  *
- * @param {Mixed} value
+ * @param  {Mixed} value
- *        The thing to check
+ *         The value to check.
  *
  * @return {boolean}
- *         - True if it is a DOM element
+ *         Will be `true` if the value is a DOM element, `false` otherwise.
- *         - False otherwise
  */
 export function isEl(value) {
   return isObject(value) && value.nodeType === 1;
@@ -83,7 +84,8 @@ export function isEl(value) {
  * Determines if the current DOM is embedded in an iframe.
  *
  * @return {boolean}
- *
+ *         Will be `true` if the DOM is embedded in an iframe, `false`
+ *         otherwise.
  */
 export function isInFrame() {
 
@@ -99,11 +101,12 @@ export function isInFrame() {
 /**
  * Creates functions to query the DOM using a given method.
  *
- * @param {string} method
+ * @private
- *         The method to create the query with.
+ * @param   {string} method
+ *          The method to create the query with.
  *
- * @return {Function}
+ * @return  {Function}
- *         The query method
+ *          The query method
  */
 function createQuerier(method) {
   return function(selector, context) {
@@ -121,19 +124,19 @@ function createQuerier(method) {
 }
 
 /**
- * Creates an element and applies properties.
+ * Creates an element and applies properties, attributes, and inserts content.
  *
- * @param {string} [tagName='div']
+ * @param  {string} [tagName='div']
  *         Name of tag to be created.
  *
- * @param {Object} [properties={}]
+ * @param  {Object} [properties={}]
  *         Element properties to be applied.
  *
- * @param {Object} [attributes={}]
+ * @param  {Object} [attributes={}]
  *         Element attributes to be applied.
  *
- * @param {String|Element|TextNode|Array|Function} [content]
+ * @param {module:dom~ContentDescriptor} content
- *         Contents for the element (see: {@link dom:normalizeContent})
+ *        A content descriptor object.
  *
  * @return {Element}
  *         The element that was created.
@@ -176,11 +179,11 @@ export function createEl(tagName = 'div', properties = {}, attributes = {}, cont
 /**
  * Injects text into an element, replacing any existing contents entirely.
  *
- * @param {Element} el
+ * @param  {Element} el
- *        The element to add text content into
+ *         The element to add text content into
  *
- * @param {string} text
+ * @param  {string} text
- *        The text content to add.
+ *         The text content to add.
  *
  * @return {Element}
  *         The element with added text content.
@@ -212,17 +215,16 @@ export function prependTo(child, parent) {
 }
 
 /**
- * Check if an element has a CSS class
+ * Check if an element has a class name.
  *
- * @param {Element} element
+ * @param  {Element} element
- *        Element to check
+ *         Element to check
  *
- * @param {string} classToCheck
+ * @param  {string} classToCheck
- *        Class name to check for
+ *         Class name to check for
  *
  * @return {boolean}
- *         - True if the element had the class
+ *         Will be `true` if the element has a class, `false` otherwise.
- *         - False otherwise.
  *
  * @throws {Error}
  *         Throws an error if `classToCheck` has white space.
@@ -236,16 +238,16 @@ export function hasClass(element, classToCheck) {
 }
 
 /**
- * Add a CSS class name to an element
+ * Add a class name to an element.
  *
- * @param {Element} element
+ * @param  {Element} element
- *        Element to add class name to.
+ *         Element to add class name to.
  *
- * @param {string} classToAdd
+ * @param  {string} classToAdd
- *        Class name to add.
+ *         Class name to add.
  *
  * @return {Element}
- *         The dom element with the added class name.
+ *         The DOM element with the added class name.
  */
 export function addClass(element, classToAdd) {
   if (element.classList) {
@@ -261,16 +263,16 @@ export function addClass(element, classToAdd) {
 }
 
 /**
- * Remove a CSS class name from an element
+ * Remove a class name from an element.
  *
- * @param {Element} element
+ * @param  {Element} element
- *        Element to remove a class name from.
+ *         Element to remove a class name from.
  *
- * @param {string} classToRemove
+ * @param  {string} classToRemove
- *        Class name to remove
+ *         Class name to remove
  *
  * @return {Element}
- *         The dom element with class name removed.
+ *         The DOM element with class name removed.
  */
 export function removeClass(element, classToRemove) {
   if (element.classList) {
@@ -286,33 +288,33 @@ export function removeClass(element, classToRemove) {
 }
 
 /**
- * The callback definition for toggleElClass.
+ * The callback definition for toggleClass.
  *
- * @callback Dom~PredicateCallback
+ * @callback module:dom~PredicateCallback
- * @param {Element} element
+ * @param    {Element} element
- *        The DOM element of the Component.
+ *           The DOM element of the Component.
  *
- * @param {string} classToToggle
+ * @param    {string} classToToggle
- *        The `className` that wants to be toggled
+ *           The `className` that wants to be toggled
  *
- * @return {boolean|undefined}
+ * @return   {boolean|undefined}
- *         - If true the `classToToggle` will get added to `element`.
+ *           If `true` is returned, the `classToToggle` will be added to the
- *         - If false the `classToToggle` will get removed from `element`.
+ *           `element`. If `false`, the `classToToggle` will be removed from
- *         - If undefined this callback will be ignored
+ *           the `element`. If `undefined`, the callback will be ignored.
  */
 
 /**
- * Adds or removes a CSS class name on an element depending on an optional
+ * Adds or removes a class name to/from an element depending on an optional
  * condition or the presence/absence of the class name.
  *
- * @param {Element} element
+ * @param  {Element} element
- *        The element to toggle a class name on.
+ *         The element to toggle a class name on.
  *
- * @param {string} classToToggle
+ * @param  {string} classToToggle
- *        The class that should be toggled
+ *         The class that should be toggled.
  *
- * @param {boolean|PredicateCallback} [predicate]
+ * @param  {boolean|module:dom~PredicateCallback} [predicate]
- *        See the return value for {@link Dom~PredicateCallback}
+ *         See the return value for {@link module:dom~PredicateCallback}
  *
  * @return {Element}
  *         The element with a class that has been toggled.
@@ -369,16 +371,17 @@ export function setAttributes(el, attributes) {
 }
 
 /**
- * Get an element's attribute values, as defined on the HTML tag
+ * Get an element's attribute values, as defined on the HTML tag.
- * Attributes are not the same as properties. They're defined on the tag
- * or with setAttribute (which shouldn't be used with HTML)
- * This will return true or false for boolean attributes.
  *
- * @param {Element} tag
+ * Attributes are not the same as properties. They're defined on the tag
- *        Element from which to get tag attributes.
+ * or with setAttribute.
+ *
+ * @param  {Element} tag
+ *         Element from which to get tag attributes.
  *
  * @return {Object}
- *         All attributes of the element.
+ *         All attributes of the element. Boolean attributes will be `true` or
+ *         `false`, others will be strings.
  */
 export function getAttributes(tag) {
   const obj = {};
@@ -412,52 +415,52 @@ export function getAttributes(tag) {
 }
 
 /**
- * Get the value of an element's attribute
+ * Get the value of an element's attribute.
  *
  * @param {Element} el
- *        A DOM element
+ *        A DOM element.
  *
  * @param {string} attribute
- *        Attribute to get the value of
+ *        Attribute to get the value of.
  *
  * @return {string}
- *         value of the attribute
+ *         The value of the attribute.
  */
 export function getAttribute(el, attribute) {
   return el.getAttribute(attribute);
 }
 
 /**
- * Set the value of an element's attribute
+ * Set the value of an element's attribute.
  *
  * @param {Element} el
- *        A DOM element
+ *        A DOM element.
  *
  * @param {string} attribute
- *        Attribute to set
+ *        Attribute to set.
  *
  * @param {string} value
- *        Value to set the attribute to
+ *        Value to set the attribute to.
  */
 export function setAttribute(el, attribute, value) {
   el.setAttribute(attribute, value);
 }
 
 /**
- * Remove an element's attribute
+ * Remove an element's attribute.
  *
  * @param {Element} el
- *        A DOM element
+ *        A DOM element.
  *
  * @param {string} attribute
- *        Attribute to remove
+ *        Attribute to remove.
  */
 export function removeAttribute(el, attribute) {
   el.removeAttribute(attribute);
 }
 
 /**
- * Attempt to block the ability to select text while dragging controls
+ * Attempt to block the ability to select text.
  */
 export function blockTextSelection() {
   document.body.focus();
@@ -467,7 +470,7 @@ export function blockTextSelection() {
 }
 
 /**
- * Turn off text selection blocking
+ * Turn off text selection blocking.
  */
 export function unblockTextSelection() {
   document.onselectstart = function() {
@@ -492,7 +495,7 @@ export function unblockTextSelection() {
  *         Element whose `ClientRect` we want to calculate.
  *
  * @return {Object|undefined}
- *         Always returns a plain
+ *         Always returns a plain object - or `undefined` if it cannot.
  */
 export function getBoundingClientRect(el) {
   if (el && el.getBoundingClientRect && el.parentNode) {
@@ -518,26 +521,26 @@ export function getBoundingClientRect(el) {
 }
 
 /**
- * The postion of a DOM element on the page.
+ * Represents the position of a DOM element on the page.
  *
- * @typedef {Object} module:dom~Position
+ * @typedef  {Object} module:dom~Position
  *
  * @property {number} left
- *           Pixels to the left
+ *           Pixels to the left.
  *
  * @property {number} top
- *           Pixels on top
+ *           Pixels from the top.
  */
 
 /**
- * Offset Left.
+ * Get the position of an element in the DOM.
- * getBoundingClientRect technique from
+ *
- * John Resig
+ * Uses `getBoundingClientRect` technique from John Resig.
  *
  * @see http://ejohn.org/blog/getboundingclientrect-is-awesome/
  *
- * @param {Element} el
+ * @param  {Element} el
- *        Element from which to get offset
+ *         Element from which to get offset.
  *
  * @return {module:dom~Position}
  *         The position of the element that was passed in.
@@ -575,9 +578,9 @@ export function findPosition(el) {
 }
 
 /**
- * x and y coordinates for a dom element or mouse pointer
+ * Represents x and y coordinates for a DOM element or mouse pointer.
  *
- * @typedef {Object} Dom~Coordinates
+ * @typedef  {Object} module:dom~Coordinates
  *
  * @property {number} x
  *           x coordinate in pixels
@@ -587,18 +590,18 @@ export function findPosition(el) {
  */
 
 /**
- * Get pointer position in element
+ * Get the pointer position within an element.
- * Returns an object with x and y coordinates.
+ *
  * The base on the coordinates are the bottom left of the element.
  *
- * @param {Element} el
+ * @param  {Element} el
- *        Element on which to get the pointer position on
+ *         Element on which to get the pointer position on.
  *
- * @param {EventTarget~Event} event
+ * @param  {EventTarget~Event} event
- *        Event object
+ *         Event object.
  *
- * @return {Dom~Coordinates}
+ * @return {module:dom~Coordinates}
- *         A Coordinates object corresponding to the mouse position.
+ *         A coordinates object corresponding to the mouse position.
  *
  */
 export function getPointerPosition(el, event) {
@@ -626,12 +629,11 @@ export function getPointerPosition(el, event) {
 /**
  * Determines, via duck typing, whether or not a value is a text node.
  *
- * @param {Mixed} value
+ * @param  {Mixed} value
- *        Check if this value is a text node.
+ *         Check if this value is a text node.
  *
  * @return {boolean}
- *         - True if it is a text node
+ *         Will be `true` if the value is a text node, `false` otherwise.
- *         - False otherwise
  */
 export function isTextNode(value) {
   return isObject(value) && value.nodeType === 3;
@@ -640,8 +642,8 @@ export function isTextNode(value) {
 /**
  * Empties the contents of an element.
  *
- * @param {Element} el
+ * @param  {Element} el
- *        The element to empty children from
+ *         The element to empty children from
  *
  * @return {Element}
  *         The element with no children
@@ -653,26 +655,37 @@ export function emptyEl(el) {
   return el;
 }
 
+/**
+ * This is a mixed value that describes content to be injected into the DOM
+ * via some method. It can be of the following types:
+ *
+ * Type       | Description
+ * -----------|-------------
+ * `string`   | The value will be normalized into a text node.
+ * `Element`  | The value will be accepted as-is.
+ * `TextNode` | The value will be accepted as-is.
+ * `Array`    | A one-dimensional array of strings, elements, text nodes, or functions. These functions should return a string, element, or text node (any other return value, like an array, will be ignored).
+ * `Function` | A function, which is expected to return a string, element, text node, or array - any of the other possible values described above. This means that a content descriptor could be a function that returns an array of functions, but those second-level functions must return strings, elements, or text nodes.
+ *
+ * @typedef {string|Element|TextNode|Array|Function} module:dom~ContentDescriptor
+ */
+
 /**
  * Normalizes content for eventual insertion into the DOM.
  *
- * This allows a wide range of content definition methods, but protects
+ * This allows a wide range of content definition methods, but helps protect
- * from falling into the trap of simply writing to `innerHTML`, which is
+ * from falling into the trap of simply writing to `innerHTML`, which could
- * an XSS concern.
+ * be an XSS concern.
  *
  * The content for an element can be passed in multiple types and
  * combinations, whose behavior is as follows:
  *
- * @param {string|Element|TextNode|Array|Function} content
+ * @param {module:dom~ContentDescriptor} content
- *        - String: Normalized into a text node.
+ *        A content descriptor value.
- *        - Element/TextNode: Passed through.
- *        - Array: A one-dimensional array of strings, elements, nodes, or functions
- *          (which return single strings, elements, or nodes).
- *        - Function: If the sole argument, is expected to produce a string, element,
- *          node, or array as defined above.
  *
  * @return {Array}
- *         All of the content that was passed in normalized.
+ *         All of the content that was passed in, normalized to an array of
+ *         elements or text nodes.
  */
 export function normalizeContent(content) {
 
@@ -705,12 +718,11 @@ export function normalizeContent(content) {
 /**
  * Normalizes and appends content to an element.
  *
- * @param {Element} el
+ * @param  {Element} el
- *        Element to append normalized content to.
+ *         Element to append normalized content to.
  *
- *
+ * @param {module:dom~ContentDescriptor} content
- * @param {string|Element|TextNode|Array|Function} content
+ *        A content descriptor value.
- *        See the `content` argument of {@link dom:normalizeContent}
  *
  * @return {Element}
  *         The element with appended normalized content.
@@ -727,26 +739,24 @@ export function appendContent(el, content) {
  * @param {Element} el
  *        Element to insert normalized content into.
  *
- * @param {string|Element|TextNode|Array|Function} content
+ * @param {module:dom~ContentDescriptor} content
- *        See the `content` argument of {@link dom:normalizeContent}
+ *        A content descriptor value.
  *
  * @return {Element}
  *         The element with inserted normalized content.
- *
  */
 export function insertContent(el, content) {
   return appendContent(emptyEl(el), content);
 }
 
 /**
- * Check if event was a single left click
+ * Check if an event was a single left click.
  *
- * @param {EventTarget~Event} event
+ * @param  {EventTarget~Event} event
- *        Event object
+ *         Event object.
  *
  * @return {boolean}
- *         - True if a left click
+ *         Will be `true` if a single left click, `false` otherwise.
- *         - False if not a left click
  */
 export function isSingleLeftClick(event) {
   // Note: if you create something draggable, be sure to
@@ -792,14 +802,14 @@ export function isSingleLeftClick(event) {
  * Finds a single DOM element matching `selector` within the optional
  * `context` of another DOM element (defaulting to `document`).
  *
- * @param {string} selector
+ * @param  {string} selector
- *        A valid CSS selector, which will be passed to `querySelector`.
+ *         A valid CSS selector, which will be passed to `querySelector`.
  *
- * @param {Element|String} [context=document]
+ * @param  {Element|String} [context=document]
- *        A DOM element within which to query. Can also be a selector
+ *         A DOM element within which to query. Can also be a selector
- *        string in which case the first matching element will be used
+ *         string in which case the first matching element will be used
- *        as context. If missing (or no element matches selector), falls
+ *         as context. If missing (or no element matches selector), falls
- *        back to `document`.
+ *         back to `document`.
  *
  * @return {Element|null}
  *         The element that was found or null.
@@ -810,17 +820,18 @@ export const $ = createQuerier('querySelector');
  * Finds a all DOM elements matching `selector` within the optional
  * `context` of another DOM element (defaulting to `document`).
  *
- * @param {string} selector
+ * @param  {string} selector
- *           A valid CSS selector, which will be passed to `querySelectorAll`.
+ *         A valid CSS selector, which will be passed to `querySelectorAll`.
  *
- * @param {Element|String} [context=document]
+ * @param  {Element|String} [context=document]
- *           A DOM element within which to query. Can also be a selector
+ *         A DOM element within which to query. Can also be a selector
- *           string in which case the first matching element will be used
+ *         string in which case the first matching element will be used
- *           as context. If missing (or no element matches selector), falls
+ *         as context. If missing (or no element matches selector), falls
- *           back to `document`.
+ *         back to `document`.
  *
  * @return {NodeList}
- *         A element list of elements that were found. Will be empty if none were found.
+ *         A element list of elements that were found. Will be empty if none
+ *         were found.
  *
  */
 export const $$ = createQuerier('querySelectorAll');

src/js/utils/events.js

@@ -4,9 +4,9 @@
  * This should work very similarly to jQuery's events, however it's based off the book version which isn't as
  * robust as jquery's, so there's probably some differences.
  *
+ * @file events.js
  * @module events
  */
-
 import * as DomData from './dom-data';
 import * as Guid from './guid.js';
 import log from './log.js';
@@ -398,8 +398,8 @@ export function off(elem, type, fn) {
  *        data hash to pass along with the event
  *
  * @return {boolean|undefined}
- *         - Returns the opposite of `defaultPrevented` if default was prevented
+ *         Returns the opposite of `defaultPrevented` if default was
- *         - Otherwise returns undefined
+ *         prevented. Otherwise, returns `undefined`
  */
 export function trigger(elem, event, hash) {
   // Fetches element data and a reference to the parent (for bubbling).
@@ -452,7 +452,7 @@ export function trigger(elem, event, hash) {
 }
 
 /**
- * Trigger a listener only once for an event
+ * Trigger a listener only once for an event.
  *
  * @param {Element|Object} elem
  *        Element or object to bind to.
@@ -461,7 +461,7 @@ export function trigger(elem, event, hash) {
  *        Name/type of event
  *
  * @param {Event~EventListener} fn
- *        Event Listener function
+ *        Event listener function
  */
 export function one(elem, type, fn) {
   if (Array.isArray(type)) {

src/js/utils/fn.js

@@ -6,20 +6,24 @@ import { newGUID } from './guid.js';
 import window from 'global/window';
 
 /**
- * Bind (a.k.a proxy or Context). A simple method for changing the context of a function
+ * Bind (a.k.a proxy or context). A simple method for changing the context of
- * It also stores a unique id on the function so it can be easily removed from events.
+ * a function.
  *
- * @param {Mixed} context
+ * It also stores a unique id on the function so it can be easily removed from
- *        The object to bind as scope.
+ * events.
  *
- * @param {Function} fn
+ * @function
- *        The function to be bound to a scope.
+ * @param    {Mixed} context
+ *           The object to bind as scope.
  *
- * @param {number} [uid]
+ * @param    {Function} fn
- *        An optional unique ID for the function to be set
+ *           The function to be bound to a scope.
  *
- * @return {Function}
+ * @param    {number} [uid]
- *         The new function that will be bound into the context given
+ *           An optional unique ID for the function to be set
+ *
+ * @return   {Function}
+ *           The new function that will be bound into the context given
  */
 export const bind = function(context, fn, uid) {
   // Make sure the function has a unique ID
@@ -47,13 +51,14 @@ export const bind = function(context, fn, uid) {
  * Wraps the given function, `fn`, with a new function that only invokes `fn`
  * at most once per every `wait` milliseconds.
  *
- * @param  {Function} fn
+ * @function
- *         The function to be throttled.
+ * @param    {Function} fn
+ *           The function to be throttled.
  *
- * @param  {number}   wait
+ * @param    {Number}   wait
- *         The number of milliseconds by which to throttle.
+ *           The number of milliseconds by which to throttle.
  *
- * @return {Function}
+ * @return   {Function}
  */
 export const throttle = function(fn, wait) {
   let last = Date.now();
@@ -77,23 +82,24 @@ export const throttle = function(fn, wait) {
  *
  * Inspired by lodash and underscore implementations.
  *
- * @param  {Function} func
+ * @function
- *         The function to wrap with debounce behavior.
+ * @param    {Function} func
+ *           The function to wrap with debounce behavior.
  *
- * @param  {number} wait
+ * @param    {number} wait
- *         The number of milliseconds to wait after the last invocation.
+ *           The number of milliseconds to wait after the last invocation.
  *
- * @param  {boolean} [immediate]
+ * @param    {boolean} [immediate]
- *         Whether or not to invoke the function immediately upon creation.
+ *           Whether or not to invoke the function immediately upon creation.
  *
- * @param  {Object} [context=window]
+ * @param    {Object} [context=window]
- *         The "context" in which the debounced function should debounce. For
+ *           The "context" in which the debounced function should debounce. For
- *         example, if this function should be tied to a Video.js player,
+ *           example, if this function should be tied to a Video.js player,
- *         the player can be passed here. Alternatively, defaults to the
+ *           the player can be passed here. Alternatively, defaults to the
- *         global `window` object.
+ *           global `window` object.
  *
- * @return {Function}
+ * @return   {Function}
- *         A debounced function.
+ *           A debounced function.
  */
 export const debounce = function(func, wait, immediate, context = window) {
   let timeout;

src/js/utils/format-time.js

@@ -4,14 +4,16 @@
  */
 
 /**
- * Format seconds as a time string, H:MM:SS or M:SS. Supplying a guide (in seconds)
+ * Format seconds as a time string, H:MM:SS or M:SS. Supplying a guide (in
- * will force a number of leading zeros to cover the length of the guide.
+ * seconds) will force a number of leading zeros to cover the length of the
+ * guide.
  *
- * @param {number} seconds
+ * @private
- *        Number of seconds to be turned into a string
+ * @param  {number} seconds
+ *         Number of seconds to be turned into a string
  *
- * @param {number} guide
+ * @param  {number} guide
- *        Number (in seconds) to model the string after
+ *         Number (in seconds) to model the string after
  *
  * @return {string}
  *         Time formatted as H:MM:SS or M:SS
@@ -44,14 +46,16 @@ const defaultImplementation = function(seconds, guide) {
   return h + m + s;
 };
 
+// Internal pointer to the current implementation.
 let implementation = defaultImplementation;
 
 /**
  * Replaces the default formatTime implementation with a custom implementation.
  *
  * @param {Function} customImplementation
- *        A function which will be used in place of the default formatTime implementation.
+ *        A function which will be used in place of the default formatTime
- *        Will receive the current time in seconds and the guide (in seconds) as arguments.
+ *        implementation. Will receive the current time in seconds and the
+ *        guide (in seconds) as arguments.
  */
 export function setFormatTime(customImplementation) {
   implementation = customImplementation;
@@ -64,6 +68,27 @@ export function resetFormatTime() {
   implementation = defaultImplementation;
 }
 
-export default function(seconds, guide = seconds) {
+/**
+ * Delegates to either the default time formatting function or a custom
+ * function supplied via `setFormatTime`.
+ *
+ * Formats seconds as a time string (H:MM:SS or M:SS). Supplying a
+ * guide (in seconds) will force a number of leading zeros to cover the
+ * length of the guide.
+ *
+ * @static
+ * @example  formatTime(125, 600) === "02:05"
+ * @param    {number} seconds
+ *           Number of seconds to be turned into a string
+ *
+ * @param    {number} guide
+ *           Number (in seconds) to model the string after
+ *
+ * @return   {string}
+ *           Time formatted as H:MM:SS or M:SS
+ */
+function formatTime(seconds, guide = seconds) {
   return implementation(seconds, guide);
 }
+
+export default formatTime;

src/js/utils/log.js

@@ -69,7 +69,21 @@ export const logByType = (type, args) => {
 /**
  * Logs plain debug messages. Similar to `console.log`.
  *
- * @class
+ * Due to [limitations](https://github.com/jsdoc3/jsdoc/issues/955#issuecomment-313829149)
+ * of our JSDoc template, we cannot properly document this as both a function
+ * and a namespace, so its function signature is documented here.
+ *
+ * #### Arguments
+ * ##### *args
+ * Mixed[]
+ *
+ * Any combination of values that could be passed to `console.log()`.
+ *
+ * #### Return Value
+ *
+ * `undefined`
+ *
+ * @namespace
  * @param    {Mixed[]} args
  *           One or more messages or objects that should be logged.
  */
@@ -83,7 +97,7 @@ log = function(...args) {
  * in that logging level. These strings are used to create a regular expression
  * matching the function name being called.
  *
- * Levels provided by video.js are:
+ * Levels provided by Video.js are:
  *
  * - `off`: Matches no calls. Any value that can be cast to `false` will have
  *   this effect. The most restrictive.
@@ -107,12 +121,13 @@ log.levels = {
 };
 
 /**
- * Get or set the current logging level. If a string matching a key from
+ * Get or set the current logging level.
- * {@link log.levels} is provided, acts as a setter. Regardless of argument,
+ *
- * returns the current logging level.
+ * If a string matching a key from {@link module:log.levels} is provided, acts
+ * as a setter.
  *
  * @param  {string} [lvl]
- *         Pass to set a new logging level.
+ *         Pass a valid level to set a new logging level.
  *
  * @return {string}
  *         The current logging level.

src/js/utils/merge-options.js

@@ -5,16 +5,23 @@
 import {each, isPlain} from './obj';
 
 /**
- * Deep-merge one or more options objects, recursively merging **only** plain
+ * Merge two objects recursively.
- * object properties.
  *
+ * Performs a deep merge like
+ * {@link https://lodash.com/docs/4.17.10#merge|lodash.merge}, but only merges
+ * plain objects (not arrays, elements, or anything else).
+ *
+ * Non-plain object values will be copied directly from the right-most
+ * argument.
+ *
+ * @static
  * @param   {Object[]} sources
  *          One or more objects to merge into a new object.
  *
  * @return {Object}
  *          A new object that is the merged result of all sources.
  */
-export default function mergeOptions(...sources) {
+function mergeOptions(...sources) {
   const result = {};
 
   sources.forEach(source => {
@@ -38,3 +45,5 @@ export default function mergeOptions(...sources) {
 
   return result;
 }
+
+export default mergeOptions;

src/js/utils/time-ranges.js

@@ -7,29 +7,30 @@
  * Returns the time for the specified index at the start or end
  * of a TimeRange object.
  *
- * @function time-ranges:indexFunction
+ * @typedef    {Function} TimeRangeIndex
  *
- * @param {number} [index=0]
+ * @param      {number} [index=0]
- *        The range number to return the time for.
+ *             The range number to return the time for.
  *
- * @return {number}
+ * @return     {number}
- *         The time that offset at the specified index.
+ *             The time offset at the specified index.
  *
- * @depricated index must be set to a value, in the future this will throw an error.
+ * @deprecated The index argument must be provided.
+ *             In the future, leaving it out will throw an error.
  */
 
 /**
- * An object that contains ranges of time for various reasons.
+ * An object that contains ranges of time.
  *
- * @typedef {Object} TimeRange
+ * @typedef  {Object} TimeRange
  *
  * @property {number} length
- *           The number of time ranges represented by this Object
+ *           The number of time ranges represented by this object.
  *
- * @property {time-ranges:indexFunction} start
+ * @property {module:time-ranges~TimeRangeIndex} start
  *           Returns the time offset at which a specified time range begins.
  *
- * @property {time-ranges:indexFunction} end
+ * @property {module:time-ranges~TimeRangeIndex} end
  *           Returns the time offset at which a specified time range ends.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges
@@ -38,16 +39,17 @@
 /**
  * Check if any of the time ranges are over the maximum index.
  *
- * @param {string} fnName
+ * @private
- *        The function name to use for logging
+ * @param   {string} fnName
+ *          The function name to use for logging
  *
- * @param {number} index
+ * @param   {number} index
- *        The index to check
+ *          The index to check
  *
- * @param {number} maxIndex
+ * @param   {number} maxIndex
- *        The maximum possible index
+ *          The maximum possible index
  *
- * @throws {Error} if the timeRanges provided are over the maxIndex
+ * @throws  {Error} if the timeRanges provided are over the maxIndex
  */
 function rangeCheck(fnName, index, maxIndex) {
   if (typeof index !== 'number' || index < 0 || index > maxIndex) {
@@ -59,24 +61,25 @@ function rangeCheck(fnName, index, maxIndex) {
  * Get the time for the specified index at the start or end
  * of a TimeRange object.
  *
- * @param {string} fnName
+ * @private
- *        The function name to use for logging
+ * @param      {string} fnName
+ *             The function name to use for logging
  *
- * @param {string} valueIndex
+ * @param      {string} valueIndex
- *        The property that should be used to get the time. should be 'start' or 'end'
+ *             The property that should be used to get the time. should be
+ *             'start' or 'end'
  *
- * @param {Array} ranges
+ * @param      {Array} ranges
- *        An array of time ranges
+ *             An array of time ranges
  *
- * @param {Array} [rangeIndex=0]
+ * @param      {Array} [rangeIndex=0]
- *        The index to start the search at
+ *             The index to start the search at
  *
- * @return {number}
+ * @return     {number}
- *         The time that offset at the specified index.
+ *             The time that offset at the specified index.
  *
- *
+ * @deprecated rangeIndex must be set to a value, in the future this will throw an error.
- * @depricated rangeIndex must be set to a value, in the future this will throw an error.
+ * @throws     {Error} if rangeIndex is more than the length of ranges
- * @throws {Error} if rangeIndex is more than the length of ranges
  */
 function getRange(fnName, valueIndex, ranges, rangeIndex) {
   rangeCheck(fnName, rangeIndex, ranges.length - 1);
@@ -86,8 +89,9 @@ function getRange(fnName, valueIndex, ranges, rangeIndex) {
 /**
  * Create a time range object given ranges of time.
  *
- * @param {Array} [ranges]
+ * @private
- *        An array of time ranges.
+ * @param   {Array} [ranges]
+ *          An array of time ranges.
  */
 function createTimeRangesObj(ranges) {
   if (ranges === undefined || ranges.length === 0) {
@@ -109,15 +113,16 @@ function createTimeRangesObj(ranges) {
 }
 
 /**
- * Should create a fake `TimeRange` object which mimics an HTML5 time range instance.
+ * Create a `TimeRange` object which mimics an
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges|HTML5 TimeRanges instance}.
  *
- * @param {number|Array} start
+ * @param {number|Array[]} start
- *        The start of a single range or an array of ranges
+ *        The start of a single range (a number) or an array of ranges (an
+ *        array of arrays of two numbers each).
  *
  * @param {number} end
- *        The end of a single range.
+ *        The end of a single range. Cannot be used with the array form of
- *
+ *        the `start` argument.
- * @private
  */
 export function createTimeRanges(start, end) {
   if (Array.isArray(start)) {

src/js/utils/url.js

@@ -33,11 +33,12 @@ import window from 'global/window';
 /**
  * Resolve and parse the elements of a URL.
  *
- * @param  {String} url
+ * @function
- *         The url to parse
+ * @param    {String} url
+ *           The url to parse
  *
- * @return {url:URLObject}
+ * @return   {url:URLObject}
- *         An object of url details
+ *           An object of url details
  */
 export const parseUrl = function(url) {
   const props = ['protocol', 'hostname', 'port', 'pathname', 'search', 'hash', 'host'];
@@ -93,16 +94,16 @@ export const parseUrl = function(url) {
 };
 
 /**
- * Get absolute version of relative URL. Used to tell flash correct URL.
+ * Get absolute version of relative URL. Used to tell Flash the correct URL.
  *
+ * @function
+ * @param    {string} url
+ *           URL to make absolute
  *
- * @param  {string} url
+ * @return   {string}
- *         URL to make absolute
+ *           Absolute URL
  *
- * @return {string}
+ * @see      http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue
- *         Absolute URL
- *
- * @see http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue
  */
 export const getAbsoluteURL = function(url) {
   // Check if absolute URL
@@ -121,12 +122,13 @@ export const getAbsoluteURL = function(url) {
  * Returns the extension of the passed file name. It will return an empty string
  * if passed an invalid path.
  *
- * @param {string} path
+ * @function
- *        The fileName path like '/path/to/file.mp4'
+ * @param    {string} path
+ *           The fileName path like '/path/to/file.mp4'
  *
- * @return {string}
+ * @returns  {string}
- *          The extension in lower case or an empty string if no
+ *           The extension in lower case or an empty string if no
- *          extension could be found.
+ *           extension could be found.
  */
 export const getFileExtension = function(path) {
   if (typeof path === 'string') {
@@ -144,11 +146,12 @@ export const getFileExtension = function(path) {
 /**
  * Returns whether the url passed is a cross domain request or not.
  *
- * @param {string} url
+ * @function
- *        The url to check.
+ * @param    {string} url
+ *           The url to check.
  *
- * @return {boolean}
+ * @return   {boolean}
- *         Whether it is a cross domain request or not.
+ *           Whether it is a cross domain request or not.
  */
 export const isCrossOrigin = function(url) {
   const winLoc = window.location;

src/js/video.js

@@ -26,7 +26,7 @@ import * as browser from './utils/browser.js';
 import * as Url from './utils/url.js';
 import {isObject} from './utils/obj';
 import computedStyle from './utils/computed-style.js';
-import extendFn from './extend.js';
+import extend from './extend.js';
 import xhr from 'xhr';
 
 // Include the built-in techs
@@ -36,6 +36,7 @@ import { use as middlewareUse, TERMINATOR } from './tech/middleware.js';
 /**
  * Normalize an `id` value by trimming off a leading `#`
  *
+ * @private
  * @param   {string} id
  *          A string, maybe with a leading `#`.
  *
@@ -45,21 +46,83 @@ import { use as middlewareUse, TERMINATOR } from './tech/middleware.js';
 const normalizeId = (id) => id.indexOf('#') === 0 ? id.slice(1) : id;
 
 /**
- * Doubles as the main function for users to create a player instance and also
+ * The `videojs()` function doubles as the main function for users to create a
- * the main library object.
+ * {@link Player} instance as well as the main library namespace.
- * The `videojs` function can be used to initialize or retrieve a player.
-  *
- * @param {string|Element} id
- *        Video element or video element ID
  *
- * @param {Object} [options]
+ * It can also be used as a getter for a pre-existing {@link Player} instance.
- *        Optional options object for config/settings
+ * However, we _strongly_ recommend using `videojs.getPlayer()` for this
+ * purpose because it avoids any potential for unintended initialization.
  *
- * @param {Component~ReadyCallback} [ready]
+ * Due to [limitations](https://github.com/jsdoc3/jsdoc/issues/955#issuecomment-313829149)
- *        Optional ready callback
+ * of our JSDoc template, we cannot properly document this as both a function
+ * and a namespace, so its function signature is documented here.
+ *
+ * #### Arguments
+ * ##### id
+ * string|Element, **required**
+ *
+ * Video element or video element ID.
+ *
+ * ##### options
+ * Object, optional
+ *
+ * Options object for providing settings.
+ * See: [Options Guide](https://docs.videojs.com/tutorial-options.html).
+ *
+ * ##### ready
+ * {@link Component~ReadyCallback}, optional
+ *
+ * A function to be called when the {@link Player} and {@link Tech} are ready.
+ *
+ * #### Return Value
+ *
+ * The `videojs()` function returns a {@link Player} instance.
+ *
+ * @namespace
+ *
+ * @borrows AudioTrack as AudioTrack
+ * @borrows Component.getComponent as getComponent
+ * @borrows module:computed-style~computedStyle as computedStyle
+ * @borrows module:events.on as on
+ * @borrows module:events.one as one
+ * @borrows module:events.off as off
+ * @borrows module:events.trigger as trigger
+ * @borrows EventTarget as EventTarget
+ * @borrows module:extend~extend as extend
+ * @borrows module:fn.bind as bind
+ * @borrows module:format-time.formatTime as formatTime
+ * @borrows module:format-time.resetFormatTime as resetFormatTime
+ * @borrows module:format-time.setFormatTime as setFormatTime
+ * @borrows module:merge-options.mergeOptions as mergeOptions
+ * @borrows module:middleware.use as use
+ * @borrows Player.players as players
+ * @borrows Plugin.registerPlugin as registerPlugin
+ * @borrows Plugin.deregisterPlugin as deregisterPlugin
+ * @borrows Plugin.getPlugins as getPlugins
+ * @borrows Plugin.getPlugin as getPlugin
+ * @borrows Plugin.getPluginVersion as getPluginVersion
+ * @borrows Tech.getTech as getTech
+ * @borrows Tech.registerTech as registerTech
+ * @borrows TextTrack as TextTrack
+ * @borrows module:time-ranges.createTimeRanges as createTimeRange
+ * @borrows module:time-ranges.createTimeRanges as createTimeRanges
+ * @borrows module:url.isCrossOrigin as isCrossOrigin
+ * @borrows module:url.parseUrl as parseUrl
+ * @borrows VideoTrack as VideoTrack
+ *
+ * @param  {string|Element} id
+ *         Video element or video element ID.
+ *
+ * @param  {Object} [options]
+ *         Options object for providing settings.
+ *         See: [Options Guide](https://docs.videojs.com/tutorial-options.html).
+ *
+ * @param  {Component~ReadyCallback} [ready]
+ *         A function to be called when the {@link Player} and {@link Tech} are
+ *         ready.
  *
  * @return {Player}
- *         A player instance
+ *         The `videojs()` function returns a {@link Player|Player} instance.
  */
 function videojs(id, options, ready) {
   let player = videojs.getPlayer(id);
@@ -111,19 +174,19 @@ function videojs(id, options, ready) {
 /**
  * An Object that contains lifecycle hooks as keys which point to an array
  * of functions that are run when a lifecycle is triggered
+ *
+ * @private
  */
 videojs.hooks_ = {};
 
 /**
  * Get a list of hooks for a specific lifecycle
  *
- * @function videojs.hooks
+ * @param  {string} type
+ *         the lifecyle to get hooks from
  *
- * @param {string} type
+ * @param  {Function|Function[]} [fn]
- *        the lifecyle to get hooks from
+ *         Optionally add a hook (or hooks) to the lifecycle that your are getting.
- *
- * @param {Function|Function[]} [fn]
- *        Optionally add a hook (or hooks) to the lifecycle that your are getting.
  *
  * @return {Array}
  *         an array of hooks, or an empty array if there are none.
@@ -172,11 +235,11 @@ videojs.hookOnce = function(type, fn) {
 /**
  * Remove a hook from a specific videojs lifecycle.
  *
- * @param {string} type
+ * @param  {string} type
- *        the lifecycle that the function hooked to
+ *         the lifecycle that the function hooked to
  *
- * @param {Function} fn
+ * @param  {Function} fn
- *        The hooked function to remove
+ *         The hooked function to remove
  *
  * @return {boolean}
  *         The function that was removed or undef
@@ -224,7 +287,7 @@ if (window.VIDEOJS_NO_DYNAMIC_STYLE !== true && Dom.isReal()) {
 setup.autoSetupTimeout(1, videojs);
 
 /**
- * Current software version. Follows semver.
+ * Current Video.js version. Follows [semantic versioning](https://semver.org/).
  *
  * @type {string}
  */
@@ -303,19 +366,7 @@ videojs.getAllPlayers = () =>
   // we filter those out.
   Object.keys(Player.players).map(k => Player.players[k]).filter(Boolean);
 
-/**
- * Expose players object.
- *
- * @memberOf videojs
- * @property {Object} players
- */
 videojs.players = Player.players;
-
-/**
- * Get a component class object by name
- *
- * @borrows Component.getComponent as videojs.getComponent
- */
 videojs.getComponent = Component.getComponent;
 
 /**
@@ -343,27 +394,8 @@ videojs.registerComponent = (name, comp) => {
   Component.registerComponent.call(Component, name, comp);
 };
 
-/**
- * Get a Tech class object by name
- *
- * @borrows Tech.getTech as videojs.getTech
- */
 videojs.getTech = Tech.getTech;
-
-/**
- * Register a Tech so it can referred to by name.
- * This is used in the tech order for the player.
- *
- * @borrows Tech.registerTech as videojs.registerTech
- */
 videojs.registerTech = Tech.registerTech;
-
-/**
- * Register a middleware to a source type.
- *
- * @param {String} type A string representing a MIME type.
- * @param {function(player):object} middleware A middleware factory that takes a player.
- */
 videojs.use = middlewareUse;
 
 /**
@@ -371,7 +403,6 @@ videojs.use = middlewareUse;
  * that the middleware is being terminated.
  *
  * @type {object}
- * @memberOf {videojs}
  * @property {object} middleware.TERMINATOR
  */
 Object.defineProperty(videojs, 'middleware', {
@@ -387,90 +418,32 @@ Object.defineProperty(videojs.middleware, 'TERMINATOR', {
 });
 
 /**
- * A suite of browser and device tests from {@link browser}.
+ * A reference to the {@link module:browser|browser utility module} as an object.
  *
  * @type {Object}
- * @private
+ * @see  {@link module:browser|browser}
  */
 videojs.browser = browser;
 
 /**
- * Whether or not the browser supports touch events. Included for backward
+ * Use {@link module:browser.TOUCH_ENABLED|browser.TOUCH_ENABLED} instead; only
- * compatibility with 4.x, but deprecated. Use `videojs.browser.TOUCH_ENABLED`
+ * included for backward-compatibility with 4.x.
- * instead going forward.
  *
- * @deprecated since version 5.0
+ * @deprecated Since version 5.0, use {@link module:browser.TOUCH_ENABLED|browser.TOUCH_ENABLED instead.
  * @type {boolean}
  */
 videojs.TOUCH_ENABLED = browser.TOUCH_ENABLED;
 
-/**
+videojs.extend = extend;
- * Subclass an existing class
- * Mimics ES6 subclassing with the `extend` keyword
- *
- * @borrows extend:extendFn as videojs.extend
- */
-videojs.extend = extendFn;
-
-/**
- * Merge two options objects recursively
- * Performs a deep merge like lodash.merge but **only merges plain objects**
- * (not arrays, elements, anything else)
- * Other values will be copied directly from the second object.
- *
- * @borrows merge-options:mergeOptions as videojs.mergeOptions
- */
 videojs.mergeOptions = mergeOptions;
-
-/**
- * Change the context (this) of a function
- *
- * > NOTE: as of v5.0 we require an ES5 shim, so you should use the native
- * `function() {}.bind(newContext);` instead of this.
- *
- * @borrows fn:bind as videojs.bind
- */
 videojs.bind = Fn.bind;
-
-/**
- * Register a Video.js plugin.
- *
- * @borrows plugin:registerPlugin as videojs.registerPlugin
- * @method registerPlugin
- *
- * @param  {string} name
- *         The name of the plugin to be registered. Must be a string and
- *         must not match an existing plugin or a method on the `Player`
- *         prototype.
- *
- * @param  {Function} plugin
- *         A sub-class of `Plugin` or a function for basic plugins.
- *
- * @return {Function}
- *         For advanced plugins, a factory function for that plugin. For
- *         basic plugins, a wrapper function that initializes the plugin.
- */
 videojs.registerPlugin = Plugin.registerPlugin;
-
-/**
- * Deregister a Video.js plugin.
- *
- * @borrows plugin:deregisterPlugin as videojs.deregisterPlugin
- * @method deregisterPlugin
- *
- * @param  {string} name
- *         The name of the plugin to be deregistered. Must be a string and
- *         must match an existing plugin or a method on the `Player`
- *         prototype.
- *
- */
 videojs.deregisterPlugin = Plugin.deregisterPlugin;
 
 /**
  * Deprecated method to register a plugin with Video.js
  *
- * @deprecated
+ * @deprecated videojs.plugin() is deprecated; use videojs.registerPlugin() instead
- *        videojs.plugin() is deprecated; use videojs.registerPlugin() instead
  *
  * @param {string} name
  *        The plugin name
@@ -483,39 +456,8 @@ videojs.plugin = (name, plugin) => {
   return Plugin.registerPlugin(name, plugin);
 };
 
-/**
- * Gets an object containing multiple Video.js plugins.
- *
- * @param  {Array} [names]
- *         If provided, should be an array of plugin names. Defaults to _all_
- *         plugin names.
- *
- * @return {Object|undefined}
- *         An object containing plugin(s) associated with their name(s) or
- *         `undefined` if no matching plugins exist).
- */
 videojs.getPlugins = Plugin.getPlugins;
-
-/**
- * Gets a plugin by name if it exists.
- *
- * @param  {string} name
- *         The name of a plugin.
- *
- * @return {Function|undefined}
- *         The plugin (or `undefined`).
- */
 videojs.getPlugin = Plugin.getPlugin;
-
-/**
- * Gets a plugin's version, if available
- *
- * @param  {string} name
- *         The name of a plugin.
- *
- * @return {string}
- *         The plugin's version or an empty string.
- */
 videojs.getPluginVersion = Plugin.getPluginVersion;
 
 /**
@@ -543,264 +485,43 @@ videojs.addLanguage = function(code, data) {
 };
 
 /**
- * Log messages
+ * A reference to the {@link module:log|log utility module} as an object.
  *
- * @borrows log:log as videojs.log
+ * @type {Function}
+ * @see  {@link module:log|log}
  */
 videojs.log = log;
 
-/**
- * Creates an emulated TimeRange object.
- *
- * @borrows time-ranges:createTimeRanges as videojs.createTimeRange
- */
-/**
- * @borrows time-ranges:createTimeRanges as videojs.createTimeRanges
- */
 videojs.createTimeRange = videojs.createTimeRanges = createTimeRanges;
-
-/**
- * Format seconds as a time string, H:MM:SS or M:SS
- * Supplying a guide (in seconds) will force a number of leading zeros
- * to cover the length of the guide
- *
- * @borrows format-time:formatTime as videojs.formatTime
- */
 videojs.formatTime = formatTime;
-
-/**
- * Replaces format-time with a custom implementation, to be used in place of the default.
- *
- * @borrows format-time:setFormatTime as videojs.setFormatTime
- *
- * @method setFormatTime
- *
- * @param {Function} customFn
- *        A custom format-time function which will be called with the current time and guide (in seconds) as arguments.
- *        Passed fn should return a string.
- */
 videojs.setFormatTime = setFormatTime;
-
-/**
- * Resets format-time to the default implementation.
- *
- * @borrows format-time:resetFormatTime as videojs.resetFormatTime
- *
- * @method resetFormatTime
- */
 videojs.resetFormatTime = resetFormatTime;
-
-/**
- * Resolve and parse the elements of a URL
- *
- * @borrows url:parseUrl as videojs.parseUrl
- *
- */
 videojs.parseUrl = Url.parseUrl;
-
-/**
- * Returns whether the url passed is a cross domain request or not.
- *
- * @borrows url:isCrossOrigin as videojs.isCrossOrigin
- */
 videojs.isCrossOrigin = Url.isCrossOrigin;
-
-/**
- * Event target class.
- *
- * @borrows EventTarget as videojs.EventTarget
- */
 videojs.EventTarget = EventTarget;
-
-/**
- * Add an event listener to element
- * It stores the handler function in a separate cache object
- * and adds a generic handler to the element's event,
- * along with a unique id (guid) to the element.
- *
- * @borrows events:on as videojs.on
- */
 videojs.on = Events.on;
-
-/**
- * Trigger a listener only once for an event
- *
- * @borrows events:one as videojs.one
- */
 videojs.one = Events.one;
-
-/**
- * Removes event listeners from an element
- *
- * @borrows events:off as videojs.off
- */
 videojs.off = Events.off;
-
-/**
- * Trigger an event for an element
- *
- * @borrows events:trigger as videojs.trigger
- */
 videojs.trigger = Events.trigger;
 
 /**
- * A cross-browser XMLHttpRequest wrapper. Here's a simple example:
+ * A cross-browser XMLHttpRequest wrapper.
  *
- * @param {Object} options
+ * @function
- *        settings for the request.
+ * @param    {Object} options
+ *           Settings for the request.
  *
- * @return {XMLHttpRequest|XDomainRequest}
+ * @return   {XMLHttpRequest|XDomainRequest}
- *         The request object.
+ *           The request object.
  *
- * @see https://github.com/Raynos/xhr
+ * @see      https://github.com/Raynos/xhr
  */
 videojs.xhr = xhr;
 
-/**
- * TextTrack class
- *
- * @borrows TextTrack as videojs.TextTrack
- */
 videojs.TextTrack = TextTrack;
-
-/**
- * export the AudioTrack class so that source handlers can create
- * AudioTracks and then add them to the players AudioTrackList
- *
- * @borrows AudioTrack as videojs.AudioTrack
- */
 videojs.AudioTrack = AudioTrack;
-
-/**
- * export the VideoTrack class so that source handlers can create
- * VideoTracks and then add them to the players VideoTrackList
- *
- * @borrows VideoTrack as videojs.VideoTrack
- */
 videojs.VideoTrack = VideoTrack;
 
-/**
- * Determines, via duck typing, whether or not a value is a DOM element.
- *
- * @borrows dom:isEl as videojs.isEl
- * @deprecated Use videojs.dom.isEl() instead
- */
-
-/**
- * Determines, via duck typing, whether or not a value is a text node.
- *
- * @borrows dom:isTextNode as videojs.isTextNode
- * @deprecated Use videojs.dom.isTextNode() instead
- */
-
-/**
- * Creates an element and applies properties.
- *
- * @borrows dom:createEl as videojs.createEl
- * @deprecated Use videojs.dom.createEl() instead
- */
-
-/**
- * Check if an element has a CSS class
- *
- * @borrows dom:hasElClass as videojs.hasClass
- * @deprecated Use videojs.dom.hasClass() instead
- */
-
-/**
- * Add a CSS class name to an element
- *
- * @borrows dom:addElClass as videojs.addClass
- * @deprecated Use videojs.dom.addClass() instead
- */
-
-/**
- * Remove a CSS class name from an element
- *
- * @borrows dom:removeElClass as videojs.removeClass
- * @deprecated Use videojs.dom.removeClass() instead
- */
-
-/**
- * Adds or removes a CSS class name on an element depending on an optional
- * condition or the presence/absence of the class name.
- *
- * @borrows dom:toggleElClass as videojs.toggleClass
- * @deprecated Use videojs.dom.toggleClass() instead
- */
-
-/**
- * Apply attributes to an HTML element.
- *
- * @borrows dom:setElAttributes as videojs.setAttribute
- * @deprecated Use videojs.dom.setAttributes() instead
- */
-
-/**
- * Get an element's attribute values, as defined on the HTML tag
- * Attributes are not the same as properties. They're defined on the tag
- * or with setAttribute (which shouldn't be used with HTML)
- * This will return true or false for boolean attributes.
- *
- * @borrows dom:getElAttributes as videojs.getAttributes
- * @deprecated Use videojs.dom.getAttributes() instead
- */
-
-/**
- * Empties the contents of an element.
- *
- * @borrows dom:emptyEl as videojs.emptyEl
- * @deprecated Use videojs.dom.emptyEl() instead
- */
-
-/**
- * Normalizes and appends content to an element.
- *
- * The content for an element can be passed in multiple types and
- * combinations, whose behavior is as follows:
- *
- * - String
- *   Normalized into a text node.
- *
- * - Element, TextNode
- *   Passed through.
- *
- * - Array
- *   A one-dimensional array of strings, elements, nodes, or functions (which
- *   return single strings, elements, or nodes).
- *
- * - Function
- *   If the sole argument, is expected to produce a string, element,
- *   node, or array.
- *
- * @borrows dom:appendContents as videojs.appendContet
- * @deprecated Use videojs.dom.appendContent() instead
- */
-
-/**
- * Normalizes and inserts content into an element; this is identical to
- * `appendContent()`, except it empties the element first.
- *
- * The content for an element can be passed in multiple types and
- * combinations, whose behavior is as follows:
- *
- * - String
- *   Normalized into a text node.
- *
- * - Element, TextNode
- *   Passed through.
- *
- * - Array
- *   A one-dimensional array of strings, elements, nodes, or functions (which
- *   return single strings, elements, or nodes).
- *
- * - Function
- *   If the sole argument, is expected to produce a string, element,
- *   node, or array.
- *
- * @borrows dom:insertContent as videojs.insertContent
- * @deprecated Use videojs.dom.insertContent() instead
- */
 [
   'isEl',
   'isTextNode',
@@ -821,27 +542,21 @@ videojs.VideoTrack = VideoTrack;
   };
 });
 
-/**
- * A safe getComputedStyle.
- *
- * This is because in Firefox, if the player is loaded in an iframe with `display:none`,
- * then `getComputedStyle` returns `null`, so, we do a null-check to make sure
- * that the player doesn't break in these cases.
- * See https://bugzilla.mozilla.org/show_bug.cgi?id=548397 for more details.
- *
- * @borrows computed-style:computedStyle as videojs.computedStyle
- */
 videojs.computedStyle = computedStyle;
 
 /**
- * Export the Dom utilities for use in external plugins
+ * A reference to the {@link module:dom|DOM utility module} as an object.
- * and Tech's
+ *
+ * @type {Object}
+ * @see  {@link module:dom|dom}
  */
 videojs.dom = Dom;
 
 /**
- * Export the Url utilities for use in external plugins
+ * A reference to the {@link module:url|URL utility module} as an object.
- * and Tech's
+ *
+ * @type {Object}
+ * @see  {@link module:url|url}
  */
 videojs.url = Url;
 

test/unit/extend.test.js

@@ -1,5 +1,5 @@
 /* eslint-env qunit */
-import extendFn from '../../src/js/extend.js';
+import extend from '../../src/js/extend.js';
 
 QUnit.module('extend.js');
 
@@ -8,7 +8,7 @@ QUnit.test('should add implicit parent constructor call', function(assert) {
   const Parent = function() {
     superCalled = true;
   };
-  const Child = extendFn(Parent, {
+  const Child = extend(Parent, {
     foo: 'bar'
   });
   const child = new Child();

test/unit/tech/tech.test.js

@@ -3,7 +3,7 @@ import Tech from '../../../src/js/tech/tech.js';
 import Html5 from '../../../src/js/tech/html5.js';
 import Button from '../../../src/js/button.js';
 import { createTimeRange } from '../../../src/js/utils/time-ranges.js';
-import extendFn from '../../../src/js/extend.js';
+import extend from '../../../src/js/extend.js';
 import MediaError from '../../../src/js/media-error.js';
 import AudioTrack from '../../../src/js/tracks/audio-track';
 import VideoTrack from '../../../src/js/tracks/video-track';
@@ -42,7 +42,7 @@ QUnit.module('Media Tech', {
 });
 
 QUnit.test('Tech.registerTech and Tech.getTech', function(assert) {
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
   const oldTechs = Tech.techs_;
   const oldDefaultTechOrder = Tech.defaultTechOrder_;
 
@@ -222,7 +222,7 @@ QUnit.test('switching sources should clear all remote tracks that are added with
   };
 
   // Define a new tech class
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
 
   // Create source handler
   const handler = {
@@ -307,7 +307,7 @@ QUnit.test('should add the source handler interface to a tech', function(assert)
   const sourceB = { src: 'no-support', type: 'no-support' };
 
   // Define a new tech class
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
 
   // Extend Tech with source handlers
   Tech.withSourceHandlers(MyTech);
@@ -506,7 +506,7 @@ QUnit.test('should add the source handler interface to a tech', function(assert)
 
 QUnit.test('should handle unsupported sources with the source handler API', function(assert) {
   // Define a new tech class
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
 
   // Extend Tech with source handlers
   Tech.withSourceHandlers(MyTech);
@@ -555,7 +555,7 @@ QUnit.test('should track whether a video has played', function(assert) {
 });
 
 QUnit.test('delegates deferrables to the source handler', function(assert) {
-  const MyTech = extendFn(Tech, {
+  const MyTech = extend(Tech, {
     seekable() {
       throw new Error('You should not be calling me!');
     },
@@ -605,7 +605,7 @@ QUnit.test('delegates deferrables to the source handler', function(assert) {
 
 QUnit.test('delegates only deferred deferrables to the source handler', function(assert) {
   let seekingCount = 0;
-  const MyTech = extendFn(Tech, {
+  const MyTech = extend(Tech, {
     seekable() {
       throw new Error('You should not be calling me!');
     },
@@ -663,7 +663,7 @@ QUnit.test('Tech.isTech returns correct answers for techs and components', funct
 });
 
 QUnit.test('setSource after tech dispose should dispose source handler once', function(assert) {
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
 
   Tech.withSourceHandlers(MyTech);
 
@@ -707,7 +707,7 @@ QUnit.test('setSource after tech dispose should dispose source handler once', fu
 });
 
 QUnit.test('setSource after previous setSource should dispose source handler once', function(assert) {
-  const MyTech = extendFn(Tech);
+  const MyTech = extend(Tech);
 
   Tech.withSourceHandlers(MyTech);