Refactor JSDocs for events

src/core/tags.js

@@ -7,6 +7,40 @@ import { EventHandler } from './event-handler.js';
  * @augments EventHandler
  */
 class Tags extends EventHandler {
+    /**
+     * Fired for each individual tag that is added.
+     *
+     * @event
+     * @example
+     * tags.on('add', (tag, parent) => {
+     *    console.log(`${tag} added to ${parent.name}`);
+     * });
+     */
+    static EVENT_ADD = 'add';
+
+    /**
+     * Fired for each individual tag that is removed.
+     *
+     * @event
+     * @example
+     * tags.on('remove', (tag, parent) => {
+     *   console.log(`${tag} removed from ${parent.name}`);
+     * });
+     */
+    static EVENT_REMOVE = 'remove';
+
+    /**
+     * Fired when tags have been added or removed. It will fire once on bulk changes, while `add`
+     * and `remove` will fire on each tag operation.
+     *
+     * @event
+     * @example
+     * tags.on('change', (parent) => {
+     *    console.log(`Tags changed on ${parent.name}`);
+     * });
+     */
+    static EVENT_CHANGE = 'change';
+
     /** @private */
     _index = {};
 
@@ -24,26 +58,6 @@ class Tags extends EventHandler {
         this._parent = parent;
     }
 
-    /**
-     * @event Tags#add
-     * @param {string} tag - Name of a tag added to a set.
-     * @param {object} parent - Parent object who tags belong to.
-     */
-
-    /**
-     * @event Tags#remove
-     * @param {string} tag - Name of a tag removed from a set.
-     * @param {object} parent - Parent object who tags belong to.
-     */
-
-    /**
-     * Fires when tags have been added or removed. It will fire once on bulk changes, while
-     * `add`/`remove` will fire on each tag operation.
-     *
-     * @event Tags#change
-     * @param {object} [parent] - Parent object who tags belong to.
-     */
-
     /**
      * Add a tag, duplicates are ignored. Can be array or comma separated arguments for multiple tags.
      *

src/framework/asset/asset-registry.js

@@ -34,182 +34,171 @@ import { Asset } from './asset.js';
  */
 class AssetRegistry extends EventHandler {
     /**
-     * @type {Set<Asset>}
-     * @private
-     */
-    _assets = new Set();
-
-    /**
-     * @type {Map<number, Asset>}
-     * @private
-     */
-    _idToAsset = new Map();
-
-    /**
-     * @type {Map<string, Asset>}
-     * @private
-     */
-    _urlToAsset = new Map();
-
-    /**
-     * @type {Map<string, Set<Asset>>}
-     * @private
-     */
-    _nameToAsset = new Map();
-
-    /**
-     * Index for looking up by tags.
+     * Fired when an asset completes loading. This event is available in three forms. They are as
+     * follows:
      *
-     * @private
-     */
-    _tags = new TagsCache('_id');
-
-    /**
-     * A URL prefix that will be added to all asset loading requests.
+     * 1. `load` - Fired when any asset finishes loading.
+     * 2. `load:[id]` - Fired when a specific asset has finished loading, where `[id]` is the
+     * unique id of the asset.
+     * 3. `load:url:[url]` - Fired when an asset finishes loading whose URL matches `[url]`, where
+     * `[url]` is the URL of the asset.
      *
-     * @type {string|null}
+     * @event
+     * @example
+     * app.assets.on('load', (asset) => {
+     *     console.log(`Asset loaded: ${asset.name}`);
+     * });
+     * @example
+     * const id = 123456;
+     * const asset = app.assets.get(id);
+     * app.assets.on('load:' + id, (asset) => {
+     *     console.log(`Asset loaded: ${asset.name}`);
+     * });
+     * app.assets.load(asset);
+     * @example
+     * const id = 123456;
+     * const asset = app.assets.get(id);
+     * app.assets.on('load:url:' + asset.file.url, (asset) => {
+     *     console.log(`Asset loaded: ${asset.name}`);
+     * });
+     * app.assets.load(asset);
      */
-    prefix = null;
+    static EVENT_LOAD = 'load';
 
     /**
-     * Create an instance of an AssetRegistry.
+     * Fired when an asset is added to the registry. This event is available in three forms. They
+     * are as follows:
      *
-     * @param {import('../handlers/loader.js').ResourceLoader} loader - The ResourceLoader used to
-     * load the asset files.
-     */
-    constructor(loader) {
-        super();
-
-        this._loader = loader;
-    }
-
-    /**
-     * Fired when an asset completes loading.
+     * 1. `add` - Fired when any asset is added to the registry.
+     * 2. `add:[id]` - Fired when an asset is added to the registry, where `[id]` is the unique id
+     * of the asset.
+     * 3. `add:url:[url]` - Fired when an asset is added to the registry and matches the URL
+     * `[url]`, where `[url]` is the URL of the asset.
      *
-     * @event AssetRegistry#load
-     * @param {Asset} asset - The asset that has just loaded.
+     * @event
+     * @example
+     * app.assets.on('add', (asset) => {
+     *    console.log(`Asset added: ${asset.name}`);
+     * });
+     * @example
+     * const id = 123456;
+     * app.assets.on('add:' + id, (asset) => {
+     *    console.log(`Asset added: ${asset.name}`);
+     * });
      * @example
-     * app.assets.on("load", function (asset) {
-     *     console.log("asset loaded: " + asset.name);
+     * const id = 123456;
+     * const asset = app.assets.get(id);
+     * app.assets.on('add:url:' + asset.file.url, (asset) => {
+     *    console.log(`Asset added: ${asset.name}`);
      * });
      */
+    static EVENT_ADD = 'add';
 
     /**
-     * Fired when an asset completes loading.
+     * Fired when an asset is removed from the registry. This event is available in three forms.
+     * They are as follows:
      *
-     * @event AssetRegistry#load:[id]
-     * @param {Asset} asset - The asset that has just loaded.
+     * 1. `remove` - Fired when any asset is removed from the registry.
+     * 2. `remove:[id]` - Fired when an asset is removed from the registry, where `[id]` is the
+     * unique id of the asset.
+     * 3. `remove:url:[url]` - Fired when an asset is removed from the registry and matches the
+     * URL `[url]`, where `[url]` is the URL of the asset.
+     *
+     * @event
+     * @param {Asset} asset - The asset that was removed.
+     * @example
+     * app.assets.on('remove', (asset) => {
+     *    console.log(`Asset removed: ${asset.name}`);
+     * });
+     * @example
+     * const id = 123456;
+     * app.assets.on('remove:' + id, (asset) => {
+     *    console.log(`Asset removed: ${asset.name}`);
+     * });
      * @example
      * const id = 123456;
      * const asset = app.assets.get(id);
-     * app.assets.on("load:" + id, function (asset) {
-     *     console.log("asset loaded: " + asset.name);
+     * app.assets.on('remove:url:' + asset.file.url, (asset) => {
+     *    console.log(`Asset removed: ${asset.name}`);
      * });
-     * app.assets.load(asset);
      */
+    static EVENT_REMOVE = 'remove';
 
     /**
-     * Fired when an asset completes loading.
+     * Fired when an error occurs during asset loading. This event is available in two forms. They
+     * are as follows:
+     *
+     * 1. `error` - Fired when any asset reports an error in loading.
+     * 2. `error:[id]` - Fired when an asset reports an error in loading, where `[id]` is the
+     * unique id of the asset.
      *
-     * @event AssetRegistry#load:url:[url]
-     * @param {Asset} asset - The asset that has just loaded.
+     * @event
      * @example
      * const id = 123456;
      * const asset = app.assets.get(id);
-     * app.assets.on("load:url:" + asset.file.url, function (asset) {
-     *     console.log("asset loaded: " + asset.name);
+     * app.assets.on('error', (err, asset) => {
+     *     console.error(err);
      * });
      * app.assets.load(asset);
-     */
-
-    /**
-     * Fired when an asset is added to the registry.
-     *
-     * @event AssetRegistry#add
-     * @param {Asset} asset - The asset that was added.
      * @example
-     * app.assets.on("add", function (asset) {
-     *     console.log("New asset added: " + asset.name);
+     * const id = 123456;
+     * const asset = app.assets.get(id);
+     * app.assets.on('error:' + id, (err, asset) => {
+     *     console.error(err);
      * });
+     * app.assets.load(asset);
      */
+    static EVENT_ERROR = 'error';
 
     /**
-     * Fired when an asset is added to the registry.
-     *
-     * @event AssetRegistry#add:[id]
-     * @param {Asset} asset - The asset that was added.
-     * @example
-     * const id = 123456;
-     * app.assets.on("add:" + id, function (asset) {
-     *     console.log("Asset 123456 loaded");
-     * });
+     * @type {Set<Asset>}
+     * @private
      */
+    _assets = new Set();
 
     /**
-     * Fired when an asset is added to the registry.
-     *
-     * @event AssetRegistry#add:url:[url]
-     * @param {Asset} asset - The asset that was added.
+     * @type {Map<number, Asset>}
+     * @private
      */
+    _idToAsset = new Map();
 
     /**
-     * Fired when an asset is removed from the registry.
-     *
-     * @event AssetRegistry#remove
-     * @param {Asset} asset - The asset that was removed.
-     * @example
-     * app.assets.on("remove", function (asset) {
-     *     console.log("Asset removed: " + asset.name);
-     * });
+     * @type {Map<string, Asset>}
+     * @private
      */
+    _urlToAsset = new Map();
 
     /**
-     * Fired when an asset is removed from the registry.
-     *
-     * @event AssetRegistry#remove:[id]
-     * @param {Asset} asset - The asset that was removed.
-     * @example
-     * const id = 123456;
-     * app.assets.on("remove:" + id, function (asset) {
-     *     console.log("Asset removed: " + asset.name);
-     * });
+     * @type {Map<string, Set<Asset>>}
+     * @private
      */
+    _nameToAsset = new Map();
 
     /**
-     * Fired when an asset is removed from the registry.
+     * Index for looking up by tags.
      *
-     * @event AssetRegistry#remove:url:[url]
-     * @param {Asset} asset - The asset that was removed.
+     * @private
      */
+    _tags = new TagsCache('_id');
 
     /**
-     * Fired when an error occurs during asset loading.
+     * A URL prefix that will be added to all asset loading requests.
      *
-     * @event AssetRegistry#error
-     * @param {string} err - The error message.
-     * @param {Asset} asset - The asset that generated the error.
-     * @example
-     * const id = 123456;
-     * const asset = app.assets.get(id);
-     * app.assets.on("error", function (err, asset) {
-     *     console.error(err);
-     * });
-     * app.assets.load(asset);
+     * @type {string|null}
      */
+    prefix = null;
 
     /**
-     * Fired when an error occurs during asset loading.
+     * Create an instance of an AssetRegistry.
      *
-     * @event AssetRegistry#error:[id]
-     * @param {Asset} asset - The asset that generated the error.
-     * @example
-     * const id = 123456;
-     * const asset = app.assets.get(id);
-     * app.assets.on("error:" + id, function (err, asset) {
-     *     console.error(err);
-     * });
-     * app.assets.load(asset);
+     * @param {import('../handlers/loader.js').ResourceLoader} loader - The ResourceLoader used to
+     * load the asset files.
      */
+    constructor(loader) {
+        super();
+
+        this._loader = loader;
+    }
 
     /**
      * Create a filtered list of assets from the registry.