From 32a7be23a1a573eaec4ec37d60932d77ecbe8381 Mon Sep 17 00:00:00 2001 From: Snowflake107 Date: Wed, 21 Apr 2021 14:55:44 +0545 Subject: [PATCH] fix jsdoc --- src/Player.ts | 56 +++++++++++--- src/Structures/ExtractorModel.ts | 2 + src/Structures/Queue.ts | 11 ++- src/Structures/Track.ts | 122 +++++++++++++++++-------------- src/utils/Util.ts | 11 +++ 5 files changed, 132 insertions(+), 70 deletions(-) diff --git a/src/Player.ts b/src/Player.ts index fcba88a..5c23749 100644 --- a/src/Player.ts +++ b/src/Player.ts @@ -26,16 +26,7 @@ import YouTube from 'youtube-sr'; const SoundCloud = new SoundCloudClient(); export class Player extends EventEmitter { - /** - * The discord client that instantiated this player - * @type {DiscordClient} - */ public client: Client; - - /** - * The player options - * @type {PlayerOptions} - */ public options: PlayerOptionsType; /** @@ -45,7 +36,7 @@ export class Player extends EventEmitter { /** * The collection of queues in this player - * @type {DiscordCollection} + * @type {DiscordCollection} */ public queues = new Collection(); private _resultsCollectors = new Collection>(); @@ -53,7 +44,7 @@ export class Player extends EventEmitter { /** * The extractor model collection - * @type {DiscordCollection} + * @type {DiscordCollection} */ public Extractors = new Collection(); @@ -65,16 +56,30 @@ export class Player extends EventEmitter { constructor(client: Client, options?: PlayerOptionsType) { super(); + /** + * The discord client that instantiated this player + * @name Player#client + * @type {DiscordClient} + * @readonly + */ Object.defineProperty(this, 'client', { value: client, enumerable: false }); + /** + * The player options + * @type {PlayerOptions} + */ this.options = Object.assign({}, PlayerOptions, options ?? {}); // check FFmpeg void Util.alertFFmpeg(); + /** + * Audio filters + * @type {Object} + */ this.filters = AudioFilters; this.client.on('voiceStateUpdate', (o, n) => void this._handleVoiceStateUpdate(o, n)); @@ -86,6 +91,10 @@ export class Player extends EventEmitter { } } + /** + * The audio filters + * @returns {Object} + */ static get AudioFilters(): typeof AudioFilters { return AudioFilters; } @@ -94,6 +103,7 @@ export class Player extends EventEmitter { * Define custom extractor in this player * @param {String} extractorName The extractor name * @param {any} extractor The extractor itself + * @returns {Player} */ use(extractorName: string, extractor: any): Player { if (!extractorName) throw new PlayerError('Missing extractor name!', 'PlayerExtractorError'); @@ -113,6 +123,7 @@ export class Player extends EventEmitter { /** * Remove existing extractor from this player * @param {String} extractorName The extractor name + * @returns {Boolean} */ unuse(extractorName: string): boolean { if (!extractorName) throw new PlayerError('Missing extractor name!', 'PlayerExtractorError'); @@ -369,6 +380,7 @@ export class Player extends EventEmitter { * @param {string|Track} query Search query, can be `Player.Track` instance * @param {Boolean} [firstResult] If it should play the first result * @example await player.play(message, "never gonna give you up", true) + * @returns {Promise} */ async play(message: Message, query: string | Track, firstResult?: boolean): Promise { if (!message) throw new PlayerError('Play function needs message'); @@ -451,6 +463,7 @@ export class Player extends EventEmitter { /** * Checks if this player is playing in a server * @param {DiscordMessage} message The message object + * @returns {Boolean} */ isPlaying(message: Message): boolean { return this.queues.some((g) => g.guildID === message.guild.id); @@ -459,6 +472,7 @@ export class Player extends EventEmitter { /** * Returns guild queue object * @param {DiscordMessage} message The message object + * @returns {Queue} */ getQueue(message: Message): Queue { return this.queues.find((g) => g.guildID === message.guild.id); @@ -468,6 +482,7 @@ export class Player extends EventEmitter { * Sets audio filters in this player * @param {DiscordMessage} message The message object * @param {QueueFilters} newFilters Audio filters object + * @returns {Promise} */ setFilters(message: Message, newFilters: QueueFilters): Promise { return new Promise((resolve) => { @@ -503,6 +518,7 @@ export class Player extends EventEmitter { * Sets track position * @param {DiscordMessage} message The message object * @param {Number} time Time in ms to set + * @returns {Promise} */ setPosition(message: Message, time: number): Promise { return new Promise((resolve) => { @@ -526,6 +542,7 @@ export class Player extends EventEmitter { * Sets track position * @param {DiscordMessage} message The message object * @param {Number} time Time in ms to set + * @returns {Promise} */ seek(message: Message, time: number): Promise { return this.setPosition(message, time); @@ -534,6 +551,7 @@ export class Player extends EventEmitter { /** * Skips current track * @param {DiscordMessage} message The message object + * @returns {Boolean} */ skip(message: Message): boolean { const queue = this.getQueue(message); @@ -556,6 +574,7 @@ export class Player extends EventEmitter { * Moves to a new voice channel * @param {DiscordMessage} message The message object * @param {DiscordVoiceChannel} channel New voice channel to move to + * @returns {Boolean} */ moveTo(message: Message, channel?: VoiceChannel): boolean { if (!channel || channel.type !== 'voice') return; @@ -582,6 +601,7 @@ export class Player extends EventEmitter { /** * Pause the playback * @param {DiscordMessage} message The message object + * @returns {Boolean} */ pause(message: Message): boolean { const queue = this.getQueue(message); @@ -602,6 +622,7 @@ export class Player extends EventEmitter { /** * Resume the playback * @param {DiscordMessage} message The message object + * @returns {Boolean} */ resume(message: Message): boolean { const queue = this.getQueue(message); @@ -622,6 +643,7 @@ export class Player extends EventEmitter { /** * Stops the player * @param {DiscordMessage} message The message object + * @returns {Boolean} */ stop(message: Message): boolean { const queue = this.getQueue(message); @@ -647,6 +669,7 @@ export class Player extends EventEmitter { * Sets music volume * @param {DiscordMessage} message The message object * @param {Number} percent The volume percentage/amount to set + * @returns {Boolean} */ setVolume(message: Message, percent: number): boolean { const queue = this.getQueue(message); @@ -668,6 +691,7 @@ export class Player extends EventEmitter { /** * Clears the queue * @param {DiscordMessage} message The message object + * @returns {Boolean} */ clearQueue(message: Message): boolean { const queue = this.getQueue(message); @@ -684,6 +708,7 @@ export class Player extends EventEmitter { /** * Plays previous track * @param {DiscordMessage} message The message object + * @returns {Boolean} */ back(message: Message): boolean { const queue = this.getQueue(message); @@ -724,6 +749,7 @@ export class Player extends EventEmitter { * Sets loop mode * @param {DiscordMessage} message The message object * @param {Boolean} enabled If it should enable the loop mode + * @returns {Boolean} */ setLoopMode(message: Message, enabled: boolean): boolean { const queue = this.getQueue(message); @@ -740,6 +766,7 @@ export class Player extends EventEmitter { /** * Returns currently playing track * @param {DiscordMessage} message The message object + * @returns {Track} */ nowPlaying(message: Message): Track { const queue = this.getQueue(message); @@ -754,6 +781,7 @@ export class Player extends EventEmitter { /** * Shuffles the queue * @param {DiscordMessage} message The message object + * @returns {Queue} */ shuffle(message: Message): Queue { const queue = this.getQueue(message); @@ -778,6 +806,7 @@ export class Player extends EventEmitter { * Removes specified track * @param {DiscordMessage} message The message object * @param {Track|number} track The track object/id to remove + * @returns {Track} */ remove(message: Message, track: Track | number): Track { const queue = this.getQueue(message); @@ -806,6 +835,7 @@ export class Player extends EventEmitter { * Returns time code of currently playing song * @param {DiscordMessage} message The message object * @param {Boolean} [queueTime] If it should make the time code of the whole queue + * @returns {Object} */ getTimeCode(message: Message, queueTime?: boolean): { current: string; end: string } { const queue = this.getQueue(message); @@ -830,6 +860,7 @@ export class Player extends EventEmitter { * Creates progressbar * @param {DiscordMessage} message The message object * @param {PlayerProgressbarOptions} [options] Progressbar options + * @returns {String} */ createProgressBar(message: Message, options?: PlayerProgressbarOptions): string { const queue = this.getQueue(message); @@ -879,6 +910,7 @@ export class Player extends EventEmitter { * @param {String} query Search query * @example const lyrics = await player.lyrics("alan walker faded") * message.channel.send(lyrics.lyrics); + * @returns {Promise} */ async lyrics(query: string): Promise { const extractor = Util.require('@discord-player/extractor'); @@ -894,6 +926,7 @@ export class Player extends EventEmitter { * Toggle autoplay for youtube streams * @param {DiscordMessage} message The message object * @param {Boolean} enable Enable/Disable autoplay + * @returns {boolean} */ setAutoPlay(message: Message, enable: boolean): boolean { const queue = this.getQueue(message); @@ -906,6 +939,7 @@ export class Player extends EventEmitter { /** * Player stats + * @returns {PlayerStats} */ getStats(): PlayerStats { return { diff --git a/src/Structures/ExtractorModel.ts b/src/Structures/ExtractorModel.ts index 00d5902..578470a 100644 --- a/src/Structures/ExtractorModel.ts +++ b/src/Structures/ExtractorModel.ts @@ -22,6 +22,7 @@ class ExtractorModel { /** * Method to handle requests from `Player.play()` * @param {String} query Query to handle + * @returns {Promise} */ async handle(query: string): Promise { const data = await this._raw.getInfo(query); @@ -42,6 +43,7 @@ class ExtractorModel { /** * Method used by Discord Player to validate query with this extractor * @param {String} query The query to validate + * @returns {Boolean} */ validate(query: string): boolean { return Boolean(this._raw.validate(query)); diff --git a/src/Structures/Queue.ts b/src/Structures/Queue.ts index c29f028..1cee68b 100644 --- a/src/Structures/Queue.ts +++ b/src/Structures/Queue.ts @@ -6,9 +6,6 @@ import { Track } from './Track'; import { QueueFilters } from '../types/types'; export class Queue extends EventEmitter { - /** - * The player that instantiated this Queue - */ public player!: Player; public guildID: Snowflake; public voiceConnection?: VoiceConnection; @@ -39,6 +36,12 @@ export class Queue extends EventEmitter { constructor(player: Player, message: Message) { super(); + /** + * The player that instantiated this Queue + * @name Queue#player + * @type {Player} + * @readonly + */ Object.defineProperty(this, 'player', { value: player, enumerable: false }); /** @@ -191,7 +194,7 @@ export class Queue extends EventEmitter { /** * String representation of this Queue - * @type {String} + * @returns {String} */ toString(): string { return ``; diff --git a/src/Structures/Track.ts b/src/Structures/Track.ts index 9327330..9ac73ad 100644 --- a/src/Structures/Track.ts +++ b/src/Structures/Track.ts @@ -4,70 +4,16 @@ import { TrackData } from '../types/types'; import Queue from './Queue'; export class Track { - /** - * The player that instantiated this Track - * @type {Player} - */ public player!: Player; - - /** - * Title of this track - * @type {String} - */ public title!: string; - - /** - * Description of this track - * @type {String} - */ public description!: string; - - /** - * Author of this track - * @type {String} - */ public author!: string; - - /** - * Link of this track - * @type {String} - */ public url!: string; - - /** - * Thumbnail of this track - * @type {String} - */ public thumbnail!: string; - - /** - * Duration of this track - * @type {String} - */ public duration!: string; - - /** - * View count of this track - * @type {Number} - */ public views!: number; - - /** - * Person who requested this track - * @type {DiscordUser} - */ public requestedBy!: User; - - /** - * If this track belongs to a playlist - * @type {Boolean} - */ public fromPlaylist!: boolean; - - /** - * Raw data of this track - * @type {TrackData} - */ public raw!: TrackData; /** @@ -76,8 +22,74 @@ export class Track { * @param {TrackData} data Track data */ constructor(player: Player, data: TrackData) { + /** + * The player that instantiated this Queue + * @name Track#player + * @type {Player} + * @readonly + */ Object.defineProperty(this, 'player', { value: player, enumerable: false }); + /** + * Title of this track + * @name Track#title + * @type {String} + */ + + /** + * Description of this track + * @name Track#description + * @type {String} + */ + + /** + * Author of this track + * @name Track#author + * @type {String} + */ + + /** + * URL of this track + * @name Track#url + * @type {String} + */ + + /** + * Thumbnail of this track + * @name Track#thumbnail + * @type {String} + */ + + /** + * Duration of this track + * @name Track#duration + * @type {String} + */ + + /** + * Views count of this track + * @name Track#views + * @type {Number} + */ + + /** + * Person who requested this track + * @name Track#requestedBy + * @type {DiscordUser} + */ + + /** + * If this track belongs to playlist + * @name Track#fromPlaylist + * @type {Boolean} + */ + + /** + * Raw track data + * @name Track#raw + * @type {TrackData} + */ + void this._patch(data); } @@ -124,7 +136,7 @@ export class Track { /** * String representation of this track - * @type {String} + * @returns {String} */ toString(): string { return `${this.title} by ${this.author}`; diff --git a/src/utils/Util.ts b/src/utils/Util.ts index d33fb53..7826f5d 100644 --- a/src/utils/Util.ts +++ b/src/utils/Util.ts @@ -25,6 +25,7 @@ export class Util { /** * Checks FFmpeg Version * @param {Boolean} [force] If it should forcefully get the version + * @returns {String} */ static getFFmpegVersion(force?: boolean): string { try { @@ -39,6 +40,7 @@ export class Util { /** * Checks FFmpeg * @param {Boolean} [force] If it should forcefully get the version + * @returns {Boolean} */ static checkFFmpeg(force?: boolean): boolean { const version = Util.getFFmpegVersion(force); @@ -60,6 +62,7 @@ export class Util { /** * Resolves query type * @param {String} query The query + * @returns {QueryType} */ static getQueryType(query: string): QueryType { if (SoundcloudValidateURL(query) && !query.includes('/sets/')) return 'soundcloud_track'; @@ -80,6 +83,7 @@ export class Util { /** * Checks if the given string is url * @param {String} str URL to check + * @returns {Boolean} */ static isURL(str: string): boolean { return str.length < 2083 && attachmentRegex.test(str); @@ -88,6 +92,7 @@ export class Util { /** * Returns Vimeo ID * @param {String} query Vimeo link + * @returns {String} */ static getVimeoID(query: string): string { return Util.getQueryType(query) === 'vimeo' @@ -101,6 +106,7 @@ export class Util { /** * Parses ms time * @param {Number} milliseconds Time to parse + * @returns {TimeData} */ static parseMS(milliseconds: number): TimeData { const roundTowardsZero = milliseconds > 0 ? Math.floor : Math.ceil; @@ -116,6 +122,7 @@ export class Util { /** * Creates simple duration string * @param {object} durObj Duration object + * @returns {String} */ static durationString(durObj: object): string { return Object.values(durObj) @@ -161,6 +168,7 @@ export class Util { /** * Checks if this system is running in replit.com + * @returns {Boolean} */ static isRepl(): boolean { if ('DP_REPL_NOCHECK' in process.env) return false; @@ -183,6 +191,7 @@ export class Util { /** * Checks if the given voice channel is empty * @param {DiscordVoiceChannel} channel The voice channel + * @returns {Boolean} */ static isVoiceEmpty(channel: VoiceChannel): boolean { return channel.members.filter((member) => !member.user.bot).size === 0; @@ -191,6 +200,7 @@ export class Util { /** * Builds time code * @param {object} data The data to build time code from + * @returns {String} */ static buildTimeCode(data: any): string { const items = Object.keys(data); @@ -207,6 +217,7 @@ export class Util { /** * Manage CJS require * @param {String} id id to require + * @returns {any} */ static require(id: string): any { try {