refactor(types): Type enhancements

build/jsdoc-typeof-plugin.js

@@ -1,8 +1,19 @@
 /**
- * The jsdoc plugin that will convert types like {typeof ClassName} into {Class<ClassName>}
+ * The jsdoc plugin to transform some typescript jsdoc to actual jsdoc, so doc generation works.
  */
 exports.handlers = {
   jsdocCommentFound: event => {
+    // @template {ClassName} T ; {T} -> {typeof ClassName}
+    const templateMatch = /@template {(typeof )?(.*)} ([A-Z])\n/.exec(event.comment || '');
+
+    if (templateMatch) {
+      const className = templateMatch[2];
+      const templateName = templateMatch[3];
+
+      event.comment = event.comment.replace(new RegExp(`{(.*\\b)(${templateName})(\\b.*)}`, 'g'), `{$1typeof ${className}$3}`);
+    }
+
+    // {typeof ClassName} -> {Class<ClassName>}
     event.comment = (event.comment || '').replace(/\{.*typeof\s+([^\s\|]+).*\}/g, typeExpression => {
       return typeExpression.replace(/typeof\s+([^\s\|\}]+)/g, (expression, className) => {
         return 'Class<' + className + '>';

package.json

@@ -124,7 +124,7 @@
     "humanize-duration": "^3.26.0",
     "husky": "^1.3.1",
     "is-ci": "^3.0.0",
-    "jsdoc": "^4.0.3",
+    "jsdoc": "^4.0.4",
     "karma": "^6.4.3",
     "lint-staged": "^10.5.4",
     "markdown-table": "^1.1.3",
@@ -160,7 +160,7 @@
     "shelljs": "^0.8.5",
     "shx": "^0.3.2",
     "sinon": "^11.1.1",
-    "typescript": "^5.5.2",
+    "typescript": "^5.7.2",
     "uglify-js": "^3.19.0",
     "unified": "^7.0.2",
     "videojs-generate-karma-config": "^8.1.0",

src/js/component.js

@@ -23,6 +23,18 @@ import {merge} from './utils/obj.js';
  * @returns  {void}
  */
 
+/**
+  * @typedef {Object} ComponentOptions
+  * @property {Object[]}    [children]
+  * @property {string}      [classname]
+  * @property {boolean}     [initChildren]
+  * @property {boolean}     [reportTouchActivity]
+  * @property {string}      [name]
+  * @property {boolean}     [createEl=true]
+  * @property {HTMLElement} [el]
+  * @property {boolean}     [evented]
+  */
+
 /**
  * Base class for all UI Components.
  * Components are UI objects which represent both a javascript object and an element
@@ -39,17 +51,9 @@ class Component {
    * @param {Player} player
    *        The `Player` that this class should be attached to.
    *
-   * @param {Object} [options]
+   * @param {ComponentOptions} [options]
    *        The key/value store of component options.
    *
-   * @param {Object[]} [options.children]
-   *        An array of children objects to initialize this component with. Children objects have
-   *        a name property that will be used if more than one component of the same type needs to be
-   *        added.
-   *
-   * @param  {string} [options.className]
-   *         A class or space separated list of classes to add the component
-   *
    * @param {ReadyCallback} [ready]
    *        Function that gets called when the `Component` is ready.
    */
@@ -589,22 +593,22 @@ class Component {
 
     return iconContainer;
   }
-
   /**
    * Add a child `Component` inside the current `Component`.
    *
-   * @param {string|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 {Component}
+   * @return {T}
    *         The `Component` that gets added as a child. When using a string the
    *         `Component` will get created by this process.
    */
@@ -1242,7 +1246,7 @@ class Component {
    * An object that contains width and height values of the `Component`s
    * computed style. Uses `window.getComputedStyle`.
    *
-   * @typedef {Object} Component~DimensionObject
+   * @typedef {Object} DimensionObject
    *
    * @property {number} width
    *           The width of the `Component`s computed style.
@@ -1257,7 +1261,7 @@ class Component {
    *
    * Uses `window.getComputedStyle`.
    *
-   * @return {Component~DimensionObject}
+   * @return {DimensionObject}
    *         The computed dimensions of the component's element.
    */
   currentDimensions() {
@@ -1967,6 +1971,8 @@ class Component {
   }
 
   /**
+   * @template {typeof Component} T
+   *
    * Register a `Component` with `videojs` given the name and the component.
    *
    * > NOTE: {@link Tech}s should not be registered as a `Component`. {@link Tech}s
@@ -1979,10 +1985,10 @@ class Component {
    * @param {string} name
    *        The name of the `Component` to register.
    *
-   * @param {Component} ComponentToRegister
+   * @param {T} ComponentToRegister
    *        The `Component` class to register.
    *
-   * @return {Component}
+   * @return {T}
    *         The `Component` that was registered.
    */
   static registerComponent(name, ComponentToRegister) {

src/js/fullscreen-api.js

@@ -8,6 +8,14 @@ import document from 'global/document';
  * Store the browser-specific methods for the fullscreen API.
  *
  * @type {Object}
+ * @property {string} requestFullscreen
+ * @property {string} exitFullscreen
+ * @property {string} fullscreenElement
+ * @property {string} fullscreenEnabled
+ * @property {string} fullscreenchange
+ * @property {string} fullscreenerror
+ * @property {string} fullscreen
+ * @property {boolean} prefixed
  * @see [Specification]{@link https://fullscreen.spec.whatwg.org}
  * @see [Map Approach From Screenfull.js]{@link https://github.com/sindresorhus/screenfull.js}
  */