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

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

src/js/fullscreen-api.js

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

src/js/loading-spinner.js

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

src/js/media-error.js

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