From 2ed7aad1204d634e441a7fcfb1f998cbbfc9a5b8 Mon Sep 17 00:00:00 2001 From: execaman <151807496+execaman@users.noreply.github.com> Date: Mon, 2 Nov 2026 12:06:21 +0530 Subject: [PATCH] chore(docs): make content and jsdoc comments consistent --- docs/src/content/docs/basics/voice.mdx | 2 +- src/main/player.ts | 52 ++++++++++++++------------ src/node/manager.ts | 8 ++-- src/queue/filter.ts | 12 +++--- src/queue/manager.ts | 10 ++--- src/types/main/player.ts | 2 +- src/voice/manager.ts | 4 +- src/voice/region.ts | 4 +- src/voice/state.ts | 22 +++++------ 9 files changed, 60 insertions(+), 56 deletions(-) diff --git a/docs/src/content/docs/basics/voice.mdx b/docs/src/content/docs/basics/voice.mdx index 6ac79f5..52b974b 100644 --- a/docs/src/content/docs/basics/voice.mdx +++ b/docs/src/content/docs/basics/voice.mdx @@ -39,7 +39,7 @@ await player.voices.connect(guildId, voiceChannelId, { If a connection to the same guild and channel is already in progress, `connect()` returns the existing promise rather than starting a new one. If the bot is already connected to that channel and the connection is live, it returns the existing `VoiceState` immediately. -`connect()` times out after 30 seconds if the gateway events don't arrive. +`connect()` times out after `voiceTimeout` milliseconds (default 10_000 / 10s) if the gateway events don't arrive. #### Why a connection might fail diff --git a/src/main/player.ts b/src/main/player.ts index f541617..db787c6 100644 --- a/src/main/player.ts +++ b/src/main/player.ts @@ -111,11 +111,15 @@ export class Player< } /** - * Returns the queue of a guild + * Get the queue of a guild * @param guildId Id of the guild - * @param error Whether to throw an error if queue is not found */ getQueue(guildId: string): Queue | undefined; + /** + * Get the queue of a guild + * @param guildId Id of the guild + * @param error Whether to throw an error if no queue is found + */ getQueue(guildId: string, error: true): Queue; getQueue(guildId: string, error?: true) { const queue = this.queues.get(guildId); @@ -124,15 +128,15 @@ export class Player< } /** - * Creates a queue from options - * @param options Options to create from + * Create (or get) the queue of a guild + * @param options Options for customization */ async createQueue(options: CreateQueueOptions) { return this.queues.create(options); } /** - * Destroys the queue of a guild + * Destroy the queue of a guild * @param guildId Id of the guild * @param reason Reason for destroying */ @@ -141,8 +145,8 @@ export class Player< } /** - * Searches for results based on query and options - * @param query Query (or URL as well) + * Search tracks by query + * @param query Query or URL * @param options Options for customization */ async search(query: string, options?: SearchOptions): Promise { @@ -171,7 +175,7 @@ export class Player< } /** - * Adds or searches if source is query and resumes the queue if stopped + * Add (or search) and play the first resolvable track from source * @param source Source to play from * @param options Options for customization */ @@ -193,16 +197,16 @@ export class Player< } /** - * Jumps to the specified index in queue of a guild + * Jump to a specific track in queue * @param guildId Id of the guild - * @param index Index to jump to + * @param index Index of the track */ async jump(guildId: string, index: number) { return this.getQueue(guildId, true).jump(index); } /** - * Pauses the queue of a guild + * Pause the queue of a guild * @param guildId Id of the guild */ async pause(guildId: string) { @@ -210,7 +214,7 @@ export class Player< } /** - * Plays the previous track in queue of a guild + * Play the previous track in queue * @param guildId Id of the guild */ async previous(guildId: string) { @@ -218,7 +222,7 @@ export class Player< } /** - * Resumes the queue of a guild + * Resume the queue of a guild * @param guildId Id of the guild */ async resume(guildId: string) { @@ -226,7 +230,7 @@ export class Player< } /** - * Seeks to a position in the current track of a guild + * Seek to a specific position in the current track * @param guildId Id of the guild * @param ms Position in milliseconds */ @@ -235,43 +239,43 @@ export class Player< } /** - * Enables or disables autoplay for the queue of a guild + * Set autoplay of a queue * @param guildId Id of the guild - * @param autoplay Whether to enable autoplay + * @param autoplay Whether to enable autoplay (`false` by default) */ setAutoplay(guildId: string, autoplay?: boolean) { return this.getQueue(guildId, true).setAutoplay(autoplay); } /** - * Sets the repeat mode for the queue of a guild + * Set repeat mode of a queue * @param guildId Id of the guild - * @param repeatMode The repeat mode + * @param repeatMode `track`, `queue`, `none` (`none` by default) */ setRepeatMode(guildId: string, repeatMode: RepeatMode) { return this.getQueue(guildId, true).setRepeatMode(repeatMode); } /** - * Sets the volume of the queue of a guild + * Set volume of a queue * @param guildId Id of the guild - * @param volume The volume to set + * @param volume Numeric value between 0 and 1000 */ async setVolume(guildId: string, volume: number) { return this.getQueue(guildId, true).setVolume(volume); } /** - * Shuffles tracks for the queue of a guild + * Shuffle tracks of a queue * @param guildId Id of the guild - * @param includePrevious Whether to pull previous tracks to current + * @param includePrevious Whether to move previous tracks to current */ shuffle(guildId: string, includePrevious?: boolean) { return this.getQueue(guildId, true).shuffle(includePrevious); } /** - * Plays the next track in queue of a guild + * Play the next track in queue * @param guildId Id of the guild */ async next(guildId: string) { @@ -279,7 +283,7 @@ export class Player< } /** - * Stops the queue of a guild + * Stop the queue of a guild * @param guildId Id of the guild */ async stop(guildId: string) { diff --git a/src/node/manager.ts b/src/node/manager.ts index 521b5f8..f2cc2e4 100644 --- a/src/node/manager.ts +++ b/src/node/manager.ts @@ -71,9 +71,9 @@ export class NodeManager implements Partial> { */ state(name: string): NodeState; /** - * Check if a node is in a certain state + * Check if a node is in a specific state * @param name Name of the node - * @param equals Expected state of the node + * @param equals State of the node */ state(name: string, equals: NodeState): boolean; state(name: string, equals?: NodeState) { @@ -98,8 +98,8 @@ export class NodeManager implements Partial> { /** * Delete a node - * @remarks Only a disconnected node with no queues can be deleted, an error is thrown otherwise * @param name Name of the node + * @remarks Only a disconnected node with no queues can be deleted, an error is thrown otherwise */ delete(name: string) { const node = this.#nodes.get(name); @@ -201,7 +201,7 @@ export class NodeManager implements Partial> { } /** - * Fetch info for a specific node (cache-first) + * Fetch lavalink info of a node (cache-first) * @param name Name of the node */ async fetchInfo(name: string) { diff --git a/src/queue/filter.ts b/src/queue/filter.ts index 2cabf62..ca24722 100644 --- a/src/queue/filter.ts +++ b/src/queue/filter.ts @@ -23,8 +23,8 @@ export class FilterManager; @@ -72,8 +72,8 @@ export class FilterManager>(...names: Name[]) { if (names.length === 0) return this.#player.filters as Filters; @@ -88,8 +88,8 @@ export class FilterManager = QueueContext /** * Raw lavalink player objects. - * For reference or advanced usage only, do not `set` or `delete` + * For reference or advanced usage only */ get cache() { return this.#cache as ReadonlyMap; @@ -145,11 +145,11 @@ export class QueueManager = QueueContext } /** - * Sync multiple lavalink player data + * Sync queues and their lavalink players by node * @param node Name of the node - * @param target Target to update (`local` for queues, `remote` for node) + * @param target `local` for queue, `remote` for node (`local` by default) */ - async sync(node: string, target: "local" | "remote" = "local") { + async sync(node: string, target: Parameters[0] = "local") { const _node = this.player.nodes.get(node); if (!_node) throw new Error(`Node '${node}' not found`); @@ -185,7 +185,7 @@ export class QueueManager = QueueContext } /** - * Relocate all queues of a specific node + * Relocate queues by node * @param node Name of the node */ async relocate(node: string) { diff --git a/src/types/main/player.ts b/src/types/main/player.ts index a35ad71..2fcbfd8 100644 --- a/src/types/main/player.ts +++ b/src/types/main/player.ts @@ -204,7 +204,7 @@ export interface PlayerOptions * Return empty or populated array of related tracks * @param queue The queue requesting track(s) * @param track The track suggested for reference - * @remarks DO NOT throw an error + * @remarks Do NOT throw an error through this function */ fetchRelatedTracks?: (queue: Queue, track: Track) => Promise; } diff --git a/src/voice/manager.ts b/src/voice/manager.ts index ff29314..a2c8b1b 100644 --- a/src/voice/manager.ts +++ b/src/voice/manager.ts @@ -66,7 +66,7 @@ export class VoiceManager implements Partial> { /** * Raw voice state objects. - * For reference or advanced usage only, do not `set` or `delete` + * For reference or advanced usage only */ get cache() { return this.#cache as ReadonlyMap; @@ -96,7 +96,7 @@ export class VoiceManager implements Partial> { * Connect to a voice channel * @param guildId Id of the guild * @param voiceId Id of the voice channel - * @param options Options for the queue + * @param options Options for the queue to be created */ async connect(guildId: string, voiceId: string, options?: ConnectOptions) { if (!isString(guildId, SnowflakeRegex)) throw new Error("Guild Id is not a valid Discord Id"); diff --git a/src/voice/region.ts b/src/voice/region.ts index 77018cf..5d48320 100644 --- a/src/voice/region.ts +++ b/src/voice/region.ts @@ -4,13 +4,13 @@ import type { Player } from "@/main"; import type { PlayerState, VoiceNodePingStats } from "@/types"; /** - * Class representing a voice region and evaluating performing nodes + * Class representing a voice region, tracking latency of ready nodes */ export class VoiceRegion { #stats = new Map(); /** - * Id of the region + * Id of this region */ readonly id: string; readonly player: Player; diff --git a/src/voice/state.ts b/src/voice/state.ts index b9b32a3..040ac48 100644 --- a/src/voice/state.ts +++ b/src/voice/state.ts @@ -6,7 +6,7 @@ import type { Player } from "@/main"; import type { APIPlayer, BotVoiceState, PlayerUpdateRequestBody } from "@/types"; /** - * Class representing the state of a voice connection + * Class representing voice state of the bot as a guild member */ export class VoiceState { #changePromise: Promise | null = null; @@ -57,7 +57,7 @@ export class VoiceState { } /** - * Node of this voice connection + * Node of the voice connection */ get node() { return this.#node; @@ -113,28 +113,28 @@ export class VoiceState { } /** - * Whether the bot is in voice channel + * Whether the bot is in a voice channel at all */ get joined() { return this.#state.in_channel; } /** - * Whether the bot is suppressed + * Whether the bot is suppressed (in stage audience, i.e. not a speaker) */ get suppressed() { return this.#state.suppress; } /** - * Whether the voice state is (or being) destroyed + * Whether the queue associated with this voice state is (or being) destroyed */ get unusable() { return this.destroyed || this.player.queues[QueueDestroySymbol](this.guildId) !== undefined; } /** - * Whether this voice state instance is destroyed + * Whether the queue associated with this voice state is destroyed */ get destroyed() { return this.player.voices.get(this.guildId) !== this; @@ -162,14 +162,14 @@ export class VoiceState { } /** - * Whether the node for this connection is being changed + * Whether the node of the voice connection is being changed */ get changingNode() { return this.#changePromise !== null; } /** - * Connect to a voice channel by Id (default if not specified) + * Connect to a voice channel in guild by Id (current if not specified) * @param channelId Id of the voice channel */ async connect(channelId = this.#state.channel_id) { @@ -177,7 +177,7 @@ export class VoiceState { } /** - * Rejoin the voice channel + * Rejoin current voice channel */ async reconnect() { if (this.#reconnectPromise !== null) return this.#reconnectPromise; @@ -198,14 +198,14 @@ export class VoiceState { } /** - * Disconnect from the voice channel + * Disconnect from the current voice channel */ async disconnect() { return this.player.voices.disconnect(this.guildId); } /** - * Change the node of this voice connection + * Change the node of the voice connection * @param name Name of the node. Auto-picks if not specified and throws if none are available. */ async changeNode(name?: string) {