docs(jsdoc): Update the jsdoc comments to modern syntax - Part 4 (#3756)

Files in this PR:
* src/js/poster-image.js
* src/js/tech/flash-rtmp.js
* src/js/tech/flash.js
* src/js/tech/html5.js
* src/js/tech/loader.js
* src/js/tech/tech.js

src/js/poster-image.js

@@ -8,15 +8,21 @@ import * as Dom from './utils/dom.js';
 import * as browser from './utils/browser.js';
 
 /**
- * The component that handles showing the poster image.
+ * A `ClickableComponent` that handles showing the poster image for the player.
  *
- * @param {Player|Object} player
- * @param {Object=} options
- * @extends Button
- * @class PosterImage
+ * @extends ClickableComponent
  */
 class PosterImage extends ClickableComponent {
 
+  /**
+   * Create an instance of this class.
+   *
+   * @param {Player} player
+   *        The `Player` that this class should attach to.
+   *
+   * @param {Object} [options]
+   *        The key/value store of player options.
+   */
   constructor(player, options) {
     super(player, options);
 
@@ -25,20 +31,18 @@ class PosterImage extends ClickableComponent {
   }
 
   /**
-   * Clean up the poster image
-   *
-   * @method dispose
+   * Clean up and dispose of the `PosterImage`.
    */
   dispose() {
     this.player().off('posterchange', this.update);
     super.dispose();
   }
 
   /**
-   * Create the poster's image element
+   * Create the `PosterImage`s DOM element.
    *
    * @return {Element}
-   * @method createEl
+   *         The element that gets created.
    */
   createEl() {
     const el = Dom.createEl('div', {
@@ -61,11 +65,14 @@ class PosterImage extends ClickableComponent {
   }
 
   /**
-   * Event handler for updates to the player's poster source
+   * An {@link EventTarget~EventListener} for {@link Player#posterchange} events.
+   *
+   * @listens Player#posterchange
    *
-   * @method update
+   * @param {EventTarget~Event} [event]
+   *        The `Player#posterchange` event that triggered this function.
    */
-  update() {
+  update(event) {
     const url = this.player().poster();
 
     this.setSrc(url);
@@ -80,10 +87,10 @@ class PosterImage extends ClickableComponent {
   }
 
   /**
-   * Set the poster source depending on the display method
+   * Set the source of the `PosterImage` depending on the display method.
    *
-   * @param {String} url The URL to the poster source
-   * @method setSrc
+   * @param {String} url
+   *        The URL to the source for the `PosterImage`.
    */
   setSrc(url) {
     if (this.fallbackImg_) {
@@ -102,11 +109,17 @@ class PosterImage extends ClickableComponent {
   }
 
   /**
-   * Event handler for clicks on the poster image
+   * An {@link EventTarget~EventListener} for clicks on the `PosterImage`. See
+   * {@link ClickableComponent#handleClick} for instances where this will be triggered.
+   *
+   * @listens tap
+   * @listens click
+   * @listens keydown
    *
-   * @method handleClick
+   * @param {EventTarget~Event} event
+   +        The `click`, `tap` or `keydown` event that caused this function to be called.
    */
-  handleClick() {
+  handleClick(event) {
     // We don't want a click to trigger playback when controls are disabled
     // but CSS should be hiding the poster to prevent that from happening
     if (this.player_.paused()) {

src/js/tech/flash-rtmp.js

@@ -1,16 +1,56 @@
 /**
  * @file flash-rtmp.js
+ * @module flash-rtmp
+ */
+
+/**
+ * Add RTMP properties to the {@link Flash} Tech.
+ *
+ * @param {Flash} Flash
+ *        The flash tech class.
+ *
+ * @mixin FlashRtmpDecorator
  */
 function FlashRtmpDecorator(Flash) {
   Flash.streamingFormats = {
     'rtmp/mp4': 'MP4',
     'rtmp/flv': 'FLV'
   };
 
+  /**
+   * Join connection and stream with an ampersand.
+   *
+   * @param {string} connection
+   *        The connection string.
+   *
+   * @param {string} stream
+   *        The stream string.
+   */
   Flash.streamFromParts = function(connection, stream) {
     return connection + '&' + stream;
   };
 
+  /**
+   * The flash parts object that contains connection and stream info.
+   *
+   * @typedef {Object} Flash~PartsObject
+   *
+   * @property {string} connection
+   *           The connection string of a source, defaults to an empty string.
+   *
+   * @property {string} stream
+   *           The stream string of the source, defaults to an empty string.
+   */
+
+  /**
+   * Convert a source url into a stream and connection parts.
+   *
+   * @param {string} src
+   *        the source url
+   *
+   * @return {Flash~PartsObject}
+   *         The parts object that contains a connection and a stream
+   */
   Flash.streamToParts = function(src) {
     const parts = {
       connection: '',
@@ -44,14 +84,41 @@ function FlashRtmpDecorator(Flash) {
     return parts;
   };
 
+  /**
+   * Check if the source type is a streaming type.
+   *
+   * @param {string} srcType
+   *        The mime type to check.
+   *
+   * @return {boolean}
+   *          - True if the source type is a streaming type.
+   *          - False if the source type is not a streaming type.
+   */
   Flash.isStreamingType = function(srcType) {
     return srcType in Flash.streamingFormats;
   };
 
   // RTMP has four variations, any string starting
   // with one of these protocols should be valid
+
+  /**
+   * Regular expression used to check if the source is an rtmp source.
+   *
+   * @property
+   * @type {RegExp}
+   */
   Flash.RTMP_RE = /^rtmp[set]?:\/\//i;
 
+  /**
+   * Check if the source itself is a streaming type.
+   *
+   * @param {string} src
+   *        The url to the source.
+   *
+   * @return {boolean}
+   *          - True if the source url indicates that the source is streaming.
+   *          - False if the shource url indicates that the source url is not streaming.
+   */
   Flash.isStreamingSrc = function(src) {
     return Flash.RTMP_RE.test(src);
   };
@@ -63,9 +130,13 @@ function FlashRtmpDecorator(Flash) {
   Flash.rtmpSourceHandler = {};
 
   /**
-   * Check if Flash can play the given videotype
-   * @param  {String} type    The mimetype to check
-   * @return {String}         'probably', 'maybe', or '' (empty string)
+   * Check if Flash can play the given mime type.
+   *
+   * @param {string} type
+   *        The mime type to check
+   *
+   * @return {string}
+   *         'maybe', or '' (empty string)
    */
   Flash.rtmpSourceHandler.canPlayType = function(type) {
     if (Flash.isStreamingType(type)) {
@@ -77,9 +148,15 @@ function FlashRtmpDecorator(Flash) {
 
   /**
    * Check if Flash can handle the source natively
-   * @param  {Object} source  The source object
-   * @param  {Object} options The options passed to the tech
-   * @return {String}         'probably', 'maybe', or '' (empty string)
+   *
+   * @param {Object} source
+   *        The source object
+   *
+   * @param {Object} [options]
+   *        The options passed to the tech
+   *
+   * @return {string}
+   *         'maybe', or '' (empty string)
    */
   Flash.rtmpSourceHandler.canHandleSource = function(source, options) {
     const can = Flash.rtmpSourceHandler.canPlayType(source.type);
@@ -96,12 +173,16 @@ function FlashRtmpDecorator(Flash) {
   };
 
   /**
-   * Pass the source to the flash object
-   * Adaptive source handlers will have more complicated workflows before passing
-   * video data to the video element
-   * @param  {Object} source   The source object
-   * @param  {Flash}  tech     The instance of the Flash tech
-   * @param  {Object} options  The options to pass to the source
+   * Pass the source to the flash object.
+   *
+   * @param {Object} source
+   *        The source object
+   *
+   * @param {Flash} tech
+   *        The instance of the Flash tech
+   *
+   * @param {Object} [options]
+   *        The options to pass to the source
    */
   Flash.rtmpSourceHandler.handleSource = function(source, tech, options) {
     const srcParts = Flash.streamToParts(source.src);