From 11ec2d29e05be73cd93b2273eced05e622d64a3a Mon Sep 17 00:00:00 2001 From: Harrison Deng Date: Mon, 18 Apr 2022 01:31:27 -0500 Subject: [PATCH] Added JSDoc linting again. --- audioshowkit/.eslintrc.json | 8 +- audioshowkit/package-lock.json | 136 ++++++++++++++++++ audioshowkit/package.json | 3 +- audioshowkit/src/player/PlaylistSong.js | 18 +-- audioshowkit/src/player/SongPlayer.js | 22 +-- audioshowkit/src/player/SongPlaylist.js | 5 +- .../src/player/VisualizedSongPlayer.js | 6 +- audioshowkit/src/visualization/Visualizer.js | 4 +- .../visualization/VisualizerUpdateManager.js | 6 +- 9 files changed, 177 insertions(+), 31 deletions(-) diff --git a/audioshowkit/.eslintrc.json b/audioshowkit/.eslintrc.json index b1f159f..01573af 100644 --- a/audioshowkit/.eslintrc.json +++ b/audioshowkit/.eslintrc.json @@ -5,7 +5,8 @@ }, "extends": [ "eslint:recommended", - "plugin:import/recommended" + "plugin:import/recommended", + "plugin:jsdoc/recommended" ], "parserOptions": { "ecmaVersion": "latest", @@ -32,5 +33,8 @@ "error", "ignorePackages" ] - } + }, + "plugins": [ + "jsdoc" + ] } \ No newline at end of file diff --git a/audioshowkit/package-lock.json b/audioshowkit/package-lock.json index a4eab21..26c4de5 100644 --- a/audioshowkit/package-lock.json +++ b/audioshowkit/package-lock.json @@ -19,6 +19,7 @@ "esdoc-standard-plugin": "^1.0.0", "eslint": "^8.13.0", "eslint-plugin-import": "^2.26.0", + "eslint-plugin-jsdoc": "^39.2.2", "eslint-webpack-plugin": "^3.1.1", "mocha": "^9.2.2", "mocha-junit-reporter": "^2.0.2", @@ -1882,6 +1883,20 @@ "node": ">=10.0.0" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.23.6", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.23.6.tgz", + "integrity": "sha512-cCtumxG+qrYORGeOkDQ58GtSt/bb2XiP9GC0x2YduoUEX2EmBQ48FtoZMUs+8wiIdTDN1izUiRUD2FDu+p+Lvg==", + "dev": true, + "dependencies": { + "comment-parser": "1.3.1", + "esquery": "^1.4.0", + "jsdoc-type-pratt-parser": "~2.2.5" + }, + "engines": { + "node": "^12 || ^14 || ^16 || ^17" + } + }, "node_modules/@eslint/eslintrc": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.2.1.tgz", @@ -3070,6 +3085,15 @@ "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", "dev": true }, + "node_modules/comment-parser": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.1.tgz", + "integrity": "sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA==", + "dev": true, + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/commondir": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz", @@ -4167,6 +4191,27 @@ "integrity": "sha1-VgiurfwAvmwpAd9fmGF4jeDVl8g=", "dev": true }, + "node_modules/eslint-plugin-jsdoc": { + "version": "39.2.2", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.2.2.tgz", + "integrity": "sha512-ybkvja0p9JRzHEd2ST9h+Z47DLOuPyXpeb6r18/zKHdMmggPU1J0/zl+F0phea8ze9rMxi42MJVmGXi2NZ7PpA==", + "dev": true, + "dependencies": { + "@es-joy/jsdoccomment": "~0.23.1", + "comment-parser": "1.3.1", + "debug": "^4.3.4", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.4.0", + "semver": "^7.3.7", + "spdx-expression-parse": "^3.0.1" + }, + "engines": { + "node": "^14 || ^16 || ^17" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, "node_modules/eslint-scope": { "version": "7.1.1", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.1.1.tgz", @@ -5414,6 +5459,15 @@ "dev": true, "optional": true }, + "node_modules/jsdoc-type-pratt-parser": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-2.2.5.tgz", + "integrity": "sha512-2a6eRxSxp1BW040hFvaJxhsCMI9lT8QB8t14t+NY5tC5rckIR0U9cr2tjOeaFirmEOy6MHvmJnY7zTBHq431Lw==", + "dev": true, + "engines": { + "node": ">=12.0.0" + } + }, "node_modules/jsdom": { "version": "7.2.2", "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-7.2.2.tgz", @@ -6856,6 +6910,28 @@ "source-map": "^0.6.0" } }, + "node_modules/spdx-exceptions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz", + "integrity": "sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A==", + "dev": true + }, + "node_modules/spdx-expression-parse": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz", + "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==", + "dev": true, + "dependencies": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/spdx-license-ids": { + "version": "3.0.11", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.11.tgz", + "integrity": "sha512-Ctl2BrFiM0X3MANYgj3CkygxhRmr9mi6xhejbdO960nF6EDJApTYpn0BQnDKlnNBULKiCN1n3w9EBkHK8ZWg+g==", + "dev": true + }, "node_modules/sshpk": { "version": "1.17.0", "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.17.0.tgz", @@ -8993,6 +9069,17 @@ "integrity": "sha512-dBVuXR082gk3jsFp7Rd/JI4kytwGHecnCoTtXFb7DB6CNHp4rg5k1bhg0nWdLGLnOV71lmDzGQaLMy8iPLY0pw==", "dev": true }, + "@es-joy/jsdoccomment": { + "version": "0.23.6", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.23.6.tgz", + "integrity": "sha512-cCtumxG+qrYORGeOkDQ58GtSt/bb2XiP9GC0x2YduoUEX2EmBQ48FtoZMUs+8wiIdTDN1izUiRUD2FDu+p+Lvg==", + "dev": true, + "requires": { + "comment-parser": "1.3.1", + "esquery": "^1.4.0", + "jsdoc-type-pratt-parser": "~2.2.5" + } + }, "@eslint/eslintrc": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.2.1.tgz", @@ -9962,6 +10049,12 @@ "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", "dev": true }, + "comment-parser": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.1.tgz", + "integrity": "sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA==", + "dev": true + }, "commondir": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz", @@ -10848,6 +10941,21 @@ } } }, + "eslint-plugin-jsdoc": { + "version": "39.2.2", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.2.2.tgz", + "integrity": "sha512-ybkvja0p9JRzHEd2ST9h+Z47DLOuPyXpeb6r18/zKHdMmggPU1J0/zl+F0phea8ze9rMxi42MJVmGXi2NZ7PpA==", + "dev": true, + "requires": { + "@es-joy/jsdoccomment": "~0.23.1", + "comment-parser": "1.3.1", + "debug": "^4.3.4", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.4.0", + "semver": "^7.3.7", + "spdx-expression-parse": "^3.0.1" + } + }, "eslint-scope": { "version": "7.1.1", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.1.1.tgz", @@ -11770,6 +11878,12 @@ "dev": true, "optional": true }, + "jsdoc-type-pratt-parser": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-2.2.5.tgz", + "integrity": "sha512-2a6eRxSxp1BW040hFvaJxhsCMI9lT8QB8t14t+NY5tC5rckIR0U9cr2tjOeaFirmEOy6MHvmJnY7zTBHq431Lw==", + "dev": true + }, "jsdom": { "version": "7.2.2", "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-7.2.2.tgz", @@ -12871,6 +12985,28 @@ "source-map": "^0.6.0" } }, + "spdx-exceptions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz", + "integrity": "sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A==", + "dev": true + }, + "spdx-expression-parse": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz", + "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==", + "dev": true, + "requires": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "spdx-license-ids": { + "version": "3.0.11", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.11.tgz", + "integrity": "sha512-Ctl2BrFiM0X3MANYgj3CkygxhRmr9mi6xhejbdO960nF6EDJApTYpn0BQnDKlnNBULKiCN1n3w9EBkHK8ZWg+g==", + "dev": true + }, "sshpk": { "version": "1.17.0", "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.17.0.tgz", diff --git a/audioshowkit/package.json b/audioshowkit/package.json index 2ba7d2c..81d5a2e 100644 --- a/audioshowkit/package.json +++ b/audioshowkit/package.json @@ -28,6 +28,7 @@ "esdoc-standard-plugin": "^1.0.0", "eslint": "^8.13.0", "eslint-plugin-import": "^2.26.0", + "eslint-plugin-jsdoc": "^39.2.2", "eslint-webpack-plugin": "^3.1.1", "mocha": "^9.2.2", "mocha-junit-reporter": "^2.0.2", @@ -36,4 +37,4 @@ "webpack-cli": "^4.9.2", "webpack-merge": "^5.8.0" } -} \ No newline at end of file +} diff --git a/audioshowkit/src/player/PlaylistSong.js b/audioshowkit/src/player/PlaylistSong.js index 94e5021..380e77d 100644 --- a/audioshowkit/src/player/PlaylistSong.js +++ b/audioshowkit/src/player/PlaylistSong.js @@ -26,7 +26,7 @@ export default class PlayListSong { } /** - * @typedef {function} AudioEventCallback + * @typedef {Function} AudioEventCallback * @param {HTMLAudioElement} audio */ @@ -55,31 +55,27 @@ export default class PlayListSong { } /** - * - * The name of the song to be displayed. + * @returns {string} The name of the song to be displayed. */ get displayName() { return this.#displayName; } /** - * - * The author of the song. + * @returns {string} The author of the song. */ get author() { return this.#author; } /** - * - * The url at which the file for this song can be found. + * @returns {string} The url at which the file for this song can be found. */ get url() { return this.#url; } /** - * * @returns {boolean} true if and only if there is audio data that is either already loaded or is being loaded. */ isAudioInstantiated() { @@ -109,7 +105,7 @@ export default class PlayListSong { /** * - * The volume on a scale of 0 to 1. + * @returns {number} The volume on a scale of 0 to 1. */ get volume() { return this.fetchAudio().volume; @@ -124,7 +120,7 @@ export default class PlayListSong { } /** * - * The number of seconds into the song. + * @returns {number} The number of seconds into the song. */ get currentTime() { return this.fetchAudio().currentTime; @@ -140,7 +136,7 @@ export default class PlayListSong { /** * - * The duration of the song. + * @returns {number} The duration of the song. */ get duration() { return this.fetchAudio().duration; diff --git a/audioshowkit/src/player/SongPlayer.js b/audioshowkit/src/player/SongPlayer.js index ef8c3ea..7d48f96 100644 --- a/audioshowkit/src/player/SongPlayer.js +++ b/audioshowkit/src/player/SongPlayer.js @@ -1,4 +1,6 @@ import "../styles/songplayer.css"; +import PlayListSong from "./PlaylistSong.js"; +import SongPlaylist from "./SongPlaylist.js"; /** * A player that keeps track of global properties for playback as well as traversing a playlist. Additionally keeps track of song audio data and attempts to reduce memory usage when possible. @@ -41,8 +43,9 @@ export default class SongPlayer { } /** - * * The current playlist of songs that this player is in charge of. + * + * @returns {SongPlaylist} The song playlist this player is currently using. */ get playlist() { return this.#playlist; @@ -100,7 +103,7 @@ export default class SongPlayer { /** * - * The current song's index in the playlist. + * @returns {number} The current song's index in the playlist. */ get currentSongIndex() { return this.#current; @@ -115,6 +118,9 @@ export default class SongPlayer { }); } + /** + * Pauses the current playing song (if there is one playing). + */ pauseCurrent() { console.log("Pausing."); this.currentSong.fetchAudio().pause(); @@ -143,7 +149,7 @@ export default class SongPlayer { /** * - * The current volume of the player represented by a number between 0 and 1 inclusive. + * @returns {number} The current volume of the player represented by a number between 0 and 1 inclusive. */ get volume() { return this.#volume; @@ -165,7 +171,7 @@ export default class SongPlayer { /** * - * How many seconds into the audio track has been played in seconds. + * @returns {number} How many seconds into the audio track has been played in seconds. */ get currentPosition() { return this.currentSong.fetchAudio().currentTime; @@ -173,7 +179,7 @@ export default class SongPlayer { /** * - * The total length of the song, or NaN if this information has not loaded yet. + * @returns {number} The total length of the song, or NaN if this information has not loaded yet. */ get currentDuration() { return this.currentSong.fetchAudio().duration; @@ -227,14 +233,14 @@ export default class SongPlayer { } /** - * The current {@link PlaylistSong}. + * @returns {PlayListSong} The current playlist being used. */ get currentSong() { return this.#playlist.songAtIndex(this.#current); } /** - * @typedef {function} changeListener + * @typedef {Function} changeListener * @param {*} old the previous value. * @param {*} current the the current (new) value. */ @@ -348,7 +354,7 @@ export default class SongPlayer { } /** - * If the player is playing any songs right now. + * @returns {boolean} If the player is playing any songs right now. */ get playing() { return this.currentSong.isAudioInstantiated() && !this.currentSong.fetchAudio().paused; diff --git a/audioshowkit/src/player/SongPlaylist.js b/audioshowkit/src/player/SongPlaylist.js index e353259..c5ad755 100644 --- a/audioshowkit/src/player/SongPlaylist.js +++ b/audioshowkit/src/player/SongPlaylist.js @@ -1,7 +1,7 @@ import PlaylistSong from "./PlaylistSong.js"; /** - * A playlist that holds a multitude of songs in the form of {@see PlaylistSong}. + * A playlist that holds a multitude of songs in the form of {@link PlaylistSong}. */ export default class SongPlaylist { #list = []; @@ -17,8 +17,7 @@ export default class SongPlaylist { } /** - * - * The name of the playlist. + * @returns {string} The name of the playlist. */ get name() { return this.#name; diff --git a/audioshowkit/src/player/VisualizedSongPlayer.js b/audioshowkit/src/player/VisualizedSongPlayer.js index f656f12..f09e70a 100644 --- a/audioshowkit/src/player/VisualizedSongPlayer.js +++ b/audioshowkit/src/player/VisualizedSongPlayer.js @@ -1,5 +1,7 @@ +import Visualizer from "../visualization/Visualizer.js"; import VisualizerUpdateManager from "../visualization/VisualizerUpdateManager.js"; import SongPlayer from "./SongPlayer.js"; +import SongPlaylist from "./SongPlaylist.js"; /** * A song player that provides easier access to the current songs visualizer data. @@ -72,14 +74,14 @@ export default class VisualizedSongPlayer extends SongPlayer { } /** - * The current visualizer update manager. + * @returns {VisualizerUpdateManager} The current visualizer update manager. */ get currentVisualizerUpdateManager() { return this.#visualizerUpdateManager(); } /** - * The current song's visualizer. + * @returns {Visualizer} The current song's visualizer. */ get currentSongVisualizer() { return this.getCurrentSong().getVisualizer(); diff --git a/audioshowkit/src/visualization/Visualizer.js b/audioshowkit/src/visualization/Visualizer.js index 092ddc5..3578370 100644 --- a/audioshowkit/src/visualization/Visualizer.js +++ b/audioshowkit/src/visualization/Visualizer.js @@ -101,7 +101,7 @@ export default class Visualizer { /** - * The number of bins based on the size of the FFT window. + * @returns {number} The number of bins based on the size of the FFT window. */ get numberOfBins() { return this.#buffer.length; @@ -109,7 +109,7 @@ export default class Visualizer { /** * - * The fft window size. + * @returns {number} The fft window size. */ get fftSize() { return this.#analyzer.fftSize; diff --git a/audioshowkit/src/visualization/VisualizerUpdateManager.js b/audioshowkit/src/visualization/VisualizerUpdateManager.js index ff9e99e..73cd51b 100644 --- a/audioshowkit/src/visualization/VisualizerUpdateManager.js +++ b/audioshowkit/src/visualization/VisualizerUpdateManager.js @@ -1,3 +1,5 @@ +import Visualizer from "./Visualizer.js"; + /** * A visualizer update manager offers an extra layer of abstraction on top of the {@link Visualizer}'s update listener. * @@ -49,14 +51,14 @@ export default class VisualizerUpdateManager { } /** - * @typedef {function} visualizerBinUpdateListener + * @typedef {Function} visualizerBinUpdateListener * @param {number} timeDelta elapsed time since last update. * @param {number} amplitude The amplitude of the associated bin. * @param {number} ampDelta change in amplitude of the frequency bin. */ /** - * @typedef {function} visualizerRangedUpdateListener + * @typedef {Function} visualizerRangedUpdateListener * @param {number} timeDelta elapsed time since last update. * @param {number} bins the bins of the range. */