From ef07e0f3c8a94abbdbd457e98b822094b5244830 Mon Sep 17 00:00:00 2001 From: Snowflake107 Date: Wed, 21 Apr 2021 12:37:59 +0545 Subject: [PATCH] jsdoc --- src/Player.ts | 142 +++++++++++++++++++++++++++---- src/Structures/ExtractorModel.ts | 12 +-- src/Structures/Queue.ts | 16 ++-- src/Structures/Track.ts | 20 ++--- src/types/types.ts | 98 --------------------- src/utils/Util.ts | 16 ++-- 6 files changed, 157 insertions(+), 147 deletions(-) diff --git a/src/Player.ts b/src/Player.ts index d8cda8a..7892599 100644 --- a/src/Player.ts +++ b/src/Player.ts @@ -91,7 +91,7 @@ export class Player extends EventEmitter { /** * Define custom extractor in this player - * @param {string} extractorName The extractor name + * @param {String} extractorName The extractor name * @param {any} extractor The extractor itself */ use(extractorName: string, extractor: any): Player { @@ -111,7 +111,7 @@ export class Player extends EventEmitter { /** * Remove existing extractor from this player - * @param {string} extractorName The extractor name + * @param {String} extractorName The extractor name */ unuse(extractorName: string): boolean { if (!extractorName) throw new PlayerError('Missing extractor name!', 'PlayerExtractorError'); @@ -366,7 +366,7 @@ export class Player extends EventEmitter { * Play a song * @param {Discord.Message} message The discord.js message object * @param {string|Track} query Search query, can be `Player.Track` instance - * @param {boolean} [firstResult] If it should play the first result + * @param {Boolean} [firstResult] If it should play the first result * @example await player.play(message, "never gonna give you up", true) */ async play(message: Message, query: string | Track, firstResult?: boolean): Promise { @@ -501,7 +501,7 @@ export class Player extends EventEmitter { /** * Sets track position * @param {Discord.Message} message The message object - * @param {number} time Time in ms to set + * @param {Number} time Time in ms to set */ setPosition(message: Message, time: number): Promise { return new Promise((resolve) => { @@ -524,7 +524,7 @@ export class Player extends EventEmitter { /** * Sets track position * @param {Discord.Message} message The message object - * @param {number} time Time in ms to set + * @param {Number} time Time in ms to set */ seek(message: Message, time: number): Promise { return this.setPosition(message, time); @@ -645,7 +645,7 @@ export class Player extends EventEmitter { /** * Sets music volume * @param {Discord.Message} message The message object - * @param {number} percent The volume percentage/amount to set + * @param {Number} percent The volume percentage/amount to set */ setVolume(message: Message, percent: number): boolean { const queue = this.getQueue(message); @@ -705,7 +705,7 @@ export class Player extends EventEmitter { /** * Sets repeat mode * @param {Discord.Message} message The message object - * @param {boolean} enabled If it should enable the repeat mode + * @param {Boolean} enabled If it should enable the repeat mode */ setRepeatMode(message: Message, enabled: boolean): boolean { const queue = this.getQueue(message); @@ -722,7 +722,7 @@ export class Player extends EventEmitter { /** * Sets loop mode * @param {Discord.Message} message The message object - * @param {boolean} enabled If it should enable the loop mode + * @param {Boolean} enabled If it should enable the loop mode */ setLoopMode(message: Message, enabled: boolean): boolean { const queue = this.getQueue(message); @@ -804,7 +804,7 @@ export class Player extends EventEmitter { /** * Returns time code of currently playing song * @param {Discord.Message} message The message object - * @param {boolean} [queueTime] If it should make the time code of the whole queue + * @param {Boolean} [queueTime] If it should make the time code of the whole queue */ getTimeCode(message: Message, queueTime?: boolean): { current: string; end: string } { const queue = this.getQueue(message); @@ -875,7 +875,7 @@ export class Player extends EventEmitter { /** * Gets lyrics of a song - * @param {string} query Search query + * @param {String} query Search query * @example const lyrics = await player.lyrics("alan walker faded") * message.channel.send(lyrics.lyrics); */ @@ -892,7 +892,7 @@ export class Player extends EventEmitter { /** * Toggle autoplay for youtube streams * @param {Discord.Message} message The message object - * @param {boolean} enable Enable/Disable autoplay + * @param {Boolean} enable Enable/Disable autoplay */ setAutoPlay(message: Message, enable: boolean): boolean { const queue = this.getQueue(message); @@ -1199,7 +1199,7 @@ export default Player; * Emitted when the bot is awaiting search results * @event Player#searchResults * @param {Discord.Message} message The message - * @param {string} query The query + * @param {String} query The query * @param {Track[]} tracks The tracks * @param {Discord.Collector} collector The collector */ @@ -1208,9 +1208,9 @@ export default Player; * Emitted when the user has sent an invalid response for search results * @event Player#searchInvalidResponse * @param {Discord.Message} message The message - * @param {string} query The query + * @param {String} query The query * @param {Track[]} tracks The tracks - * @param {string} invalidResponse The `invalidResponse` string + * @param {String} invalidResponse The `invalidResponse` string * @param {Discord.MessageCollector} collector The collector */ @@ -1218,7 +1218,7 @@ export default Player; * Emitted when the bot has stopped awaiting search results (timeout) * @event Player#searchCancel * @param {Discord.Message} message The message - * @param {string} query The query + * @param {String} query The query * @param {Track[]} tracks The tracks */ @@ -1226,7 +1226,7 @@ export default Player; * Emitted when the bot can't find related results to the query * @event Player#noResults * @param {Discord.Message} message The message - * @param {string} query The query + * @param {String} query The query */ /** @@ -1268,7 +1268,7 @@ export default Player; /** * Emitted when an error is triggered * @event Player#error - * @param {string} error It can be `NotConnected`, `UnableToJoin`, `NotPlaying`, `ParseError`, `LiveVideo` or `VideoUnavailable`. + * @param {String} error It can be `NotConnected`, `UnableToJoin`, `NotPlaying`, `ParseError`, `LiveVideo` or `VideoUnavailable`. * @param {Discord.Message} message The message */ @@ -1285,3 +1285,111 @@ export default Player; * @param {Object} playlist The playlist data (parsed) * @param {Discord.Message} message The message */ + +/** + * @typedef {Object} PlayerOptions + * @property {Boolean} [leaveOnEnd=false] If it should leave on queue end + * @property {Number} [leaveOnEndCooldown=0] Time in ms to wait before executing `leaveOnEnd` + * @property {Boolean} [leaveOnStop=false] If it should leave on stop command + * @property {Boolean} [leaveOnEmpty=false] If it should leave on empty voice channel + * @property {Number} [leaveOnEmptyCooldown=0] Time in ms to wait before executing `leaveOnEmpty` + * @property {Boolean} [autoSelfDeaf=false] If it should set the client to `self deaf` mode on joining + * @property {Boolean} [enableLive=false] If it should enable live videos support + * @property {YTDLDownloadOptions} [ytdlDownloadOptions={}] The download options passed to `ytdl-core` + * @property {Boolean} [useSafeSearch=false] If it should use `safe search` method for youtube searches + */ + +/** + * @typedef {'soundcloud'|'youtube'|'arbitrary'} TrackSource + */ + +/** + * @typedef {Object} TrackData + * @property {String} title The title + * @property {String} description The description + * @property {String} author The author + * @property {String} url The url + * @property {String} duration The duration + * @property {Number} views The view count + * @property {Discord.User} requestedBy The user who requested this track + * @property {Boolean} fromPlaylist If this track came from a playlist + * @property {TrackSource} [source] The track source + * @property {string|Readable} [engine] The stream engine + * @property {Boolean} [live=false] If this track is livestream instance + */ + +/** + * @typedef {Object} QueueFilters + * The FFmpeg Filters + */ + +/** + * @typedef {'soundcloud_track'|'soundcloud_playlist'|'spotify_song'|'spotify_album'|'spotify_playlist'|'youtube_video'|'youtube_playlist'|'vimeo'|'facebook'|'reverbnation'|'attachment'|'youtube_search'} QueryType The query type + */ + +/** + * @typedef {Object} ExtractorModelData + * @property {String} title The title + * @property {Number} duration The duration in ms + * @property {String} thumbnail The thumbnail url + * @property {string|Readable} engine The audio engine + * @property {Number} views The views count of this stream + * @property {String} author The author + * @property {String} description The description + * @property {String} url The url + * @property {String} [version='0.0.0'] The extractor version + * @property {Boolean} [important=false] Mark as important + */ + +/** + * @typedef {Object} PlayerProgressbarOptions + * @property {Boolean} [timecodes] If it should return progres bar with time codes + * @property {Boolean} [queue] if it should return the progress bar of the whole queue + * @property {Number} [length] The length of progress bar to build + */ + +/** + * @typedef {Object} LyricsData + * @property {String} title The title of the lyrics + * @property {Number} id The song id + * @property {String} thumbnail The thumbnail + * @property {String} image The image + * @property {String} url The url + * @property {Object} artist The artust info + * @property {String} [artist.name] The name of the artist + * @property {Number} [artist.id] The ID of the artist + * @property {String} [artist.url] The profile link of the artist + * @property {String} [artist.image] The artist image url + * @property {String?} lyrics The lyrics + */ + +/** + * @typedef {Object} PlayerStats + * @property {Number} uptime The uptime in ms + * @property {Number} connections The number of connections + * @property {Number} users The number of users + * @property {Number} queues The number of queues + * @property {Number} extractors The number of custom extractors registered + * @property {Object} versions The versions metadata + * @property {String} [versions.ffmpeg] The ffmpeg version + * @property {String} [versions.node] The node version + * @property {String} [versions.v8] The v8 JavaScript engine version + * @property {Object} system The system data + * @property {String} [system.arch] The system arch + * @property {'aix'|'android'|'darwin'|'freebsd'|'linux'|'openbsd'|'sunos'|'win32'|'cygwin'|'netbsd'} [system.platform] The system platform + * @property {Number} [system.cpu] The cpu count + * @property {Object} [system.memory] The memory info + * @property {String} [system.memory.total] The total memory + * @property {String} [system.memory.usage] The memory usage + * @property {String} [system.memory.rss] The memory usage in RSS + * @property {String} [system.memory.arrayBuffers] The memory usage in ArrayBuffers + * @property {Number} [system.uptime] The system uptime + */ + +/** + * @typedef {Object} TimeData + * @property {Number} days The time in days + * @property {Number} hours The time in hours + * @property {Number} minutes The time in minutes + * @property {Number} seconds The time in seconds + */ \ No newline at end of file diff --git a/src/Structures/ExtractorModel.ts b/src/Structures/ExtractorModel.ts index 6c25fab..00d5902 100644 --- a/src/Structures/ExtractorModel.ts +++ b/src/Structures/ExtractorModel.ts @@ -6,13 +6,13 @@ class ExtractorModel { /** * Model for raw Discord Player extractors - * @param {string} extractorName Name of the extractor + * @param {String} extractorName Name of the extractor * @param {Object} data Extractor object */ constructor(extractorName: string, data: any) { /** * The extractor name - * @type {string} + * @type {String} */ this.name = extractorName; @@ -21,7 +21,7 @@ class ExtractorModel { /** * Method to handle requests from `Player.play()` - * @param {string} query Query to handle + * @param {String} query Query to handle */ async handle(query: string): Promise { const data = await this._raw.getInfo(query); @@ -41,7 +41,7 @@ class ExtractorModel { /** * Method used by Discord Player to validate query with this extractor - * @param {string} query The query to validate + * @param {String} query The query to validate */ validate(query: string): boolean { return Boolean(this._raw.validate(query)); @@ -49,7 +49,7 @@ class ExtractorModel { /** * The extractor version - * @type {string} + * @type {String} */ get version(): string { return this._raw.version ?? '0.0.0'; @@ -57,7 +57,7 @@ class ExtractorModel { /** * If player should mark this extractor as important - * @type {boolean} + * @type {Boolean} */ get important(): boolean { return Boolean(this._raw.important); diff --git a/src/Structures/Queue.ts b/src/Structures/Queue.ts index 41391a9..50d64b8 100644 --- a/src/Structures/Queue.ts +++ b/src/Structures/Queue.ts @@ -78,7 +78,7 @@ export class Queue extends EventEmitter { /** * Queue volume - * @type {number} + * @type {Number} */ this.volume = 100; @@ -102,7 +102,7 @@ export class Queue extends EventEmitter { /** * The additional calculated stream time - * @type {number} + * @type {Number} */ this.additionalStreamTime = 0; @@ -133,7 +133,7 @@ export class Queue extends EventEmitter { /** * Calculated volume of this queue - * @type {number} + * @type {Number} */ get calculatedVolume(): number { return this.filters.normalizer ? this.volume + 70 : this.volume; @@ -141,7 +141,7 @@ export class Queue extends EventEmitter { /** * Total duration - * @type {number} + * @type {Number} */ get totalTime(): number { return this.tracks.length > 0 ? this.tracks.map((t) => t.durationMS).reduce((p, c) => p + c) : 0; @@ -149,7 +149,7 @@ export class Queue extends EventEmitter { /** * Current stream time - * @type {number} + * @type {Number} */ get currentStreamTime(): number { return this.voiceConnection?.dispatcher?.streamTime + this.additionalStreamTime || 0; @@ -166,7 +166,7 @@ export class Queue extends EventEmitter { /** * Returns array of all enabled filters - * @type {string[]} + * @type {String[]} */ getFiltersEnabled(): string[] { const filters: string[] = []; @@ -180,7 +180,7 @@ export class Queue extends EventEmitter { /** * Returns all disabled filters - * @type {string[]} + * @type {String[]} */ getFiltersDisabled(): string[] { const enabled = this.getFiltersEnabled(); @@ -190,7 +190,7 @@ export class Queue extends EventEmitter { /** * String representation of this Queue - * @type {string} + * @type {String} */ toString(): string { return ``; diff --git a/src/Structures/Track.ts b/src/Structures/Track.ts index 10c98e2..c257374 100644 --- a/src/Structures/Track.ts +++ b/src/Structures/Track.ts @@ -12,43 +12,43 @@ export class Track { /** * Title of this track - * @type {string} + * @type {String} */ public title!: string; /** * Description of this track - * @type {string} + * @type {String} */ public description!: string; /** * Author of this track - * @type {string} + * @type {String} */ public author!: string; /** * Link of this track - * @type {string} + * @type {String} */ public url!: string; /** * Thumbnail of this track - * @type {string} + * @type {String} */ public thumbnail!: string; /** * Duration of this track - * @type {string} + * @type {String} */ public duration!: string; /** * View count of this track - * @type {number} + * @type {Number} */ public views!: number; @@ -60,7 +60,7 @@ export class Track { /** * If this track belongs to a playlist - * @type {boolean} + * @type {Boolean} */ public fromPlaylist!: boolean; @@ -106,7 +106,7 @@ export class Track { /** * The track duration in millisecond - * @type {number} + * @type {Number} */ get durationMS(): number { const times = (n: number, t: number) => { @@ -124,7 +124,7 @@ export class Track { /** * String representation of this track - * @type {string} + * @type {String} */ toString(): string { return `${this.title} by ${this.author}`; diff --git a/src/types/types.ts b/src/types/types.ts index a302503..5be7d34 100644 --- a/src/types/types.ts +++ b/src/types/types.ts @@ -2,18 +2,6 @@ import { downloadOptions } from 'ytdl-core'; import { User } from 'discord.js'; import { Readable, Duplex } from 'stream'; -/** - * @typedef {object} PlayerOptions - * @property {boolean} [leaveOnEnd=false] If it should leave on queue end - * @property {number} [leaveOnEndCooldown=0] Time in ms to wait before executing `leaveOnEnd` - * @property {boolean} [leaveOnStop=false] If it should leave on stop command - * @property {boolean} [leaveOnEmpty=false] If it should leave on empty voice channel - * @property {number} [leaveOnEmptyCooldown=0] Time in ms to wait before executing `leaveOnEmpty` - * @property {boolean} [autoSelfDeaf=false] If it should set the client to `self deaf` mode on joining - * @property {boolean} [enableLive=false] If it should enable live videos support - * @property {YTDLDownloadOptions} [ytdlDownloadOptions={}] The download options passed to `ytdl-core` - * @property {boolean} [useSafeSearch=false] If it should use `safe search` method for youtube searches - */ export interface PlayerOptions { leaveOnEnd?: boolean; leaveOnEndCooldown?: number; @@ -28,25 +16,8 @@ export interface PlayerOptions { export type FiltersName = keyof QueueFilters; -/** - * @typedef {'soundcloud'|'youtube'|'arbitrary'} TrackSource - */ export type TrackSource = 'soundcloud' | 'youtube' | 'arbitrary'; -/** - * @typedef {object} TrackData - * @property {string} title The title - * @property {string} description The description - * @property {string} author The author - * @property {string} url The url - * @property {string} duration The duration - * @property {number} views The view count - * @property {Discord.User} requestedBy The user who requested this track - * @property {boolean} fromPlaylist If this track came from a playlist - * @property {TrackSource} [source] The track source - * @property {string|Readable} [engine] The stream engine - * @property {boolean} [live=false] If this track is livestream instance - */ export interface TrackData { title: string; description: string; @@ -62,10 +33,6 @@ export interface TrackData { live?: boolean; } -/** - * @typedef {object} QueueFilters - * The FFmpeg Filters - */ export type QueueFilters = { bassboost?: boolean; '8D'?: boolean; @@ -97,9 +64,6 @@ export type QueueFilters = { fadein?: boolean; }; -/** - * @typedef {'soundcloud_track'|'soundcloud_playlist'|'spotify_song'|'spotify_album'|'spotify_playlist'|'youtube_video'|'youtube_playlist'|'vimeo'|'facebook'|'reverbnation'|'attachment'|'youtube_search'} QueryType The query type - */ export type QueryType = | 'soundcloud_track' | 'soundcloud_playlist' @@ -114,19 +78,6 @@ export type QueryType = | 'attachment' | 'youtube_search'; -/** - * @typedef {object} ExtractorModelData - * @property {string} title The title - * @property {number} duration The duration in ms - * @property {string} thumbnail The thumbnail url - * @property {string|Readable} engine The audio engine - * @property {number} views The views count of this stream - * @property {string} author The author - * @property {string} description The description - * @property {string} url The url - * @property {string} [version='0.0.0'] The extractor version - * @property {boolean} [important=false] Mark as important - */ export interface ExtractorModelData { title: string; duration: number; @@ -140,32 +91,12 @@ export interface ExtractorModelData { important?: boolean; } -/** - * @typedef {object} PlayerProgressbarOptions - * @property {boolean} [timecodes] If it should return progres bar with time codes - * @property {boolean} [queue] if it should return the progress bar of the whole queue - * @property {number} [length] The length of progress bar to build - */ export interface PlayerProgressbarOptions { timecodes?: boolean; queue?: boolean; length?: number; } -/** - * @typedef {object} LyricsData - * @property {string} title The title of the lyrics - * @property {number} id The song id - * @property {string} thumbnail The thumbnail - * @property {string} image The image - * @property {string} url The url - * @property {object} artist The artust info - * @property {string} [artist.name] The name of the artist - * @property {number} [artist.id] The ID of the artist - * @property {string} [artist.url] The profile link of the artist - * @property {string} [artist.image] The artist image url - * @property {string?} lyrics The lyrics - */ export interface LyricsData { title: string; id: number; @@ -181,28 +112,6 @@ export interface LyricsData { lyrics?: string; } -/** - * @typedef {object} PlayerStats - * @property {number} uptime The uptime in ms - * @property {number} connections The number of connections - * @property {number} users The number of users - * @property {number} queues The number of queues - * @property {number} extractors The number of custom extractors registered - * @property {object} versions The versions metadata - * @property {string} [versions.ffmpeg] The ffmpeg version - * @property {string} [versions.node] The node version - * @property {string} [versions.v8] The v8 JavaScript engine version - * @property {object} system The system data - * @property {string} [system.arch] The system arch - * @property {'aix'|'android'|'darwin'|'freebsd'|'linux'|'openbsd'|'sunos'|'win32'|'cygwin'|'netbsd'} [system.platform] The system platform - * @property {number} [system.cpu] The cpu count - * @property {object} [system.memory] The memory info - * @property {string} [system.memory.total] The total memory - * @property {string} [system.memory.usage] The memory usage - * @property {string} [system.memory.rss] The memory usage in RSS - * @property {string} [system.memory.arrayBuffers] The memory usage in ArrayBuffers - * @property {number} [system.uptime] The system uptime - */ export interface PlayerStats { uptime: number; connections: number; @@ -238,13 +147,6 @@ export interface PlayerStats { }; } -/** - * @typedef {object} TimeData - * @property {number} days The time in days - * @property {number} hours The time in hours - * @property {number} minutes The time in minutes - * @property {number} seconds The time in seconds - */ export interface TimeData { days: number; hours: number; diff --git a/src/utils/Util.ts b/src/utils/Util.ts index e3645d8..d569a22 100644 --- a/src/utils/Util.ts +++ b/src/utils/Util.ts @@ -24,7 +24,7 @@ export class Util { /** * Checks FFmpeg Version - * @param {boolean} [force] If it should forcefully get the version + * @param {Boolean} [force] If it should forcefully get the version */ static getFFmpegVersion(force?: boolean): string { try { @@ -38,7 +38,7 @@ export class Util { /** * Checks FFmpeg - * @param {boolean} [force] If it should forcefully get the version + * @param {Boolean} [force] If it should forcefully get the version */ static checkFFmpeg(force?: boolean): boolean { const version = Util.getFFmpegVersion(force); @@ -59,7 +59,7 @@ export class Util { /** * Resolves query type - * @param {string} query The query + * @param {String} query The query */ static getQueryType(query: string): QueryType { if (SoundcloudValidateURL(query) && !query.includes('/sets/')) return 'soundcloud_track'; @@ -79,7 +79,7 @@ export class Util { /** * Checks if the given string is url - * @param {string} str URL to check + * @param {String} str URL to check */ static isURL(str: string): boolean { return str.length < 2083 && attachmentRegex.test(str); @@ -87,7 +87,7 @@ export class Util { /** * Returns Vimeo ID - * @param {string} query Vimeo link + * @param {String} query Vimeo link */ static getVimeoID(query: string): string { return Util.getQueryType(query) === 'vimeo' @@ -100,7 +100,7 @@ export class Util { /** * Parses ms time - * @param {number} milliseconds Time to parse + * @param {Number} milliseconds Time to parse */ static parseMS(milliseconds: number): TimeData { const roundTowardsZero = milliseconds > 0 ? Math.floor : Math.ceil; @@ -125,7 +125,7 @@ export class Util { /** * Makes youtube searches - * @param {string} query The query + * @param {String} query The query * @param {any} options Options * @returns {Promise} */ @@ -206,7 +206,7 @@ export class Util { /** * Manage CJS require - * @param {string} id id to require + * @param {String} id id to require */ static require(id: string): any { try {