From 2e9625363223ae86dfc56306e7d7c8843b405030 Mon Sep 17 00:00:00 2001
From: Grzegorz Blaszczyk <gjanblaszczyk@gmail.com>
Date: Tue, 24 Jan 2023 22:07:30 +0100
Subject: [PATCH] fix: Improves types for registerPlugin and getPlugin (#8058)

* fix: improves types for registerPlugin and getPlugin

* fix: corrects parameter type for registerPlugin

* docs(fix): add support for {typeof class} expression

* chore: move js-doc-typeof-plugin to build dir
---
 .jsdoc.json                  |  2 +-
 build/jsdoc-typeof-plugin.js | 12 ++++++++++++
 src/js/plugin.js             |  8 ++++----
 3 files changed, 17 insertions(+), 5 deletions(-)
 create mode 100644 build/jsdoc-typeof-plugin.js

diff --git a/.jsdoc.json b/.jsdoc.json
index b17db1e618..e518998c93 100644
--- a/.jsdoc.json
+++ b/.jsdoc.json
@@ -33,7 +33,7 @@
       "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css"
     ]
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": ["plugins/markdown", "build/jsdoc-typeof-plugin"],
   "markdown": {
     "tags": ["example"],
     "idInHeadings": true
diff --git a/build/jsdoc-typeof-plugin.js b/build/jsdoc-typeof-plugin.js
new file mode 100644
index 0000000000..70564825a1
--- /dev/null
+++ b/build/jsdoc-typeof-plugin.js
@@ -0,0 +1,12 @@
+/**
+ * The jsdoc plugin that will convert types like {typeof ClassName} into {Class<ClassName>}
+ */
+exports.handlers = {
+  jsdocCommentFound: event => {
+    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/plugin.js b/src/js/plugin.js
index 835c10a6ba..d55698ad3c 100644
--- a/src/js/plugin.js
+++ b/src/js/plugin.js
@@ -52,7 +52,7 @@ const pluginExists = (name) => pluginStorage.hasOwnProperty(name);
  * @param   {string} name
  *          The name of a plugin.
  *
- * @return {Function|undefined}
+ * @return {typeof Plugin|Function|undefined}
  *          The plugin (or undefined).
  */
 const getPlugin = (name) => pluginExists(name) ? pluginStorage[name] : undefined;
@@ -336,10 +336,10 @@ class Plugin {
    *          must not match an existing plugin or a method on the `Player`
    *          prototype.
    *
-   * @param   {Function} plugin
+   * @param   {typeof Plugin|Function} plugin
    *          A sub-class of `Plugin` or a function for basic plugins.
    *
-   * @return {Function}
+   * @return {typeof Plugin|Function}
    *          For advanced plugins, a factory function for that plugin. For
    *          basic plugins, a wrapper function that initializes the plugin.
    */
@@ -444,7 +444,7 @@ class Plugin {
  * @param    {string} name
  *           The name of a plugin.
  *
- * @returns  {Function|undefined}
+ * @returns  {typeof Plugin|Function|undefined}
  *           The plugin (or `undefined`).
  */
 Plugin.getPlugin = getPlugin;