Types overhaul

mister-ben · Dec 6, 2024 · 705df44 · 705df44
1 parent 53c6c3d
commit 705df44
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 47 deletions.
diff --git a/build/jsdoc-typeof-plugin.js b/build/jsdoc-typeof-plugin.js
@@ -3,6 +3,16 @@
  */
 exports.handlers = {
   jsdocCommentFound: event => {
+    const templateMatch = /@template {(.*)} ([A-Z])\n/.exec(event.comment || '');
+
+    if (templateMatch) {
+      const className = templateMatch[1];
+      const templateName = templateMatch[2];
+
+      event.comment = event.comment.replace(new RegExp(`{(.*\\b)(${templateName})(\\b.*)}`, 'g'), `{$1typeof ${className}$3}`);
+    }
+
+    // \{.*\bT\b.*\}
     event.comment = (event.comment || '').replace(/\{.*typeof\s+([^\s\|]+).*\}/g, typeExpression => {
       return typeExpression.replace(/typeof\s+([^\s\|\}]+)/g, (expression, className) => {
         return 'Class<' + className + '>';

diff --git a/src/js/component.js b/src/js/component.js
@@ -595,54 +595,22 @@ class Component {
 
     return iconContainer;
   }
-  // /**
-  //  * Add a child `Component` inside the current `Component`.
-  //  *
-  //  * @template {Component} T
-  //  * @param {string|T} 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.
-  //  *
-  //  * @param {number} [index=this.children_.length]
-  //  *        The index to attempt to add a child into.
-  //  *
-  //  *
-  //  * @return {T}
-  //  *         The `Component` that gets added as a child. When using a string the
-  //  *         `Component` will get created by this process.
-  //  */
-  /**
-   * @overload
-   * @param {typeof Component} child
-   * @param {Object} [options={}]
-   * @param {number} [index=this.children_.length]
-   * @return {typeof Component}
-   */
-  /**
-   * @overload
-   * @param {string} child
-   * @param {Object} [options={}]
-   * @param {number} [index=this.children_.length]
-   * @return {typeof Component}
-   */
   /**
    * Add a child `Component` inside the current `Component`.
    *
-   * @param {string|typeof Component} child
+   * @template {Component} T
+   * @param {string|T} child
    *        The name or instance of a child to add.
    *
-   * @param {Object} [options={}]
+   * @param {ComponentOptions} [options={}]
    *        The key/value store of options that will get passed to children of
    *        the child.
    *
    * @param {number} [index=this.children_.length]
    *        The index to attempt to add a child into.
    *
    *
-   * @return {typeof Component}
+   * @return {T}
    *         The `Component` that gets added as a child. When using a string the
    *         `Component` will get created by this process.
    */

diff --git a/src/js/player.js b/src/js/player.js
@@ -58,6 +58,7 @@ import './tech/html5.js';
 
 /** @import { TimeRange } from './utils/time' */
 /** @import HtmlTrackElement from './tracks/html-track-element' */
+/** @import { SourceObject } from './tech/tech' */
 
 /**
  * @callback PlayerReadyCallback
@@ -1567,7 +1568,7 @@ class Player extends Component {
    *         in the current `currentSources` cache.
    *
    *
-   * @param {Tech~SourceObject} srcObj
+   * @param {SourceObject} srcObj
    *        A string or object source to update our caches to.
    */
   updateSourceCaches_(srcObj = '') {
@@ -3533,7 +3534,7 @@ class Player extends Component {
   /**
    * Executes source setting and getting logic
    *
-   * @param {Tech~SourceObject|Tech~SourceObject[]|string} [source]
+   * @param {SourceObject|SourceObject[]|string} [source]
    *        A SourceObject, an array of SourceObjects, or a string referencing
    *        a URL to a media source. It is _highly recommended_ that an object
    *        or array of objects is used here, so that source selection
@@ -3644,7 +3645,7 @@ class Player extends Component {
   /**
    * Get or set the video source.
    *
-   * @param {Tech~SourceObject|Tech~SourceObject[]|string} [source]
+   * @param {SourceObject|SourceObject[]|string} [source]
    *        A SourceObject, an array of SourceObjects, or a string referencing
    *        a URL to a media source. It is _highly recommended_ that an object
    *        or array of objects is used here, so that source selection
@@ -3664,7 +3665,7 @@ class Player extends Component {
    * Set the source object on the tech, returns a boolean that indicates whether
    * there is a tech that can play the source or not
    *
-   * @param {Tech~SourceObject} source
+   * @param {SourceObject} source
    *        The source object to set on the Tech
    *
    * @return {boolean}
@@ -3869,7 +3870,7 @@ class Player extends Component {
   /**
    * Returns all of the current source objects.
    *
-   * @return {Tech~SourceObject[]}
+   * @return {SourceObject[]}
    *         The current source objects
    */
   currentSources() {
@@ -3887,7 +3888,7 @@ class Player extends Component {
   /**
    * Returns the current source object.
    *
-   * @return {Tech~SourceObject}
+   * @return {SourceObject}
    *         The current source object
    */
   currentSource() {
@@ -5132,7 +5133,7 @@ class Player extends Component {
    * @property {string} [poster]
    *           URL to an image that will display before playback.
    *
-   * @property {Tech~SourceObject|Tech~SourceObject[]|string} [src]
+   * @property {SourceObject|SourceObject[]|string} [src]
    *           A single source object, an array of source objects, or a string
    *           referencing a URL to a media source. It is _highly recommended_
    *           that an object or array of objects is used here, so that source

diff --git a/src/js/tech/tech.js b/src/js/tech/tech.js
@@ -19,18 +19,24 @@ import * as Guid from '../utils/guid.js';
 /** @import { TimeRange } from '../utils/time' */
 
 /**
- * An Object containing a structure like: `{src: 'url', type: 'mimetype'}` or string
- * that just contains the src url alone.
+ * An Object containing a structure like: `{src: 'url', type: 'mimetype'}`
  * * `var SourceObject = {src: 'http://ex.com/video.mp4', type: 'video/mp4'};`
-   * `var SourceString = 'http://example.com/some-video.mp4';`
  *
- * @typedef {Object|string} SourceObject
+ * @typedef {Object} SourceObject
  *
  * @property {string} src
  *           The url to the source
  *
  * @property {string} type
  *           The mime type of the source
+ *
+ * @property {boolean} [withCredentials]
+ * @property {boolean} [allowSeeksWithinUnsafeLiveWindow]
+ * @property {Array} [customTagParsers]
+ * @property {Array} [customTagMappers]
+ * @property {boolean} [cacheEncryptionKeys]
+ * @property {boolean} [useForcedSubtitles]
+ * @property {Object} [keySystems]
  */
 
 /**